Documentation

Providing high quality documentation for end users and especially for developers is absolutely vital to this project. The main source of documentation will be this website, but a hand-written manual and an automatically generated API reference will be distributed with the source package as well (like most free software projects out there already do).

Spending a little time finding out which documentation tools to use has not proven to be unuseful. There's really not much to say about such choice: after doing some experimentation with different manual documentation systems (LaTeX, DocBook, GNU Texinfo), the last seemed to be the easiest to use and to integrate in a build system (especially using Autoconf and Automake) and the most likely to be found in free software systems. Despite the differences on how they work interally, all are capable to create very high quality output in the most relevant formats and sometimes source files can be converted from one's format to another's (not perfectly though), so the choice was relatively easy.

For automatically generated documentation, instead, Doxygen seems to be a lot ahead of its counterparts and, thanks to the Doxample example package by Oren Ben-Kiki which contains usable Autoconf and Automake scripts for building documentation using Doxygen, integration with the build system is a trivial task.