On Fri, Apr 17, 2009 at 9:52 PM, Ville Skyttä <ville.sky...@iki.fi> wrote: > This is my first experience with asciidoc (tried 8.4.3), and I > must say I'm not too impressed. Does this mean one needs to know > the DocBook DTD and be able to write the docs in a > asciidoc/plaintext format that kind of conforms to the DTD, > instead of asciidoc just taking care of that stuff? If so, > doesn't sound too interesting. > > $ ./makeHtml.sh > ./main.xml:18: element preface: validity error : Element preface > content does not follow the DTD, expecting (...), got (title) > ... > a2x: failed: xmllint --nonet --noout --valid "./main.xml"
Installing asciidoc-8.4.3 (was asciidoc-8.2.6) gave me the same problem. I fixed it by adding a `Preface' section to main.txt. This is what AsciiDoc has to say about this gotcha: (from http://www.methods.co.nz/asciidoc/userguide.html#_gotchas): Invalid output AsciiDoc attempts to validate the input AsciiDoc source but makes no attempt to validate the output markup, it leaves that to external tools such as xmllint(1) (integrated into a2x(1)). Backend validation cannot be hardcoded into AsciiDoc because backends are dynamically configured. The following example generates valid HTML but invalid DocBook (the DocBook literal element cannot contain an emphasis element): +monospaced text with an _emphasized_ word+ It is possible to omit the DocBook DTD validation by adding `-L' or `--no-xmllint' to `a2x', but I think adhering to the DocBook DTD is the way to go. Another solution would be to let AsciiDoc generate HTML without using DocBook (from http://www.methods.co.nz/asciidoc/userguide.html#_html_generation): HTML generation AsciiDoc produces nicely styled HTML directly without requiring a DocBook toolchain but there are also advantages in going the DocBook route: - HTML from DocBook includes automatically generated indexes, tables of contents, footnotes, lists of figures and tables. - DocBook toolchains can also (optionally) generate separate (chunked) linked HTML pages for each document section. - Toolchain processing performs link and document validity checks. - If the DocBook lang attribute is set then things like table of contents, revision history, figure and table captions and admonition captions will be output in the specified language (setting the AsciiDoc lang attribute sets the DocBook lang attribute). On the other hand, HTML output directly from AsciiDoc is much faster, is easily customized and can be used in situations where there is no suitable DocBook toolchain (see the AsciiDoc website for example). This can be done with: $ asciidoc -d book main.txt Or just generating a particular section, e.g.: $ asciidoc -d book styleguide.txt Hope this helps in gaining confidence using AsiiDoc. Greetings, Freddy Vulto _______________________________________________ Bash-completion-devel mailing list Bash-completion-devel@lists.alioth.debian.org http://lists.alioth.debian.org/mailman/listinfo/bash-completion-devel