lkml.org 
[lkml]   [2016]   [Feb]   [18]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: V4L docs and docbook
Em Thu, 18 Feb 2016 07:10:14 -0200
Mauro Carvalho Chehab <mchehab@infradead.org> escreveu:

> Em Thu, 18 Feb 2016 06:31:14 -0200
> Mauro Carvalho Chehab <mchehab@infradead.org> escreveu:
>
> > Em Thu, 18 Feb 2016 08:17:00 +0000
> > Russel Winder <russel@winder.org.uk> escreveu:
> >
> > > On Wed, 2016-02-17 at 21:51 -0200, Mauro Carvalho Chehab wrote:
> > > > […]
> > > >
> > > > We have 2 types of documentation for the Kernel part of the
> > > > subsystem,
> > > > Both using DocBook:
> > > > - The uAPI documentation:
> > > > https://linuxtv.org/downloads/v4l-dvb-apis
> > > > - The kAPI documentation:
> > > > https://linuxtv.org/downloads/v4l-dvb-internals/device-drivers/
> > > > mediadev.html
> > > […]
> > >
> > > I may not be introducing new data here but…
> > >
> > > Whilst ReStructuredText and Markdown are fairly popular text markup
> > > languages, they are not related to the DocBook/XML toolchain.
> > >
> > > Many people, especially authors of books etc. are not really willing to
> > > write in DocBook/XML even though it is the re-purposable representation
> > > of choice for most of the major publishers. This led to ASCIIDoc.
> > >
> > > ASCIIDoc is a plain text markup language in the same way
> > > ReStructuredText and Markdown are, but it's intention was always to be
> > > a lightweight front end to DocBook/XML so as to allow authors to write
> > > in a nice markup language but work with the DocBook/XML toolchain.
> > >
> > > ASCIIDoc has gained quite a strong following. So much so that it now
> > > has a life of its own separate from the DocBook/XML tool chain. There
> > > is ASCIIDoctor which generates PDF, HTML,… from the source without
> > > using DocBook/XML, yet the source can quite happily go through a
> > > DocBook/XML toolchain as well.
> > >
> > > Many of the open source projects I am involved with are now using
> > > ASCIIDoctor as the documentation form. This has increased the number of
> > > non-main-contributor contributions via pull requests. It is so much
> > > easier to work with ASCIIDoc(tor) source than DocBook/XML source. 
> >
> > Are there any tools that would convert from DocBook to ASCIIDoc?
>
> Answering myself:
>
> I found one tool at:
> https://github.com/oreillymedia/docbook2asciidoc
>
> That seemed to work. I ran it with:
> $ make DOCBOOKS=media_api.xml htmldocs 2>&1 | grep -v "element.*: validity error : ID .* already defined"
> $ xmllint --noent --postvalid "$PWD/Documentation/DocBook/media_api.xml" >/tmp/x.xml 2>/dev/null
> $ java -jar saxon9he.jar -s /tmp/x.xml -o book.asciidoc d2a_docbook.xsl chunk-output=true
>
> And it produced a series of documents, that I stored at:
> https://mchehab.fedorapeople.org/media-kabi-docs-test/
>
> I noticed, however, that it kept some things using DocBook xml. Perhaps
> because some things cannot be translated to markup (see appa.asciidoc)?
>
> Also, converting them to HTML produced me some errors, but perhaps because
> I don't know what I'm doing ;)
>
> What I did was:
> for i in book-docinfo.xml *.asciidoc; do asciidoc $i; done
>
> errors enclosed.

Stupid me: it should be just:
asciidoc book.asciidoc

Still, there are lots of broken things there, and lots of errors when
building it:
https://mchehab.fedorapeople.org/media-kabi-docs-test/book.html

Ok, I would expect the need to handling some things manually, but
it worries that it broke the tables. For example, see
"Table 1. Control IDs" at https://mchehab.fedorapeople.org/media-kabi-docs-test/book.html

It was mapped as a 3 cols table, but this is how it should be,
instead:
https://linuxtv.org/downloads/v4l-dvb-apis/control.html

As this table has actually 5 cols, because some controls have a list
of multiple values (see V4L2_CID_COLORFX for example).
--
Thanks,
Mauro

\
 
 \ /
  Last update: 2016-02-18 10:41    [W:0.083 / U:0.720 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site