[PATCH 02/22] docs-rst: convert usb docbooks to ReST

[Markus Heiser]

Am 30.03.2017 um 12:12 schrieb Mauro Carvalho Chehab <mchehab at s-opensource.com>:
>>> At this point I'd just go with what Mauro has. It's here now, as
>>> patches. We've seen from the GPU documentation that polishing the
>>> one-time initial conversion is, after a point, wasted effort. Having the
>>> documentation in rst attracts more attention and contributions, and any
>>> remaining issues will get ironed out in rst.  
>> 
>> I totally agree with you (I have never said something different)
>> 
>>> This is also one reason I'm in favor of just bulk converting the rest of
>>> the .tmpl files using Documentation/sphinx/tmplcvt, get rid of DocBook
>>> and be done with it, and have the crowds focus on rst.  
>> 
>> I also agree with that. The tmplcvt script is good enough for this task,
>> the dbxml2rst tool is more elaborate.
> 
> I like the idea of a bulk conversion. My personal preference here is to
> use the tmplcvt for such task, at least for simple books like the ones
> I converted from USB.
> 
> The advantage is that it places everything on a single rst file, with,
> IMHO, works best for books that aren't too complex.
> Of course, it doesn't hurt to compare the end result with dbxml2rst
> and see if something could be improved.

If it helps ... dbxml2rst also supports single file conversion  ... I updated:

  https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated

There you find a folder for each DocBook conversion with only one rst file (index.rst)
in .. If you like, use it for comparison.

-- Markus --