Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Date:   Tue, 24 Sep 2019 14:50:19 -0700
From:   Kees Cook <keescook@chromium.org>
To:     Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Cc:     Jonathan Corbet <corbet@lwn.net>, linux-doc@vger.kernel.org,
        linux-kernel@vger.kernel.org
Subject: Re: [RFC][PATCH] docs: Programmatically render MAINTAINERS into ReST
Message-ID: <201909241446.3284D27@keescook>
References: <201909231534.E8BE691@keescook>
 <20190924070819.0a7b6658@coco.lan>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <20190924070819.0a7b6658@coco.lan>
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

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