Am 30.03.2017 um 10:21 schrieb Jani Nikula <jani.nikula@xxxxxxxxx>: > 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. 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 --
