Sorry, I missed part of your comments on my last reply...
Em Tue, 18 Oct 2016 09:03:28 +0200
Markus Heiser <markus.hei...@darmarit.de> escreveu:
> +- ``T:`` SCM tree type and location.
> +
> > + - Type is one of: **git**, **hg**, **quilt**, **stgit**, **topgit**
> > +
>
> Hmm, why is the last line a bullet list, shouldn't it be:
>
> +- ``T:`` SCM tree type and location
> + Type is one of: git, hg, quilt, stgit, topgit
IMHO, it is better to output it as:
- T: SCM tree type and location.
* Type is one of: git, hg, quilt, stgit, topgit
Putting the explanation on a separate line, then merging the description
of the tag with the details about the valid values.
>
>
> > +- ``S:`` Status, one of the following:
> > +
> > + - Supported:
> > + Someone is actually paid to look after this.
>
> Sorry, but I will never understand why you using mixed tabs and space
> for the same thing ;-) ... what I mean; why is the top-list indented by
> a tab after the bullet and the sub-list by two spaces ...
>
> We had the tab discussion already ... and IMO calling the CodeStyle is not
> helpful when using ASCII markup ... lets take the ASCI documentation compact
> and forget the tab ;-)
Well, my text editor is set to replace 8 spaces by tabs, as this is the
Kernel CodingStyle. I suspect other Kernel hackers do the same.
Using a different style just for documentation is really odd and will
cause problems, and make the maintainers life like hell if they would
need to manually check if a documentation hunk is not using tabs.
>
> > + - Maintained:
> > + Someone actually looks after it.
> > + - Odd Fixes:
> > + It has a maintainer but they don't have time to do
> > much other than throw the odd patch in. See below..
> > - Orphan: No current maintainer [but maybe you could take the
> > + - Orphan:
> > + No current maintainer [but maybe you could take the
> > role as you write your new code].
> > - Obsolete: Old code. Something tagged obsolete generally means
> > + - Obsolete:
> > + Old code. Something tagged obsolete generally means
> > it has been replaced by a better system and you
> > should be using that.
>
> Hmm, here its the same with the indent. List, list-items, paragraphs etc. are
> all
> "body elements".
>
> *
> http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#body-elements
>
> A body element is always introduced by a leading empty line. E.g:
>
> - ``S:`` Status, one of the following:
>
> - Supported:
>
> Someone is actually paid to look after this.
>
> - Maintained:
>
> Someone actually looks after it.
>
> or even more compact (which I do prefer), without paragraphs in the list
> items:
>
> - ``S:`` Status, one of the following:
>
> - Supported: Someone is actually paid to look after this.
>
> - Maintained: Someone actually looks after it.
Hmm... we actually use a lot of markups on the media books like:
- foo
- bar
when we want to put the first line in **bold**, as this seems to be the
only way to make the first line bold if it contains a verbatim.
There's an additional advantage of the above... it requires less typing
than:
- **foo**
- bar
:-)
>
> > - F: Files and directories with wildcard patterns.
> > +- ``F:`` Files and directories with wildcard patterns.
> > +
> > A trailing slash includes all files and subdirectory files.
> > - F: drivers/net/ all files in and below drivers/net
> > - F: drivers/net/* all files in drivers/net, but not below
> > - F: */net/* all files in "any top level directory"/net
> > - One pattern per line. Multiple F: lines acceptable.
> > - N: Files and directories with regex patterns.
> > - N: [^a-z]tegra all files whose path contains the word tegra
> > - One pattern per line. Multiple N: lines acceptable.
> > - scripts/get_maintainer.pl has different behavior for files that
> > - match F: pattern and matches of N: patterns. By default,
> > - get_maintainer will not look at git log history when an F: pattern
> > - match occurs. When an N: match occurs, git log history is used
> > - to also notify the people that have git commit signatures.
> > - X: Files and directories that are NOT maintained, same rules as F:
> > - Files exclusions are tested before file matches.
> > - Can be useful for excluding a specific subdirectory, for instance:
> > - F: net/
> > - X: net/ipv6/
> > - matches all files in and below net excluding net/ipv6/
> > - K: Keyword perl extended regex pattern to match content in a
> > +
> > + ============================== ======================================
> > + ``F:`` ``drivers/net/`` all files in and below
> > + ``drivers/net``
> > + ``F:`` ``drivers/net/*`` all files in ``drivers/net``,
> > + but not below
> > + ``F:`` ``*/net/*`` all files in "any top level
> > + directory" ``/net``
> > + ============================== ======================================
> > +
> > + One pattern per line. Multiple ``F:`` lines acceptable.
> > +- ``N:`` Files and directories with regex patterns.
>
> Between the last two lines, a empty line is required ... I fond this more
> times
> (will not comment each).
Surely we can improve the markups here. Yet, the point is that the html
produced via kernel-cmd is completely different than he one produced by
calling the perl script directly. When kernel-cmd is used, lots of tags are
not parsed.
That's said, if I add a logic at the script to expand the tabs before
output (patch enclosed), everything looks OK.
>
> OK, I will stop here, if you are interested in I can prepare a patch for
> illustration ....
>
Thanks,
Mauro
diff --git a/Documentation/sphinx/format_maintainers.pl
b/Documentation/sphinx/format_maintainers.pl
index fb3af2a30c36..c3174c2b180a 100755
--- a/Documentation/sphinx/format_maintainers.pl
+++ b/Documentation/sphinx/format_maintainers.pl
@@ -1,4 +1,5 @@
#!/usr/bin/perl
+use Text::Tabs;
my $is_rst = 1;
@@ -15,18 +16,20 @@ my %tags = (
);
while (<>) {
+ my $s = expand($_);
+
if ($is_rst) {
- if (m/^\s+\-+$/) {
+ if ($s =~ m/^\s+\-+$/) {
$is_rst = 0;
next;
}
- print $_;
+ print $s;
next;
}
- next if (m/^$/);
+ next if ($s =~ m/^\s*$/);
- if (m/^([A-Z])\:(.*)/) {
+ if ($s =~ m/^([A-Z])\:(.*)/) {
my $tag = $1;
my $value = $2;
@@ -38,7 +41,7 @@ while (<>) {
next;
}
- print "\n$_";
+ print "\n$s";
}
print "\n";
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
