Front page | perl.perl5.porters |
Postings from May 2003
That which is better left unsed: Removing language digressions
From:
Michael G Schwern
Date:
May 13, 2003 18:16
Subject:
That which is better left unsed: Removing language digressions
Message ID:
20030514011636.GA22001@windhund.schwern.org
The recent threads about perlsyn made me take another look at the Perl
documentation. It talks an awful lot about other languages to the
point of sometimes obscuring the point: Perl.
I've come to the conculsion that most of the direct comparisions to
other languages in the Perl documentation are not particularly relevent
anymore. Perl is no longer primarily populated by former awk, sed, Pascal
and C programmers. In fact, I'd easily say that most folks reading the docs
don't know those languages very well at all. Referencing them is not
helping and just clutters up the docs. Perl can stand on its own now.
Besides, we have a man page for all that, perltrap.
Case in point, the first two paragraphs of perlsyn. In these paragraphs,
likely to be one of the first paragraphs read by someone coming into Perl,
we learn that:
Perl consists of a sequence of declarations and statements
These statements are executed only once
Awk and sed execute once for each input line
-n and -p can make Perl act more like awk and sed.
-n and -p are not the default.
Perl is a free-form language
...except for formats
# is the comment character
/* */ and // are not a comment character
// could be an empty regex, division or defined-or
In this introduction to Perl syntax we have learned more about advanced
Perl features, awk, sed and C than introductory Perl syntax. The
introductory paragraphs in perlsyn should probably introduce the reader
to an overview of perl syntax, not digress about Unix tools. I know,
sometimes I talk crazy.
Clearly this is a pathological example but it makes the point: digressions
into other languages detract from the documentation, whether or not
the reader is familiar with those other languages. They're better
grouped in one place, perltrap.
What I intend to do about this is simply sweep through the perl documentation,
find references to other languages and decide if they should be struck out
or not. Sometimes this is a simple act of removal, sometimes it requires
a big restructuring as with the perlsyn intro. Any useful information
removed is moved to perltrap. I'll submit patches on a perl page basis, plus
perltrap additions, but sometimes submitting particularly contentious bits
seperately, like the perlsyn introduction.
I might also sweep out other obsolete things along the way. Favoring
"program" over "script" is on the list.
I've posted my intention so we can have all the doc philosophy arguments
of whether this is a good idea in one thread and leave the patch posts to
discussion of details.
Besides, I never could pass up an opportunity to propgate a bad pun.
--
Cottleston, Cottleston, Cottleston Pie.
A fish can't whistle and neither can I.
Ask me a riddle and I reply:
"Cottlestone, Cottleston, Cottleston Pie."