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

[Jonathan Corbet]

On Thu,  7 Feb 2019 17:03:15 +1100
"Tobin C. Harding" <tobin@xxxxxxxxxx> 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