Re: [tlug] Docbook XML for documenting database tables

["Stephen J. Turnbull" <stephen@example.com>]

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

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

What do you do that requires more than reST or pod can do for you?

reST supports the pythondoc (Jim T, is that right, or am I thinking of
something else?) format, so that

papa% python
Python 2.4.2 (#1, Dec 23 2005, 01:55:50) 
[GCC 3.3 20030304 (Apple Computer, Inc. build 1666)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> ['t', 'e', 's', 't'].join()
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
AttributeError: 'list' object has no attribute 'join'
>>> ''.join(['t', 'e', 's', 't'])
'test'
>>> 

is an actual regression test for python, embedded in this email.  (The
test module extracts the >>> lines and executes them, and checks that
the results match.)  reST will format that so it's more readable
(deemphsizing prompts and other junk, giving distinctive style to
input vs. output) in a document.  You can also embed live code in a
document like this::

    # this is a test
    ''.join(['t', 'e', 's', 't'])

and the double colon (did you notice the double colon? :-) will format
it like xhtml <pre>.

====== === =========================
Tables Are Easy
====== === =========================
This   is  a simple, 3-column table.
Don't  you think it's really cool?
====== === =========================

You can embed images, etc, etc.

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

Of course LaTeX is human-readable.  Your problem is that you've
learned to read without moving your lips.  Try reading it out loud,
and ask the mathematician next to you to write it down.  Betcha he has
no problem!

True, the text formatting parts tend to get in the way even when
reading aloud, especially the environments.  But there's just no way
you can beat TeX equation notation, and the declarative style used in
Plain TeX reads quite well even in the text formatting arena.

Really, the TeX family is a special case, and shouldn't be compared to
systematic attempts to come up with either simple or very general
markup languages.

    Josh> IMO, one should use one system for all documentation,

Ah, there's a real philosophical difference.

I just don't think it's possible, not even within the realm of stuff I
use every day.  At the simple documentation end, when I find a wiki
that uses XML for editing pages, that's a whole site that's going into
my local nameserver bound to 127.127.127.127.  At the complex end,
there's no chance that I will ever use a MathML DTD in preference to
LaTeX, but LaTeX is very much unsuited for machine processing,
especially the 'web (as the output of latex2hell proves).

So at the moment I use reST (or XEmacs docstringish) at the wiki-ish
end of my work, texinfo (by historical accident) in the somewhat hairy
middle, and LaTeX for the truly hairy technical stuff I do for a
living.

    Josh> prefer NaturalDocs[1],

Was that hanging footnote generated by NaturalDocs?  ;-)

    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.  Of course you *can* do all that
later with CSS and/or XSLT.  But style sheets are really more about
giving a bunch of related documents a consistent look and feel than
about controlling style in a single document.

    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.  :-)

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.

-- 
School of Systems and Information Engineering http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba                    Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
               Ask not how you can "do" free software business;
              ask what your business can "do for" free software.