docs-rst: user: add MAINTAINERS

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

FOO SUBSYSTEM:
M: My Name <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.

One option would be to use code blocks for every maintainer's entry, like:

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

But this produces a complex html file, with takes a while to be parsed by Firefox. Also, it would require to rewrite the entire MAINTAINERS file, with is a terrible idea, as merging it upstream will cause lots of conflicts.

So, let's use an unusual approach: manually convert the text at the MAINTAINERS file head, adding it at a new Documentation/user/MAINTAINERS.rst, and include, as a code block, the rest of MAINTAINERS contents, with only the contents of the maintainers entries.

There's a side effect of this approach: now, if the explanation text at the MAINTAINERS file is touched, it should be modified also at the Documentation/user/MAINTAINERS.rst file. Yet, as the number of changes there are small, this should be manageable.

---

v2: please ignore this one: e-mail got truncated.

v3: fix a typo at LKML address and on the description below.

I did several tests before coming up with this patch. This one seems to be one of the best ways to handle MAINTAINERS and add it to a ReST file, without needing to change the MAINTAINERS format.

IMHO, the MAINTAINERS file contains important information for patch submitters and bug reporters, so, its content would fit on either the user's manual or development-process one.

If one wants to see how this will be formatted, please see:
https://mchehab.fedorapeople.org/user/MAINTAINERS.html

That's said, I didn't like the idea of duplicating the introductory section of MAINTAINERS into a user/MAINTAINERS.rst file. Yet, no Sphinx extension currently available would do what we need. Maybe an option would be to add an extension similar to the contrib-programoutput whose output could be either parsed as a code-block or as a ReST file.

Btw, a possible improvement would be to change the script executed by programoutput, in order to replace entries like:
M: Foo Bar
to a more human output:
Maintainer: Foo Bar

Anyway, the intention of this patch is to start some discussions about how MAINTAINERS should be placed inside the Kernel documentation.

 Documentation/conf.py              |   2 +-
 Documentation/user/MAINTAINERS.rst | 174 +++++++++++++++++++++++++++++++++++++
 Documentation/user/index.rst       |   1 +
 MAINTAINERS                        |   3 +
 4 files changed, 179 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/user/MAINTAINERS.rst

index b77b23cc1a86..58e79a68033b 100644
@@ -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', 'sphinxcontrib.programoutput']
 
 # The name of the math extension changed on Sphinx 1.4
 if minor > 3:

index 6762af7fc7f5..5c31fb0dc90f 100644
@@ -21,3 +21,4 @@ Contents:
    binfmt_misc
    bad_memory
    basic_profiling
+   MAINTAINERS

index 46a2ce64df68..17fc1b5dacb5 100644
@@ -2,6 +2,9 @@
 
 	List of maintainers and how to submit kernel changes
 
+NOTE: if you update the instuctions below, you should also update
+Documentation/user/MAINTAINERS.rst.
+
 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.

2.7.4

So I'm generally in favor of moving things over to RST, but I have to ask:
what's the payoff for doing that with the MAINTAINERS file? I *suppose* it's documentation, but it's also really a flat-file database of who-to-email information. I'm not sure I see the value of including it in the docs? What am I missing here?

Thanks,

jon

Em Fri, 23 Sep 2016 09:15:01 -0600
Jonathan Corbet <[email protected]> escreveu:

It is part of the REPORTING-BUGS procedure to check MAINTAINERS and find to what ML the bug should be reported:
https://mchehab.fedorapeople.org/user/REPORTING-BUGS.html#how-to-report-linux-kernel-bugs

I _suspect_ that the vast majority of Linux users don't read the MAINTAINERS file, but, instead, just google at the net for an answer to their troubles.

By having it on an html file, together with other user's documentation, the payoff is that more people should do the right thing when seeking for bug resolutions at the right mailing lists or when reporting bugs, ultimately helping to improve the Kernel quality.

Regards,
Mauro

Am 23.09.2016 um 17:35 schrieb Mauro Carvalho Chehab <[email protected]>:

my 2cent: and whats about a simple link into the repo?

* http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/MAINTAINERS#n123

with a hint on using scripts/get_maintainer.pl ...

-- Markus --

couldn't this be a generated file from some awk script instead of being duplicated content with a plea to be kept in sync?

Em Fri, 23 Sep 2016 09:26:34 -0700
Joe Perches <[email protected]> escreveu:

Yes, using a script (awk/perl/bash/python/....) is another alternative.

In such case, we would need to either generate it via Makefile or to have a Sphinx extension that would tell what script to run.

I actually think that a generic include-like Sphinx extension that would run a script and use its result as an included text could be interesting, as it would be a way to get rid of the Documentation/media Makefile.

Thanks,
Mauro