Perl Documentation, again. :(

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. ;)

Comment on Perl Documentation, again. :(

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

standard

perldoc perldoc should give the docs for perldoc itself. perldoc perl perl should give the document index for perl. perldoc perlpod should give you an indication of how to write your own documentation in pod.

"What should it profit a man, if he should win a flame war, yet lose his cool?"

[reply]

Re: Perl Documentation, again. :(
by jdporter (Paladin) on Mar 23, 2005 at 17:06 UTC

PodMaster

pdoc website

scripts

perlmod2www.pl

-h

[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]

Re^2: Perl Documentation, again. :(

by MidLifeXis (Monsignor) on Mar 24, 2005 at 00:02 UTC

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]

Re^3: Perl Documentation, again. :(

by duct_tape (Hermit) on Mar 24, 2005 at 00:15 UTC

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?...

download page

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]

Re^2: Perl Documentation, again. :(

by Seventh (Beadle) on Mar 28, 2005 at 16:34 UTC

[reply]


Keep It Simple, Stupid
	PerlMonks