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

[Ville Skyttä]

On Wednesday 15 April 2009, Freddy Vulto wrote:
> On Tue, Apr 14, 2009 at 8:50 PM, Ville Skyttä <ville.skytta at iki.fi> wrote:
> > Yeah... why not :).  Anyone want to write a style guide?  Here's a start
> > for a table of contents, in no particular order:
>
> I'm in the process of writing documentation for the test suite and I'd
> like to propose using asciidoc: http://www.methods.co.nz/asciidoc/ for
> all bash completion documentation.

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 (beginpage? , prefaceinfo? , (title, subtitle? , 
titleabbrev?) , (toc | lot | index | glossary | bibliography)* , tocchap? , 
(((calloutlist | glosslist | bibliolist | itemizedlist | orderedlist | 
segmentedlist | simplelist | variablelist | caution | important | note | tip | 
warning | literallayout | programlisting | programlistingco | screen | 
screenco | screenshot | synopsis | cmdsynopsis | funcsynopsis | classsynopsis 
| fieldsynopsis | constructorsynopsis | destructorsynopsis | methodsynopsis | 
formalpara | para | simpara | address | blockquote | graphic | graphicco | 
mediaobject | mediaobjectco | informalequation | informalexample | 
informalfigure | informaltable | equation | example | figure | table | msgset 
| procedure | sidebar | qandaset| task | anchor | bridgehead | remark | 
highlights | abstract | authorblurb | epigraph | indexterm | beginpage)+ , 
(sect1* | refentry* | simplesect* | section*)) | sect1+ | refentry+ | 
simplesect+ | section+) , (toc | lot | index | glossary | bibliography)*), got 
(title )
</preface>
          ^
./main.xml:23: element part: validity error : Element part content does not 
follow the DTD, expecting (beginpage? , partinfo? , (title , subtitle? , 
titleabbrev?) , partintro? , (appendix | chapter | toc | lot | index | 
glossary | bibliography | article | preface | refentry | reference)+), got 
(title simpara simpara )
</part>
       ^
a2x: failed: xmllint --nonet --noout --valid "./main.xml"