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

[Mauro Carvalho Chehab]

Em Wed, 14 Dec 2016 08:14:44 -0800
Joe Perches <joe@xxxxxxxxxxx> 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@xxxxxxxxxxx> 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