On Sat, Jul 02, 2005 at 10:17:01AM -0600, John Williams wrote:
: There is something to be said for actually _organizing_ the documentation
: too, which is why POD docs for a function are not always next to the
: function itself.

I always cringe when I hear "the documentation", as if it's only one thing.

: That said, I hope the documentation trait on subs can optionally be a
: pointer to the (section of the POD) document where the documentation
: actually resides.

We'll certainly make that possible, though going that direction is
a little problematic insofar as it's pretty easy for the document to
link to a function that already has a name that is unlikely to change,
whereas it's difficult for a function to point into a document where
the section numbers are changing, unless you come up with some kind of
naming scheme for document sections, which by and large comes out to
naming the sections with the same long name as the routines.

If you store the doc info with the function, then you also have the
ability to massage it different ways and autogenerate sections of
your docs without having to have an explicit doc specifying the order
of every entry.  Of course, from the document-centric point of view
these are just slicing operations, which can be based on either rules
or enumerations.  But if we want to slice by rule, the functions have
to have at least enough associated metadata to specify the slicing

But going back to the "must have the same name" idea, names are just
keys into something, so this kinda smells to me like parallel hashes
that ought to be normalized into a single relation containing both
kinds of information.  Something like Literate Programming, but LP
isn't quite the right answer to the multiple viewpoints problem here.
There's some kind of a <em> vs <i> problem going on here, so maybe
rather than thinking of "the document" we should be thinking of
"stylesheets" that can take the raw information naturally associated
with the functions and massage it into the view currently desired.
I suspect the basic underlying problem with LP is that it assumes
the document is more rational than the program.  Looking at it
linguistically, I think the more useful appoach is to consider the
program itself to be the most accurate "text".  But because of the
limitations of human reason we need to take different slices of the
program in order to comprehend it in various dimensions while hiding
other dimensions.  Call it "Illiterate Programming" if you will,
but I expect that's why javadocs are more popular than tangle/weave.
Large programs are hyperrational objects, and we need multiple
viewpoints to understand such things.

So thanks for prodding me into figuring out what bothers me about LP.
When you say "the document" you're being modern rather than postmodern.  :-)


Reply via email to