subject:"\"\\\[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 drivers/net, but not below
>>> -  F:   */net/* al

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;
> > +   }
> > +   print $_;
> > +   next;
> > +   }
> > +
> > +   next if (m/^$/);
> > +
> > +   if (m/^([A-Z])\:(.*)/) {
> > +   my $tag = $1;

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

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

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

2016-10-17 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-17 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::
> +
> +   **PLEASE:**
> +
> +   - check your patch with the automate

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 aren't as silly as they seem. One
job the maintainers (and especially Linus) do is

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

2016-10-06 Thread Markus Heiser

From: Markus Heiser 

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.

Overview of directive's argument and options.

.. code-block:: rst

.. kernel-cmd:: 
:depends: 
:code-block: 
:debug:

The argument  is required, it is a command line to be
executed. The stdout stream of the command is captured and is inserted as
reST content. The command line is executed in a system shell where the PATH
environment is extended with the paths ::

PATH=$(srctree)/scripts:$(srctree)/Documentation/sphinx:...

A very simple example, which includes the output as ``code-block``::

  .. kernel-cmd:: ls -la $srctree
:code-block: sh

The ``code-block`` is optional, leaving it will include the output as
pure (hopefully well) formated reST.

.. warning::

   The kernel-cmd directive **executes** commands, whatever poses a risk
   (shell injection) in itself!

   The command might depend on local installations, don't use commands which
   are not available in some OS (be clear about the dependencies).

Signed-off-by: Markus Heiser 
---
 Documentation/conf.py  |   2 +-
 Documentation/sphinx/kernel_cmd.py | 206 +
 2 files changed, 207 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/sphinx/kernel_cmd.py

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 0cc8765..64231e1 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -34,7 +34,7 @@ from load_config import loadConfig
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['kernel-doc', 'rstFlatTable', 'kernel_include', 'cdomain']
+extensions = ['kernel-doc', 'rstFlatTable', 'kernel_include', 'cdomain', 
'kernel_cmd']
 
 # The name of the math extension changed on Sphinx 1.4
 if minor > 3:
diff --git a/Documentation/sphinx/kernel_cmd.py 
b/Documentation/sphinx/kernel_cmd.py
new file mode 100644
index 000..ddb2a27
--- /dev/null
+++ b/Documentation/sphinx/kernel_cmd.py
@@ -0,0 +1,206 @@
+# -*- coding: utf-8; mode: python -*-
+u"""
+kernel-cmd
+~~
+
+Implementation of the ``kernel-cmd`` reST-directive.
+
+:copyright:  Copyright (C) 2016  Markus Heiser
+:license:GPL Version 2, June 1991 see Linux/COPYING for details.
+
+The ``kernel-cmd`` (:py:class:`KernelCmd`) directive includes contend
+from the stdout of a comand-line.
+
+Overview of directive's argument and options.
+
+.. code-block:: rst
+
+.. kernel-cmd:: 
+:depends: 
+:code-block: 
+:debug:
+
+The argument  is required, it is a command line to be
+executed. The stdout stream of the command is captured and is inserted as
+reST content. The command line is executed in a system shell where the PATH
+environment is extended with the paths ::
+
+PATH=$(srctree)/scripts:$(srctree)/Documentation/sphinx:...
+
+``depends ``
+
+  If the stdout of the command line depends on files, you can add them as
+  dependency, which means: if one of the listed files is changed, the
+  sphinx-build (environment) is newly build.
+
+``code-block ``
+
+  If the called script outputs a code-block, use the ``code-block`` option
+  with an *language* as argument.  The valid values for the highlighting
+  language are:
+
+  * none (no highlighting)
+  * guess (let Pygments guess the lexer based on contents, only works
+with certain well-recognizable languages)
+  * rest
+  * c
+  * and any other lexer alias that `Pygments
+`_ supports.
+
+``debug``
+  Inserts a code-block with the *raw* reST. Sometimes it is helpful to see
+  what reST is generated.
+
+.. warning::
+
+   The kernel-cmd directive **executes** commands, whatever poses a risk
+   (shell injection) in itself!
+
+   The command might depend on local installations, don't use commands 
which
+   are not available in some OS (be clear about the dependencies).
+
+"""
+
+import sys
+import os
+from os import path
+import subprocess
+
+from sphinx.ext.autodoc import AutodocReporter
+
+from docutils import nodes
+from docutils.parsers.rst import Directive, directives
+from docutils.statemachine import ViewList
+from docutils.utils.error_reporting import ErrorString
+
+
+__version__  = '1.0'
+
+# We can't assume that six is installed
+PY3 = sys.version_info[0] == 3
+PY2 = sys.version_info[0] == 2
+if PY3:
+# pylint: disable=C0103, W0622
+unicode = str
+basestring  = str
+
+def setup(app):
+
+app.add_directive("kernel-cmd", KernelCmd)
+re

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

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

9 matches

Site Navigation

Mail list logo

Footer information