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

In reply to Re: Re: My module - my latest step by ihb
in thread My module - my latest step by John M. Dlugosz

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.