I agree that making a perfectly executable synopsis is problematic for some modules, so you have to use judgement. I also agree that language extension modules are different. I didn't think of Exporter::VA as a language extension like strict. If it really is a language extension, then my preferences for the synopsis do not apply.

Perhaps my favorite synopsis is the one in CGI.

The idea of tearing off the shrink-wrap is to think about the initial user experience with a module. I don't know if you remember your first experience with use strict;, but I remember that mine was rough! It introduced a whole new way of coding for me. If Exporter::VA is to change the way that I code and become a 'way of life' module, the documentation needs to be especially clearly written. The strict perldoc is quite good, for example. Even with this documentation, I really had to read a detailed article about the requirements and benefits of strict before I was successful with it.

For ordinary modules that just do something clever, I like to try them out quickly. I typically evaluate five to ten modules a week, so speed is important to me.

Here is what I did to try out File::Slurp, which I think has a synopsis that is slightly more complex than my ideal, but it is actually fine how it is.

$ cpan
> install File::Slurp
> quit

$ mkdir fileslurp
$ cd fileslurp
$ perldoc File::Slurp
# This next bit is cut and paste:
$ cat > t.pl
               use File::Slurp;

               $all_of_it = read_file($filename);
               @all_lines = read_file($filename);

               write_file($filename, @contents)

               overwrite_file($filename, @new_contnts);

               append_file($filename, @additional_contents);

               @files = read_dir($directory);


$ vi t.pl
[download]

After pulling in my perl test-program template and a bit of editing I have this:

<P>
#!/home/toma/perl58i/bin/perl
#!/home/toma/perl58i/bin/perl -d:ptkdb
#
# Tom Anderson
# Sat Jan 11 12:31:00 PST 2003
#
# Program to try out File::Slurp
#
#

my $VERSION=".01";

use strict;
use warnings;
use diagnostics;

use File::Slurp;

my $filename = "/etc/passwd";
my $all_of_it = read_file($filename);

print $all_of_it;
[download]

With very few keystrokes and very little time I have evaluated File::Slurp and my first impression is that it is a very good module. I understand what it does, although I have only scratched the surface. I think that the author of File::Slurp has done me a great favor by uploading this module to CPAN, because I got to experience it working perfectly the first time!

It should work perfectly the first time! - toma