develooper Front page | perl.perl5.porters | Postings from October 2011

Re: [perl #101976] [PATCH] Remove cruft from the module example

Thread Previous | Thread Next
Nicholas Clark
October 27, 2011 04:37
Re: [perl #101976] [PATCH] Remove cruft from the module example
Message ID:
On Sun, Oct 23, 2011 at 02:16:41PM -0700, Michael G Schwern wrote:
> On 2011.10.23 5:04 AM, H.Merijn Brand wrote:
> >> * Remove %EXPORT_TAGS.  It's not explained and rarely used.
> > 
> > I use them all the time in some corporate modules.
> I have no doubt.  There's lots of features we use all the time which this
> example does not and should not mention.
> This is supposed to be a concise teaching example of My First Module and only
> needs what is necessary to get a module working.  It's still too long.

I agree with Schwern for exactly these reasons.

"We" need to be careful to distinguish between (at least) tutorials, examples,
and reference documentation.

[And quite possibly between tutorials on "current consistent best practice
on writing new code" and "what to expect when maintaining someone else's

Even something used and useful doesn't necessarily belong early in a

> That said, I'm sure the %EXPORT_TAGS docs in Exporter could use work.  To go
> further, chopping out the tutorial from Exporter into Exporter::Tutorial and
> leaving Exporter as API docs would make Exporter far easier to understand.

I guess that's part of the "big picture" problem - many docs try to be all
things to all people, and I'm not sure if there's a good way to discipline
a split between [at least] teaching and reference.

[Disclaimer - I'm somewhat swamped with everything, playing catchup, and have
not read the actual patch in detail. I got the impression that others had done
this, and me doing it would be duplication of effort. I am trying to spot the
"big picture" problems.]

Nicholas Clark

Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About