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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <20161214144341.0d679d75@vento.lan>
Date:   Wed, 14 Dec 2016 14:43:41 -0200
From:   Mauro Carvalho Chehab <mchehab@...pensource.com>
To:     Joe Perches <joe@...ches.com>
Cc:     Jonathan Corbet <corbet@....net>,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Mauro Carvalho Chehab <mchehab@...radead.org>,
        LKML <linux-kernel@...r.kernel.org>,
        Markus Heiser <markus.heiser@...marit.de>,
        "David S. Miller" <davem@...emloft.net>,
        Andrew Morton <akpm@...ux-foundation.org>,
        Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
        Mauro Carvalho Chehab <mchehab@...nel.org>,
        Geert Uytterhoeven <geert+renesas@...der.be>
Subject: Re: [PATCH 0/2] Add maintainers to the admin guide

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