develooper Front page | perl.perl5.porters | Postings from May 2003

Re: [PATCH] perlsyn.pod Revamp (take 2)

From:
Tom Christiansen
Date:
May 12, 2003 17:13
Subject:
Re: [PATCH] perlsyn.pod Revamp (take 2)
Message ID:
2826.1052784651@chthon
>Well, you're trying to change the meaning completely. 

That, too, but there's something else to consider.

It might be of some interest to reflect upon the evolution of the document
in question since its initial release as perl1's one and only manpage back
in distant 1987:

    Perl is a interpreted language optimized for scanning arbitrary text
    files, extracting information from those text files, and printing reports
    based on that information.  It's also a good language for many system
    management tasks.  The language is intended to be practical (easy to
    use, efficient, complete) rather than beautiful (tiny, elegant, minimal).
    It combines (in the author's opinion, anyway) some of the best features
    of C, sed, awk, and sh, so people familiar with those languages should
    have little difficulty with it.  (Language historians will also note some
    vestiges of csh, Pascal, and even BASIC-PLUS.)  Expression syntax
    corresponds quite closely to C expression syntax.  If you have a problem
    that would ordinarily use sed or awk or sh, but it exceeds their
    capabilities or must run a little faster, and you don't want to write
    the silly thing in C, then perl may be for you.  There are also translators
    to turn your sed and awk scripts into perl scripts.  OK, enough hype.

through its perl4 version from 1992 (or possibly very early 1993 
if changes occurred to it between 4.035 and 4.036):

    Perl is an interpreted language optimized for scanning arbitrary text
    files, extracting information from those text files, and printing reports
    based on that information.  It's also a good language for many system
    management tasks.  The language is intended to be practical (easy to
    use, efficient, complete) rather than beautiful (tiny, elegant, minimal).
    It combines (in the author's opinion, anyway) some of the best features
    of C, sed, awk, and sh, so people familiar with those languages should
    have little difficulty with it.  (Language historians will also note some
    vestiges of csh, Pascal, and even BASIC- PLUS.)  Expression syntax
    corresponds quite closely to C expression syntax.  Unlike most Unix
    utilities, perl does not arbitrarily limit the size of your data--if
    you've got the memory, perl can slurp in your whole file as a single
    string.  Recursion is of unlimited depth.  And the hash tables used by
    associative arrays grow as necessary to prevent degraded performance.
    Perl uses sophisticated pattern matching techniques to scan large amounts
    of data very quickly.  Although optimized for scanning text, perl can
    also deal with binary data, and can make dbm files look like associative
    arrays (where dbm is available).  Setuid perl scripts are safer than C
    programs through a dataflow tracing mechanism which prevents many stupid
    security holes.  If you have a problem that would ordinarily use sed or
    awk or sh, but it exceeds their capabilities or must run a little faster,
    and you don't want to write the silly thing in C, then perl may be for
    you.  There are also translators to turn your sed and awk scripts into
    perl scripts.  OK, enough hype.

up now to its v5.8.1 incarnation, psalmlessly :-) dated the 23rd day of the
first month of our current year:

    Perl is a language optimized for scanning arbitrary text files, extracting
    information from those text files, and printing reports based on that
    information.  It's also a good language for many system management tasks.
    The language is intended to be practical (easy to use, efficient, complete)
    rather than beautiful (tiny, elegant, minimal).

    Perl combines (in the author's opinion, anyway) some of the best features
    of C, sed, awk, and sh, so people familiar with those languages should
    have little difficulty with it.  (Language historians will also note some
    vestiges of csh, Pascal, and even BASIC-PLUS.)  Expression syntax corresponds
    closely to C expression syntax.  Unlike most Unix utilities, Perl does
    not arbitrarily limit the size of your data--if you've got the memory,
    Perl can slurp in your whole file as a single string.  Recursion is of
    unlimited depth.  And the tables used by hashes (sometimes called
    "associative arrays") grow as necessary to prevent degraded performance.
    Perl can use sophisticated pattern matching techniques to scan large
    amounts of data quickly.  Although optimized for scanning text, Perl can
    also deal with binary data, and can make dbm files look like hashes.
    Setuid Perl scripts are safer than C programs through a dataflow tracing
    mechanism that prevents many stupid security holes.

    If you have a problem that would ordinarily use sed or awk or sh, but
    it exceeds their capabilities or must run a little faster, and you don't
    want to write the silly thing in C, then Perl may be for you.  There are
    also translators to turn your sed and awk scripts into Perl scripts.

    But wait, there's more...

    Begun in 1993 (see perlhist), Perl version 5 is nearly a complete rewrite
    that provides the following additional benefits:

    [VERBA DELETA]

    Okay, that's definitely enough hype.

In addition to your point of meaning change, Casey, the proffered patch
changes the underlying flavor and tone of the document at a crucial point
in its presentation.  The original displayed a cheerful flare and a gentle
enthusiasm.  It never cedes humility to bluster, however deserving of pride
in hard work and craftsmanship it might be.  It is never scolding.  It
doesn't lose sight of pleasant readability in some soulless quest for
didactic correctness--or, perhaps, for political correctness in the OS
sense of PC, but that may be more an accident of the times than by intent,
for exclusion has never been a Perl value.

All those things would risk losing the reader by rendering the prose too
plodding.  As the opening fanfare in the entire documentation epic, it
merits special care and attention to subtleties potentially dispensable
further in.

To achieve all that--and I contend that it did so--would be really quite
remarkable indeed if one did not consider its author.  Perhaps it still is.

Admittedly, the target audiences of those three documents has shifted as
Perl's reach has broadened.  Compared with our 1987 audience, today's audience
is much more heterogeneous in experience and skill, to put it charitably
(as one should).

When patching the code in a program, it is important to maintain the style
of the original, even when that style should conflict with one's own.  This
advice might be more applicable still when patching the text in a document.
It is a shame that the current Perl documentation no longer shows many of
those virtues I've just touched upon that its earlier versions more notably
enjoyed.

Yet I do not know how the current state of uneven embellishments and strange
artifacts could have been avoided.  Many more hands are now involved in the
entire effort, and changes to functionality cannot help but engender
corresponding changes to the documentation.

More importantly, one cannot expect the same skills and sensitivities of
all the many helpers, and one *must* not reject (on that basis, nor perhaps
on any other) *any* truly well-intentioned attempt to contribute to helping
make that corner of the world a better place.  For that would discourage
them and poison the culture, too, and that would quickly be the end of it
all.  You cannot ask of someone something that exceeds their own gifts, nor
begrudge them whatever they can manage.  Tritely, beggars can't be choosers.

But I still like what Larry wrote better; maybe I'm just prejudiced.

And *that*, by the way, Casey, is my take on the long-standing and sometimes
querulous (though not by you) debate and speculation on the myriad whys and
wherefores that have brought the Perl documentation to its current state, a
state that's clearly far from perfect in overall presentation, detail,
correctness, execution, and character.

But I do not in retrospect know how any other outcome could have been
reasonably and realistically effected, and I just wanted to thank you
personally and everyone generally for their efforts great and small 
that have helped the Perl documentation project.

--tom



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