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
