Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1540497 > unrolled thread

Re: [PATCH 0/2] Add maintainers to the admin guide

Back to article view | Back to linux.kernel

This discussion starts older than the indexed window; earlier articles aren't shown. The article labeled Started by below is the oldest one visible, not the original post.

Contents

  Re: [PATCH 0/2] Add maintainers to the admin guide Jonathan Corbet <corbet@lwn.net> - 2016-12-12 19:10 +0100
    Re: [PATCH 0/2] Add maintainers to the admin guide Joe Perches <joe@perches.com> - 2016-12-12 22:00 +0100
      Re: [PATCH 0/2] Add maintainers to the admin guide Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-12-13 10:40 +0100
        Re: [PATCH 0/2] Add maintainers to the admin guide Joe Perches <joe@perches.com> - 2016-12-14 17:20 +0100
          Re: [PATCH 0/2] Add maintainers to the admin guide Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-12-14 17:50 +0100

#1540497 — Re: [PATCH 0/2] Add maintainers to the admin guide

On Fri,  2 Dec 2016 10:15:13 -0200
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

> On the past approaches, was planning to keep the documentation
> about what's at the MAINTAINERS file inside it, but that would
> require running an external script or use some Sphinx extension.
> 
> This time, I took a much simpler approach: convert the initial
> part of the MAINTAINERS file to ReST and move to a file at the
> admin-guide. So, MAINTAINERS file will now contain only the
> maintainer's database, and a single line pointing to its documentation.

So sorry for the silence on this...I decided that I wanted to think about
it past the merge window, then promptly got buried by other stuff.

I like this approach better than one came before, but I do still have to
wonder about what the objective is.  The documentation of the MAINTAINERS
format is going to be of interest to people while the are ... looking at
or modifying MAINTAINERS.  So perhaps it's already in the most useful
place?  Are we really doing people a favor by telling them they have to
follow a pointer to a different file?  What is gained by doing that?

I won't dig in my heels against this forever, but I am curious to hear
what others think about why this change should (or should not) be made.

Thanks,

jon

[toc] | [next] | [standalone]

#1540647

On Mon, 2016-12-12 at 11:00 -0700, Jonathan Corbet wrote:
> On Fri,  2 Dec 2016 10:15:13 -0200
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > On the past approaches, was planning to keep the documentation
> > about what's at the MAINTAINERS file inside it, but that would
> > require running an external script or use some Sphinx extension.
> > 
> > This time, I took a much simpler approach: convert the initial
> > part of the MAINTAINERS file to ReST and move to a file at the
> > admin-guide. So, MAINTAINERS file will now contain only the
> > maintainer's database, and a single line pointing to its documentation.
> 
> So sorry for the silence on this...I decided that I wanted to think about
> it past the merge window, then promptly got buried by other stuff.
> 
> I like this approach better than one came before, but I do still have to
> wonder about what the objective is.  The documentation of the MAINTAINERS
> format is going to be of interest to people while the are ... looking at
> or modifying MAINTAINERS.  So perhaps it's already in the most useful
> place?  Are we really doing people a favor by telling them they have to
> follow a pointer to a different file?  What is gained by doing that?
> 
> I won't dig in my heels against this forever, but I am curious to hear
> what others think about why this change should (or should not) be made.

As long as I don't have to update the get_maintainers script
just to satisfy some external desire to make it rst style
compatible, I don't much care.

About the change itself:

Does the boxing with the ======= blocks align properly?
It it really useful?  Is there another/better way?

[toc] | [prev] | [next] | [standalone]

#1540940

Em Mon, 12 Dec 2016 12:56:50 -0800
Joe Perches <joe@perches.com> escreveu:

> On Mon, 2016-12-12 at 11:00 -0700, Jonathan Corbet wrote:
> > On Fri,  2 Dec 2016 10:15:13 -0200
> > Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> >   
> > > On the past approaches, was planning to keep the documentation
> > > about what's at the MAINTAINERS file inside it, but that would
> > > require running an external script or use some Sphinx extension.
> > > 
> > > This time, I took a much simpler approach: convert the initial
> > > part of the MAINTAINERS file to ReST and move to a file at the
> > > admin-guide. So, MAINTAINERS file will now contain only the
> > > maintainer's database, and a single line pointing to its documentation.  
> > 
> > So sorry for the silence on this...I decided that I wanted to think about
> > it past the merge window, then promptly got buried by other stuff.

Yeah, MAINTAINERS and ABI are two things that require some thinking.

> > 
> > I like this approach better than one came before, but I do still have to
> > wonder about what the objective is.  The documentation of the MAINTAINERS
> > format is going to be of interest to people while the are ... looking at
> > or modifying MAINTAINERS.  So perhaps it's already in the most useful
> > place?  Are we really doing people a favor by telling them they have to
> > follow a pointer to a different file?  What is gained by doing that?

The MAINTAINERS file currently has 3 parts:

1) instructions for patch submitters;
2) descriptions about the database fields;
3) the maintainer's database.

IMHO, part (1) is misplaced. Also, before doing the conversion, I suspect
that the last time I read it were when I became a maintainer, more than
ten years ago :)

Along all those years, I read part (2) only on rare situations,
e. g. when I need to do something different. On such cases, I usually 
open MAINTAINERS file on two windows, one with part (2) and another one
on the editor where I'm filling the database. So, at least for my usecase,
it doesn't really matter if both are in the same file or on different ones.

