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

One thing that's frustrating to people new to open source stuff is that the documentation is more often than not way too focused on "Look what my wonderful application does" and not "By the way, here's how you use it."

That being said, for months now I've been trying to get various perl doc tools to work. I've tried OODoc, ePod, docgen, pdoc, and Doxygen with a few opensource filters.

Today I tried pdoc. The documentation is basically "It's great. Type make, then make install, then make test!".

That's it for the readme. Here is the post on here about it. Certainly sounds lovely doesn't it? Well apparently it's not meant to be used by newbies, because nobody ever seems to bother to say "Here is how you actually execute my wonderful program". I'm sure it's common knowledge to most of you, but for those of us just starting out, I don't understand how we're supposed to figure this out without at least someone, somewhere saying "Hey, this is how you do it, and it will apply going forward".

Anyhow, sorry for the vent, but if anyone can tell me how to use, for example, pdoc with my scripts, I'll fedex you a puppy. I've got it installed. I have a script in a folder that I want to generate POD from. Where from here?

Thanks. ;)

Replies are listed 'Best First'.
Re: Perl Documentation, again. :(
by hardburn (Abbot) on Mar 23, 2005 at 15:49 UTC

    The 'perldoc' binary has to know where to look for your script (somewhat like the path to find modules). The filters (like pod2text and pod2html) can work on it by filename directly:

    $ pod2text file.pl | less

    [download]

    Perldoc can work on installed modules:

    perldoc HTML::Template

    [download]

    Or on specific perl documentation:

    perldoc perlref

    [download]

    Or, using the -f switch, on a builtin function:

    perldoc -f print

    [download]

    "There is no shame in being self-taught, only in not trying to learn in the first place." -- Atrus, Myst: The Book of D'ni.

[reply]
[d/l]
[select]
Re: Perl Documentation, again. :(
by Joost (Canon) on Mar 23, 2005 at 17:24 UTC
[reply]
Re: Perl Documentation, again. :(
by jdporter (Paladin) on Mar 23, 2005 at 17:06 UTC
    I've never used pdoc (in fact, I'd never heard of it before your post — sorry, PodMaster) but looking around on the pdoc website, there seems to be some relevant info on the scripts page. The main program you run to use pdoc seems to be perlmod2www.pl, which "transforms a Perl library directory tree to an HTML tree." Run it with just the -h switch to get a usage overview.
[reply]
[d/l]
[select]
Re: Perl Documentation, again. :(
by duct_tape (Hermit) on Mar 23, 2005 at 16:50 UTC

    I know that this doesn't answer your question, but maybe you could give a look at http://www.naturaldocs.org/. It has support for perl, and is somewhat similar in concept to doxygen. Put some extra comments in your code, run the tool against it and it generates your documentation. I successfully got it to work on one of my recent projects without much work. The documentation for it is pretty good.

[reply]

      One thing I don't like about NaturalDocs is that if you want to use POD and ND, you need to write your documentation twice -- or at least I have not found a way to have both available with a single set of source. That is not to say that ND is not a very good system. I am quite happy with most of what it does.

      I would be more than happy to see this response proven wrong :)

      --MidLifeXis

[reply]

        Yah, I agree with that. For the last project that I used ND on I decided to only use ND and not both it and POD. It would definately be cool to have a POD output format for ND. If you ever find anything out, let me know :)

[reply]
Re: Perl Documentation, again. :(
by PodMaster (Abbot) on Mar 24, 2005 at 04:50 UTC
    Today I tried pdoc. The documentation is basically "It's great. Type make, then make install, then make test!".

    That's it for the readme. ...Certainly sounds lovely doesn't it?...

    What readme? The module doesn't come with a readme. Yes on the download page the standard Makefile.PL instructions are given, but if you've gotten that far, why didn't you look through the rest of the website?

    You should contact the author and ask him to add a readme to the distribution (the tarball).

    MJD says "you can't just make shit up and expect the computer to know what you mean, retardo!"
    I run a Win32 PPM repository for perl 5.6.x and 5.8.x -- I take requests (README).
    ** The third rule of perl club is a statement of fact: pod is sexy.

[reply]
      Pardon, the makefile instructions.

      And (as you've so delicately told me ;) ) I did RTFM on the rest of the website. Their documentation page is down, and the downloadable docs are an abysmal selection of informational tidbits generated by their own software.

      I can't beleive this is this difficult. :\
[reply]

Back to Seekers of Perl Wisdom