Em Tue, 8 Mar 2016 12:39:21 -0300 Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxx> escreveu: > Pandoc failed to fully convert it, but at least it left all the texts, > with prevented rewriting it from scratch. This is the manual fix > I applied to it: > https://git.linuxtv.org/mchehab/asciidoc-poc.git/commit/func-ioctl.adoc?id=801d336c3742f26731e08c284290c32c0b4632fc > > FYI, we have 133 xml files at the media uAPI doc with refmeta. I used pandoc to convert from the html files and manually edited it. I also fixed lots of other issues with the conversion. I guess the conversion to asciidoc format is now in good shape, at least to demonstrate that it is possible to use this format for the media docbook. Still, there are lots of broken references. The proof of concept html file is at: https://mchehab.fedorapeople.org/media-kabi-docs-test/asciidoc_tests/media_api.html I also added the ascii doc files there, at: https://mchehab.fedorapeople.org/media-kabi-docs-test/asciidoc_tests/ And I'm keeping the git tree, with helps to identify the work that was needed to make it work: https://git.linuxtv.org/mchehab/asciidoc-poc.git In summary, AsciiDoc, formatted via AsciiDoctor worked fine to produce an html file. PROBLEMS ======== 1) I was not able to produce outputs on any other format. For example, when trying to generate docbook45 output, it sems that part of the trouble was due to pandoc conversion. It produces links like: link:#ftn.id-1.4.11.43.5.11.2.7.2.6.2[^[a]^] Which causes errors with DocBook parsers, like xmllint: media_api.xml:32300: parser error : Opening and ending tag mismatch: superscript line 32300 and ulink <ulink url="#id-1.4.11.43.5.11.2.7.2.6.2"><superscript>[a</ulink></superscript>] ^ I suspect that this is fixable. I may try to fix it later. 2) It seems that Asciidoctor doesn't allow annexes per document part. It numberates them as chapters, instead of using A, B, C, ... 3) Even producing the html without troubles, it produces an error: asciidoctor: ERROR: media_api.adoc: line 57: invalid part, must have at least one section (e.g., chapter, appendix, etc.) 4) There are some things that got lost during the conversion, like copyright notes and revision notes. This could be simply a problem with pandoc conversion. Nothing serious, I guess, as we could insert the lost data manually. Yet, it means that, to move from the PoC to the Kernel, there are still lots of work to do. I was unable do discover why, nor to suppress this error message. Yet, from my side, if we're willing to get rid of DocBook, then Asciidoctor seems to be the *only* alternative so far to parse the complex media documents. Regards, Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
