Melvin has asked for the wisdom of the Perl Monks concerning the following question:

I was wandering around, meditating on documentation, when I came across this article on perl.com about literate programming.

I'm looking for a program similar to javadoc, but for perl. I'd like to know what other monks use out there for documentation purposes, that is, weaving documentation codes into perl sources, and then cutting them out with a parser and prettying them up in html, ps or what have you.

I really really like javadoc, which would probably be very easy to write up, especially with perl's superdooper text manipulation tools, but I'm sure there are better alternatives out there already written up. tex?

Replies are listed 'Best First'.
RE: Literate Programming?
by vroom (His Eminence) on Jun 23, 2000 at 18:39 UTC
    Check out perlpod this is a format commonly used for documenting Perl code and there are a slew of Pod2XXX modules on CPAN pod

    vroom | Tim Vroom | vroom@cs.hope.edu
[reply]
Re: Literate Programming?
by eduardo (Curate) on Jun 23, 2000 at 19:06 UTC
    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 :)

[reply]
[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]
Re: Literate Programming?
by davorg (Chancellor) on Jun 23, 2000 at 18:48 UTC

    POD (Plain Old Documentation) is great for writing documentation inside your code. Perl comes with pod2html. pod2man and pod2text for processing it and there are a number of other translators available.

    If you're interested in using Literate Programming with Perl, there's a good chapter on it in Andrew Johnson's book Elements of Programming with Perl

    --
    <http://www.dave.org.uk>

    European Perl Conference - Sept 22/24 2000
    <http://www.yapc.org/Europe/>
[reply]
Re: Literate Programming?
by Melvin (Beadle) on Jun 23, 2000 at 18:44 UTC
    I guess I'm looking for something a little more indepth than perlpod, but then again, maybe the bare framework is all that I need.

    What I like about javadoc is the ability to spell out the documentation of each variable, each function (return values, description etc), each class, and have a very nicely formatted set of html pages, that provided links to the various declarations, snippits etc.

    Maybe I'm missing something, but perldoc doesn't seem to have the features that something like javadoc does. (Please let me know if I'm wrong.)

[reply]

Back to Seekers of Perl Wisdom