develooper Front page | perl.perl5.porters | Postings from February 2022

Re: pod/perluni* and older perls

Thread Previous | Thread Next
"G.W. Haywood" via perl5-porters
February 7, 2022 18:15
Re: pod/perluni* and older perls
Message ID:
Hi there,

On Mon, 7 Feb 2022, Ricardo Signes wrote:

> On Mon, Feb 7, 2022, at 8:55 AM, Felipe Gasper wrote:
>> `perldoc perldocstyle` says to “Recount the past only when
>> necessary”. Meanwhile, the various perluni* docs are rife with
>> mentions of older perls.  Should these be removed? It would make
>> those documents more concise, less imposing for newcomers.
>  It sounds reasonable.  I had only a quick skim and didn't see much
> that I'd remove -- but that's probably because I skimmed and didn't
> carefully read or scan these.  Could you provide some examples of
> what you'd cut?

[Drumbeat] The Perl documentation is outstanding.  I constantly refer
to it, and it's the main reason that I'm still coding with Perl after
a quarter of a century.  Please let's not do anything to make it even
slightly less useful. [/Drumbeat]

Briefly I scanned 'perldoc perlunicode', then grepped for the string
'5.' in the output.  The count was over 50.  Probably a bad idea to
pick something about unicode and Perl for the example, but I'd say in
this case that "rife" is a very appropriate term.

Some of us *like* to use old software.  We get a warm, fuzzy feeling
from knowing that it's worked fine like that for several years; that
helps us sleep, knowing that in all probability it will *still* work
when we get into work tomorrow.  Printing, for example, is a case to
illustrate this very well, as I've just had an email from a customer
who says that printing doesn't work after upgrading a Debian system,
from 'Buster' to 'Bullseye'.  Oh, rapture, they've improved it, so I
have to make a trip to Nottinghamshire to fix the improved package.

So wherever possible I'll avoid upgrading, because most of the time it
just breaks everything.  Unfortunately I'm the one who carries the can
when that happens.  I'm kicking the can here because that's where the
worms *will* find an escape route.

Sometimes there are security issues which I can't mitigate in any
other way.  Sometimes an essential package has to be upgraded for
non-security reasons although that's less common.  But apart from
that, if I'm given the choice between the stuff which works and the
shiny new stuff, I'll take the stuff which works every time thanks
very much.  People who want to get work done without having to worry
about tools breaking every five minutes are more often than not people
running older versions of the tools, not the latest shiny ones.

What I'm saying is that old software can't just be forgotten.  But it
can equally get out of hand.  In this case, I think it has.  Perl 5.8
is nearly 20 years old, and I can't imagine that there are many people
who depend on it for their livelihoods, so multiple references to it
in the documentation only serve further to confuse an already highly
confused subject.  (Of course that's leaving aside the confusion over
what "use 5.008" actually means, if you haven't yet tripped over it -
you couldn't make this stuff up.)

There's a case for dropping some history from the documentation; most
of the time it will detract from the reader's experience.  But when
there are significant differences between a Perl that carries the
notice "Copyright 1987-2018, Larry Wall" (like the one on my laptop)
and the one that's currently being distributed with 'BleedingEdgeOS'
then it might help me enormously to know about them *without* having
to remember to read up about it separately in the changelog.

I don't think there's a pressing need at the moment to rush around all
the docs with a feather duster, but if someone feels that urge then he
should probably have some guidelines, and maintainers need them too.

Perhaps there should be a stated policy covering what's "necessary"?

Taking a stab in the dark I'd say that covering differences in Perl
versions for the past five years wouldn't be too far off the mark.  It
would be useful to have an 'attic' section for each document where any
significant differences from old versions can live, with references in
the main text added when something is moved upstairs, but if that's a
pain to manage then there will be archived versions of the documents
available so perhaps a simple link to the archives at the foot of each
document might be easier.  Bear in mind that because unfortunately we
do not live in an ideal world, the document which one might be reading
might not live on the system for which he's coding.


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