Sorry, I missed part of your comments on my last reply... Em Tue, 18 Oct 2016 09:03:28 +0200 Markus Heiser <markus.heiser@xxxxxxxxxxx> 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-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
