> NOTE: I am (was?) a strong believer in markup. I started this
> work because I thought the document doesn't belong in the
> Docu section, and needed updating, without being aware of
> the potential problems with SGML. By the time I was done,
> I was completely horrified by this SGML business. It has
> it's advantages, but they come at a hefty price, so we
> have to be very careful when we employ it. It works OK
> for documents that don't require a lot of markup, like the
> FAQ. In fact, in that case it _saves_ on formating markup.
> It works nicely for documents that are essentially books
> (such as the User Guide, etc.) where you can expect someone
> to print out the nicely formatted .pdf/.ps. However, for
> technical documents that need to be maintained often, and
> are useful as a online resource that people are likely to
> open in an editor, it blows chunks. Now I start to understand
> Alexandre's preference for troff for man pages...
Hehe, I'm glad I'm not the only one who thinks DocBook is overrated -
I've been wrestling with it for the past few weeks as part of writing a
shared packaging metadata spec, and an automatic documentation framework
for bash libraries, and I have NEVER got it to work correctly.
I've found that clean HTML with some small CSS can make a document that
looks more professional (imo) and is far easier to read in a text
editor, not least because emacs (and i assume vim) can apply the
formatting in the tags to the text itself.
I've never looked at troff, but free software seems to need a better
documentation/markup system - DocBook SGML just seems far, far too
complex for doing something that is essentially quite simple.