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