With regards to part (3),  what I do myself, and what it seems that
new media drivers' submitters do is that they simply clone the media
subsystem's entry (or a previous clone of it) and then modify the "M:"
and the "F:" entry, eventually adding new "L:" entries, when other lists
should be c/c on patch submissions, like on this example:

	AIMSLAB FM RADIO RECEIVER DRIVER
	M:	Hans Verkuil <hverkuil@xs4all.nl>
	L:	linux-media@vger.kernel.org
	T:	git git://linuxtv.org/media_tree.git
	W:	https://linuxtv.org
	S:	Maintained
	F:	drivers/media/radio/radio-aimslab*

IMHO, the meaning of the most used fields are clear to anyone that reads the
database, even without reading part (2).

That's said, in the case of ABI database, the instructions about the
expected fields are on a separate file (Documentation/ABI/README).
That doesn't make any harder to write a new ABI file.

So, I don't see any issue on splitting the non-database stuff on
separate file(s).

Yet, if you prefer to keep them altogether, we could return back to
the previous approach of having a parser that would detect where the
database starts and show it in a literal way. On such case, we could
apply patch 1/2 and modify get_maintainers.pl to output MAINTAINERS
as a ReST format, adding a Sphinx extension that would allow calling
get_maintainers.pl.

> > I won't dig in my heels against this forever, but I am curious to hear
> > what others think about why this change should (or should not) be made.  
> 
> As long as I don't have to update the get_maintainers script
> just to satisfy some external desire to make it rst style
> compatible, I don't much care.
> 
> About the change itself:
> 
> Does the boxing with the ======= blocks align properly?
> It it really useful?  Is there another/better way?

Do you mean those?

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

This is a table. We might instead use a literal block, like:

::

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

But the result looks uglier when generating LaTeX or HTML, as it won't
unwrap the continuation lines of the field descriptions.

Another alternative would be to use ascii artwork, like:

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

That makes it better to read, at the expense that it takes more time to
handwrite.

Yet, once the tables are there, they can easily convert it to ascii artwork
with pandoc:

	$ pandoc -f rst -t rst Documentation/admin-guide/maintainers.rst 

If you think that it makes easier to read, I can replace the tables
there by their asciiart alter ego.

Thanks,
Mauro

[toc] | [prev] | [next] | [standalone]

#1542021

On Tue, 2016-12-13 at 07:38 -0200, Mauro Carvalho Chehab wrote:
> Em Mon, 12 Dec 2016 12:56:50 -0800
> Joe Perches <joe@perches.com> escreveu:
> > Does the boxing with the ======= blocks align properly?
> > It it really useful?  Is there another/better way?
> 
> Do you mean those?
> 
>   ===============================	================================
>   ``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``
>   ===============================	================================

Yes.

> This is a table. We might instead use a literal block, like:
> 
> ::
> 
>   ``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``
> 
> But the result looks uglier when generating LaTeX or HTML, as it won't
> unwrap the continuation lines of the field descriptions.
> 
> Another alternative would be to use ascii artwork, like:
> 
>  +------------------------------------+----------------------------------+
>  | ``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``		 |
>  +------------------------------------+----------------------------------+

Isn't the ascii art is going to get odd looking
output after the sphinx conversion because of the
doubled quotes being converted to bold?

I suspect the table formatting just isn't necessary
and it could be paragraphed instead.

[toc] | [prev] | [next] | [standalone]

#1542036

Em Wed, 14 Dec 2016 08:14:44 -0800
Joe Perches <joe@perches.com> escreveu:

> On Tue, 2016-12-13 at 07:38 -0200, Mauro Carvalho Chehab wrote:
> > Em Mon, 12 Dec 2016 12:56:50 -0800
> > Joe Perches <joe@perches.com> escreveu:  
> > > Does the boxing with the ======= blocks align properly?
> > > It it really useful?  Is there another/better way?  
> > 
> > Do you mean those?
> > 
> >   ===============================	================================
> >   ``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``
> >   ===============================	================================  
> 
> Yes.
> 
> > This is a table. We might instead use a literal block, like:
> > 
> > ::
> > 
> >   ``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``
> > 
> > But the result looks uglier when generating LaTeX or HTML, as it won't
> > unwrap the continuation lines of the field descriptions.
> > 
> > Another alternative would be to use ascii artwork, like:
> > 
> >  +------------------------------------+----------------------------------+
> >  | ``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``		 |
> >  +------------------------------------+----------------------------------+  
> 
> Isn't the ascii art is going to get odd looking
> output after the sphinx conversion because of the
> doubled quotes being converted to bold?

Doubled quotes should be converted to monospaced fonts, and not to
bold. We might remove the double quotes, but the end result would
be worse, as we would need to escape the asterisks.

> I suspect the table formatting just isn't necessary
> and it could be paragraphed instead.

We could use indented paragraphs instead, like:

   * ``F:``   	``drivers/net/``
       all files in and below ``drivers/net``

   * ``F:``   	``*/net/*``
       all files in "any top level directory" ``/net``

But, IMHO, it would look worse than tables on both ASCII and on
formatted outputs.

Thanks,
Mauro

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web