On Oct 27, 2008, at 10:36 PM, Adam Murdoch wrote:
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.
I'm using Textmate for editing LaTeX, which is OK. But I see the
advantages you are pointing out.
- 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.
This would be a big plus.
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).
Another big plus.
Having docbook integration might also be an interesting option for
report/website generation too.
I don't feel pain with the current way we generate the website. But
if it grows more complex things might change.
- 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.
One unique selling point of LaTeX is that it is a true type setting
system. It calculates the position for every letter it writes, based
on algorithms containing many of the rules of the typesetting craft.
You can publish a book with LaTeX. I doubt that the apache FO can
compete here. This is the reason why most of the modern mark up
languages have a transform to LaTeX code. But there is a docbook to
latex converter (as well as latex to docbook converter).
- 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.
If it weren't for you, we would still have the crappy html user's
guide, because it was not obvious to me how to configure tex4ht. So I
see your point ;)
Thoughts?
I'm not wedded to LaTeX. For me it was an obvious choice as I knew it
and it did the job (except easy html transformation). But your points
are very valid.
The question is which alternative to choose. I'm not an expert here
at all. One thing I have come across lately is, that the Python guys
have switched from LaTeX recently to Sphinx (they still use a LaTeX
transform to produce the PDF). See: http://sphinx.pocoo.org/. But is
has the disadvantage of not having a Java tool chain (unless it works
with Jython).
- Hans
--
Hans Dockter
Gradle Project lead
http://www.gradle.org
---------------------------------------------------------------------
To unsubscribe from this list, please visit:
http://xircles.codehaus.org/manage_email
