[Bash-completion-devel] Style guide (was: Re: [SCM] bash-completion branch, master, updated. 95cd673b5cbd5658cbf56a56a4113722aab92177)

[Freddy Vulto]

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
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