Re: [tlug] Docbook XML for documenting database tables

[Josh Glover <jmglov@example.com>]

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

> >>>>> "Josh" == Josh Glover <jmglov@example.com> writes:

>     Josh> IMO, one should use one system for all documentation,
>
> Ah, there's a real philosophical difference.

'Fraid so. :)

I don't like corner cases, so when something like...

>     Josh> prefer NaturalDocs[1],
>
> Was that hanging footnote generated by NaturalDocs?  ;-)

NaturalDocs[1] (work, damnit!) comes along, which groks all of the
programming languages I want to use, and can generate XHTML output,
which can then be transformed by XSLT and XML tools that I Myself
might write, that is a slam-dunk for me.

>     Josh> POD is a little too "do what I mean"-y for me. I like "do
>     Josh> what I say", and XML gives me that control.
>
> Hm.  You may not like ASCIItext and reST, then.  While both have
> precise grammars, the generated stuff is sorta magic and you don't
> have much control in the source.

Right. I hate not having precise control, because that means that my
documentation lacks consistency, which I hate more than almost
anything in this chaotic world! ;)

>     Josh> I disagree. I think the sooner I learn [XML], the sooner I
>     Josh> can benefit from what it does.
>
> Maybe.  My feeling about XML is that the sooner you learn it, the
> sooner the rest of the world will benefit from the enormous effort you
> have to put into writing generator and editor programs to make it do
> anything at all.  :-)

Well, I guess you have a bit of a point there, but I have already put
a non-trivial amount of time into learning how to mess with XML, and I
have a slew of tools at my fingertips to assist me.

> I'll be interested to see what you do with this.  Don't let me
> discourage you---our philosophies are different, and it's not just I'm
> an old fart so I know better.  But if you discover that things aren't
> working out the way you hoped, I encourage you: give up immediately! :-)
> Smarter people than you or I have come to that conclusion.

I think I am just more of a BSD guy at heart than a Linux guy: I like
to [over-]engineer everything, and have it Just So(TM). Of course,
this often means that my working code is a little slower to emerge,
full-formed, from my forehead. :)

Cheers,
Josh

[1] http://naturaldocs.org/ or
http://packages.gentoo.org/search/?sstring=naturaldocs&sourceid=mozilla-search