Quoteing ruby-talk / pcppopper.org, on Sat, Feb 07, 2004 at 08:03:25AM +0900:
> What I would like to see in a good documentation format is:
> 
> * PS/PDF output backends
> * Math support done in an intuitive way
> * Graphics support done in an intuitive way
> * Markup that doesn't chop the input into bits while still allowing you
>   to markup easily and with meaning (such as adding emphasis and so on)
> 
> P.S.
> TeX produces wonderful output, but is crap when it comes to actually
> writing documents with it, I'm sorry to say.  And its graphics packages
> are rather retarded as well.

LaTeX does everything you mention, doesn't it?

What is the problem with how it does graphics? You make a eps picture,
it puts it in the document... its been a while, but I don't remember it
being too much worse than this!

As for markup, I don't really care if I type

  {\em important}
  <em>important</em>
  _important_
  .....

What I don't like about TeX, is if you are doing a large document,
eventally you will decide you want some particular kind of
layout/presentation, and getting TeX to do something different can be
painful, for me anyhow. In a way its good, its so hard I don't even wast
time trying, I just take the default layout, and get on with my work.

Out of curiosity, why don't you think it fits the bill?

I don't have great things to say about writing in docbook, other than emacs makes
it a bunch easier (the only thing I use emacs for... its vim for
everything else). On the other hand, the variety of output formats is
amazing. My last company produced its docs as 1-manual per product, plus
super-manuals for all the products, in html, pdf, QNX html-similar help
files... all from one src base. Doing that with commercial tools would
have cost multiple  thousands of dollars!

Personally, when I just want  to type some text, but I want to make it
to look a little "pretty" (html or pdf, say, so it looks more
professional to marketing folks), I use .pod. Dirt simple, but not what
you want for a large document.

Cheers,
Sam