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:
pgpNnMouDstZJ.pgp
Description: Assinatura digital OpenPGP
