Re: [tlug] Docbook XML for documenting database tables

[Josh Glover <jmglov@example.com>]

On 20/01/06, Stephen J. Turnbull <stephen@example.com> wrote:

> Into "M" are you?  *ML is for machines, Docbook included.

Right, but if I write my documentation in XML, I can generate
plaintext from it, as well.

I use LaTeX for the same reason: it is not exactly human-readable, but
it is well-formatted, so I can generate PDF, HTML, (probably) XML,
etc. from it.

> Of course you can.  But you can do all that with reST, ASCIItext, and
> pod, too....

This may be strange to hear, coming from a Perl hacker, but I hate
POD. IMO, one should use one system for all documentation, so I prefer
NaturalDocs[1], which supports Perl, C[++], Python, Javascript, XML,
etc.

POD is a little too "do what I mean"-y for me. I like "do what I say",
and XML gives me that control.

> IIRC, ASCIItext comes with a Docbook generator, which
> then gets processed to manpages by xmlto.  That's the sane way to do
> things, for most people.

This *may* be worth my while to look into, but see my above comment on
POD and "do-what-I-mean".

> Don't get me wrong.  Docbook (and XML in general) is a GoodThang[tm].
> But it's one of those things that you should seriously think about
> paying somebody (or downloading a program ;-) to create for you,
> rather than dealing with it yourself.  Postpone learning about it
> until you need to do something you can't beg, buy, or steal.

I disagree. I think the sooner I learn from it, the sooner I can
benefit from what it does. I want The One True Documentation System,
or rather, one that can convert docs into any format.

-Josh