in reply to Literate Programming?

hm... *grumble grumble grumble* pod is an amazing tool for giving excellent "birds eye view" documentation, however I am going to state my rather (probably) unpopular opinion, that it is woefully underqualified to do code documentation and reference documentation (which I belive javadoc has as a forte.) I think this stems from the very different backgrounds that perl and java have, in the "standard" perl problem, the solution is small enough that one person can understand it, and someone else can learn it with little effort (as long as they are a qualified perl programmer.) Java never had that idea, i have worked on java projects with well over 1000 class files where no one person understood well the entire project, and very few people even understood where there part of the machine fit. When you are having to write documentation for such an enviroment, a more low level API-ish documentation (such as javadoc) is the logical progression.

As perl grows and expands and begins to be used in large scale software development, this is going to become more and more of an issue. (Before I get flamed, by large scale development i mean projects with a very large function point analysis score, an OO heirarchy with multiple levels of inheritance, and something with a great many interfaces.) It may be that Perl ends up inheriting 2 documentation systems, POD for birds eye view, and (insert_name_here) for API and low level documentation. Does anyone with more experience want to step up to the plate, and give this a more formal treatment?

and in closing... neither one of those are really good examples of literate programming... read the knuth book, you'll see what I mean :)

Replies are listed 'Best First'.
RE: Re: Literate Programming?
by davorg (Chancellor) on Jun 23, 2000 at 19:22 UTC
[reply]
      realistically, because there is very little i could add :) my field of experience is not this, this just happens to be one of those "little things" that i happen to know a bit about. I would be completely out of my space if I tried to aid in the design of a more advances series of tools for documentation development... oh well, que sera sera ;) what i need to do is clone about 5-10 copies of myself and have them study all of the facets of computer science that interest me, so that i can be of more use to the world :)
[reply]
        As a perl user, of course your input is valuable. Just because you don't feel qualified to actually design new features yourself, shouldn't mean you are not qualified to know what features would be usefull to you. Isn't that what the open nature of the perl community is all about? 
        Paris Sinclair    |    4a75737420416e6f74686572
pariss@efn.org    |    205065726c204861636b6572
I wear my Geek Code on my finger.
[reply]

In Section Seekers of Perl Wisdom