develooper Front page | perl.perl5.porters | Postings from June 2015

Re: Question/suggestion on perlfunc.pod example

Thread Previous | Thread Next
From:
Glenn Golden
Date:
June 7, 2015 00:53
Subject:
Re: Question/suggestion on perlfunc.pod example
Message ID:
20150607005247.GA5793@huh.zplane.com
Aristotle Pagaltzis <pagaltzis@gmx.de> [2015-06-05 18:41:32 +0200]:
>
> I wondered: if the diff is going to be big anyway, maybe it’s worthwhile
> to rewrite the whole thing and smooth it out properly instead of trying
> to tweak it in place. So I gave that a shot:
> 
> http://perl5.git.perl.org/perl.git/commitdiff/refs/heads/ap/perlfunc-do
> 
> How does that look to you?
> 

I totally agree with your approach of reworking it from scratch instead of
hacking what was there.  I'm fine with everything you have, starting from

     "Unfortunately, "do" does not provide... "

until the end.  I have some whinings on the text prior to that though:

  * "That is, these statements...."

    The phrase "That is..." seems inappropriate in the context in which it's
    used.  "That is, ..." is usually used to restate, using different words,
    a concept that has just been previously put forth.  But the way you've used
    it, the subsequent text (comparing "do" with "eval") is not really a
    restatement of the previous sentence; it's the beginning of a new concept,
    i.e. the contrasting of "do" with "eval".

  * In your version, "runs no external processes" has been dropped. Imo, as a
    relatively inexpert perl user, that was a useful reminder, even though one
    can certainly argue that the presence of backtics "obviously" implies an
    external process.  To put it another way, a reader of my skill level might
    well appreciate that reminder, even though it's redundant for the more
    experienced user.  For the cost of four words, I'd favor keeping it.

  * Substitution of "achieve the same overall purpose" for "functionally
    similar".

    I didn't like this because it doesn't seem quite accurate.  For example,
    if stat.pl intentionally references lexicals in the enclosing scope, the
    two constructs will not necessarily "achieve the same overall purpose".

    The phrase "functionally similar" that I'd suggested seems to get the job
    done for the reader: It informs him that the constructs behave in a roughly
    comparable way, yet avoids being over-specific about it, instead saving that
    specificity for the subsequent sentences, which get into it in more detail.

  * "The difference is...",

    The phrase "the difference is" has a singular feel to it, yet there are
    multiple differences mentioned.

  * "It also hides the lexicals from its enclosing scope from the evaluated
    code (whereas "eval" exposes them; either behaviour could be what you
    want)."

    I suspect Strunk and White might barf on the semicolon within the
    parenthetical phrase. :)  Also the double occurrence of "from" confuses
    the semantic that is being conveyed by the verb "hides": Better imo would
    be:

	"It also hides lexicals visible in its enclosing scope from the
	 evaluated code, whereas "eval" exposes them; either behaviour could
	 be what you want."


Anyway... taking all of the above yakking into account, and starting with your
ground rule of tabula rasa, here's an attempt at a happy medium between the
leading text of our two versions:


=========================================================================
do EXPR
    Searches @INC for a readable file having the name given by EXPR, and
    if found, executes the contents of that file as a Perl script and updates
    %INC.

    The "do EXPR" construct is functionally similar to "eval `cat FILENAME`",
    the main difference being that "do EXPR" hides lexicals visible in its
    enclosing scope from the evaluated code, whereas "eval" exposes them; either
    behaviour could be what you want. (Other differences: "do" keeps track of
    the target filename for error reporting; and it does not spawn an external
    process as `cat FILENAME` does.)

    Both constructs have in common that they read, parse, and run the code in
    the file every time they are encountered, so you probably don't want to use
    either of them inside a busy loop.


    Unfortunately, "do" does not provide..........
=========================================================================

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