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

Mauro Carvalho Chehab
2017-05-15T17:41:03Z

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