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:01:09 +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 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?

> 
> 
> Rob
> 
> [1] https://git.kernel.org/pub/scm/linux/kernel/git/devicetree/devicetree-rebasing.git/