linux-kernel - Re: [PATCH 0/1] Start conversion of PowerPC docs

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]

Message-ID: <20190207170131.1fd2bb03@lwn.net>
Date:   Thu, 7 Feb 2019 17:01:31 -0700
From:   Jonathan Corbet <corbet@....net>
To:     "Tobin C. Harding" <tobin@...nel.org>
Cc:     Michael Ellerman <mpe@...erman.id.au>, linux-doc@...r.kernel.org,
        linuxppc-dev@...ts.ozlabs.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH 0/1] Start conversion of PowerPC docs

On Thu,  7 Feb 2019 17:03:15 +1100
"Tobin C. Harding" <tobin@...nel.org> wrote:

> As discussed at LCA here is the start to the docs conversion for PowerPC
> to RST.
> 
> This applies cleanly on top of the mainline (5.20-rc5) and Jon's tree
> (docs-next branch).
> 
> I'm guessing it should go in through the PowerPC tree because I doubt
> you want to review this Jon, it's one big single patch (all blame for
> that falls on mpe ;)

Well, I went and took a look anyway, being a glutton for punishment.  So
naturally I do have some comments...

- 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.  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.

- 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.
  cpu_features.txt predates the git era, as does mpc52xx.txt; hvcs.txt is
  nearly as old. And so on.  Can we perhaps stop dragging some of those
  docs around?

- The use of flat-table in isa-versions.rst totally wrecks the readability
  of those tables in the plain-text version.  Said tables are pretty close
  to being RST in their original form; it would be far better to just fix
  anything needing fixing but to keep that form.

- 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.

Thanks,

jon