Beefy Boxes and Bandwidth Generously Provided by pair Networks
Pathologically Eclectic Rubbish Lister

examples in CPAN distributions

by zby (Vicar)
on Apr 25, 2007 at 09:55 UTC ( #611952=perlquestion: print w/replies, xml ) Need Help??
zby has asked for the wisdom of the Perl Monks concerning the following question:

Dear Monks,

What is the current practice for providing examples in CPAN distributions? I mean things that are more than you can insert into POD - like examples involving many files. Is creating an examples subdir a common practice here? Is it the best one? Not everyone finds it very intuitive.

Update: How about a tool, or an option for CPAN (perl -MCPAN -e 'install_examples Distro::Name') that would install the examples in current directory? So that they could be installed and tweaked many times.

Replies are listed 'Best First'.
Re: examples in CPAN distributions
by jettero (Monsignor) on Apr 25, 2007 at 10:56 UTC

    It's actually pretty common to have an examples/ dir included with the distribution. It's fairly rare for any of the examples to actually install anywhere. LWP comes with a few programs that install in /usr/bin, so you might check there for an example of installing examples...

    For examples of modules that include examples that don't install, look at things like POE, Mail::SPF::Query, Math::BigInt, Digest::SHA, Archive::Zip, Compress::Zlib, et al. (Those are just some of the ones that happened to be in my .cpan/build dir.)

    I think it is indeed the standard practice to include the examples but not install them. I imagine the idea is that if people want the examples then they can perl -MCPAN -e 'get Distro::Name' even if they weren't the ones that actually installed the module.


Re: examples in CPAN distributions
by rinceWind (Monsignor) on Apr 25, 2007 at 11:00 UTC

    For trivial modules, the examples are encompassed by the tests, in t/*.t which is the standard place. For test data, there is no convention.

    For something non-trivial, having example code is a good idea. Again there is no convention that I'm aware of.

    Do you have a preference? If so, please tell us. Expressing it in Perlmonks is a good way to get feedback, and to set conventions and standards in the Perl community.

    wetware hacker
    (Qualified NLP Practitioner and Hypnotherapist)

      The tests of a module provide good clues as to how to use the module, but one has to realise that some of those tests may be there to see how the modules deals with incorrect usages. There may be lots of obscure corner case tests designed to achieve a high level of code coverage.

      Sometimes it can be hard to spot what is essential.

      Real examples are better in that there's none of the test infrastructure, or the test suite's goals, getting in the way. You can take one and then start to bend it into shape to solve your own task. This is my usual approach to HTML::Parser, since I don't use it enough to remember all of the API. Having a usable skeleton is a great way to start hanging lumps of flesh off it :)

      Also, as far as conventions and standards regarding modules goes, if it isn't discussed on the module-authors mailing list, it will become neither. This is not to dismiss Perlmonks, but these things tend to get thrashed out over there. People sometimes don't realise that a lot of the Perl community doesn't hang out on Perlmonks.

      • another intruder with the mooring in the heart of the Perl

        People sometimes don't realise that a lot of the Perl community doesn't hang out on Perlmonks.

        May I take the freedom and point to somewhere else? is a pretty good start too.

        Please don't reply as it was merely intended as a pointer; we would be getting more and more offtopic if we'd do otherwise.

        I don't feel qualified to ask this question on module-authors mailing list - at least for the one reason that I have not read that list bofore. If anyone would ask this question on this list please post the link to the thread in the archives here if that is possible.
Re: examples in CPAN distributions
by Herkum (Parson) on Apr 25, 2007 at 11:40 UTC

    There are a few distributions that create a cookbook CGI::Session::CookBook. This is basically an empty module with lots of package documentation. I am sure that there are other distributions that call it something else.

    So I would say yes it is a relatively common practice to include examples

Re: examples in CPAN distributions
by bart (Canon) on Apr 25, 2007 at 12:04 UTC
      Example though is a bit different from extra docs - it is executable code. When the example is small enough that it can be copy-pasted then you can just put it whole into the docs, but when it is too big or comprises of many files copy-pasting it is much more inconvenient.
Re: examples in CPAN distributions
by naikonta (Curate) on Apr 26, 2007 at 05:31 UTC
    Stuff under examples, eg, or ex directories are, IMO, partially meant for documentation to show how the module is used. Putting real codes (read: runnable examples) along with some description are best to put in the POD, be it in the main package or a package of its own.

    But I assume that the examples are supposed to be runnable so they must be on their on files. If this is the case then it's actually natural to have these files are officially installed somewhere in the path. The problem is, the standard path installation of Perl modules are not like normal programs. For Linux system for example, there's a bunch of places to put different kind of stuff around.

    My suggestion is to specify those examples files as executable files so the module installation process will put those files to the standard place, e.g. /usr/bin. To achieve this you say in the Makefile.PL file:

    WriteMakefile( # other standard pairs EXE_FILES => [qw( examples/file1 examples/file2 examples/fileN )], );
    For other destination of where to install the examples, you may want to tweak the Makefile.PL based on ExtUtils::MakeMaker, or other means for module installation like Module::Build or Module::Install.

    Yet, I don't guarantee this to be "intuitive" :-)

    Open source softwares? Share and enjoy. Make profit from them if you can. Yet, share and enjoy!

Re: examples in CPAN distributions
by wjw (Curate) on Apr 26, 2007 at 03:16 UTC
    ... going a bit further along the lines of a tool.... Maybe a dedicated site for Perl examples, ordered in the same way CPAN search (R.K.'s search). Maybe I wierd (ok, probably), but I learn more by reading simple code examples, then expanding on them using the docs, than I do from the docs by themselves. That is not to say that the docs are bad,(or that they are not bad) just that they do not always help me get up to speed as quickly as I would like to.

    I see real value in this idea, regardless of implementation.

    Good Idea zby!

    • ...the majority is always wrong, and always the last to know about it...
    • The Spice must flow...
    • my will, and by will alone.. I set my mind in motion

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://611952]
Approved by GrandFather
Front-paged by grinder
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others lurking in the Monastery: (3)
As of 2016-10-23 03:10 GMT
Find Nodes?
    Voting Booth?
    How many different varieties (color, size, etc) of socks do you have in your sock drawer?

    Results (300 votes). Check out past polls.