Format for documentation?

[Martin G. <gim...@gi...>]

Hi everybody!

Although I'm in the middle of my exams (Probability Theory tomorrow!),
I've been thinking about how we can write some documentation for PHP
Weather. I've tried all sorts of formats, and I'm currently thinking
about using Texinfo.

These are the formats I've played with:

  LaTeX: I've written some documentation in LaTeX, it's currently in
    CVS. LaTeX is very good at producing printable documentation in PS
    and PDF formats.

    The problem with LaTeX is, that it's difficult to convert to HTML,
    and I think that it would be best if we could produce some HTML
    pages to put up at phpweather.net.

  Texinfo: this is the format used by the GNU-people. It's possible to
    generate documentation in several formats: HTML, PDF, PS, Info,
    Docbook and plain text. All those formats look very nice - have a
    look for yourself: I've written some test-documentation here:

      http://gimpster.com/temp/phpweather-doc/=20=20=20=20

  Docbook: With all the buzz about SGML and XML, I thought that
    Docbook would be the thing to use... I've tried it, but I don't
    particularly like it. The good thing about Docbook is, that it's
    designed for this task: there's tags for filenames, code examples
    and so on.

    But Docbook is a very verbose markup language because all tags has
    to be closed, and because the tag-names are long: they use <para>
    instead of just <p>. Can this be changed?

    Docbook can be converted to HTML which looks good. It can also be
    converted into PDF and PS which looks very bad. I don't know why,
    but the Docbook source is converted into a strange mess which can
    only be processed by jadetex. Why not just convert it into good-
    looking LaTeX-code?

  HTML/PHP: We could also just write the documentation in HTML and
    save us the trouble of converting from another language.

    This also means that we could embed PHP code in the documentation,
    so that we could refer to live examples of what PHP Weather can
    do. We might be able to do this with Texinfo also, but it'll
    involve hacking the Perl texi2html script.


So, what do you guys think? Which formats do you know and which
formats do you like?


=2D-=20
Martin Geisler                       My GnuPG Key: 0xF7F6B57B

See my homepage at http://www.gimpster.com/ for:
PHP Weather =3D> Shows the current weather on your webpage.
PHP Shell   =3D> A telnet-connection (almost :-) in a PHP page.