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

[Markus Heiser]

Am 30.03.2017 um 10:21 schrieb Jani Nikula <jani.nikula at intel.com>:

> On Thu, 30 Mar 2017, Markus Heiser <markus.heiser at darmarit.de> wrote:
>> Hi Mauro,
>> 
>> Am 29.03.2017 um 20:54 schrieb Mauro Carvalho Chehab <mchehab at s-opensource.com>:
>> 
>>> As we're moving out of DocBook, let's convert the remaining
>>> USB docbooks to ReST.
>>> 
>>> The transformation itself on this patch is a no-brainer
>>> conversion using pandoc.
>> 
>> right, its a no-brainer ;-) I'am not very happy with this
>> conversions, some examples see below.
>> 
>> I recommend to use a more elaborate conversion as starting point,
>> e.g. from my sphkerneldoc project:
>> 
>> * https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/gadget
>> * https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/writing_musb_glue_layer
>> * https://github.com/return42/sphkerneldoc/tree/master/Documentation/books_migrated/writing_usb_driver
>> 
>> Since these DocBooks hasn't been changed in the last month, the linked reST
>> should be up to date.
> 
> Markus, I know you've done a lot of work on your conversions, and you
> like to advocate them, but AFAICT you have never posted the conversions
> as patches to the list. Your project isn't a clone of the kernel
> tree. It's a pile of .rst files that nobody knows how to produce from
> current upstream DocBook .tmpl files. I'm sorry, but this just doesn't
> work that way.

The conversion is done with the dbxml2rst tool:

  https://github.com/return42/dbxml2rst

But you are right, the links I send are decoupled from kernel. It is
a 5 month old snapshot of a DocBook to reST conversion (now updated,
with no affect to the linked files, since they have not been patched
in the meantime) ...

> 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.

If Jonathan also likes to have a bulk conversion of the rest DocBooks,
we can use tmplcvt or even dbxml2rst for this task. Everything under

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

is just a "make dbxm2rst", I can update every time and if a bulk conversion
is the way ... I can send such patches or you send a tmplcvt conversion.

@Jon: what do you think about a bulk conversion?

 -- Markus --