linux-kernel - Re: [PATCH v2 00/12] Convert some DT documentation files to 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]

Date:   Tue, 3 Mar 2020 18:07:02 +0100
From:   Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To:     Rob Herring <robh@...nel.org>
Cc:     Jonathan Corbet <corbet@....net>,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        "linux-kernel@...r.kernel.org" <linux-kernel@...r.kernel.org>,
        devicetree@...r.kernel.org
Subject: Re: [PATCH v2 00/12] Convert some DT documentation files to ReST

Em Tue, 3 Mar 2020 18:01:09 +0100
Mauro Carvalho Chehab <mchehab+huawei@...nel.org> escreveu:

> Em Tue, 3 Mar 2020 10:20:25 -0600
> Rob Herring <robh@...nel.org> escreveu:
> 
> > On Tue, Mar 3, 2020 at 1:09 AM Mauro Carvalho Chehab
> > <mchehab+huawei@...nel.org> wrote:  
> > >
> > > Em Mon, 2 Mar 2020 12:35:54 -0700
> > > Jonathan Corbet <corbet@....net> escreveu:
> > >    
> > > > On Mon,  2 Mar 2020 08:59:25 +0100
> > > > Mauro Carvalho Chehab <mchehab+huawei@...nel.org> wrote:
> > > >    
> > > > > While most of the devicetree stuff has its own format (with is now being
> > > > > converted to YAML format), some documents there are actually
> > > > > describing the DT concepts and how to contribute to it.
> > > > >
> > > > > IMHO, those documents would fit perfectly as part of the documentation
> > > > > body, as part of the firmare documents set.
> > > > >
> > > > > This patch series manually converts some DT documents that, on my
> > > > > opinion, would belong to it.    
> > > >
> > > > Did you consider putting this stuff into the firmware-guide while you were
> > > > at it?  It's not a perfect fit, I guess, but it doesn't seem too awkward
> > > > either.    
> > >
> > > I placed it just below the firmware-guide at the main index file.
> > >
> > > I have split thoughts about moving the files to there, though. From
> > > one side, it may fit better from the PoV of organizing the documentation.
> > >
> > > From other side, newcomers working with DT may expect looking at the
> > > text files inside Documentation/devicetree/.
> > >
> > > Maybe I could add an extra patch at the end of this series with the
> > > move, adding a "RFC" on his title. This way, we can better discuss it,
> > > and either merge the last one or not depending on the comments.    
> > 
> > Keep in mind that we generate a standalone DT only tree[1] with the
> > documentation, dts files and headers. So things should be structured
> > such that all the DT documentation could be built by itself without
> > dependencies on the 'kernel documentation'. I'm not asking for that to
> > be done in this series, but just don't do anything to make that
> > harder. I don't *think* have, but just want to make sure that's clear.  
> 
> So, I guess it is better to keep the .rst files under Documentation/devicetree,
> instead of moving them to Documentation/firmware-guide.
> 
> Well, if moved, I guess it would be easy to modify the scripts that produce
> the documentation to also parse something a new directory inside
> Documentation/firmware-guide.
> 
> >   
> > > > It also seems like it would be good to CC the devicetree folks, or at
> > > > least the devicetree mailing list?    
> > 
> > I was wondering what happened to the cover letter on v2...
> >   
> > > Yeah, that would make sense. I'm using get-maintainers script to
> > > prepare the c/c list, as it is simply too much work to find the
> > > right maintainers by hand, for every single patch.
> > >
> > > I just noticed today that there's just *one entry* at MAINTAINERS
> > > file for Documentation/devicetree, and that points to you:
> > >
> > >         DOCUMENTATION
> > >         M:      Jonathan Corbet <corbet@....net>
> > >         L:      linux-doc@...r.kernel.org
> > >         S:      Maintained
> > >         F:      Documentation/
> > >         F:      scripts/documentation-file-ref-check
> > >         F:      scripts/kernel-doc
> > >         F:      scripts/sphinx-pre-install
> > >         X:      Documentation/ABI/
> > >         X:      Documentation/firmware-guide/acpi/
> > >         X:      Documentation/devicetree/    
> > 
> > You mean doesn't point to Jon as 'X' is exclude. You missed this entry:
> > 
> > OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS
> > M:      Rob Herring <robh+dt@...nel.org>
> > M:      Mark Rutland <mark.rutland@....com>
> > L:      devicetree@...r.kernel.org
> > T:      git git://git.kernel.org/pub/scm/linux/kernel/git/robh/linux.git
> > Q:      http://patchwork.ozlabs.org/project/devicetree-bindings/list/
> > S:      Maintained
> > F:      Documentation/devicetree/
> > F:      arch/*/boot/dts/
> > F:      include/dt-bindings/  
> 
> Yeah, I remember I saw something like the above in the past. However,
> I'm not seeing this entry at the MAINTAINERS file at next-20200303 anymore.
> 
> Did someone removed such entry?

Sorry, false alarm. 

It is there at next. 

I guess it is time for call it a day.

That doesn't explain why I didn't add DT ML to the c/c. I'll try to 
verify what's going on tomorrow.

Regards,
Mauro