Em Thu, 30 Mar 2017 13:17:16 +0200 Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu: > Am 30.03.2017 um 12:12 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>: > >>> 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 Ok, I double-checked the results from dbxml2rst with pandoc (via the script). Those are the differences after running the following commands: $ wget https://raw.githubusercontent.com/return42/sphkerneldoc/master/Documentation/books_migrated/writing_usb_driver/index.rst $ Documentation/sphinx/tmplcvt Documentation/DocBook/writing_usb_driver.tmpl writing_usb_driver.rst $ diff -uprBw writing_usb_driver.rst index.rst 1) Author data: -:Author: Greg Kroah-Hartman +:author: Kroah-Hartman Greg +:address: greg@xxxxxxxxx dbxml2rst inverted the author's name. It also added author's e-mail. IMHO, it is better to not have email address there, as it could be outdated, but this is just my personal preference. 2) dbxml2rst added a copyright information: +**Copyright** 2001-2002 : Greg Kroah-Hartman This is a good thing. 3) dbxml2rst added a GPL information. IMHO, we should add just one GPL information, per hole book (and not per converted file). 4) dbxml2rst created some references that won't be unique: +.. _intro: That's a bad thing, as I bet most converted documents will have "intro" sections. 5) dbxml2rst use ".. code-block:: c" instead of "::" I prefer using "::" 6) dbxml2rst appends a commentary at the end: +.. ------------------------------------------------------------------------------ +.. This file was automatically converted from DocBook-XML with the dbxml +.. library (https://github.com/return42/dbxml2rst). The origin XML comes +.. from the linux kernel: +.. +.. http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git +.. ------------------------------------------------------------------------------ 7) dbxml2rst did a worse job with URB conversions: -USB Home Page: http://www.usb.org +USB Home Page: `http://www.usb.org <http://www.usb.org>`__ So, in summary, at least for this document, the only thing good with dbxml2rst was that it filled the copyright info. Maybe for more complex documents, it would do a better job. Yet, in order to standardize it everywhere, I guess the best would be to produce copyright data like: .. include:: <isonum.txt> :Copyright: |copy| 2001-2002 : Greg Kroah-Hartman Regards, Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
