linux-kernel - Re: [RFC][PATCH] docs: Programmatically render MAINTAINERS into ReST

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] [thread-next>] [day] [month] [year] [list]

Message-ID: <201909241446.3284D27@keescook>
Date:   Tue, 24 Sep 2019 14:50:19 -0700
From:   Kees Cook <keescook@...omium.org>
To:     Mauro Carvalho Chehab <mchehab+samsung@...nel.org>
Cc:     Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org
Subject: Re: [RFC][PATCH] docs: Programmatically render MAINTAINERS into ReST

On Tue, Sep 24, 2019 at 07:08:19AM -0300, Mauro Carvalho Chehab wrote:
> It probably makes sense to change some things there, as, right now, it 
> is considering multiple lines as continuation. So, for example, if
> it has multiple M: entries, it will produce this at MAINTAINERS.rst
> output:
> 
> 
> 	:Mail:
> 		Juergen Gross <jgross@...e.com>
> 		Thomas Hellstrom <thellstrom@...are.com>
> 		"VMware, Inc." <pv-drivers@...are.com>
> 
> With would be displayed as:
> 
> 	Mail
> 	    Juergen Gross <jgross@...e.com> Thomas Hellstrom <thellstrom@...are.com> “VMware, Inc.” <pv-drivers@...are.com>
> 
> It would probably be better to output it as:
> 
> 	:Mail:
> 		- Juergen Gross <jgross@...e.com>
> 		- Thomas Hellstrom <thellstrom@...are.com>
> 		- "VMware, Inc." <pv-drivers@...are.com>
> 
> or:
> 	:Mail:
> 		Juergen Gross <jgross@...e.com>
> 
> 		Thomas Hellstrom <thellstrom@...are.com>
> 
> 		"VMware, Inc." <pv-drivers@...are.com>
> 
> or, eventually:
> 
> 	:Mail:
> 		Juergen Gross <jgross@...e.com>,
> 		Thomas Hellstrom <thellstrom@...are.com>,
> 		"VMware, Inc." <pv-drivers@...are.com>
> 
> (Using commas is probably a bad idea, as DT file names may have a
> comma in the middle)

Doing explicit lists here made the output, I think, way too long and
hard to read. Adding commas for email fields seems like the right
solution here.

> No need to use "python3" here, as the script has a shebang markup. Just
> ensure that it has 755 permission, and call it directly.

BTW, I found where I thought python3 was required:
sphinx/kernel_include.py's shebang is "#!/usr/bin/env python3"

> > +/* Keep fields from being strangely far apart due to inheirited table CSS. */
> > +.rst-content table.field-list th.field-name {
> > +    padding-top: 1px;
> > +    padding-bottom: 1px;
> > +}
> > +.rst-content table.field-list td.field-body {
> > +    padding-top: 1px;
> > +    padding-bottom: 1px;
> > +}
> > +
> >  @media screen {
> >  
> >      /* content column
> 
> I would place this on a separate patch, as this is a layout change that
> may affect other files.

Noted, yes.

> Btw, what does this change?

This gets rid of what looks like an extra blank line after every field
line. I checked other places where fields are used and they suffer from
a similar problem. I'll split this out and call attention to the
existing users.

-- 
Kees Cook