[Bash-completion-devel] Style guide (was: Re: [SCM] bash-completion branch, master, updated. 95cd673b5cbd5658cbf56a56a4113722aab92177)
fvulto at gmail.com
Mon Apr 20 08:09:46 UTC 2009
On Fri, Apr 17, 2009 at 9:52 PM, Ville Skyttä <ville.skytta at 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
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
AsciiDoc produces nicely styled HTML directly without requiring
a DocBook toolchain but there are also advantages in going the
- 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
- 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
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
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.
More information about the Bash-completion-devel