From: Jonathan Corbet <corbet@lwn.net>
To: Michael Ellerman <mpe@ellerman.id.au>
Cc: linux-kernel@vger.kernel.org, linuxppc-dev@lists.ozlabs.org,
"Tobin C. Harding" <tobin@kernel.org>,
linux-doc@vger.kernel.org
Subject: Re: [PATCH 0/1] Start conversion of PowerPC docs
Date: Fri, 8 Feb 2019 13:00:34 -0700 [thread overview]
Message-ID: <20190208130034.6bccffbd@lwn.net> (raw)
In-Reply-To: <87ef8jj6c3.fsf@concordia.ellerman.id.au>
On Fri, 08 Feb 2019 14:40:28 +1100
Michael Ellerman <mpe@ellerman.id.au> wrote:
> > - I don't think this should be a top-level directory full of docs; the top
> > level is already rather overpopulated. At worst, we should create an
> > arch/ directory for architecture-specific docs.
>
> We currently have arch specific directories for arm, arm64, ia64, m68k,
> nios2, openrisc, parisc, powerpc, s390, sh, sparc, x86, xtensa.
>
> Do you mean they should all be moved to Documentation/arch ?
Over time I'm really trying to bring some organization to Documentation/,
and to have that reflected in an RST tree that looks like somebody actually
thought about it. So yes, I would eventually like to see something like
Documentation/arch, just like we have arch/ in the top-level directory.
> > I kind of think that
> > this should be thought through a bit more, though, with an eye toward
> > who the audience is. Some of it is clearly developer documentation, and
> > some of it is aimed at admins; ptrace.rst is user-space API stuff.
> > Nobody ever welcomes me saying this, but we should really split things
> > into the appropriate manuals according to audience.
>
> I don't think any of it's aimed at admins, but I haven't read every
> word. I see it as aimed at kernel devs or people writing directly to the
> kernel API, eg. gdb developers reading ptrace.rst.
>
> If Documentation/ wants to be more user focused and nicely curated
> perhaps we need arch/foo/docs/ for these developer centric docs?
Stuff for GDB developers is best placed in the userspace-api docbook; we're
trying to concentrate that there. Stuff for kernel developers is a bit
more diffuse still; arch/foo/docs may end up being the best place for it in
the end, yes.
> > - It would be good to know how much of this stuff is still relevant.
> > bootwrapper.txt hasn't been modified since it was added in 2008.
>
> It hasn't been modified but AFAIK it's still pretty much accurate and
> definitely something we want to have documented.
That's fine for this (and all the others); I'm just hoping that somebody
has thought about it. We're carrying a *lot* of dusty old stuff that, IMO,
can only serve to confuse those who read it. If these files don't fall
into that category, that's great.
> We support some hardware that is ~25 years old, so we have some old
> documentation too, and I'd rather we didn't drop things just because
> they're old.
I agree, as long as they remain correct and relevant.
> > - I'm glad you're adding SPDX lines, but do you know that the license is
> > correct in each case? It's best to be careful with such things.
>
> None of the files have licenses so I think we just fall back to COPYING
> don't we? In which case GPL-2.0 is correct for all files.
That's often the best choice, though some people have resorted to some
rather more in-depth archeology to try to figure out what the original
author actually intended. Again, I'm just asking so that we're sure it's
the best choice.
Thanks,
jon
prev parent reply other threads:[~2019-02-08 20:02 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-02-07 6:03 [PATCH 0/1] Start conversion of PowerPC docs Tobin C. Harding
2019-02-07 6:03 ` [PATCH 1/1] docs: powerpc: Convert to RST format Tobin C. Harding
2019-02-07 22:58 ` Randy Dunlap
2019-02-08 0:01 ` [PATCH 0/1] Start conversion of PowerPC docs Jonathan Corbet
2019-02-08 3:40 ` Michael Ellerman
2019-02-08 20:00 ` Jonathan Corbet [this message]
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=20190208130034.6bccffbd@lwn.net \
--to=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linuxppc-dev@lists.ozlabs.org \
--cc=mpe@ellerman.id.au \
--cc=tobin@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).