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

[Kees Cook <keescook@chromium.org>]

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@suse.com>
> 		Thomas Hellstrom <thellstrom@vmware.com>
> 		"VMware, Inc." <pv-drivers@vmware.com>
> 
> With would be displayed as:
> 
> 	Mail
> 	    Juergen Gross <jgross@suse.com> Thomas Hellstrom <thellstrom@vmware.com> “VMware, Inc.” <pv-drivers@vmware.com>
> 
> It would probably be better to output it as:
> 
> 	:Mail:
> 		- Juergen Gross <jgross@suse.com>
> 		- Thomas Hellstrom <thellstrom@vmware.com>
> 		- "VMware, Inc." <pv-drivers@vmware.com>
> 
> or:
> 	:Mail:
> 		Juergen Gross <jgross@suse.com>
> 
> 		Thomas Hellstrom <thellstrom@vmware.com>
> 
> 		"VMware, Inc." <pv-drivers@vmware.com>
> 
> or, eventually:
> 
> 	:Mail:
> 		Juergen Gross <jgross@suse.com>,
> 		Thomas Hellstrom <thellstrom@vmware.com>,
> 		"VMware, Inc." <pv-drivers@vmware.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