Em Mon, 15 May 2017 11:11:41 -0600 Jonathan Corbet corbet@lwn.net escreveu:
On Fri, 12 May 2017 10:59:43 -0300 Mauro Carvalho Chehab mchehab@s-opensource.com wrote:
This patch series convert the following books from DocBook to ReST:
- filesystems
- kernel-hacking
- kernel-locking
- kgdb
- libata
- networking
- rapidio
- s390-drivers
- scsi
- w1
- z8530book
It also adjusts some Sphinx-pedantic errors/warnings on some kernel-doc markups.
I also added some patches here to add PDF output for all existing ReST books.
So I've been through the series (including digging out the parts that weren't sent to me).
I did my best to check if what's there is not too outdated, but the best is if the subsystem maintainers could check it.
That has been my real concern with those remaining books; many of them have not been touched in any significant way in at least ten years. Just shoveling a bunch of stuff into RST doesn't really solve the problem that Documentation/ is an unorganized jumble of sometimes highly outdated documentation.
True. Yet, on the checks I did, on the books that have API descriptions, the C domain references still exist. On the books that just have kernel-doc tags, I wouldn't expect any changes there, as the API changes should be, instead, at the C code.
So, I guess that it is not that bad, and, by having them in ReST will make them easier to be updated, as ReST is basically ascii with benefits.
But, then, I guess there's value in having a disorganized jumble that depends on only one fragile toolchain rather than two :) So maybe we should just do this.
I only had one real comment with the series beyond the general stuff here. I see Markus had a few. When the tweaks are done, can you send me a series for the stuff I can apply, and I'll do it?
Sure, I'm addressing the comments and will send you a new series.
Thanks, Mauro