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

[Mauro Carvalho Chehab <mchehab@s-opensource.com>]

Em Thu, 30 Mar 2017 13:17:16 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> Am 30.03.2017 um 12:12 schrieb Mauro Carvalho Chehab <mchehab@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

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@kroah.com

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