Documentation format for dak

[Ansgar Burchardt <ansgar@debian.org>]

Hi,

I'm considering writing some documentation for dak, starting with the
dak-command files.  As we have only have API documentation so far I am
wondering what a good format would be.

The format should support output to HTML and man and support translations.

DocBook:
  Already used for policy, devref.
  Output formats: HTML, man and others.
  Can be translated (po4a).
  SGML :-/

AsciiDoc:
  Used by Git.
  Output formats: HTML, DocBook, man and others.
  Can be translated (po4a).

Org-mode:
  Emacs.
  Output formats: HTML, LaTeX, man and others.
    Not sure about man, but it was said it's possible on IRC.
  Not sure about translation support.

sphinx / rst:
  Used for API documentation in many Python projects.
  Output formats: HTML, LaTeX, man, plain text.
  Can be translated (gettext) [1].

I do like human-readable formats so suggest going with either AsciiDoc
or Sphinx.  From a quick glance at two random documents[2][3], I find
the AsciiDoc syntax a bit nicer, however using Sphinx might allow us to
use the same format for API and other documentation (should we decide to
switch from epydoc).

Are there any other formats to consider or other things to think of? Do
you already have some experience with any of these formats?

Ansgar

[1] <http://sphinx-doc.org/intl.html#intl>
[2] <http://docutils.sourceforge.net/docs/user/rst/quickstart.txt>
[3] <https://raw.github.com/git/git/master/Documentation/git-config.txt>