Hi,
I don't like latex. At all. I tried to like it, I really did. I just
can't do it.
So, I'd like to suggest we move our documentation to something else.
I've been having a play with docbook, and I quite like it. Here's what I
think are it's advantages over latex:
- Tool support
Because docbook is an xml based markup language, I can point intellij at
the (well documented) schema and then get all kinds of goodness, such as
code completion, error checking, syntax highlighting, refactors, etc.
For example, Intellij understands the code includes, so I can jump back
and forth between the doc files and the samples.
- 100% Java toolchain
There are a bunch of tools for converting docbook to other formats. The
one I've been playing with is 100% Java.
To convert docbook to (x)html, you run the source documents through
xalan with some stylesheets provided by the docbook project. To convert
docbook to pdf, you do the above (with a different stylesheet) to
produce XML-FO output, then run that through apache FOP.
Because these tools are 100% java, and relatively small (certainly
compared to the 600meg texlive distro needed for the mac), they could be
checked in to subversion. This means that there would be no setup effort
for a developer to build (and contribute to) the documentation: just
checkout and gradle userguide. Setting up the latex tools is complex and
confusing and fragile.
Having the tools in svn would also mean that the CI builds could
generate the documentation (and test the generation of the documentation
on multiple platforms).
Having docbook integration might also be an interesting option for
report/website generation too.
- Familiar technologies
I think xml + xslt are technologies more familiar to java developers and
the pool of potential Gradle contributors, than latex is. This lowers
the barrier for contributing to the documentation.
- Better documented
Latex has heaps of documentation, and most of it is not very detailed.
Docbook has some fine and detailed documentation. There's the definitive
guide:
http://docbook.org/tdg/en/html/docbook.html
and the user guide for the stylesheets:
http://www.sagehill.net/docbookxsl/index.html
- Better looking output
The pdf that latex produces looks dated (and not in a funky retro kind
of way, just kind of tired and old). I think the docbook generated
output looks better.
- More options for customisation
Because docbook is an xml based markup, we have more options for
transformation and customisation. The docbook stylesheets have
(apparently) been designed to be easily extended to change the generated
markup. The HTML markup that they generate is semantically cleaner than
that produced by tex4ht, and so is easier to style.
More importantly, the documentation describes how to do the
customisations, which cannot be said for the atrocious tex4ht documentation.
I could keep going, but you get the idea.
Thoughts?
Adam
---------------------------------------------------------------------
To unsubscribe from this list, please visit:
http://xircles.codehaus.org/manage_email
