Front page | perl.perl5.porters |
Postings from February 2022
Re: pod/perluni* and older perls
February 8, 2022 10:00
Re: pod/perluni* and older perls
Message ID: email@example.com
On 07.02.2022 19:15, G.W. Haywood via perl5-porters wrote:
> 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.
Just to add my little drop to the ocean : +1 to most of the above, circumstances similar
here (except that I have even more than a quarter century programming with perl)