David Landgren wrote:
Hey! It's been over two months since we last had one of these suggestions!
I did battle with a module that shall remain nameless the other day. I
had a difficult time figuring out how to use it. In times like these, I
like being about to go to the build directory and p(aw|ore) through the
eg/ directory and take a script and bend it into a suitable shape.
The package in question didn't have an eg/ directory, so I had to spend
far more time studying the source and running it through the debugger
than I really cared to.
For instance, I know that when I have something tricky to do with
HTML::Parser, I know there's always going to be something close to what
I need to do in the eg/ directory. I think its a good adjunct to POD,
which tends to be more (or should be) more theoretical.
/eg scripts are a nice "hands-on" way of finding out how a module works
in real life.
No distribution should be without one!
I have a shitload of distributions, mostly small components.
For all those component distributions I consider it a failure if it is
so complex that you need something more than just three or four lines
from the SYNOPSIS.
How about we penalise anything with a eg/example directory, for not
having clear enough documentation, or a clean enough design/API. :)
There's a lot of reasons for not having an eg/ directory, unless your
distribution is huge and complicated, like say bioperl.
Adam K
