
Yesterday I did what Free Software authors supposedly don t do. I wrote documentation. In fact, I had a relatively detailed README already, but I thought this would be a good opportunity to create a more elaborate documentation, using the ubiquitous DocBook. You can read the
HTML documentation for arbtt online, where it s automatically updated when I push to the
darcs repository. You can see, I use the same CSS file that most Haskell-related DocBook documentation seems to use.One motivation to use
DocBook was that I can extract manpages from it, which should be present if I package arbtt for Debian. I was about to complain that references from the manpages to other part of the documentation can not work sensibly, but using the
profiling feature of docbook-xsl, I can replace them by a textual reference to the user s manual if the file is processed for manpage output. Have a look at
my changes for that if you want to know how it works.For some reason, the <refentry>-tags that make up the manpages are split to separate files when generating chunked HTML output, but they do not appear in the table of contents. You have to find a spot in the text where they are linked, as they are now in the section
Program references , to find them. This is unfortunate, I expect that a few readers might miss this important part of the documentation. Am I doing something wrong?For the configuration file, I put an
EBNF-style grammar description in the documentation. There is a special
DocBook module for that, but I m not satisfied with it. On the right hand side of production rules, it has only special support for nonterminals, but no tags to semantically mark up choice, repetition etc. I followed the lead found at the
YAML specification and put <quote>-Tags around literal parts of the grammar, but this is not valid according to the DocBook DTD. Speaking of the DTD: I guess since the EBNF-stuff is just a module, the tag <productionset> is not a valid content of <figure>. So, if I choose to use the EBNF module in a sensible way, I will not have a valid DocBook file.All in all, I am satisified with the result. Especially that nobody can say any more I like your program, but I can t contribute, because I don t know Haskell . Just improve the docs! :-)