From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Rob Herring <robh@kernel.org>
Cc: Jonathan Corbet <corbet@lwn.net>,
Linux Doc Mailing List <linux-doc@vger.kernel.org>,
"linux-kernel@vger.kernel.org" <linux-kernel@vger.kernel.org>,
devicetree@vger.kernel.org
Subject: Re: [PATCH v2 00/12] Convert some DT documentation files to ReST
Date: Tue, 3 Mar 2020 18:01:09 +0100 [thread overview]
Message-ID: <20200303180109.670ad7f8@onda.lan> (raw)
In-Reply-To: <CAL_JsqKsZNFDSsZJ+wzgD1Eaf0fBwZ7BeUv=32jAuE29TeRfnA@mail.gmail.com>
Em Tue, 3 Mar 2020 10:20:25 -0600
Rob Herring <robh@kernel.org> escreveu:
> On Tue, Mar 3, 2020 at 1:09 AM Mauro Carvalho Chehab
> <mchehab+huawei@kernel.org> wrote:
> >
> > Em Mon, 2 Mar 2020 12:35:54 -0700
> > Jonathan Corbet <corbet@lwn.net> escreveu:
> >
> > > On Mon, 2 Mar 2020 08:59:25 +0100
> > > Mauro Carvalho Chehab <mchehab+huawei@kernel.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@lwn.net>
> > L: linux-doc@vger.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@kernel.org>
> M: Mark Rutland <mark.rutland@arm.com>
> L: devicetree@vger.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/
next prev parent reply other threads:[~2020-03-03 17:01 UTC|newest]
Thread overview: 33+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-03-02 7:59 [PATCH v2 00/12] Convert some DT documentation files to ReST Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 01/12] docs: dt: add an index.rst file for devicetree Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 02/12] docs: dt: convert usage-model.txt to ReST Mauro Carvalho Chehab
2020-03-02 11:54 ` Lee Jones
2020-03-02 21:11 ` Frank Rowand
2020-03-03 7:13 ` Mauro Carvalho Chehab
2020-03-02 21:18 ` Frank Rowand
2020-03-03 7:25 ` Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 03/12] docs: dt: usage_model.rst: fix link for DT usage Mauro Carvalho Chehab
2020-03-02 21:11 ` Frank Rowand
2020-03-02 21:40 ` Rob Herring
2020-03-03 7:31 ` Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 04/12] docs: dt: convert booting-without-of.txt to ReST format Mauro Carvalho Chehab
2020-03-04 18:25 ` Rob Herring
2020-03-05 1:45 ` Alex Shi
2020-03-02 7:59 ` [PATCH v2 05/12] docs: dt: convert changesets to ReST Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 06/12] docs: dt: convert dynamic-resolution-notes.txt " Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 07/12] docs: dt: convert of_unittest.txt " Mauro Carvalho Chehab
2020-03-02 21:11 ` Frank Rowand
2020-03-03 7:15 ` Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 08/12] docs: dt: convert overlay-notes.txt to ReST format Mauro Carvalho Chehab
2020-03-02 21:13 ` Frank Rowand
2020-03-03 7:17 ` Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 09/12] docs: dt: minor adjustments at writing-schema.rst Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 10/12] docs: dt: convert ABI.txt to ReST format Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 11/12] docs: dt: convert submitting-patches.txt " Mauro Carvalho Chehab
2020-03-02 7:59 ` [PATCH v2 12/12] docs: dt: convert writing-bindings.txt to ReST Mauro Carvalho Chehab
2020-03-02 19:35 ` [PATCH v2 00/12] Convert some DT documentation files " Jonathan Corbet
2020-03-03 7:09 ` Mauro Carvalho Chehab
2020-03-03 16:20 ` Rob Herring
2020-03-03 17:01 ` Mauro Carvalho Chehab [this message]
2020-03-03 17:07 ` Mauro Carvalho Chehab
2020-03-02 21:10 ` Frank Rowand
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200303180109.670ad7f8@onda.lan \
--to=mchehab+huawei@kernel.org \
--cc=corbet@lwn.net \
--cc=devicetree@vger.kernel.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=robh@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).