develooper Front page | perl.perl5.porters | Postings from July 2011

Re: bless document unclear

Thread Previous | Thread Next
From:
Aristotle Pagaltzis
Date:
July 1, 2011 11:58
Subject:
Re: bless document unclear
Message ID:
20110701185751.GL8585@klangraum.plasmasturm.org
* David Golden <xdaveg@gmail.com> [2011-06-30 22:00]:
> I'm not sure that that level of informality is appropriate for
> Perl's documentation.

I am.

Larry opted for whimsy and evocation over stuffiness in many
places, which made Perl as a culture what it is (– or was?). Why
is called `bless`? Or `my`, or `chomp`, or `die`? Or `next` and
`last` instead of `continue` and `break`? Think also of jargon
like “autovivification”.

Much of the original documentation and the Camel are written in
this spirit as well.

> Using "thing" is more common English and is no less confusing
> in this context.

It would be *worse*.

“Thingy” signals intentional informality, subtly calling out in
this context that detail is being glossed over (namely, what
exactly can be a referent?). And avoiding burdening the reader
with unnecessary detail is a key didactic and literary principle.

In contrast, using “thing” merely appears as laziness and muddled
thinking on the part of the writer. Unlike “thingy” it conveys
nothing of value, so the section should be rewritten for brevity
and precise expression.

> Or perhaps more simply:
>
>  This function makes REF into an object of type CLASSNAME.

This is factually wrong. But with the correction pointed out by
Zefram applied, it reads

   This function makes the referent of REF into an object of type
   CLASSNAME.

Compare with

    This function tells the thingy referenced by REF that it is
    now an object in the CLASSNAME package.

In substance and structure these sentences are perfectly
identical, and they only differ in that the former is out of the
maths department and the latter from the humanities.

This is not an argument about this particular passage. Maybe it
deserves changing. My concern is over what level of formality is
or is not appropriate for Perl’s documentation overall:

Writing need not be drab or anaemic in order to be clear.

Regards,
-- 
Aristotle Pagaltzis // <http://plasmasturm.org/>

Thread Previous | Thread Next


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