[alsa-devel] [PATCH 00/36] Convert DocBook documents to ReST

[Mauro Carvalho Chehab]

Em Mon, 15 May 2017 11:11:41 -0600
Jonathan Corbet <corbet at lwn.net> escreveu:

> On Fri, 12 May 2017 10:59:43 -0300
> Mauro Carvalho Chehab <mchehab at 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