Decide upon unified documentation system

[drlight-code]

We want some unified documentation system which preferrably:

• allows generating different output formats (HTML, PDF, info, ...?) from single source
• has an easily accessible (markdown) syntax

Possible choices:

• doxygen
• texinfo
• asciidoc
• txt2tags
• docutils / reStructuredText

[drlight-code]

Having looked at the different systems a bit, I think asciidoc and docutils/reST would be the most reasonable candidates since they provide a straightforward markdown style syntax. Some examples and the available output formats:

reST: HTML, HTML5, S5, LaTeX, XML(Docutils), OpenOffice ODF/.odt

Section Header
==============

Subsection Header
-----------------

- A bullet list item
- Second item

  - A sub item

- Spacing between items creates separate lists

- Third item

1) An enumerated list item

2) Second item

   a) Sub item that goes on at length and thus needs
      to be wrapped. Note the indentation that must
      match the beginning of the text, not the 
      enumerator.

      i) List items can even include

         paragraph breaks.

3) Third item

A sentence with links to Wikipedia_ and the `Linux kernel archive`_.

.. _Wikipedia: http://www.wikipedia.org/
.. _Linux kernel archive: http://www.kernel.org/

asciidoc: HTML, XHTML, EPUB, PDF, DVI, PostScript, roff, man pages, Web help, HTML Help, additional user output formats

example: http://asciidoc.org/book.txt

To me, asciidoc looks a bit more mature and supported, is a bit more expressive but also less straight-forward to write. Docbook/RST is described in its documentation as still a bit experimental but seems to get adopted by many platforms right now such as Trac and GitHub. I think either one would do the job, but I would, for now, try asciidoc first, since there seems to be more widespread tool support and more backends/generators, also I subjectively feel it's better suited for a larger, structured document such as a user guide with different chapters and such. I have no experience with either of them, so this is more of a gut feeling. Any comments, experiences?

[game-stop]

Yes, my preference goes to asciidoc as well. Lets just go with it, put some documentation into this format and see how it feels after we have worked with it for a while

[d-j-a-y]

example and AsciiDoc cheatsheet : http://powerman.name/doc/asciidoc

[game-stop]

Close, continue under #76