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