I'd love to see your module in CPAN. It's quite heavy, and I think I won't be using it because of that, but I'm sure many module developers and users will appreciate the versioning, especially the foo => [ v1.0, 'foo_old', v2.0, 'foo_new' ] feature.

Have you seen Exporter::Dream? It has a _prefix option to have bar exported as quux_bar if the _prefix is quux_. Maybe you can add something like that to Exporter::VA?

What does "VA" stand for anyway? Couldn't find it in its documentation.

- Yes, I reinvent wheels.
- Spam: Visit eurotraQ.

I've uploaded it to CPAN, but the namespace registration seems to be taking a while. VA is for Versioning and Aliasing. I suppose I can make that more obvious where it's stated in the =head1 NAME section. Add something like _prefix? I'm thinking of

use SomeModule -rename => ['prefix_bar', 'bar', v2.4 ]
[download]

where the version is optional, and the "target" parameter can be a name to use or a reference to set, so you can grab a versioned import without modifying your namespace at all. I've not decided on a good name yet; -rename doesn't convey the ref ability and I want a name that better suits the target=source,version ordering of the parameters.

I've not read your Exporter::Dream node yet. I see bbfu and theorbtwo already pointed you to my earlier work. I'll read your node carefully soon, and see what kind of ideas you have.

—John

One of the most critical areas of the documentation is the synopsis. It should be possible to cut and paste the entire synopsis and create a working program that shows the utility of the module. While the synopsis of Exporter::VA does compile, it doesn't stand alone as a useful program. The synopsis is the equivalent of a 'hello world' program in a new language and programming environment. Think of the module as a shrink-wrapped box, and the user wants to tear off the plastic and make it work as soon as possible. Perhaps the rest of the manual will be read later, after the initial frenzy is over.

The pod needs to include examples that actually work. Foo, bar, and baz have limited utility. I need to see an example in the pod of how your module improves the use of a real CPAN modules.

The $VERSION number is also unrealistic, given that the pod states that it has only been tested on AS/Windows. While perl code is remarkably portable, the idea that pure perl code will port with zero testing is unrealistic. A reasonable version number is perhaps 0.0121, not 1.21. Much of porting deals with installation and other issues that don't seem to have anything to do with the intended use of the code.

It should work perfectly the first time! - toma

It should be possible to cut and paste the entire synopsis and create a working program that shows the utility of the module

I disagree. I think that working programs should be put under examples. I believe that synopsis should be what webster.com tells you: 1 : a condensed statement or outline (as of a narrative or treatise) : ABSTRACT

Think of the module as a shrink-wrapped box, and the user wants to tear off the plastic and make it work as soon as possible.

Not only first-time users read the synopsis. After a while of not using a module I sometimes take a quick look at the synopsis to get going again.

There are many examples of (common) Perl modules that has an IMHO good enough synopsis but doesn't show an in its own useful snippet: strict, Data::Dumper, constant, Exporter, HTML::Parser, DBI (perhaps a bit extreme), Math::BigInt, LWP::UserAgent, File::Slurp, Storable, Switch, English, and more.

Though, you can't really compare "language extention modules" such as constant or strict with modules that does a certain task for you such as HTML::Parser. They need different types of documentation. For Exporter::VA the targeted audience is people who want to export things. What they are interested in is the interface and how they can achieve exporting and what makes Exporter::VA special. So I'd be perfectly happy to see a simple synposis like the one Exporter has. Having a runnable and "useful" snippet would just take away focus from the specialities in Exporter::VA.

Just my thoughts,
ihb

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

Why does toma's excellent writeup/advice only have a noderep of +2 so far? It deserves more, folks!

Makeshifts last the longest.