Re: [PATCH 00/36] Convert DocBook documents to ReST

Jonathan Corbet
2017-05-15T17:11:41Z

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.

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?

Thanks,

jon