Re: [RFC PATCH v3] docs-rst: user: add MAINTAINERS

[Mauro Carvalho Chehab]

Em Fri, 23 Sep 2016 09:26:34 -0700
Joe Perches  escreveu:

> On Fri, 2016-09-23 at 12:07 -0300, Mauro Carvalho Chehab wrote:
> > 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.  
> 
> couldn't this be a generated file from some awk script instead
> of being duplicated content with a plea to be kept in sync?

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

Re: [RFC PATCH v3] docs-rst: user: add MAINTAINERS

[Mauro Carvalho Chehab]

Em Fri, 23 Sep 2016 09:26:34 -0700
Joe Perches  escreveu:

> On Fri, 2016-09-23 at 12:07 -0300, Mauro Carvalho Chehab wrote:
> > 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.  
> 
> couldn't this be a generated file from some awk script instead
> of being duplicated content with a plea to be kept in sync?

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

Re: [RFC PATCH v3] docs-rst: user: add MAINTAINERS

[Markus Heiser]

Am 23.09.2016 um 17:35 schrieb Mauro Carvalho Chehab :

> Em Fri, 23 Sep 2016 09:15:01 -0600
> Jonathan Corbet  escreveu:


>> I'm not sure I see the value of including it in
>> the docs?  What am I missing here?
> 
> 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.
> 

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

Re: [RFC PATCH v3] docs-rst: user: add MAINTAINERS

[Markus Heiser]

Am 23.09.2016 um 17:35 schrieb Mauro Carvalho Chehab :

> Em Fri, 23 Sep 2016 09:15:01 -0600
> Jonathan Corbet  escreveu:


>> I'm not sure I see the value of including it in
>> the docs?  What am I missing here?
> 
> 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.
> 

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

Re: [RFC PATCH v3] docs-rst: user: add MAINTAINERS

[Joe Perches]

On Fri, 2016-09-23 at 12:07 -0300, Mauro Carvalho Chehab wrote:
> 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.

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

> diff --git a/Documentation/user/MAINTAINERS.rst 
> b/Documentation/user/MAINTAINERS.rst
> new file mode 100644

[etc]

Re: [RFC PATCH v3] docs-rst: user: add MAINTAINERS

[Joe Perches]

On Fri, 2016-09-23 at 12:07 -0300, Mauro Carvalho Chehab wrote:
> 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.

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

> diff --git a/Documentation/user/MAINTAINERS.rst 
> b/Documentation/user/MAINTAINERS.rst
> new file mode 100644

[etc]

Re: [RFC PATCH v3] docs-rst: user: add MAINTAINERS

[Mauro Carvalho Chehab]

Em Fri, 23 Sep 2016 09:15:01 -0600
Jonathan Corbet  escreveu:

> On Fri, 23 Sep 2016 12:07:33 -0300
> Mauro Carvalho Chehab  wrote:
> 
> > including MAINTAINERS using ReST is tricky, because all
> > maintainer's entries are like:  
> 
> 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?

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

Re: [RFC PATCH v3] docs-rst: user: add MAINTAINERS

[Mauro Carvalho Chehab]

Em Fri, 23 Sep 2016 09:15:01 -0600
Jonathan Corbet  escreveu:

> On Fri, 23 Sep 2016 12:07:33 -0300
> Mauro Carvalho Chehab  wrote:
> 
> > including MAINTAINERS using ReST is tricky, because all
> > maintainer's entries are like:  
> 
> 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?

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

Re: [RFC PATCH v3] docs-rst: user: add MAINTAINERS

[Jonathan Corbet]

On Fri, 23 Sep 2016 12:07:33 -0300
Mauro Carvalho Chehab  wrote:

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

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

Re: [RFC PATCH v3] docs-rst: user: add MAINTAINERS

[Jonathan Corbet]

On Fri, 23 Sep 2016 12:07:33 -0300
Mauro Carvalho Chehab  wrote:

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

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