Please don't take this as a "You're stupid" post, cause it's not. I am genuinely curious as to what issues you're running into. Are they:

• A conceptual issue with what a module is?
• A problem with the OO side (which is usually a problem with references)?
• A problem with the language itself? (You can't learn calculus without knowing algebra cold...)

The other reason I'm asking is that maybe you don't have to go out and spend $$ on those books when you could just get your answer here. I like to think that people here are relatively smart ... :)

I sincerely appreciate your optimism on posting my questions to the monastery members, however I'm finding myself scratching my head with modules a bit too often. The problem isnt really "what modules are" and I don't think that its with the language itself. Some modules have what I consider very good doc that I run with, but others just leave me asking "I know what this is supposed to do, but how do I get it into my code?". Once I see an example that another monk fires over to me, I get a clearer picture, and it seems like one that I myself couldnt have drawn using just the cpan docs.

humbly -c

Yes, the documentation for File::Find would be improved a great deal if it were to actually mention (or even, *gasp*, explain) the basic concept of what the module does. ;)

It never says, for example:

For each directory you specify, File::Find calls a function that you provide (&wanted) for each file and directory found in that directory, every subdirectory, every subsubdirectory, etc., allowing you to "do something" for each file/directory within an entire directory tree. To use File::Find, you have to write a function that, each time it gets called, will decide what should be done with a specific file [for example, based on whether it is an ordinary file (-f $_) or if the file name matches some pattern (/\.html?$/i)] and then perform those operation(s). [...]

It mearly says that "it traverses a directory tree" and that you pass it a "wanted" function and talks about various details. It never actually says that "wanted" is called once for each file, much less explain the concept.

This is rather sad as File::Find is part of the base distribution. Many modules don't enjoy this level of attention and so are often just the ramblings of a lone hacker trying to offer something useful to the community. The lone hacker may not have great language skills (especially in English which might be "a second language") or have other reasons why the documentation doesn't really shine.

So modules are a very mixed bag. If you find one that has documentation that gives you a hard time, the best thing that you can do is to get the documentation updated. The most important step in that process is finding someone motivated enough to actually produce and submit a patch to the module maintainer and then follow-up if needed. I suggest you look to yourself for that.

Then you need to get someone to write some decent documentation. Perhaps just asking about the module here and requesting specific suggestions for documentation updates could get you the raw material for producing a patch.

        - tye (but my friends call me "Tye")

Learning to read Perl documentation, in its many forms, is as important as learning the language itself. Patience. You are not the first to struggle with this.

It's true that few CPAN modules come with their own separate tutorials, but you can usually get clues from the include POD documentation. In most cases, the sample code in the SYNOPSIS portion actually works by itself, or would work inside a trivial program.

There are a few problems that I've seen with people using my CPAN modules. One is that they don't read the documentation in detail. A characteristic of much CPAN module documentation is that it doesn't repeat itself. The answer is probably in there, once, but you may have to look carefully. This is a different tack than most books take; it's typical in books to see the same information presented multiple times in different contexts. Not so in most CPAN modules. Another information source is example programs that might be included with the module. Also look at the test programs; these at least work.

To make your life easier with OO modules, also make sure you understand references and Perl's object model. As has been suggested, read and understand perlmod, perlmodlib, perltoot, and perlbot. Not that you have to understand these to use modules; it's just that you'll have an easier time with them if you do.

• perlboot
• perltoot
• perltootc

Especially the first (Beginners OO tutorial) which I found useful when starting out. They might help you make more of an informed book purchase, if one is then required??

You could try looking here and choose the second link for some good info about File::Find. (note, that's a regular perlmonks search with a '_' afterward, so you get all matches, not just the default File::Find doc page. Or, a Super Search works as well.)

___
-DA
> perl -MPOSIX -le '$ENV{TZ}="EST";print ctime(1000000000)'
Sat Sep  8 20:46:40 2001
[download]