prodevel has asked for the wisdom of the Perl Monks concerning the following question:
Humbly asking newer monks if there is module documentation
beyond included, especially published material.
Syntax docs and any reference/abbreviated docs are, of
course appreciated.
It seems there are so many that would support my current situations
and my approach has always been to immerse.
Accolades to all Perl Gods, as they work hard and still grin.
Re: Many many modules
by davorg (Chancellor) on Jul 26, 2000 at 13:17 UTC
|
Generally the docs that come with a specific module are the best place to get info about the module. A couple of the most useful modules (CGI and DBI) have books dedicated to them.
Perhaps you're looking for help at a higher level tho'? Documentation about which modules are available and what they are for. It's sometimes difficult to answer questions like "Which modules would be useful for this project?" Often the best solution to this is to go to search.cpan.org and just search for likely looking names.
A few years ago, O'Reilly released the Perl Resource Kit which was a number of new Perl books together with a CD containing a snapshot of CPAN (among other things). This included a 2 volume printed copy of various CPAN modules' documentation. Another, far more useful, book in the set was called "Programming With Perl Modules" and it was an introduction to which modules could be used for various tasks. The PRK itself didn't sell particularly well, but I've often thought that the "Programming With Perl modules" book would sell well if sold separately.
--
<http://www.dave.org.uk>
European Perl Conference - Sept 22/24 2000, ICA, London
<http://www.yapc.org/Europe/>
| [reply] |
RE: Many many modules
by Corion (Patriarch) on Jul 26, 2000 at 13:02 UTC
|
Your question is somewhat unclear to me.
I assume that you are looking for documentation for the
Perl modules you get from CPAN or somewhere else.
Perl modules normally include their documentation right
in the source code in the POD (Plain Old
Documentation) format, and different outputs
are generated when you install the module. Under UNIX,
perldoc modulename will show you the documentation
and with ActiveState Perl under Windows, the documentation
will be included with the HTML documentation for ActiveState
Perl itself.
If you look for documentation beyond what's included and
/ or automatically generated, there are not many possibilities.
Some of the Books about Perl discuss several important modules
like CGI.pm, at other times, the module author
might be of assistance, but in general, Perl modules lack
good documentation, as it is the case with most open source
stuff. Of course, the Open Source Apology for not providing
documentation also holds here, you can still look at the module
source code to figure out how it works :).
A special case is the Image::Magick module, where
the documentation is not included with the Perl modules
(but only a meagre page telling us it has more bugs than
the imagemagick program suite alone), but the Perl documentation
comes with the ImageMagick program suite itself (for reasons
unknown to me).
Of course, if you have any specific questions or are in search
of examples, a question here will most likely turn up many
useful answers.
| [reply] |
|
...but in general, Perl modules lack good documentation...
I have to disagree, because IMHO, Perl Modules come with a rather good documentation, as you mentioned the perldoc. This is sufficient in most cases, if you just want to use the module. Of course, if you want to write and/or _understand_ a module, you have to look elsewhere.
| [reply] |
|
Hmmm - after desperately searching for a module in the
standard distribution of Perl, I have to admit that I can't come up with an example of bad documentation. I only remember that the documentation for HTML::Parser was really bad, as they documented that one could "use either the version 2 compatible interface" (which was nowhere documented but maybe in the obsolete version of this module that was no more around) or the new (and completely different) version 3 interface, but the documentation completely lacked any example. Maybe that's because the documentation for this module is supposed to be in some book, I don't know.
But nonetheless, I have to admit, Perl module documentation is not bad in general, it was only my
perception of the documentation (you seldom notice good documentation :).
| [reply] |
RE: Many many modules
by BlueLines (Hermit) on Jul 28, 2000 at 01:18 UTC
|
My boss asked me for printed documentation of all of my code, so i wrote this program to generate such docs. You may find this useful for CPAN modules as well...
#!/usr/bin/perl -w
use strict;
my ($module)=@ARGV or die "Usage: $0 <absolute path to module>\n";
open (MODULE, $module) or die "Can't open $module: $!\n";
while (<MODULE>) {
print if /^#/;
}
heh heh heh :-)
BlueLines | [reply] [d/l] |
|
|