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

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

Thread Previous | Thread Next
From:
Nicholas Clark
Date:
October 27, 2011 04:37
Subject:
Re: [perl #101976] [PATCH] Remove cruft from the module example
Message ID:
20111027113729.GV23881@plum.flirble.org
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
code"]

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

> 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


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About