Re: V4L docs and docbook

From: Mauro Carvalho Chehab
Date: Thu Feb 18 2016 - 04:10:48 EST

Next message: Peter Chen: "Re: [PATCH 2/3] usb: type-c: USB Type-C Connector System Software Interface"
Previous message: Srinivas Kandagatla: "Re: [PATCH] nvmem: core: fix error path in nvmem_add_cells()"
In reply to: Mauro Carvalho Chehab: "Re: V4L docs and docbook"
Next in thread: Mauro Carvalho Chehab: "Re: V4L docs and docbook"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

Em Thu, 18 Feb 2016 06:31:14 -0200
Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxx> escreveu:

> Em Thu, 18 Feb 2016 08:17:00 +0000
> Russel Winder <russel@xxxxxxxxxxxxx> 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.

Yet, it seems there are some hope on using asciidoc for the kAPI
documentation.

Thanks,
Mauro

---

asciidoc: ERROR: book.asciidoc: line 9: only book doctypes can contain level 0 sections
asciidoc: ERROR: ch01.asciidoc: line 588: only book doctypes can contain level 0 sections
asciidoc: ERROR: ch02.asciidoc: line 2: section title not permitted in delimited block
asciidoc: ERROR: ch03.asciidoc: line 2: section title not permitted in delimited block
asciidoc: ERROR: ch03.asciidoc: line 370: illegal style name: capture example
asciidoc: ERROR: ch04.asciidoc: line 2: section title not permitted in delimited block
asciidoc: ERROR: ch04.asciidoc: line 719: illegal style name: to do
asciidoc: ERROR: ch05.asciidoc: line 2: section title not permitted in delimited block
asciidoc: ERROR: ch06.asciidoc: line 2: section title not permitted in delimited block
asciidoc: ERROR: ch07.asciidoc: line 2: section title not permitted in delimited block
asciidoc: ERROR: ch07.asciidoc: line 907: illegal style name: Solution?
asciidoc: ERROR: ch07.asciidoc: line 2208: illegal style name: to do - OSS/ALSA
asciidoc: ERROR: appa.asciidoc: line 3: section title not permitted in delimited block
asciidoc: WARNING: appa.asciidoc: line 7: missing style: [blockdef-pass]: appendix
asciidoc: ERROR: appb.asciidoc: line 2: section title not permitted in delimited block
asciidoc: WARNING: appb.asciidoc: line 7: missing style: [paradef-default]: appendix
asciidoc: ERROR: appc.asciidoc: line 3: section title not permitted in delimited block
asciidoc: WARNING: appc.asciidoc: line 7: missing style: [blockdef-pass]: appendix
asciidoc: ERROR: appd.asciidoc: line 3: section title not permitted in delimited block
asciidoc: WARNING: appd.asciidoc: line 7: missing style: [blockdef-pass]: appendix
asciidoc: ERROR: appe.asciidoc: line 3: section title not permitted in delimited block
asciidoc: WARNING: appe.asciidoc: line 5: missing style: [paradef-default]: appendix
asciidoc: ERROR: book.asciidoc: line 142: section title not permitted in delimited block
asciidoc: ERROR: book.asciidoc: line 148: section title not permitted in delimited block
asciidoc: ERROR: ch08.asciidoc: line 2: section title not permitted in delimited block
asciidoc: ERROR: ch09.asciidoc: line 2: section title not permitted in delimited block
asciidoc: ERROR: ch10.asciidoc: line 2: section title not permitted in delimited block
asciidoc: ERROR: ch11.asciidoc: line 2: section title not permitted in delimited block
asciidoc: ERROR: ch12.asciidoc: line 2: section title not permitted in delimited block
asciidoc: ERROR: ch13.asciidoc: line 2: section title not permitted in delimited block
asciidoc: ERROR: ch14.asciidoc: line 2: section title not permitted in delimited block
asciidoc: ERROR: appf.asciidoc: line 3: section title not permitted in delimited block
asciidoc: WARNING: appf.asciidoc: line 7: missing style: [blockdef-pass]: appendix
asciidoc: ERROR: appg.asciidoc: line 3: section title not permitted in delimited block
asciidoc: WARNING: appg.asciidoc: line 7: missing style: [blockdef-pass]: appendix
asciidoc: ERROR: apph.asciidoc: line 3: section title not permitted in delimited block
asciidoc: WARNING: apph.asciidoc: line 7: missing style: [blockdef-pass]: appendix
asciidoc: ERROR: appi.asciidoc: line 3: section title not permitted in delimited block
asciidoc: WARNING: appi.asciidoc: line 7: missing style: [blockdef-pass]: appendix
asciidoc: ERROR: appj.asciidoc: line 3: section title not permitted in delimited block
asciidoc: WARNING: appj.asciidoc: line 7: missing style: [blockdef-pass]: appendix
asciidoc: ERROR: appk.asciidoc: line 3: section title not permitted in delimited block
asciidoc: WARNING: appk.asciidoc: line 7: missing style: [blockdef-pass]: appendix
asciidoc: ERROR: book.asciidoc: line 193: section title not permitted in delimited block
asciidoc: ERROR: ch15.asciidoc: line 2: section title not permitted in delimited block
asciidoc: ERROR: book.asciidoc: line 201: section title not permitted in delimited block
asciidoc: ERROR: ch16.asciidoc: line 2: section title not permitted in delimited block
asciidoc: ERROR: appl.asciidoc: line 3: section title not permitted in delimited block
asciidoc: WARNING: appl.asciidoc: line 7: missing style: [blockdef-pass]: appendix
asciidoc: ERROR: ch17.asciidoc: line 2: section title not permitted in delimited block
asciidoc: ERROR: appm.asciidoc: line 3: section title not permitted in delimited block
asciidoc: WARNING: appm.asciidoc: line 6: missing style: [paradef-literal]: appendix
asciidoc: ERROR: appm.asciidoc: line 17: section title not permitted in delimited block
asciidoc: ERROR: appm.asciidoc: line 50: section title not permitted in delimited block
asciidoc: ERROR: appm.asciidoc: line 144: section title not permitted in delimited block
asciidoc: ERROR: appm.asciidoc: line 166: section title not permitted in delimited block
asciidoc: ERROR: appm.asciidoc: line 217: section title not permitted in delimited block
asciidoc: ERROR: appm.asciidoc: line 434: section title not permitted in delimited block
asciidoc: ERROR: appm.asciidoc: line 471: section title not permitted in delimited block
asciidoc: ERROR: appm.asciidoc: line 492: section title not permitted in delimited block
asciidoc: ERROR: appm.asciidoc: line 514: section title not permitted in delimited block
asciidoc: ERROR: appm.asciidoc: line 531: section title not permitted in delimited block
asciidoc: ERROR: appm.asciidoc: line 545: section title not permitted in delimited block
asciidoc: ERROR: appm.asciidoc: line 569: section title not permitted in delimited block
asciidoc: ERROR: ch04.asciidoc: line 2845: [blockdef-example] missing closing delimiter
asciidoc: ERROR: ch01.asciidoc: line 588: only book doctypes can contain level 0 sections
asciidoc: ERROR: ch01.asciidoc: line 4224: [blockdef-example] missing closing delimiter
asciidoc: ERROR: ch03.asciidoc: line 370: illegal style name: capture example
asciidoc: ERROR: ch04.asciidoc: line 719: illegal style name: to do
asciidoc: ERROR: ch07.asciidoc: line 907: illegal style name: Solution?
asciidoc: ERROR: ch07.asciidoc: line 2208: illegal style name: to do - OSS/ALSA

Attachment: pgpNDQ76chqRW.pgp
Description: Assinatura digital OpenPGP

Next message: Peter Chen: "Re: [PATCH 2/3] usb: type-c: USB Type-C Connector System Software Interface"
Previous message: Srinivas Kandagatla: "Re: [PATCH] nvmem: core: fix error path in nvmem_add_cells()"
In reply to: Mauro Carvalho Chehab: "Re: V4L docs and docbook"
Next in thread: Mauro Carvalho Chehab: "Re: V4L docs and docbook"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]