On Thu, 30 Mar 2017, Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote: > Hi Mauro, > > Am 29.03.2017 um 20:54 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>: > >> 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. 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. 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. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center
