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

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

From:
Shlomi Fish
Date:
May 13, 2003 00:52
Subject:
Re: [PATCH] perlsyn.pod Revamp (take 2)
Message ID:
Pine.LNX.4.33L2.0305131048390.20214-100000@vipe.technion.ac.il
On Mon, 12 May 2003, Casey West wrote:

> It was Saturday, May 10, 2003 when Shlomi Fish took the soap box, saying:
> : --- bleadperl/pod/perlsyn.pod	2003-04-27 03:07:07.000000000 +0300
> : +++ modified/pod/perlsyn.pod	2003-05-10 09:43:20.000000000 +0300
> : @@ -5,28 +5,26 @@
> :  =head1 DESCRIPTION
> :
> :  A Perl script consists of a sequence of declarations and statements.
> : -The sequence of statements is executed just once, unlike in B<sed>
> : -and B<awk> scripts, where the sequence of statements is executed
> : -for each input line.  While this means that you must explicitly
> : -loop over the lines of your input file (or files), it also means
> : -you have much more control over which files and which lines you look at.
> : -(Actually, I'm lying--it is possible to do an implicit loop with
> : -either the B<-n> or B<-p> switch.  It's just not the mandatory
> : -default like it is in B<sed> and B<awk>.)
> : +The statements are executed one by one.  This is unlike B<awk> or
> : +B<sed> (in case you are familiar with these tools) where the sequence
> : +of statements is executed for each input line.  While it is possible
> : +to emulate this behavior, using the B<-n> or B<-p> switches, the
> : +default is to follow the standard of traditional imperative
> : +languages.
>
> Well, you're trying to change the meaning completley.  perlsyn is
> currently trying to say that "the program" will be executed once in
> its entirety, and that set and awk execute the program multiple times
> in its entirety.  Your change would lead me to believe that sed and
> awk do not execute their statements one-by-one, and that's just not
> true.
>

OK, fixed in the next release.

> :  Perl is, for the most part, a free-form language.  (The only exception
> :  to this is format declarations, for obvious reasons.)  Text from a
> :  C<"#"> character until the end of the line is a comment, and is
> : -ignored.  If you attempt to use C</* */> C-style comments, it will be
> : -interpreted either as division or pattern matching, depending on the
> : -context, and C++ C<//> comments just look like a null regular
> : -expression, so don't do that.
> : +ignored.  C-style C</* */> or C++ C<//> comments will do something else
> : +entirely, so don't use them (and I mean it).
>
> This removed important details that explain why you shouldn't use C or
> C++ style comments.  It's probably not a good idea to remove details
> from documentation.
>

Done too.

> :  =head2 Declarations
> :
> :  The only things you need to declare in Perl are report formats
> : -and subroutines--and even undefined subroutines can be handled
> : -through AUTOLOAD.  A variable holds the undefined value (C<undef>)
> : +and subroutines.  (Undefined subroutines can be handled
> : +through the AUTOLOAD feature as documented in L<perlsub>)
> : +
> : +A variable holds the undefined value (C<undef>)
> :  until it has been assigned a defined value, which is anything
> :  other than C<undef>.  When used as a number, C<undef> is treated
> :  as C<0>; when used as a string, it is treated the empty string,
>
> This is good.
>

Thanks.

> : @@ -100,6 +98,23 @@
> :      until EXPR
> :      foreach EXPR
> :
> : +C<if> executes a block of statements (or a single statement) once
> : +if C<EXPR> evaluated to a true value.  C<unless> executes it once if
> : +it did not.  A false value is C<undef>, 0, the empty string, and the
>
> Specify "it".
>

I changed it to "condition" and to C<EXPR> in the next release.

> : +floating number 0.0.  A true value is everything else. Normally,
> : +you'll wish to use comparison operators (C<==>, C<eq>, C<<<=>>, C<gt>
> : +or friends), regular expression matches or other mechanisms that
> : +explicitly return a true or false value as a boolean expression
> : +there.
>
> Overall this paragraph seems to narrow the scope of possibilities in a
> program too much.  That is, the description tries to second guess the
> programmer and that will confuse the reader.
>

I've changed it to a more generic description.

> : +
> : +C<while> and C<until> repeat the same block of statements while or
> : +until it is true.  (I.e.: C<until> iterates while it is false)
> : +The C<while> and C<until> modifiers have the usual "C<while> loop"
> : +semantics (conditional evaluated first), except when applied to a
> : +C<do>-BLOCK (or to the deprecated C<do>-SUBROUTINE statement), in
> : +which case the block executes once before the
> : +conditional is evaluated.  This is so that you can write loops like:
>
> What is "it?".  Do we need to document deprications in new
> documenatation patches?  Loops like what?
>

Changed to "condition".

> : +
> :  The C<if> and C<unless> modifiers have the expected semantics,
> :  presuming you're a speaker of English.  The C<foreach> modifier is an
> :  iterator:  For each value in EXPR, it aliases C<$_> to the value and
> : @@ -141,6 +156,10 @@
> :  it.  Future versions of perl might do something different from the
> :  version of perl you try it out on.  Here be dragons.
> :
> : +Finally, the C<foreach> modifier is an iterator: For each value
> : +in EXPR, it aliases the special "default" variable C<$_> to the
> : +value and executes the statement.
> : +
>
> This is already documented in perlsyn.  You added the same wording
> here but did not remove it's use earlier in the file.
>

Removed the previous wording in the next release.

> :  =head2 Compound statements
> :
> :  In Perl, a sequence of statements that defines a scope is called a block.
> : @@ -195,7 +214,10 @@
> :  conditional is about to be evaluated again, just like the third part of a
> :  C<for> loop in C.  Thus it can be used to increment a loop variable, even
> :  when the loop has been continued via the C<next> statement (which is
> : -similar to the C C<continue> statement).
> : +similar to the C C<continue> statement).  Note that C<continue> in C
> : +and C<continue> in Perl do entirely different things.  Fortunately, if
> : +one is used in place of the other by mistake it is likely to be a syntax
> : +error.
>
> We don't really need to mention that Perl and C are different at the
> syntax level, that's given.  Furter, we already talk about the
> differences (and similarities) between Perl and C continue within
> perlsyn.
>

Removed, then. <sigh />

> :
> :  =head2 Loop Control
> :
> : @@ -558,7 +580,8 @@
> :  The C<goto>-LABEL form finds the statement labeled with LABEL and resumes
> :  execution there.  It may not be used to go into any construct that
> :  requires initialization, such as a subroutine or a C<foreach> loop.  It
> : -also can't be used to go into a construct that is optimized away.  It
> : +also can't be used to go into a construct that is optimized away at
> : +the compilation stage, like an C<if (0) { ... }> block.  It
> :  can be used to go almost anywhere else within the dynamic scope,
> :  including out of subroutines, but it's usually better to use some other
> :  construct such as C<last> or C<die>.  The author of Perl has never felt the
>
> Again, you're trying to remove important details.
>

Actually, I was adding an important detail. (you confused the -'s and
+'s).

Regards,

	Shlomi Fish

>   Casey West
>
>



----------------------------------------------------------------------
Shlomi Fish        shlomif@vipe.technion.ac.il
Home Page:         http://t2.technion.ac.il/~shlomif/

An apple a day will keep a doctor away. Two apples a day will keep two
doctors away.

	Falk Fish




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