Re: [PATCH 1/4] doc-rst: reST-directive kernel-cmd / include contentent from scripts

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Am 18.10.2016 um 12:06 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxx>:

> 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.

right. (sorry for nitpicking) but IMO there is no need for a
list (-item), just using a simple paragraph should enough

- T: SCM tree type and location.

  Type is one of: git, hg, quilt, stgit, topgit

>> 
>> 
>>> +-	``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.

Since I suppose most Kernel hackers use Emacs I recommend:

(setq-default indent-tabs-mode nil     ; default is not using any TAB
              c-indent-tabs-mode t     ; Pressing TAB should cause indentation
              c-basic-offset 8
              )

* https://www.emacswiki.org/emacs/IndentationBasics

> Using a different style just for documentation is really odd and will
> cause problems,

We already have other sources e.g. python ;-) where spaces
are the preferred indentation method (and mixing is not allowed PY3).

* https://www.python.org/dev/peps/pep-0008/#tabs-or-spaces

> and make the maintainers life like hell if they would
> need to manually check if a documentation hunk is not using tabs.

There is no need to check ... tabs are working, but they
stretch lines unnecessary. 

BTW: There is also a smart-tab

* https://www.emacswiki.org/emacs/SmartTabs

.. have you seen what could happen if you use both ;-)

>> 
>>> +	   - 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
> 
> :-)

What you are looking for is a definition list:

foo
  lorem ipsum ...
 
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#definition-lists



> 
>> 
>>> -	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 Thanks, I will give it a try ... comment soon .. 

--Markus--

> 
>> 
>> 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



[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux