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

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

2016-10-18 Thread Markus Heiser


Am 18.10.2016 um 12:06 schrieb Mauro Carvalho Chehab :

> Sorry, I missed part of your comments on my last reply...
> 
> 
> Em Tue, 18 Oct 2016 09:03:28 +0200
> Markus Heiser  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

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

2016-10-18 Thread Mauro Carvalho Chehab

Sorry, I missed part of your comments on my last reply...


Em Tue, 18 Oct 2016 09:03:28 +0200
Markus Heiser  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
> > +

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

2016-10-18 Thread Mauro Carvalho Chehab

Em Tue, 18 Oct 2016 09:07:03 +0300
Jani Nikula  escreveu:

> On Mon, 17 Oct 2016, Mauro Carvalho Chehab  wrote:
> > [PATCH] docs-rst: user: add MAINTAINERS
> >
> > including MAINTAINERS using ReST is tricky, because all
> > maintainer's entries are like:
> >
> > FOO SUBSYSTEM:
> > M: My Name 
> > L: mailing@list
> > S: Maintained
> > F: foo/bar
> >
> > On ReST, this would be displayed on a single line. Using
> > alias, like |M|, |L|, ... won't solve, as an alias in
> > Sphinx doesn't accept breaking lines.
> >
> > So, instead of changing every line at MAINTAINERS, let's
> > use kernel-cmd extension in order to parse it via a script.  
> 
> Soon I'm going to stop fighting the windmills...
> 
> If you're going to insist on getting kernel-cmd upstream (and I haven't
> changed my opinion on that) 

I also didn't change my mind that maintaining just one python script is
easier than maintaining a plead of python scripts with almost identical
contents.

In any case, if we're willing to have one Python script per each
different non-Python parser, it helps if the source code of such extensions
would be identical, except for the command line that will run the script,
as, if we find a bug on one such script, the same bug fix could be applied
to the other almost identical ones.

> please at least have the sense to have just
> *one* perl script to parse MAINTAINERS, not many. The one script should
> be scripts/get_maintainer.pl.

Agreed. get_maintainer.pl is indeed the best place to put it. I wrote
it this separate script just for a proof of concept, whose goal is to test
if the kernel-cmd extension would be properly parsing the ReST output,
and to identify what sort of output would fit best for the MAINTAINERS
database.

Thanks,
Mauro
--
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

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

2016-10-18 Thread Mauro Carvalho Chehab

Em Tue, 18 Oct 2016 09:03:28 +0200
Markus Heiser  escreveu:

> Am 17.10.2016 um 18:46 schrieb Mauro Carvalho Chehab :
> 
> > Hi Markus,
> > 
> > Em Thu,  6 Oct 2016 09:20:17 +0200
> > Markus Heiser  escreveu:
> >   
> >> From: Markus Heiser 
> >> 
> >> The ``kernel-cmd`` directive includes contend from the stdout of a
> >> command-line. With the ``kernel-cmd`` directive we can include the
> >> output of any (Perl or whatever) script. This is a more general solution
> >> for other workarounds like the "kernel_include + parseheaders" solution.  
> > 
> > Unfortunately, there are some problems with kernel-cmd: it seems
> > that it only partially parses the ReST file, not accepting several ReST 
> > tags.
> > 
> > See the enclosed patch and see the produced html file at:
> > Documentation/output/user/MAINTAINERS.html
> > 
> > Then run the script manually with:
> > ./Documentation/sphinx/format_maintainers.pl MAINTAINERS 
> > >Documentation/user/MAINTAINERS.rst
> > 
> > And see the produced html output after re-building the user book.  
> 
> Hmm, I can't see what you mean ... the MAINTAINERS.html is formated
> according to the markup in the MAINTAINERS.html ... could you 
> be more precise?

Look, for example, on how the tables will be formatted using the
kernel-cmd extension, and how they appear if you create the
MAINTAINERS.rst with:
./Documentation/sphinx/format_maintainers.pl MAINTAINERS 
>Documentation/user/MAINTAINERS.rst

The .. attention:: is also not parsed by kernel-cmd script, nor
the item lists.


>  But before ... I added some comments in the patch
> below to clarify.
> 
> OT but as I'am looking at:
> 
> /share/linux-docs-next/Documentation/user/BUG-HUNTING.rst:247: WARNING: 
> undefined label: submittingpatches (if the link has no caption the label must 
> precede a section header)
> /share/linux-docs-next/Documentation/user/MAINTAINERS.rst:42: WARNING: 
> undefined label: codingstyle (if the link has no caption the label must 
> precede a section header)
> /share/linux-docs-next/Documentation/user/MAINTAINERS.rst:47: WARNING: 
> undefined label: submittingpatches (if the link has no caption the label must 
> precede a section header)
> /share/linux-docs-next/Documentation/user/MAINTAINERS.rst:61: WARNING: 
> undefined label: submittingpatches (if the link has no caption the label must 
> precede a section header)
> /share/linux-docs-next/Documentation/user/README.rst:92: WARNING: undefined 
> label: applying_patches (if the link has no caption the label must precede a 
> section header)
> /share/linux-docs-next/Documentation/user/README.rst:121: WARNING: undefined 
> label: changes (if the link has no caption the label must precede a section 
> header)
> /share/linux-docs-next/Documentation/user/README.rst:256: WARNING: undefined 
> label: changes (if the link has no caption the label must precede a section 
> header)
> /share/linux-docs-next/Documentation/user/devices.rst:9: WARNING: undefined 
> label: submittingpatches (if the link has no caption the label must precede a 
> section header)
> 
> .. this is why I think;  "links are the beginning of babylon" ;-)

Yes. We need intersphinx to fix those if we build just one book, as those 
links belong to other books.


> 
> 
> > 
> > PS.: You can test it on my git tree, with has the code to produce
> > it at the lkml-books branch, at
> > http:://git.linuxtv.org/mchehab/experimental.git
> > 
> > Regards,
> > Mauro
> > 
> > 
> > [PATCH] docs-rst: user: add MAINTAINERS
> > 
> > including MAINTAINERS using ReST is tricky, because all
> > maintainer's entries are like:
> > 
> > FOO SUBSYSTEM:
> > M: My Name 
> > L: mailing@list
> > S: Maintained
> > F: foo/bar
> > 
> > On ReST, this would be displayed on a single line. Using
> > alias, like |M|, |L|, ... won't solve, as an alias in
> > Sphinx doesn't accept breaking lines.
> > 
> > So, instead of changing every line at MAINTAINERS, let's
> > use kernel-cmd extension in order to parse it via a script.
> > 
> > Signed-off-by: Mauro Carvalho Chehab 
> > 
> > diff --git a/Documentation/sphinx/format_maintainers.pl 
> > b/Documentation/sphinx/format_maintainers.pl
> > new file mode 100755
> > index ..fb3af2a30c36
> > --- /dev/null
> > +++ b/Documentation/sphinx/format_maintainers.pl
> > @@ -0,0 +1,44 @@
> > +#!/usr/bin/perl
> > +
> > +my $is_rst = 1;
> > +
> > +# For now, ignore file tags, like F, N, X, K.
> > +my %tags = (
> > +   'P' => 'Person',
> > +   'M' => 'Mail',
> > +   'R' => 'Designated reviewer',
> > +   'L' => 'Mailing list',
> > +   'W' => 'Web page',
> > +   'Q' => 'Patchwork',
> > +   'T' => 'Develoment tree',
> > +   'S' => 'Status',
> > +);
> > +
> > +while (<>) {
> > +   if ($is_rst) {
> > +   if (m/^\s+\-+$/) {
> > +   $is_rst = 0;
> > +   next;
> > +   }
> > +

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

2016-10-18 Thread Markus Heiser

Am 17.10.2016 um 18:46 schrieb Mauro Carvalho Chehab :

> Hi Markus,
> 
> Em Thu,  6 Oct 2016 09:20:17 +0200
> Markus Heiser  escreveu:
> 
>> From: Markus Heiser 
>> 
>> The ``kernel-cmd`` directive includes contend from the stdout of a
>> command-line. With the ``kernel-cmd`` directive we can include the
>> output of any (Perl or whatever) script. This is a more general solution
>> for other workarounds like the "kernel_include + parseheaders" solution.
> 
> Unfortunately, there are some problems with kernel-cmd: it seems
> that it only partially parses the ReST file, not accepting several ReST tags.
> 
> See the enclosed patch and see the produced html file at:
>   Documentation/output/user/MAINTAINERS.html
> 
> Then run the script manually with:
>   ./Documentation/sphinx/format_maintainers.pl MAINTAINERS 
> >Documentation/user/MAINTAINERS.rst
> 
> And see the produced html output after re-building the user book.

Hmm, I can't see what you mean ... the MAINTAINERS.html is formated
according to the markup in the MAINTAINERS.html ... could you 
be more precise?  But before ... I added some comments in the patch
below to clarify.

OT but as I'am looking at:

/share/linux-docs-next/Documentation/user/BUG-HUNTING.rst:247: WARNING: 
undefined label: submittingpatches (if the link has no caption the label must 
precede a section header)
/share/linux-docs-next/Documentation/user/MAINTAINERS.rst:42: WARNING: 
undefined label: codingstyle (if the link has no caption the label must precede 
a section header)
/share/linux-docs-next/Documentation/user/MAINTAINERS.rst:47: WARNING: 
undefined label: submittingpatches (if the link has no caption the label must 
precede a section header)
/share/linux-docs-next/Documentation/user/MAINTAINERS.rst:61: WARNING: 
undefined label: submittingpatches (if the link has no caption the label must 
precede a section header)
/share/linux-docs-next/Documentation/user/README.rst:92: WARNING: undefined 
label: applying_patches (if the link has no caption the label must precede a 
section header)
/share/linux-docs-next/Documentation/user/README.rst:121: WARNING: undefined 
label: changes (if the link has no caption the label must precede a section 
header)
/share/linux-docs-next/Documentation/user/README.rst:256: WARNING: undefined 
label: changes (if the link has no caption the label must precede a section 
header)
/share/linux-docs-next/Documentation/user/devices.rst:9: WARNING: undefined 
label: submittingpatches (if the link has no caption the label must precede a 
section header)

.. this is why I think;  "links are the beginning of babylon" ;-)


> 
> PS.: You can test it on my git tree, with has the code to produce
> it at the lkml-books branch, at
>   http:://git.linuxtv.org/mchehab/experimental.git
> 
> Regards,
> Mauro
> 
> 
> [PATCH] docs-rst: user: add MAINTAINERS
> 
> including MAINTAINERS using ReST is tricky, because all
> maintainer's entries are like:
> 
> FOO SUBSYSTEM:
> M: My Name 
> L: mailing@list
> S: Maintained
> F: foo/bar
> 
> On ReST, this would be displayed on a single line. Using
> alias, like |M|, |L|, ... won't solve, as an alias in
> Sphinx doesn't accept breaking lines.
> 
> So, instead of changing every line at MAINTAINERS, let's
> use kernel-cmd extension in order to parse it via a script.
> 
> Signed-off-by: Mauro Carvalho Chehab 
> 
> diff --git a/Documentation/sphinx/format_maintainers.pl 
> b/Documentation/sphinx/format_maintainers.pl
> new file mode 100755
> index ..fb3af2a30c36
> --- /dev/null
> +++ b/Documentation/sphinx/format_maintainers.pl
> @@ -0,0 +1,44 @@
> +#!/usr/bin/perl
> +
> +my $is_rst = 1;
> +
> +# For now, ignore file tags, like F, N, X, K.
> +my %tags = (
> + 'P' => 'Person',
> + 'M' => 'Mail',
> + 'R' => 'Designated reviewer',
> + 'L' => 'Mailing list',
> + 'W' => 'Web page',
> + 'Q' => 'Patchwork',
> + 'T' => 'Develoment tree',
> + 'S' => 'Status',
> +);
> +
> +while (<>) {
> + if ($is_rst) {
> + if (m/^\s+\-+$/) {
> + $is_rst = 0;
> + next;
> + }
> + print $_;
> + next;
> + }
> +
> + next if (m/^$/);
> +
> + if (m/^([A-Z])\:(.*)/) {
> + my $tag = $1;
> + my $value = $2;
> +
> + my $meaning;
> +
> + next if (!defined($tags{$tag}));
> +
> + printf " - %s:\n   %s\n\n", $tags{$tag}, $value;
> + next;
> + }
> +
> + print "\n$_";
> +}
> +
> +print "\n";

OK, its a starting point, but it is IMO a bit poor.
I missed the 'F' section and the markup arguable

|3C59X NETWORK DRIVER
| - Mail:
|   Steffen Klassert 
|
| - Mailing list:
|   net...@vger.kernel.org
|
| - Status:
|   Maintained

I prefer would prefer an indent of zero/two spaces and no

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

2016-10-18 Thread Markus Heiser


Am 18.10.2016 um 08:07 schrieb Jani Nikula :

> If you're going to insist on getting kernel-cmd upstream (and I haven't
> changed my opinion on that) please at least have the sense to have just
> *one* perl script to parse MAINTAINERS, not many. The one script should
> be scripts/get_maintainer.pl.

Great minds think alike. ;-)

-- Markus --

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

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

2016-10-18 Thread Jani Nikula

On Mon, 17 Oct 2016, Mauro Carvalho Chehab  wrote:
> [PATCH] docs-rst: user: add MAINTAINERS
>
> including MAINTAINERS using ReST is tricky, because all
> maintainer's entries are like:
>
> FOO SUBSYSTEM:
> M: My Name 
> L: mailing@list
> S: Maintained
> F: foo/bar
>
> On ReST, this would be displayed on a single line. Using
> alias, like |M|, |L|, ... won't solve, as an alias in
> Sphinx doesn't accept breaking lines.
>
> So, instead of changing every line at MAINTAINERS, let's
> use kernel-cmd extension in order to parse it via a script.

Soon I'm going to stop fighting the windmills...

If you're going to insist on getting kernel-cmd upstream (and I haven't
changed my opinion on that) please at least have the sense to have just
*one* perl script to parse MAINTAINERS, not many. The one script should
be scripts/get_maintainer.pl.


BR,
Jani.

>
> Signed-off-by: Mauro Carvalho Chehab 
>
> diff --git a/Documentation/sphinx/format_maintainers.pl 
> b/Documentation/sphinx/format_maintainers.pl
> new file mode 100755
> index ..fb3af2a30c36
> --- /dev/null
> +++ b/Documentation/sphinx/format_maintainers.pl
> @@ -0,0 +1,44 @@
> +#!/usr/bin/perl
> +
> +my $is_rst = 1;
> +
> +# For now, ignore file tags, like F, N, X, K.
> +my %tags = (
> + 'P' => 'Person',
> + 'M' => 'Mail',
> + 'R' => 'Designated reviewer',
> + 'L' => 'Mailing list',
> + 'W' => 'Web page',
> + 'Q' => 'Patchwork',
> + 'T' => 'Develoment tree',
> + 'S' => 'Status',
> +);
> +
> +while (<>) {
> + if ($is_rst) {
> + if (m/^\s+\-+$/) {
> + $is_rst = 0;
> + next;
> + }
> + print $_;
> + next;
> + }
> +
> + next if (m/^$/);
> +
> + if (m/^([A-Z])\:(.*)/) {
> + my $tag = $1;
> + my $value = $2;
> +
> + my $meaning;
> +
> + next if (!defined($tags{$tag}));
> +
> + printf " - %s:\n   %s\n\n", $tags{$tag}, $value;
> + next;
> + }
> +
> + print "\n$_";
> +}
> +
> +print "\n";
> diff --git a/Documentation/user/MAINTAINERS.rst 
> b/Documentation/user/MAINTAINERS.rst
> new file mode 100644
> index ..9b01b51749bd
> --- /dev/null
> +++ b/Documentation/user/MAINTAINERS.rst
> @@ -0,0 +1 @@
> +.. kernel-cmd:: format_maintainers.pl $srctree/MAINTAINERS
> diff --git a/Documentation/user/index.rst b/Documentation/user/index.rst
> index 6fbb2dc4b3b7..c4bfd45f0649 100644
> --- a/Documentation/user/index.rst
> +++ b/Documentation/user/index.rst
> @@ -32,3 +32,4 @@ Contents:
> java
> bad_memory
> basic_profiling
> +   MAINTAINERS
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 1cd38a7e0064..d46ffec4e682 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -1,12 +1,14 @@
> -
> -
> - List of maintainers and how to submit kernel changes
> +List of maintainers and how to submit kernel changes
> +
>  
>  Please try to follow the guidelines below.  This will make things
>  easier on the maintainers.  Not all of these guidelines matter for every
>  trivial patch so apply some common sense.
>  
> -1.   Always _test_ your changes, however small, on at least 4 or
> +Tips for patch submitters
> +-
> +
> +1.   Always **test** your changes, however small, on at least 4 or
>   5 people, preferably many more.
>  
>  2.   Try to release a few ALPHA test versions to the net. Announce
> @@ -15,7 +17,7 @@ trivial patch so apply some common sense.
>   you will find things like the fact version 3 firmware needs
>   a magic fix you didn't know about, or some clown changed the
>   chips on a board and not its name.  (Don't laugh!  Look at the
> - SMC etherpower for that.)
> + SMC ``etherpower`` for that.)
>  
>  3.   Make sure your changes compile correctly in multiple
>   configurations. In particular check that changes work both as a
> @@ -25,7 +27,7 @@ trivial patch so apply some common sense.
>   testing and await feedback.
>  
>  5.   Make a patch available to the relevant maintainer in the list. Use
> - 'diff -u' to make the patch easy to merge. Be prepared to get your
> + ``diff -u`` to make the patch easy to merge. Be prepared to get your
>   changes sent back with seemingly silly requests about formatting
>   and variable names.  These aren't as silly as they seem. One
>   job the maintainers (and especially Linus) do is to keep things
> @@ -33,28 +35,34 @@ trivial patch so apply some common sense.
>   your driver to get around a problem actually needs to become a
>   generalized kernel feature ready for next time.
>  
> - PLEASE check your patch with the automated style checker
> - (scripts/checkpatch.pl) to catch trivial style violations.
> - See Documentation/CodingStyle for guidance here.
> + .. attention::
> +
> +

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

2016-10-17 Thread Mauro Carvalho Chehab

Hi Markus,

Em Thu,  6 Oct 2016 09:20:17 +0200
Markus Heiser  escreveu:

> From: Markus Heiser 
> 
> The ``kernel-cmd`` directive includes contend from the stdout of a
> command-line. With the ``kernel-cmd`` directive we can include the
> output of any (Perl or whatever) script. This is a more general solution
> for other workarounds like the "kernel_include + parseheaders" solution.

Unfortunately, there are some problems with kernel-cmd: it seems
that it only partially parses the ReST file, not accepting several ReST tags.

See the enclosed patch and see the produced html file at:
Documentation/output/user/MAINTAINERS.html

Then run the script manually with:
./Documentation/sphinx/format_maintainers.pl MAINTAINERS 
>Documentation/user/MAINTAINERS.rst

And see the produced html output after re-building the user book.


PS.: You can test it on my git tree, with has the code to produce
it at the lkml-books branch, at
http:://git.linuxtv.org/mchehab/experimental.git

Regards,
Mauro


[PATCH] docs-rst: user: add MAINTAINERS

including MAINTAINERS using ReST is tricky, because all
maintainer's entries are like:

FOO SUBSYSTEM:
M: My Name 
L: mailing@list
S: Maintained
F: foo/bar

On ReST, this would be displayed on a single line. Using
alias, like |M|, |L|, ... won't solve, as an alias in
Sphinx doesn't accept breaking lines.

So, instead of changing every line at MAINTAINERS, let's
use kernel-cmd extension in order to parse it via a script.

Signed-off-by: Mauro Carvalho Chehab 

diff --git a/Documentation/sphinx/format_maintainers.pl 
b/Documentation/sphinx/format_maintainers.pl
new file mode 100755
index ..fb3af2a30c36
--- /dev/null
+++ b/Documentation/sphinx/format_maintainers.pl
@@ -0,0 +1,44 @@
+#!/usr/bin/perl
+
+my $is_rst = 1;
+
+# For now, ignore file tags, like F, N, X, K.
+my %tags = (
+   'P' => 'Person',
+   'M' => 'Mail',
+   'R' => 'Designated reviewer',
+   'L' => 'Mailing list',
+   'W' => 'Web page',
+   'Q' => 'Patchwork',
+   'T' => 'Develoment tree',
+   'S' => 'Status',
+);
+
+while (<>) {
+   if ($is_rst) {
+   if (m/^\s+\-+$/) {
+   $is_rst = 0;
+   next;
+   }
+   print $_;
+   next;
+   }
+
+   next if (m/^$/);
+
+   if (m/^([A-Z])\:(.*)/) {
+   my $tag = $1;
+   my $value = $2;
+
+   my $meaning;
+
+   next if (!defined($tags{$tag}));
+
+   printf " - %s:\n   %s\n\n", $tags{$tag}, $value;
+   next;
+   }
+
+   print "\n$_";
+}
+
+print "\n";
diff --git a/Documentation/user/MAINTAINERS.rst 
b/Documentation/user/MAINTAINERS.rst
new file mode 100644
index ..9b01b51749bd
--- /dev/null
+++ b/Documentation/user/MAINTAINERS.rst
@@ -0,0 +1 @@
+.. kernel-cmd:: format_maintainers.pl $srctree/MAINTAINERS
diff --git a/Documentation/user/index.rst b/Documentation/user/index.rst
index 6fbb2dc4b3b7..c4bfd45f0649 100644
--- a/Documentation/user/index.rst
+++ b/Documentation/user/index.rst
@@ -32,3 +32,4 @@ Contents:
java
bad_memory
basic_profiling
+   MAINTAINERS
diff --git a/MAINTAINERS b/MAINTAINERS
index 1cd38a7e0064..d46ffec4e682 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1,12 +1,14 @@
-
-
-   List of maintainers and how to submit kernel changes
+List of maintainers and how to submit kernel changes
+
 
 Please try to follow the guidelines below.  This will make things
 easier on the maintainers.  Not all of these guidelines matter for every
 trivial patch so apply some common sense.
 
-1. Always _test_ your changes, however small, on at least 4 or
+Tips for patch submitters
+-
+
+1. Always **test** your changes, however small, on at least 4 or
5 people, preferably many more.
 
 2. Try to release a few ALPHA test versions to the net. Announce
@@ -15,7 +17,7 @@ trivial patch so apply some common sense.
you will find things like the fact version 3 firmware needs
a magic fix you didn't know about, or some clown changed the
chips on a board and not its name.  (Don't laugh!  Look at the
-   SMC etherpower for that.)
+   SMC ``etherpower`` for that.)
 
 3. Make sure your changes compile correctly in multiple
configurations. In particular check that changes work both as a
@@ -25,7 +27,7 @@ trivial patch so apply some common sense.
testing and await feedback.
 
 5. Make a patch available to the relevant maintainer in the list. Use
-   'diff -u' to make the patch easy to merge. Be prepared to get your
+   ``diff -u`` to make the patch easy to merge. Be prepared to get your
changes sent back with seemingly silly requests about formatting
and variable names.  These

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

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

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

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

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

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

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

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

8 matches

Site Navigation

Mail list logo

Footer information