I don't know what's the original issue in here, but in general I find
that documentation should *not* be tied to any particular version of
Perl, and if it really has to (for example to document either bugs
fixed or features introduced) it has to have an explicit version story
(was broken in Va.b and earlier, fixed YYYY-MM, in Vc.d and later).
Documentation should not be tied to a particular version of Perl
(without clearly pointing out what is working or not *and* in which
version) because the documentation and implementation are often *not*
conveniently colocated. People use documentation from the web, people
buy bargain books, people print out documentation onto dead trees. In
all cases they may end up reading documentation that is not at the
same level as the implementation they are using. I'm not just making
this up: people do write to [EMAIL PROTECTED] (or thankfully less often
directly to me :-) because of this unsynchrony.
As Abigail noted, having performance "tricks" that rely on some
particular (mis)feature, is of especially bad taste, because it just
leads into mindless repeating of these tricks, without clear
understanding of *why* -- and in new releases the trick may become
obsolete and actually harmful. If something is *really* slow,
benchmark it. Maybe switch the Oh-squared algorithm to Oh-N-log-N.
If something is *still* really slow, file a bug report, and the p5p
will profile it for you.
In other words, instead of just saying
Use this.
I suggest in general
Use this ... because ....
Note: the gorkulator() interface was introduced in Vx.y,
before that you had to ...
--
$jhi++; # http://www.iki.fi/jhi/
# There is this special biologist word we use for 'stable'.
# It is 'dead'. -- Jack Cohen
