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 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.

    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


    [unhandled content-type:application/pgp-signature]
    \
     
     \ /
      Last update: 2016-02-18 10:41    [W:2.087 / U:0.048 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site