> > I admit that while I like HTML it does look
> > rather clunky next to a polished PDF file. Trouble is, I don't know how
> > to format for PDF. So, what format would you prefer ?
>
> [...]
>
> Doumentation purists will prefer one of the generic formats (TeX,
> docbook, XML-based ?) that can be converted into HTML, print or other
> formats but I don't know as much about them as I ought to :-/
I guess I'm one of those documentation purists :)
I would use LaTeX for anything that has some structure to it, such
as chapters, sections, appendices, figures, etc. There is an initial
learning curve, but it pays off very quickly because you can entirely
focus on content once you've got the hang of it, and leave all the
formatting decisions to LaTeX. LaTeX will also count chapters and
figures and such for you, prepare a table of contents, lists of
figures and tables, etc. It'll manage your bibliography as well.
The finished product will have a professionally typeset look, and
you can export it to ps, pdf, html, etc.
Another advantage is that it's easy to change formats. For instance,
if you're writing a book but don't have a publisher yet, then you can
typeset your book in a generic book style. When you find a publisher,
chances are that they've got their own LaTeX style for books that'll
yield their specific look and feel. Ideally, you could then switch
from the generic style to the publisher's style just by changing the
very first line of your document.
If you feel that LaTeX may be the right tool for you, I'd be more
than happy to tell you more about it. Also, if you're reluctant to
tackle LaTeX in its pure form (which may look rather daunting), you
can use a LaTeX front end called LyX that sort of resembles familiar
word processors.
As for pictures, I agree that xfig is a decent tool for the job
you described. If you end up choosing LaTeX and xfig, then one
added benefit is that you can tell LaTeX to typeset the annotations
of your xfig illustrations in a font that'll fit the rest of the
document. I've automated much of the interplay between LaTeX and
xfig using Unix tools like make and such. Again, if you feel that
this is the way to go, I can tell you more.
Hope this helps,
Peter
