Re: Re: [PATCH] Re: [PATCH] perlfunc.pod grammar fixes

[Piotr Fusik]

>Leaving aside alternate backends (-MO=...) and the possibility of perl
>lying over and dying during the compile, there\'s still perl -c.

-c is "check syntax" and not "compile".

And there are also -h and -v, but I wouldn't take serious writing something 
like "perl can be used for checking syntax or running Perl scripts, but it can 
be also used for just displaying its version information or help instructions". 
:-)

Re: [PATCH] Re: [PATCH] perlfunc.pod grammar fixes

[Yitzchak Scott-Thoennes]

On Tue, Aug 09, 2005 at 01:38:11PM +0200, Piotr Fusik wrote:
> >+A program that compiles and usually executes L scripts.  Or is
> >+that L?
> 
> s/is that/are they/, I guess, but I may be wrong...

Implied "is that phrase in the previous sentence supposed to be".
"Or are they" would be correct also, but with a different meaning.
But I'm ok either way.

> s/usually //

Leaving aside alternate backends (-MO=...) and the possibility of perl
lying over and dying during the compile, there's still perl -c.

Re: [PATCH] Re: [PATCH] perlfunc.pod grammar fixes

[Piotr Fusik]

>+A program that compiles and usually executes L scripts.  Or is
>+that L?

s/is that/are they/, I guess, but I may be wrong...
s/usually //

[PATCH] Re: [PATCH] perlfunc.pod grammar fixes

[Yitzchak Scott-Thoennes]

On Thu, Jul 28, 2005 at 05:43:08PM -0500, David Nicol wrote:
> On 7/28/05, John P. Linderman <[EMAIL PROTECTED]> wrote:
> 
> > is there any significant difference between "perl" and "Perl"?
> 
> That is exactly the sort of edge case that is under discussion in
> this thread.  One possibility is maintaining an explicit glossary.pod file
> which would not only answer that question, but differentiate between
> effect, affect, and effect.

Sorry, no entries for [ae]ffect.  But how's this:

--- perl/pod/perlglossary.pod.orig  2005-08-01 01:42:33.0 -0700
+++ perl/pod/perlglossary.pod   2005-08-09 00:21:29.451790400 -0700
@@ -2180,6 +2180,17 @@
 file.  On Unix systems, you can check the I(1) manpage for more
 information.
 
+=item perl
+
+A program that compiles and usually executes L scripts.  Or is
+that L?
+See L.
+
+=item Perl
+
+A programming language.  You are reading part of its documentation.
+See L.
+
 =item Pern
 
 What you get when you do C twice.  Doing it only once will

Re: Y2K docs in the 21st century (was Re: [PATCH] perlfunc.pod grammar fixes)

[Michael G Schwern]

On Thu, Jul 28, 2005 at 06:58:35PM -0400, Horsley, Tom wrote:
> And therefore only Linux will have the 2039 bug.

s/Linux/Unix/  

Please let's not start confusing Linux with Unix or Redhat with Linux or 
Windows with computers on p5p, too.


-- 
Michael G Schwern [EMAIL PROTECTED] http://www.pobox.com/~schwern
Just call me 'Moron Sugar'.
http://www.somethingpositive.net/sp05182002.shtml

RE: Y2K docs in the 21st century (was Re: [PATCH] perlfunc.pod grammar fixes)

[Horsley, Tom]

> I doubt the wisdom of continuing to talk about Y2K compliance,
> here in Y2K+5.  We could talk about Y2100 compliance.

Actually the next crisis is the 2039 problem (which will be utterly
ignored because Y2K was such a bust :-).
 
Microsoft is no doubt licking its chops and waiting for 2039
since Windows doesn't use a 4 byte unsigned for its primary
timestamp, and therefore only Linux will have the 2039 bug.
 

Y2K docs in the 21st century (was Re: [PATCH] perlfunc.pod grammar fixes)

[Michael G Schwern]

On Thu, Jul 28, 2005 at 02:55:10PM -0500, David Nicol wrote:
> I like the fact that the perl documentation is peppered
> with correct uses of "effect" as a verb.
> 
> I doubt the wisdom of continuing to talk about Y2K compliance,
> here in Y2K+5.  We could talk about Y2100 compliance.

I think folks understand that Y2K is not just about the year 2000 but about
using truncated years in general and its not necessary to coin a new term.  
Same problem, different century.  Also...


> Note that the $year element is l simply one hundered plus the
> last two digits of the year.  By assuming that it is you will create
> non-Y2100-compliant code and guarantee your grandchildren careers
> in computer maintenance.

I can understand people in 1998 assuming 98 is the last two digits of the 
year and never bothering to look at the docs, but someone mistaking 105 as 
being one hundred plus the last two digits of the year... that seems a bit
contrived.

Possibly the best solution I've seen to this problem was the one employed
in Clinton Pierce's surprisingly well written "Learn Perl In 24 Hours".
Its not a year, stop calling it that.  Its years offset from 1900.  His book
always refers to it as $year_offset or $year_off but never $year.


-- 
Michael G Schwern [EMAIL PROTECTED] http://www.pobox.com/~schwern
Just call me 'Moron Sugar'.
http://www.somethingpositive.net/sp05182002.shtml

Re: [PATCH] perlfunc.pod grammar fixes

[David Nicol]

On 7/28/05, John P. Linderman <[EMAIL PROTECTED]> wrote:

> is there any significant difference between "perl" and "Perl"?

That is exactly the sort of edge case that is under discussion in
this thread.  One possibility is maintaining an explicit glossary.pod file
which would not only answer that question, but differentiate between
effect, affect, and effect.

Too worn out to get any cuter than that with that, although no doubt some
rube will.

-- 
David L Nicol
"This has been your one free extra mile"

Re: [PATCH] perlfunc.pod grammar fixes

[John P. Linderman]

I tried to keep my mouth shut (Steve Hay can verify that).
There's a distinction between maintaining accepted use of
words from eliminating all possibility of misunderstanding
them.  Should we eliminate "it's" and "its" and "their"
and "there" and "they're" because somebody can't get them
straight?  After

Date: Tue, 18 Jan 2005 11:43:30 -0500
According to John P. Linderman:
> Barring some sort of formal definitions, the C code determines the
> language (pretty much what happened to trigger this whole thread)
> rather than the language determining the parser, and that just seems
> wrong.  -- jpl

WRT Perl 5, I'm afraid that horse is not only out of the barn, but has
wandered off the ranch, joined a wild herd, and sired several foals.
--
Chip Salzenberg  - a.k.a. -   <[EMAIL PROTECTED]>

is there any significant difference between "perl" and "Perl"?
Above all, is this the most important issue facing [pP]erl?
If so, it's time declare victory and save some other language -- jpl

Re: [PATCH] perlfunc.pod grammar fixes

[David Nicol]

I like the fact that the perl documentation is peppered
with correct uses of "effect" as a verb.

I doubt the wisdom of continuing to talk about Y2K compliance,
here in Y2K+5.  We could talk about Y2100 compliance.

> >  Note that the $year element is I simply the last two digits of
> > -the year.  If you assume it is, then you create non-Y2K-compliant
> > +the year.  If you assume it is and then you create non-Y2K-compliant
> >  programs--and you wouldn't want to do that, would you?

Note that the $year element is l simply one hundered plus the
last two digits of the year.  By assuming that it is you will create
non-Y2100-compliant code and guarantee your grandchildren careers
in computer maintenance.




-- 
David L Nicol
"This has been your one free extra mile"

Re: [PATCH] perlfunc.pod

[Rafael Garcia-Suarez]

On 7/24/05, Piotr Fusik <[EMAIL PROTECTED]> wrote:
> --- perl-current/pod/perlfunc.pod Sun Jul 24 11:30:36 2005
> +++ perl-patched/pod/perlfunc.pod Sun Jul 24 11:38:16 2005

Thanks, applied as change #25241.

Re: [PATCH] perlfunc.pod grammar fixes

[Michael G Schwern]

On Thu, Jul 28, 2005 at 03:50:57AM -0400, Randy W. Sims wrote:
> Usage Note: Affect and effect have no senses in common. As a verb affect 
> is most commonly used in the sense of ?to influence? (how smoking 
> affects health). Effect means ?to bring about or execute?: layoffs 
> designed to effect savings. Thus the sentence These measures may affect 
> savings could imply that the measures may reduce savings that have 
> already been realized, whereas These measures may effect savings implies 
> that the measures will cause new savings to come about.

Forget it.  I'm learning an easier language, like Finnish.


-- 
Michael G Schwern [EMAIL PROTECTED] http://www.pobox.com/~schwern
ROCKS FALL! EVERYONE DIES!
http://www.somethingpositive.net/sp05032002.shtml

Re: [PATCH] perlfunc.pod grammar fixes

[Andy Lester]

On Thu, Jul 28, 2005 at 09:53:18AM -0400, Ronald J Kimball ([EMAIL PROTECTED]) 
wrote:
> An aside on the whole "affect" vs. "effect" thing...
> 
> In fact, both words have both a verb and a noun sense.

Quoting from _The Elements Of Style_, by Strunk & White, in the chapter
"Misused Words and Expressions":

Effect: As a noun, means "results"; as a verb, means "to bring about,"
"to accomplish," (not to be confused with I, which means
"to influence").

As a noun, often loosely used in perfunctory writing about fashions,
music, painting, and other arts: "a Southwestern effect"; "effects in
pale green"; "very delicate effects"; "subtle effects"; "a charming
effect was produced."  The writer who has a definite meaning to
express will not take refuge in such vagueness.

See also pages such as
http://owl.english.purdue.edu/handouts/grammar/g_spelprob.html
http://www.wsu.edu/~brians/errors/affect.html

It is perfectly fine, although less common, to say "to effect a sleep of
250 milliseconds."

I also agree that it would be preferable to s/effect/cause/ in the
example above.

xoxo,
Andy

-- 
Andy Lester => [EMAIL PROTECTED] => www.petdance.com => AIM:petdance

Re: [PATCH] perlfunc.pod grammar fixes

[Ronald J Kimball]

An aside on the whole "affect" vs. "effect" thing...

In fact, both words have both a verb and a noun sense.

Affect as a verb means to influence or change.
Effect as a verb means to bring about.

Affect as a noun means a feeling or emotion.
Effect as a noun means a result or influence.

Affect has the accent on the second syllable when it's a verb, but the
first syllable when it's a noun.

(Also, one definition of the verb affect is "to effect a change". :)

Ronald

Re: [PATCH] perlfunc.pod grammar fixes

[Brad Baxter]

On Thu, 28 Jul 2005, Steve Hay wrote:

> Nicholas Clark wrote:
>
> >On Thu, Jul 28, 2005 at 11:23:45AM +0100, Steve Hay wrote:
> >
> >>I didn't think it was confusing, but that be a minority opinion.
> >>
> >
> >Well, it's erudite, eloquent English written by someone with good vocabulary.
> >(Did tchrist write it?)
> >
> >However it seems that
> >
> >1: If you aren't native speaker, or don't notice these sort of differences,
> >   you won't see anything wrong
> >2: If you notice these differences but don't know the real nitty gritty
> >   subtleties, you think that there is something wrong.
> >   (I certainly did at first)
> >3: Only if you already know the subtly do you think it's fine.
> >   (but you might need to double take)
> >
> >Hence my suggestion to avoid the problem by not using the verb "effect",
> >even when it's correct.
> >
> Fair enough, I guess, but what about all the other places where these
> words are used?
>
> C:\p5p\bleadperl\pod>grep -i effect *.pod | wc -l
> 310
>
> Why bother changing it in 2 places when there are at least 308 other
> places in pod/ alone?

IMHO, to effect a change that affects something isn't erudite at all
(though I think erudite is).  Please, let's leave perfectly good
English alone.

Regards,

Brad

Re: [PATCH] perlfunc.pod grammar fixes

[Steve Hay]

Nicholas Clark wrote:

>On Thu, Jul 28, 2005 at 11:23:45AM +0100, Steve Hay wrote:
>
>  
>
>>I didn't think it was confusing, but that be a minority opinion.
>>
>>
>
>Well, it's erudite, eloquent English written by someone with good vocabulary.
>(Did tchrist write it?)
>
>However it seems that
>
>1: If you aren't native speaker, or don't notice these sort of differences,
>   you won't see anything wrong
>2: If you notice these differences but don't know the real nitty gritty
>   subtleties, you think that there is something wrong.
>   (I certainly did at first)
>3: Only if you already know the subtly do you think it's fine.
>   (but you might need to double take)
>
>Hence my suggestion to avoid the problem by not using the verb "effect",
>even when it's correct.
>
Fair enough, I guess, but what about all the other places where these 
words are used?

C:\p5p\bleadperl\pod>grep -i effect *.pod | wc -l
310

Why bother changing it in 2 places when there are at least 308 other 
places in pod/ alone?




Radan Computational Ltd.

The information contained in this message and any files transmitted with it are 
confidential and intended for the addressee(s) only.  If you have received this 
message in error or there are any problems, please notify the sender 
immediately.  The unauthorized use, disclosure, copying or alteration of this 
message is strictly forbidden.  Note that any views or opinions presented in 
this email are solely those of the author and do not necessarily represent 
those of Radan Computational Ltd.  The recipient(s) of this message should 
check it and any attached files for viruses: Radan Computational will accept no 
liability for any damage caused by any virus transmitted by this email.

Re: [PATCH] perlfunc.pod grammar fixes

[Steve Peters]

On Thu, Jul 28, 2005 at 05:32:56AM -0500, Steve Peters wrote:
> On Thu, Jul 28, 2005 at 08:55:17AM +0200, Piotr Fusik wrote:
> > I have doubts about the following changes:
> > 
Clearly, I need to read my mailbox completely after waking up in the
morning :-/

Steve Peters
[EMAIL PROTECTED]

Re: [PATCH] perlfunc.pod grammar fixes

[Steve Hay]

I've already applied the first patch, with the appropriate tweaks :-)

Steve Peters wrote:

>On Thu, Jul 28, 2005 at 08:55:17AM +0200, Piotr Fusik wrote:
>  
>
>>I have doubts about the following changes:
>>
>>
>> Note that the $year element is I simply the last two digits of
>>-the year.  If you assume it is, then you create non-Y2K-compliant
>>+the year.  If you assume it is and then you create non-Y2K-compliant
>> programs--and you wouldn't want to do that, would you?
>>
>>
>>
>"and" removed.
>  
>
Yep, I did that.

>  
>
>> Note that a block by itself is semantically identical to a loop
>>-that executes once.  Thus C can be used to effect an early
>>+that executes once.  Thus C can be used to affect an early
>> exit out of such a block.
>> 
>>
>>
>"effect" is a noun, while "affect" is a verb.  This is a common English
>grammar screw-up.
>  
>
Describing this as a screw-up seems to be a common a screw-up itself.  
"effect" is also a verb and is certainly the correct word here.  See the 
other posts if you didn't know...

>  
>
>>Sets the current position for the C routine on DIRHANDLE.  POS
>>-must be a value returned by C.  Has the same caveats about
>>-possible directory compaction as the corresponding system library
>>+must be a value returned by C.  C also Has the same caveats
>>+about possible directory compaction as the corresponding system library
>> routine.
>>
>>
>>
>"Has" changed to "has".
>  
>
Yep, did that too.

> 
>  
>
>>-You can effect a sleep of 250 milliseconds this way:
>>+You can affect a sleep of 250 milliseconds this way:
>>
>>
>>
>Again, effect vs. affect.  Here, this is a verb, so affect is the right
>word.
>  
>
No.

>  
>
>> the original quicksort was faster.  5.8 has a sort pragma for
>> limited control of the sort.  Its rather blunt control of the
>>-underlying algorithm may not persist into future perls, but the
>>+underlying algorithm may not persist into future Perls, but the
>> ability to characterize the input or output in implementation
>> independent ways quite probably will.  See L.
>>
>>
>
>Removed.
>
I agreed with Schwern that Perl was language and perl was the program, 
and that the above seemed to be referring to the language, so I kept 
your original change to "Perls".




Radan Computational Ltd.

The information contained in this message and any files transmitted with it are 
confidential and intended for the addressee(s) only.  If you have received this 
message in error or there are any problems, please notify the sender 
immediately.  The unauthorized use, disclosure, copying or alteration of this 
message is strictly forbidden.  Note that any views or opinions presented in 
this email are solely those of the author and do not necessarily represent 
those of Radan Computational Ltd.  The recipient(s) of this message should 
check it and any attached files for viruses: Radan Computational will accept no 
liability for any damage caused by any virus transmitted by this email.

Re: [PATCH] perlfunc.pod grammar fixes

[Nicholas Clark]

On Thu, Jul 28, 2005 at 11:23:45AM +0100, Steve Hay wrote:

> I didn't think it was confusing, but that be a minority opinion.

Well, it's erudite, eloquent English written by someone with good vocabulary.
(Did tchrist write it?)

However it seems that

1: If you aren't native speaker, or don't notice these sort of differences,
   you won't see anything wrong
2: If you notice these differences but don't know the real nitty gritty
   subtleties, you think that there is something wrong.
   (I certainly did at first)
3: Only if you already know the subtly do you think it's fine.
   (but you might need to double take)

Hence my suggestion to avoid the problem by not using the verb "effect",
even when it's correct.

Nicholas Clark

Re: [PATCH] perlfunc.pod grammar fixes

[Steve Peters]

On Thu, Jul 28, 2005 at 08:55:17AM +0200, Piotr Fusik wrote:
> I have doubts about the following changes:
> 
> 
>  Note that the $year element is I simply the last two digits of
> -the year.  If you assume it is, then you create non-Y2K-compliant
> +the year.  If you assume it is and then you create non-Y2K-compliant
>  programs--and you wouldn't want to do that, would you?
> 
"and" removed.

>  Note that a block by itself is semantically identical to a loop
> -that executes once.  Thus C can be used to effect an early
> +that executes once.  Thus C can be used to affect an early
>  exit out of such a block.
>  
"effect" is a noun, while "affect" is a verb.  This is a common English
grammar screw-up.

> Sets the current position for the C routine on DIRHANDLE.  POS
> -must be a value returned by C.  Has the same caveats about
> -possible directory compaction as the corresponding system library
> +must be a value returned by C.  C also Has the same caveats
> +about possible directory compaction as the corresponding system library
>  routine.
>
"Has" changed to "has".
 
> -You can effect a sleep of 250 milliseconds this way:
> +You can affect a sleep of 250 milliseconds this way:
>
Again, effect vs. affect.  Here, this is a verb, so affect is the right
word.

>  the original quicksort was faster.  5.8 has a sort pragma for
>  limited control of the sort.  Its rather blunt control of the
> -underlying algorithm may not persist into future perls, but the
> +underlying algorithm may not persist into future Perls, but the
>  ability to characterize the input or output in implementation
>  independent ways quite probably will.  See L.

Removed.

Attached below is the updated patch.

Steve Peters
[EMAIL PROTECTED]
--- pod/perlfunc.pod.old2005-07-27 11:57:23.0 -0500
+++ pod/perlfunc.pod2005-07-28 05:32:01.0 -0500
@@ -25,7 +25,7 @@
 of scalar arguments or list values; the list values will be included
 in the list as if each individual element were interpolated at that
 point in the list, forming a longer single-dimensional list value.
-Elements of the LIST should be separated by commas.
+Commas should separate elements of the LIST.
 
 Any function in the list below may be used either with or without
 parentheses around its arguments.  (The syntax descriptions omit the
@@ -139,7 +139,7 @@
 C, C, C, C, C, C,
 C, C, C
 
-=item Keywords related to the control flow of your perl program
+=item Keywords related to the control flow of your Perl program
 
 C, C, C, C, C, C, C,
 C, C, C, C, C, C, C
@@ -337,7 +337,7 @@
 The C<-T> and C<-B> switches work as follows.  The first block or so of the
 file is examined for odd characters such as strange control codes or
 characters with the high bit set.  If too many strange characters (>30%)
-are found, it's a C<-B> file, otherwise it's a C<-T> file.  Also, any file
+are found, it's a C<-B> file; otherwise it's a C<-T> file.  Also, any file
 containing null in the first block is considered a binary file.  If C<-T>
 or C<-B> is used on a filehandle, the current IO buffer is examined
 rather than the first block.  Both C<-T> and C<-B> return true on a null
@@ -351,7 +351,7 @@
 a system call.  (This doesn't work with C<-t>, and you need to remember
 that lstat() and C<-l> will leave values in the stat structure for the
 symbolic link, not the real file.)  (Also, if the stat buffer was filled by
-a C call, C<-T> and C<-B> will reset it with the results of C).
+an C call, C<-T> and C<-B> will reset it with the results of C).
 Example:
 
 print "Can do.\n" if -r $a || -w _ || -x _;
@@ -368,7 +368,7 @@
 
 As of Perl 5.9.1, as a form of purely syntactic sugar, you can stack file
 test operators, in a way that C<-f -w -x $file> is equivalent to
-C<-x $file && -w _ && -f _>. (This is only syntax fancy : if you use
+C<-x $file && -w _ && -f _>. (This is only syntax fancy: if you use
 the return value of C<-f $file> as an argument to another filetest
 operator, no special magic will happen.)
 
@@ -394,7 +394,7 @@
 =item alarm
 
 Arranges to have a SIGALRM delivered to this process after the
-specified number of wallclock seconds have elapsed.  If SECONDS is not
+specified number of wallclock seconds has elapsed.  If SECONDS is not
 specified, the value stored in C<$_> is used. (On some machines,
 unfortunately, the elapsed time may be up to one second less or more
 than you specified because of how seconds are counted, and process
@@ -547,13 +547,13 @@
 in the CLASSNAME package.  If CLASSNAME is omitted, the current package
 is used.  Because a C is often the last thing in a constructor,
 it returns the reference for convenience.  Always use the two-argument
-version if the function doing the blessing might be inherited by a
-derived class.  See L and L for more about the blessing
-(and blessings) of objects.
+version if a derived class might inherit the function doing the blessing.
+See L and L for more about the blessing (and blessings)
+of objects.
 
 Consider

Re: [PATCH] perlfunc.pod grammar fixes

[Steve Hay]

Nicholas Clark wrote:

>On Thu, Jul 28, 2005 at 08:55:17AM +0200, Piotr Fusik wrote:
>  
>
>>I have doubts about the following changes:
>>
>>
>
>  
>
>> Note that a block by itself is semantically identical to a loop
>>-that executes once.  Thus C can be used to effect an early
>>+that executes once.  Thus C can be used to affect an early
>> exit out of such a block.
>>
>>
>
>  
>
>>-You can effect a sleep of 250 milliseconds this way:
>>+You can affect a sleep of 250 milliseconds this way:
>>
>>
>
>On Thu, Jul 28, 2005 at 03:50:57AM -0400, Randy W. Sims wrote:
>  
>
>>chromatic wrote:
>>
>>
>>>On Thu, 2005-07-28 at 00:37 -0700, Michael G Schwern wrote:
>>>
>>>
>>>  
>>>
>Note that a block by itself is semantically identical to a loop
>-that executes once.  Thus C can be used to effect an early
>+that executes once.  Thus C can be used to affect an early
>exit out of such a block.
>  
>
effect is a noun.  affect is a verb so I think this change is correct.


>>>It's also a transitive verb, so "to effect (some direct object)" is
>>>valid English, if potentially unclear.
>>>  
>>>
>>Yes, they can both be used as tr verbs, but see usage from 
>>
>>
>>Usage Note: Affect and effect have no senses in common. As a verb affect 
>>is most commonly used in the sense of �to influence� (how smoking 
>>affects health). Effect means �to bring about or execute�: layoffs 
>>designed to effect savings. Thus the sentence These measures may affect 
>>savings could imply that the measures may reduce savings that have 
>>already been realized, whereas These measures may effect savings implies 
>>that the measures will cause new savings to come about.
>>
>>
>
>Which would mean that both proposed changes are indeed incorrect, as they're
>both obout causing things.
>  
>
Both changes are certainly incorrect, so I left them unchanged.

>Could we change both verbs to "cause" or "create" to avoid all confusion?
>
I didn't think it was confusing, but that be a minority opinion.




Radan Computational Ltd.

The information contained in this message and any files transmitted with it are 
confidential and intended for the addressee(s) only.  If you have received this 
message in error or there are any problems, please notify the sender 
immediately.  The unauthorized use, disclosure, copying or alteration of this 
message is strictly forbidden.  Note that any views or opinions presented in 
this email are solely those of the author and do not necessarily represent 
those of Radan Computational Ltd.  The recipient(s) of this message should 
check it and any attached files for viruses: Radan Computational will accept no 
liability for any damage caused by any virus transmitted by this email.

Re: [PATCH] perlfunc.pod grammar fixes

[Nicholas Clark]

On Thu, Jul 28, 2005 at 08:55:17AM +0200, Piotr Fusik wrote:
> I have doubts about the following changes:

>  Note that a block by itself is semantically identical to a loop
> -that executes once.  Thus C can be used to effect an early
> +that executes once.  Thus C can be used to affect an early
>  exit out of such a block.

> -You can effect a sleep of 250 milliseconds this way:
> +You can affect a sleep of 250 milliseconds this way:

On Thu, Jul 28, 2005 at 03:50:57AM -0400, Randy W. Sims wrote:
> chromatic wrote:
> >On Thu, 2005-07-28 at 00:37 -0700, Michael G Schwern wrote:
> >
> >
> >>>Note that a block by itself is semantically identical to a loop
> >>>-that executes once.  Thus C can be used to effect an early
> >>>+that executes once.  Thus C can be used to affect an early
> >>>exit out of such a block.
> >>
> >>effect is a noun.  affect is a verb so I think this change is correct.
> >
> >
> >It's also a transitive verb, so "to effect (some direct object)" is
> >valid English, if potentially unclear.
> 
> Yes, they can both be used as tr verbs, but see usage from 
> 
> 
> Usage Note: Affect and effect have no senses in common. As a verb affect 
> is most commonly used in the sense of “to influence” (how smoking 
> affects health). Effect means “to bring about or execute”: layoffs 
> designed to effect savings. Thus the sentence These measures may affect 
> savings could imply that the measures may reduce savings that have 
> already been realized, whereas These measures may effect savings implies 
> that the measures will cause new savings to come about.

Which would mean that both proposed changes are indeed incorrect, as they're
both obout causing things.

Could we change both verbs to "cause" or "create" to avoid all confusion?

Nicholas Clark

Re: [PATCH] perlfunc.pod grammar fixes

[Steve Hay]

Steve Peters wrote:

>This patch has it all:  passive voice removals; spelling fixes; which vs. 
>that change; e.g. fixes; and etc.  Thanks to Pod::Simple::RTF and 
>and handy grammar checker, this was all made much easier.  Enjoy!
>
Thanks, applied as change 25234 with minor tweaks as suggested.




Radan Computational Ltd.

The information contained in this message and any files transmitted with it are 
confidential and intended for the addressee(s) only.  If you have received this 
message in error or there are any problems, please notify the sender 
immediately.  The unauthorized use, disclosure, copying or alteration of this 
message is strictly forbidden.  Note that any views or opinions presented in 
this email are solely those of the author and do not necessarily represent 
those of Radan Computational Ltd.  The recipient(s) of this message should 
check it and any attached files for viruses: Radan Computational will accept no 
liability for any damage caused by any virus transmitted by this email.

Re: [PATCH] perlfunc.pod grammar fixes

[Randy W. Sims]

chromatic wrote:

On Thu, 2005-07-28 at 00:37 -0700, Michael G Schwern wrote:



Note that a block by itself is semantically identical to a loop
-that executes once.  Thus C can be used to effect an early
+that executes once.  Thus C can be used to affect an early
exit out of such a block.


effect is a noun.  affect is a verb so I think this change is correct.



It's also a transitive verb, so "to effect (some direct object)" is
valid English, if potentially unclear.


Yes, they can both be used as tr verbs, but see usage from 



Usage Note: Affect and effect have no senses in common. As a verb affect 
is most commonly used in the sense of “to influence” (how smoking 
affects health). Effect means “to bring about or execute”: layoffs 
designed to effect savings. Thus the sentence These measures may affect 
savings could imply that the measures may reduce savings that have 
already been realized, whereas These measures may effect savings implies 
that the measures will cause new savings to come about.

Re: Re: [PATCH] perlfunc.pod grammar fixes

[Piotr Fusik]

>>  Note that a block by itself is semantically identical to a loop
>> -that executes once.  Thus C can be used to effect an early
>> +that executes once.  Thus C can be used to affect an early
>>  exit out of such a block.
>
>effect is a noun.  affect is a verb so I think this change is correct.
>
>> -You can effect a sleep of 250 milliseconds this way:
>> +You can affect a sleep of 250 milliseconds this way:
>
>This is correct.
>
Hmm...

http://dictionary.reference.com/search?q=effect

tr.v. ef·fect·ed, ef·fect·ing, ef·fects 
To bring into existence. 
To produce as a result. 
To bring about. See Usage Note at affect. 


http://dictionary.reference.com/search?q=affect

Usage Note: Affect and effect have no senses in common. As a verb affect is 
most commonly used in the sense of “to influence” (how smoking 
affects health). Effect means “to bring about or execute”: layoffs 
designed to effect savings. Thus the sentence These measures may affect savings 
could imply that the measures may reduce savings that have already been 
realized, whereas These measures may effect savings implies that the measures 
will cause new savings to come about.

Re: [PATCH] perlfunc.pod grammar fixes

[chromatic]

On Thu, 2005-07-28 at 00:37 -0700, Michael G Schwern wrote:

> >  Note that a block by itself is semantically identical to a loop
> > -that executes once.  Thus C can be used to effect an early
> > +that executes once.  Thus C can be used to affect an early
> >  exit out of such a block.
> 
> effect is a noun.  affect is a verb so I think this change is correct.

It's also a transitive verb, so "to effect (some direct object)" is
valid English, if potentially unclear.

-- c

Re: [PATCH] perlfunc.pod grammar fixes

[Michael G Schwern]

On Thu, Jul 28, 2005 at 08:55:17AM +0200, Piotr Fusik wrote:
>  Note that the $year element is I simply the last two digits of
> -the year.  If you assume it is, then you create non-Y2K-compliant
> +the year.  If you assume it is and then you create non-Y2K-compliant
>  programs--and you wouldn't want to do that, would you?

The original looks more correct.  Maybe its using a comma wrong, but it
has the proper meaning.


>  Note that a block by itself is semantically identical to a loop
> -that executes once.  Thus C can be used to effect an early
> +that executes once.  Thus C can be used to affect an early
>  exit out of such a block.

effect is a noun.  affect is a verb so I think this change is correct.


> Sets the current position for the C routine on DIRHANDLE.  POS
> -must be a value returned by C.  Has the same caveats about
> -possible directory compaction as the corresponding system library
> +must be a value returned by C.  C also Has the same caveats
> +about possible directory compaction as the corresponding system library
>  routine.

s/Has/has/


> -You can effect a sleep of 250 milliseconds this way:
> +You can affect a sleep of 250 milliseconds this way:

This is correct.


>  the original quicksort was faster.  5.8 has a sort pragma for
>  limited control of the sort.  Its rather blunt control of the
> -underlying algorithm may not persist into future perls, but the
> +underlying algorithm may not persist into future Perls, but the
>  ability to characterize the input or output in implementation
>  independent ways quite probably will.  See L.

Perl is the language.  perl is the program.  Its a bit hazy which this is
talking about but I think it makes sense that the behavior of a module is
in a future version of the language.


-- 
Michael G Schwern [EMAIL PROTECTED] http://www.pobox.com/~schwern
Just call me 'Moron Sugar'.
http://www.somethingpositive.net/sp05182002.shtml

Re: [PATCH] perlfunc.pod grammar fixes

[Piotr Fusik]

I have doubts about the following changes:


 Note that the $year element is I simply the last two digits of
-the year.  If you assume it is, then you create non-Y2K-compliant
+the year.  If you assume it is and then you create non-Y2K-compliant
 programs--and you wouldn't want to do that, would you?

 Note that a block by itself is semantically identical to a loop
-that executes once.  Thus C can be used to effect an early
+that executes once.  Thus C can be used to affect an early
 exit out of such a block.
 
Sets the current position for the C routine on DIRHANDLE.  POS
-must be a value returned by C.  Has the same caveats about
-possible directory compaction as the corresponding system library
+must be a value returned by C.  C also Has the same caveats
+about possible directory compaction as the corresponding system library
 routine.

-You can effect a sleep of 250 milliseconds this way:
+You can affect a sleep of 250 milliseconds this way:

 the original quicksort was faster.  5.8 has a sort pragma for
 limited control of the sort.  Its rather blunt control of the
-underlying algorithm may not persist into future perls, but the
+underlying algorithm may not persist into future Perls, but the
 ability to characterize the input or output in implementation
 independent ways quite probably will.  See L.

[PATCH] perlfunc.pod grammar fixes

[Steve Peters]

This patch has it all:  passive voice removals; spelling fixes; which vs. 
that change; e.g. fixes; and etc.  Thanks to Pod::Simple::RTF and 
and handy grammar checker, this was all made much easier.  Enjoy!

Steve Peters
[EMAIL PROTECTED]
--- pod/perlfunc.pod.old2005-07-27 11:57:23.0 -0500
+++ pod/perlfunc.pod2005-07-27 21:55:46.0 -0500
@@ -25,7 +25,7 @@
 of scalar arguments or list values; the list values will be included
 in the list as if each individual element were interpolated at that
 point in the list, forming a longer single-dimensional list value.
-Elements of the LIST should be separated by commas.
+Commas should separate elements of the LIST.
 
 Any function in the list below may be used either with or without
 parentheses around its arguments.  (The syntax descriptions omit the
@@ -139,7 +139,7 @@
 C, C, C, C, C, C,
 C, C, C
 
-=item Keywords related to the control flow of your perl program
+=item Keywords related to the control flow of your Perl program
 
 C, C, C, C, C, C, C,
 C, C, C, C, C, C, C
@@ -337,7 +337,7 @@
 The C<-T> and C<-B> switches work as follows.  The first block or so of the
 file is examined for odd characters such as strange control codes or
 characters with the high bit set.  If too many strange characters (>30%)
-are found, it's a C<-B> file, otherwise it's a C<-T> file.  Also, any file
+are found, it's a C<-B> file; otherwise it's a C<-T> file.  Also, any file
 containing null in the first block is considered a binary file.  If C<-T>
 or C<-B> is used on a filehandle, the current IO buffer is examined
 rather than the first block.  Both C<-T> and C<-B> return true on a null
@@ -351,7 +351,7 @@
 a system call.  (This doesn't work with C<-t>, and you need to remember
 that lstat() and C<-l> will leave values in the stat structure for the
 symbolic link, not the real file.)  (Also, if the stat buffer was filled by
-a C call, C<-T> and C<-B> will reset it with the results of C).
+an C call, C<-T> and C<-B> will reset it with the results of C).
 Example:
 
 print "Can do.\n" if -r $a || -w _ || -x _;
@@ -368,7 +368,7 @@
 
 As of Perl 5.9.1, as a form of purely syntactic sugar, you can stack file
 test operators, in a way that C<-f -w -x $file> is equivalent to
-C<-x $file && -w _ && -f _>. (This is only syntax fancy : if you use
+C<-x $file && -w _ && -f _>. (This is only syntax fancy: if you use
 the return value of C<-f $file> as an argument to another filetest
 operator, no special magic will happen.)
 
@@ -394,7 +394,7 @@
 =item alarm
 
 Arranges to have a SIGALRM delivered to this process after the
-specified number of wallclock seconds have elapsed.  If SECONDS is not
+specified number of wallclock seconds has elapsed.  If SECONDS is not
 specified, the value stored in C<$_> is used. (On some machines,
 unfortunately, the elapsed time may be up to one second less or more
 than you specified because of how seconds are counted, and process
@@ -547,13 +547,13 @@
 in the CLASSNAME package.  If CLASSNAME is omitted, the current package
 is used.  Because a C is often the last thing in a constructor,
 it returns the reference for convenience.  Always use the two-argument
-version if the function doing the blessing might be inherited by a
-derived class.  See L and L for more about the blessing
-(and blessings) of objects.
+version if a derived class might inherit the function doing the blessing.
+See L and L for more about the blessing (and blessings)
+of objects.
 
 Consider always blessing objects in CLASSNAMEs that are mixed case.
 Namespaces with all lowercase names are considered reserved for
-Perl pragmata.  Builtin types have all uppercase names, so to prevent
+Perl pragmata.  Builtin types have all uppercase names. To prevent
 confusion, you may wish to avoid such package names as well.  Make sure
 that CLASSNAME is a true value.
 
@@ -844,8 +844,8 @@
 
 =item continue BLOCK
 
-Actually a flow control statement rather than a function.  If there is a
-C BLOCK attached to a BLOCK (typically in a C or
+C is actually a flow control statement rather than a function.  If
+there is a C BLOCK attached to a BLOCK (typically in a C or
 C), it is always executed just before the conditional is about to
 be evaluated again, just like the third part of a C loop in C.  Thus
 it can be used to increment a loop variable, even when the loop has been
@@ -887,7 +887,7 @@
 
 Creates a digest string exactly like the crypt(3) function in the C
 library (assuming that you actually have a version there that has not
-been extirpated as a potential munition).
+been extirpated as a potential munitions).
 
 crypt() is a one-way hash function.  The PLAINTEXT and SALT is turned
 into a short string, called a digest, which is returned.  The same
@@ -902,13 +902,13 @@
 primarily used to check if two pieces of text are the same without
 having to transmit or store the text itself.  An example is checking
 if a correct password is given.  The digest of the password is 

Re: [PATCH perlfunc.pod/crypt] crypt() digests, not encrypts

[Dave Mitchell]

On Tue, Jul 26, 2005 at 01:06:27AM -0700, Michael G Schwern wrote:
> Good point.  Originally that said "unsuitable for encrypting" so the
> explaination made a bit more sense.
> 
> I'd assume crypt() is unsuitable for large amounts of text because the
> hash size is too small and there's a significant risk of collision, espcially
> if its DES.  Anyone care to confirm?

I think the docs should really say that this function's only purpose is
for manipulating traditional UNIX-style password hashes, and that for any
use not requiring backwards-compatibility, they should instead use
something like Digest::MD5 (core) or Digest::SHA1 (non core).

-- 
A power surge on the Bridge is rapidly and correctly diagnosed as a faulty
capacitor by the highly-trained and competent engineering staff.
-- Things That Never Happen in "Star Trek" #9

Re: [PATCH perlfunc.pod/crypt] crypt() digests, not encrypts

[Gisle Aas]

Michael G Schwern <[EMAIL PROTECTED]> writes:

> I'd assume crypt() is unsuitable for large amounts of text because the
> hash size is too small and there's a significant risk of collision, espcially
> if its DES.  Anyone care to confirm?

I think it is because traditional versions of crypt would ignore any
but the first 8 characters of the text.  The 8 char limit is for
instance documented here:

   http://www.daemon-systems.org/man/crypt.3.html

--Gisle

Re: [PATCH perlfunc.pod/crypt] crypt() digests, not encrypts

[Michael G Schwern]

On Mon, Jul 25, 2005 at 03:30:52PM -0400, John L. Allen wrote:
> I thinks this last piece is confusing:
> 
>  The L function is unsuitable for hashing large quantities
>  of data, not least of all because you can't get the information
>  back.  Look at the L module for more robust algorithms.
> 
> Hashing is not done with the intent to get the data back, so that can't
> be the reason why crypt() is unsuitable.  Either state another reason
> - perhaps because it is too slow or doesn't easily allow hashing of an
> arbitrarily long string - or leave it unspecified.

Good point.  Originally that said "unsuitable for encrypting" so the
explaination made a bit more sense.

I'd assume crypt() is unsuitable for large amounts of text because the
hash size is too small and there's a significant risk of collision, espcially
if its DES.  Anyone care to confirm?


-- 
Michael G Schwern [EMAIL PROTECTED] http://www.pobox.com/~schwern
'All anyone gets in a mirror is themselves,' she said. 'But what you
gets in a good gumbo is everything.'
-- "Witches Abroad" by Terry Prachett

Re: [PATCH perlfunc.pod/crypt] crypt() digests, not encrypts

[John L. Allen]

I thinks this last piece is confusing:

 The L function is unsuitable for hashing large quantities
 of data, not least of all because you can't get the information
 back.  Look at the L module for more robust algorithms.

Hashing is not done with the intent to get the data back, so that can't
be the reason why crypt() is unsuitable.  Either state another reason
- perhaps because it is too slow or doesn't easily allow hashing of an
arbitrarily long string - or leave it unspecified.

Re: [PATCH perlfunc.pod/crypt] crypt() digests, not encrypts

[Michael G Schwern]

On Mon, Jul 25, 2005 at 11:21:24AM +0200, H.Merijn Brand wrote:
> > On Sun, Jul 24, 2005 at 02:03:31PM -0400, Ronald J Kimball wrote:
> > > Personally, I don't like the new documentation in this patch.  It seems to
> > > put the focus more on correcting the issue about encryption, rather than
> > > actually documenting what crypt() does.
> 
> I have applied the combo of these two as change #25220
> In the future I'd prefer a *new* patch that would overrule the first (unless
> that was already applied and acknowledged to the list). Now I had to apply
> the first before applying the second.

Ooops, I thought the second one was a combo.


-- 
Michael G Schwern [EMAIL PROTECTED] http://www.pobox.com/~schwern
Ahh email, my old friend.  Do you know that revenge is a dish that is best 
served cold?  And it is very cold on the Internet!

Re: [PATCH perlfunc.pod/crypt] crypt() digests, not encrypts

[H.Merijn Brand]

On Sun, 24 Jul 2005 13:49:25 -0700, Michael G Schwern <[EMAIL PROTECTED]>
wrote:

> On Sun, Jul 24, 2005 at 02:03:31PM -0400, Ronald J Kimball wrote:
> > Personally, I don't like the new documentation in this patch.  It seems to
> > put the focus more on correcting the issue about encryption, rather than
> > actually documenting what crypt() does.

I have applied the combo of these two as change #25220
In the future I'd prefer a *new* patch that would overrule the first (unless
that was already applied and acknowledged to the list). Now I had to apply
the first before applying the second.

> There's much less change then there seems from the patch.  Most of it is
> whitespace movement.  The 2nd and 3rd paragraphs are mostly new, expanding
> on points made in the original 2nd paragraph.  Everythig below paragraph #3
> is all but untouched.  The password example has been expanded to show how 
> having a one way crypt that doesn't work well with with large chunks of 
> data is useful.
> 
> It adds the particularly important points about crypt() that:
> 
> * The same PLAINTEXT and SALT will always return the same value
> * You cannot recover the PLAINTEXT from the digest
> * Small changes to the PLAINTEXT or SALT will result in large changes in
>   the digest.
> * The SALT is visible in the digest.
> * Its primarily used to check the equality of two strings when you don't
>   want to transmit those strings.
> 
> I think this better documents what crypt() does and how its useful without
> assuming the reader already understands hashing.
> 
> 
> > Furthermore, "extirpated" and "munition" in the opening paragraph?  The
> > perl documentation should be readable to people with various levels of
> > experience with programming and with English.  (Don't use a long word
> > where a diminutive one will do.)
> 
> Don't blame me, that was already there.  Its been there since 5.002.  I had 
> to look up extirpated, too.
> 
> 
> > In CS terms, I always thought of digest as a noun; as a verb it suggests
> > to me the intestines.  :) I would write something like "Creates a digest"
> > instead.
> 
> My verbing the "digest" noun results from trying to avoid "hashing".  The
> first paragraph is the only place that happens so I'll change it per
> your suggestion.
> 
> 
> > The second paragraph in the existing documentation seems to explain the
> > issue clearly anyway.
> 
> Sure it does, you have a CS background and already know what a digest is
> and how crypt works. :)
> 
> Attached is a patch with some improvements after reading it through again.
> 
> * Move the mentioning of Crypt modules on CPAN up to the point where we
>   explain crypt() is not about cryptography instead of at the end.
> * Mention Digest.pm rather than Crypt:: modules in the section about how
>   crypt() isn't a particuarly robust hashing algorithm because A) Digest
>   comes with Perl and B) we're talking about more robust digesting
>   algorithms, not encryption.
> * Explain why you feed the digest in as the salt a little better.
> * Stop verbing "digest".
> 
> 


-- 
H.Merijn BrandAmsterdam Perl Mongers (http://amsterdam.pm.org/)
using Perl 5.6.2, 5.8.0, 5.8.5, & 5.9.2  on HP-UX 10.20, 11.00 & 11.11,
 AIX 4.3 & 5.2, SuSE 9.2 & 9.3, and Cygwin. http://www.cmve.net/~merijn
Smoking perl: http://www.test-smoke.org,perl QA: http://qa.perl.org
 reports  to: [EMAIL PROTECTED],perl-qa@perl.org

Re: [PATCH] perlfunc.pod: s/definetely/definitely/

[H.Merijn Brand]

On Sun, 24 Jul 2005 12:55:09 +0200, "Piotr Fusik" <[EMAIL PROTECTED]> wrote:

> I googled "definetely" and it seems to be widely used.
> But I found this:
> http://wikitravel.org/en/Wikitravel:List_of_common_misspellings

My spell checker agreed. Typo changed in #25219

> --- perl-current/pod/perlfunc.pod Sun Jul 24 11:30:36 2005
> +++ perl-patched/pod/perlfunc.pod Sun Jul 24 12:26:12 2005
> @@ -3707,7 +3707,7 @@
>  platforms are using IEEE, there may be subtle differences.  Being able
>  to use C> or C> on floating point values can be very useful,
>  but also very dangerous if you don't know exactly what you're doing.
> -It is definetely not a general way to portably store floating point
> +It is definitely not a general way to portably store floating point
>  values.
>  
>  When using C> or C> on an C<()>-group, this will affect

-- 
H.Merijn BrandAmsterdam Perl Mongers (http://amsterdam.pm.org/)
using Perl 5.6.2, 5.8.0, 5.8.5, & 5.9.2  on HP-UX 10.20, 11.00 & 11.11,
 AIX 4.3 & 5.2, SuSE 9.2 & 9.3, and Cygwin. http://www.cmve.net/~merijn
Smoking perl: http://www.test-smoke.org,perl QA: http://qa.perl.org
 reports  to: [EMAIL PROTECTED],perl-qa@perl.org

Re: [PATCH perlfunc.pod/crypt] crypt() digests, not encrypts

[Michael G Schwern]

On Sun, Jul 24, 2005 at 11:09:12PM -0400, Ronald J Kimball wrote:
> Cool.  I apologize for complaining about the parts that were already
> there.

You only have to apologize if you don't provide a patch. ;)


-- 
Michael G Schwern [EMAIL PROTECTED] http://www.pobox.com/~schwern
Just call me 'Moron Sugar'.
http://www.somethingpositive.net/sp05182002.shtml

Re: [PATCH perlfunc.pod/crypt] crypt() digests, not encrypts

[Ronald J Kimball]

On Sun, Jul 24, 2005 at 01:49:25PM -0700, Michael G Schwern wrote:

> Attached is a patch with some improvements after reading it through again.
> 
> * Move the mentioning of Crypt modules on CPAN up to the point where we
>   explain crypt() is not about cryptography instead of at the end.
> * Mention Digest.pm rather than Crypt:: modules in the section about how
>   crypt() isn't a particuarly robust hashing algorithm because A) Digest
>   comes with Perl and B) we're talking about more robust digesting
>   algorithms, not encryption.
> * Explain why you feed the digest in as the salt a little better.
> * Stop verbing "digest".

Cool.  I apologize for complaining about the parts that were already
there.

Ronald

Re: [PATCH perlfunc.pod/crypt] crypt() digests, not encrypts

[Michael G Schwern]

On Sun, Jul 24, 2005 at 02:03:31PM -0400, Ronald J Kimball wrote:
> Personally, I don't like the new documentation in this patch.  It seems to
> put the focus more on correcting the issue about encryption, rather than
> actually documenting what crypt() does.

There's much less change then there seems from the patch.  Most of it is
whitespace movement.  The 2nd and 3rd paragraphs are mostly new, expanding on
points made in the original 2nd paragraph.  Everythig below paragraph #3 is
all but untouched.  The password example has been expanded to show how 
having a one way crypt that doesn't work well with with large chunks of 
data is useful.

It adds the particularly important points about crypt() that:

* The same PLAINTEXT and SALT will always return the same value
* You cannot recover the PLAINTEXT from the digest
* Small changes to the PLAINTEXT or SALT will result in large changes in
  the digest.
* The SALT is visible in the digest.
* Its primarily used to check the equality of two strings when you don't
  want to transmit those strings.

I think this better documents what crypt() does and how its useful without
assuming the reader already understands hashing.


> Furthermore, "extirpated" and "munition" in the opening paragraph?  The
> perl documentation should be readable to people with various levels of
> experience with programming and with English.  (Don't use a long word where
> a diminutive one will do.)

Don't blame me, that was already there.  Its been there since 5.002.  I had 
to look up extirpated, too.


> In CS terms, I always thought of digest as a noun; as a verb it suggests to
> me the intestines.  :) I would write something like "Creates a digest"
> instead.

My verbing the "digest" noun results from trying to avoid "hashing".  The
first paragraph is the only place that happens so I'll change it per
your suggestion.


> The second paragraph in the existing documentation seems to explain the
> issue clearly anyway.

Sure it does, you have a CS background and already know what a digest is
and how crypt works. :)

Attached is a patch with some improvements after reading it through again.

* Move the mentioning of Crypt modules on CPAN up to the point where we
  explain crypt() is not about cryptography instead of at the end.
* Mention Digest.pm rather than Crypt:: modules in the section about how
  crypt() isn't a particuarly robust hashing algorithm because A) Digest
  comes with Perl and B) we're talking about more robust digesting
  algorithms, not encryption.
* Explain why you feed the digest in as the salt a little better.
* Stop verbing "digest".


-- 
Michael G Schwern [EMAIL PROTECTED] http://www.pobox.com/~schwern
Just call me 'Moron Sugar'.
http://www.somethingpositive.net/sp05182002.shtml
--- pod/perlfunc.pod2005/07/24 02:57:16 1.2
+++ pod/perlfunc.pod2005/07/24 20:39:44
@@ -885,31 +885,35 @@
 
 =item crypt PLAINTEXT,SALT
 
-Digests a string exactly like the crypt(3) function in the C library
-(assuming that you actually have a version there that has not been
-extirpated as a potential munition).
+Creates a digest string exactly like the crypt(3) function in the C
+library (assuming that you actually have a version there that has not
+been extirpated as a potential munition).
 
 crypt() is a one-way hash function.  The PLAINTEXT and SALT is turned
-into a short, fixed length string, called a digest, which is returned.
-The same PLAINTEXT and SALT will always return the same string, but
-there is no (known) way to get the original PLAINTEXT from the hash.
-The SALT is visible as part of the digest.  Small changes in the
-PLAINTEXT will result in large changes in the hash.
+into a short string, called a digest, which is returned.  The same
+PLAINTEXT and SALT will always return the same string, but there is no
+(known) way to get the original PLAINTEXT from the hash.  Small
+changes in the PLAINTEXT or SALT will result in large changes in the
+digest.
 
 There is no decrypt function.  This function isn't all that useful for
-cryptography (for that, see your nearby CPAN mirror) and the name
-"crypt" is a bit of a misnomer.  Instead it is primarily used to check
-if two pieces of text are the same without having to transmit or store
-the text itself.  An example is checking if a correct password is
-given.  The digest of the password is stored, not the password itself.
-The user types in a password which is crypt()'d with the same salt as
-the stored digest.  If the two digests match the password is correct.
+cryptography (for that, look for F modules on your nearby CPAN
+mirror) and the name "crypt" is a bit of a misnomer.  Instead it is
+primarily used to check if two pieces of text are the same without
+having to transmit or store the text itself.  An example is checking
+if a correct password is given.  The digest of the password is stored,
+not the password itself.  The user types in a password which is
+crypt()'d with the same salt as the stored 

Re: [PATCH perlfunc.pod/crypt] crypt() digests, not encrypts

[Ronald J Kimball]

On Sat, Jul 23, 2005 at 05:25:18PM -0700, Michael G Schwern wrote:
> Attached is a patch which replaces the term "encrypt" in the perlfunc/crypt
> documentation with "digest" or "hash" which more accurately describes what
> crypt does.  I also added in some better explaination of what crypt does and
> what one-way hashing is useful for.
> 
> I tried to avoid "hash" where possible to avoid confusion with the hash
> data structure.  Even though they are related it would just confuse things.
> 
> Below is the new documentation after patching.

Personally, I don't like the new documentation in this patch.  It seems to
put the focus more on correcting the issue about encryption, rather than
actually documenting what crypt() does.

Furthermore, "extirpated" and "munition" in the opening paragraph?  The
perl documentation should be readable to people with various levels of
experience with programming and with English.  (Don't use a long word where
a diminutive one will do.)

In CS terms, I always thought of digest as a noun; as a verb it suggests to
me the intestines.  :) I would write something like "Creates a digest"
instead.

The second paragraph in the existing documentation seems to explain the
issue clearly anyway.

Ronald

[PATCH] perlfunc.pod: s/definetely/definitely/

[Piotr Fusik]

I googled "definetely" and it seems to be widely used.
But I found this:
http://wikitravel.org/en/Wikitravel:List_of_common_misspellings


--- perl-current/pod/perlfunc.pod Sun Jul 24 11:30:36 2005
+++ perl-patched/pod/perlfunc.pod Sun Jul 24 12:26:12 2005
@@ -3707,7 +3707,7 @@
 platforms are using IEEE, there may be subtle differences.  Being able
 to use C> or C> on floating point values can be very useful,
 but also very dangerous if you don't know exactly what you're doing.
-It is definetely not a general way to portably store floating point
+It is definitely not a general way to portably store floating point
 values.
 
 When using C> or C> on an C<()>-group, this will affect

Re: [PATCH] perlfunc.pod

[Piotr Fusik]

> > [...] I wanted to clarify that do {}
> > isn't special for "for"/"foreach" modifiers
> > (they are loop modifiers, aren't they?).
> 
> Good point.  I guess they are.
> 
--- perl-current/pod/perlfunc.pod Sun Jul 24 11:30:36 2005
+++ perl-patched/pod/perlfunc.pod Sun Jul 24 11:38:16 2005
@@ -1220,8 +1220,8 @@
 =item do BLOCK
 
 Not really a function.  Returns the value of the last command in the
-sequence of commands indicated by BLOCK.  When modified by a loop
-modifier, executes the BLOCK once before testing the loop condition.
+sequence of commands indicated by BLOCK.  When modified by C or C
+loop modifier, executes the BLOCK once before testing the loop condition.
 (On other statements the loop modifiers test the conditional first.)
 
 C does I count as a loop, so the loop control statements

[PATCH perlfunc.pod/crypt] crypt() digests, not encrypts

[Michael G Schwern]

Attached is a patch which replaces the term "encrypt" in the perlfunc/crypt
documentation with "digest" or "hash" which more accurately describes what
crypt does.  I also added in some better explaination of what crypt does and
what one-way hashing is useful for.

I tried to avoid "hash" where possible to avoid confusion with the hash
data structure.  Even though they are related it would just confuse things.

Below is the new documentation after patching.


=item crypt PLAINTEXT,SALT 
 
Digests a string exactly like the crypt(3) function in the C library 
(assuming that you actually have a version there that has not been 
extirpated as a potential munition). 
 
crypt() is a one-way hash function.  The PLAINTEXT and SALT is turned 
into a short, fixed length string, called a digest, which is returned. 
The same PLAINTEXT and SALT will always return the same string, but 
there is no (known) way to get the original PLAINTEXT from the hash. 
The SALT is visible as part of the digest.  Small changes in the 
PLAINTEXT will result in large changes in the hash. 
 
There is no decrypt function.  This function isn't all that useful for 
cryptography (for that, see your nearby CPAN mirror) and the name 
"crypt" is a bit of a misnomer.  Instead it is primarily used to check 
if two pieces of text are the same without having to transmit or store 
the text itself.  An example is checking if a correct password is 
given.  The digest of the password is stored, not the password itself. 
The user types in a password which is crypt()'d with the same salt as 
the stored digest.  If the two digests match the password is correct. 
 
When verifying an existing digest string you should use the digest as 
the salt (like C).  This allows 
your code to work with the standard L and with more 
exotic implementations.  In other words, do not assume anything about 
the returned string itself, or how many bytes in the digest matter. 
 
Traditionally the result is a string of 13 bytes: two first bytes of 
the salt, followed by 11 bytes from the set C<[./0-9A-Za-z]>, and only 
the first eight bytes of the digest string mattered, but alternative 
hashing schemes (like MD5), higher level security schemes (like C2), 
and implementations on non-UNIX platforms may produce different 
strings. 
 
When choosing a new salt create a random two character string whose 
characters come from the set C<[./0-9A-Za-z]> (like C).  This set of 
characters is just a recommendation; the characters allowed in 
the salt depend solely on your system's crypt library, and Perl can't 
restrict what salts C accepts. 
 
Here's an example that makes sure that whoever runs this program knows 
their own password: 

$pwd = (getpwuid($<))[1]; 
 
system "stty -echo"; 
print "Password: "; 
chomp($word = ); 
print "\n"; 
system "stty echo"; 
 
if (crypt($word, $pwd) ne $pwd) { 
die "Sorry...\n"; 
} else { 
print "ok\n"; 
} 
 
Of course, typing in your own password to whoever asks you 
for it is unwise. 
 
The L function is unsuitable for hashing large quantities 
of data, not least of all because you can't get the information 
back.  Look at the F and F directories 
on your favorite CPAN mirror for a slew of potentially useful 
modules. 
 
If using crypt() on a Unicode string (which I has 
characters with codepoints above 255), Perl tries to make sense 
of the situation by trying to downgrade (a copy of the string) 
the string back to an eight-bit byte string before calling crypt() 
(on that copy).  If that works, good.  If not, crypt() dies with 
C. 


-- 
Michael G Schwern [EMAIL PROTECTED] http://www.pobox.com/~schwern
Just call me 'Moron Sugar'.
http://www.somethingpositive.net/sp05182002.shtml
--- pod/perlfunc.pod2005/07/24 00:04:05 1.1
+++ pod/perlfunc.pod2005/07/24 00:24:01
@@ -885,31 +885,38 @@
 
 =item crypt PLAINTEXT,SALT
 
-Encrypts a string exactly like the crypt(3) function in the C library
+Digests a string exactly like the crypt(3) function in the C library
 (assuming that you actually have a version there that has not been
-extirpated as a potential munition).  This can prove useful for checking
-the password file for lousy passwords, amongst other things.  Only the
-guys wearing white hats should do this.
-
-Note that L is intended to be a one-way function, much like
-breaking eggs to make an omelette.  There is no (known) corresponding
-decrypt function (in other words, the crypt() is a one-way hash
-function).  As a result, this function isn't all that useful for
-cryptography.  (For that, see your nearby CPAN mirror.)
-
-When verifying an existing encrypted string you should use the
-encrypted text as the salt (like C).  This allows your code to work with the standard L
-and with more exotic implementations.  In other words, do not assume
-anything about the returned string itself, or how many bytes in
-the encrypted string matter.
+extirpated as a potential munition).
+
+cryp

Re: [PATCH] perlfunc.pod

[Russ Allbery]

Scott R Godin <[EMAIL PROTECTED]> writes:

> Firefox is merely being kind to all the silly web-authors out there who
> think it's a good idea to send XHTML as text/html instead of
> application/xhtml+xml because the latter breaks in nearly every browser
> due to the fact that they aren't prepared to handle XHTML as it was
> meant to be delivered. EVERYONE jumped on this way too early.

My opinion is at  for anyone
who cares.  In general, I mostly agree with you, but the software I write
for my own purposes all generates XHTML and will continue to do so.

-- 
Russ Allbery ([EMAIL PROTECTED]) 

Re: [PATCH] perlfunc.pod

[Scott R. Godin]

Rafael Garcia-Suarez wrote:

On 7/19/05, Michael G Schwern <[EMAIL PROTECTED]> wrote:



It would probably be better to evaluate the existing POD -> HTML converters
and wrap POD::Html around them, or just leave POD::Html alone and convert
installhtml to use the better module, than to write Yet Another POD -> HTML
Module.


I can think about a couple of points :
* state of the art of html documentation has greatly improved since
the perl 5.000 days. Pod::Html generates obsolete html (old syntax, no
CSS support, etc.)
* Pod::Html is barely usable, making a good pod->html translator now
would mean designing a more complete and probably incompatible
interface.
* People have hacked around the limitations of Pod::Html that were the
most annoying, and probably post-process its output. It's html, they
want eye-candy and stuff that looks like search.cpan.org. OK, that's a
weird backwards-compatibility argument.

In short, my opinion would be to leave Pod::Html alone, fixing the
most obvious bugs, and slowly deprecating it in favor of the next big
thing.


Pod::Html4 anyone? :)


PS. /me discovers that Pod::Xhtml is a module brought to you by the BBC :)


heehee :D

Re: [PATCH] perlfunc.pod

[Scott R. Godin]

Russ Allbery wrote:

Scott R Godin <[EMAIL PROTECTED]> writes:


There's only one real problem with that, however.



Sending XHTML as text/html means the browser is expecting tag-soup. NOT
XHTML..


This is not true if you use XHTML 1.0.  Try it in Firefox.  You'll see
that the browser reports that it's in standards compliance mode.


Firefox is merely being kind to all the silly web-authors out there who 
think it's a good idea to send XHTML as text/html instead of 
application/xhtml+xml because the latter breaks in nearly every browser 
due to the fact that they aren't prepared to handle XHTML as it was 
meant to be delivered. EVERYONE jumped on this way too early.



That being said, there really isn't much of a reason to use XHTML rather
than HTML 4.0 unless one just wants to for personal reasons.  I use it for
my own reasons, but it's primarily as a science experiment, and it's
probably not the right mode to run general software in.


can't disagree with you there... :)

Re: [PATCH] perlfunc.pod

[Joshua Juran]

On Jul 19, 2005, at 1:35 PM, Russ Allbery wrote:


Scott R Godin <[EMAIL PROTECTED]> writes:

Sending XHTML as text/html means the browser is expecting tag-soup. 
NOT

XHTML..


This is not true if you use XHTML 1.0.  Try it in Firefox.  You'll see
that the browser reports that it's in standards compliance mode.


I recommend Appendix C of the XHTML spec:

HTML Compatibility Guidelines


That being said, there really isn't much of a reason to use XHTML 
rather
than HTML 4.0 unless one just wants to for personal reasons.  I use it 
for

my own reasons, but it's primarily as a science experiment, and it's
probably not the right mode to run general software in.


I've been developing an HTML output library that I use with mod_perl 
for my work.  Its usage rather resembles the functional interface of 
CGI, but the output is a hierarchical structure of Perl 5 objects.  
Calling the root's (or any node's) Print method pretty-prints the 
entire document (or just that node).  Currently it generates XHTML, but 
it would be trivial to adjust it to produce HTML 4 instead.  This 
decision could be made at runtime through a parameter to Print.


This would be a way to separate the production of an HTML document 
structure from the actual markup generation.  If somebody's interested, 
I'll post it.


Josh

--
Joshua Juran
Metamage Software Creations - Mac Software and Consulting
http://www.metamage.com/

   * Creation at the highest state of the art *

Re: [PATCH] perlfunc.pod

[Rafael Garcia-Suarez]

On 7/19/05, Adriano Ferreira <[EMAIL PROTECTED]> wrote:
> On 7/19/05, Nicholas Clark <[EMAIL PROTECTED]> wrote:
> > But that doesn't rule out creating a minimal wrapper to provide Pod::Html's
> > interface.
> 
> But that would imply that wrapped modules should enter the Perl
> distribution, because Pod::Html is core. Right?

Moreover, installhtml is core :)

Re: [PATCH] perlfunc.pod

[Adriano Ferreira]

On 7/19/05, Nicholas Clark <[EMAIL PROTECTED]> wrote:
> But that doesn't rule out creating a minimal wrapper to provide Pod::Html's
> interface.

But that would imply that wrapped modules should enter the Perl
distribution, because Pod::Html is core. Right?

Adriano.

Re: [PATCH] perlfunc.pod

[Nicholas Clark]

On Tue, Jul 19, 2005 at 08:59:33PM +0200, Rafael Garcia-Suarez wrote:
> On 7/19/05, Michael G Schwern <[EMAIL PROTECTED]> wrote:
> > On Tue, Jul 19, 2005 at 11:31:01AM -0400, Scott R. Godin wrote:
> > > I've had this itch to rip Pod::Html to shreds for a while now, and
> > > refactor it to do the job more cleanly. Would anyone object to my taking
> > > a whack at it?
> > 
> > It would probably be better to evaluate the existing POD -> HTML converters
> > and wrap POD::Html around them, or just leave POD::Html alone and convert
> > installhtml to use the better module, than to write Yet Another POD -> HTML
> > Module.
> 
> I can think about a couple of points :
> * state of the art of html documentation has greatly improved since
> the perl 5.000 days. Pod::Html generates obsolete html (old syntax, no
> CSS support, etc.)
> * Pod::Html is barely usable, making a good pod->html translator now
> would mean designing a more complete and probably incompatible
> interface.

But that doesn't rule out creating a minimal wrapper to provide Pod::Html's
interface.

> * People have hacked around the limitations of Pod::Html that were the
> most annoying, and probably post-process its output. It's html, they
> want eye-candy and stuff that looks like search.cpan.org. OK, that's a
> weird backwards-compatibility argument.

On the other hand, I'm quite happy to ignore anyone who gets too upset by
their post-processing going awry. Pod::Html is documented as returning HTML.
Not the specific current output it creates.

> In short, my opinion would be to leave Pod::Html alone, fixing the
> most obvious bugs, and slowly deprecating it in favor of the next big
> thing.

I prefer Schwern's suggestion. Then again, I'm not proposing to volunteer.
my own labour here, so ultimately the choice is someone else's.

But I don't think that refactoring the existing Pod::Html to create yet
another convertor is the way to go.

Nicholas Clark

Re: [PATCH] perlfunc.pod

[Scott R. Godin]

Michael G Schwern wrote:

On Mon, Jul 18, 2005 at 02:41:30PM -0400, Scott R. Godin wrote:

FAR better would be to use HTML 4.01 Strict instead of XHTML unless you 
(because of MathML or some other such) know WHY you need it.



Ok, is there a decent POD -> HTML 4.01 Strict module out there?




oh, one additional thought.. the current Pod::Html might be better 
renamed as Pod::XHtml.. no? :)

Re: [PATCH] perlfunc.pod

[Rafael Garcia-Suarez]

On 7/19/05, Michael G Schwern <[EMAIL PROTECTED]> wrote:
> On Tue, Jul 19, 2005 at 11:31:01AM -0400, Scott R. Godin wrote:
> > I've had this itch to rip Pod::Html to shreds for a while now, and
> > refactor it to do the job more cleanly. Would anyone object to my taking
> > a whack at it?
> 
> It would probably be better to evaluate the existing POD -> HTML converters
> and wrap POD::Html around them, or just leave POD::Html alone and convert
> installhtml to use the better module, than to write Yet Another POD -> HTML
> Module.

I can think about a couple of points :
* state of the art of html documentation has greatly improved since
the perl 5.000 days. Pod::Html generates obsolete html (old syntax, no
CSS support, etc.)
* Pod::Html is barely usable, making a good pod->html translator now
would mean designing a more complete and probably incompatible
interface.
* People have hacked around the limitations of Pod::Html that were the
most annoying, and probably post-process its output. It's html, they
want eye-candy and stuff that looks like search.cpan.org. OK, that's a
weird backwards-compatibility argument.

In short, my opinion would be to leave Pod::Html alone, fixing the
most obvious bugs, and slowly deprecating it in favor of the next big
thing.

PS. /me discovers that Pod::Xhtml is a module brought to you by the BBC :)

Re: [PATCH] perlfunc.pod

[Michael G Schwern]

On Tue, Jul 19, 2005 at 11:31:01AM -0400, Scott R. Godin wrote:
> I've had this itch to rip Pod::Html to shreds for a while now, and 
> refactor it to do the job more cleanly. Would anyone object to my taking 
> a whack at it?

It would probably be better to evaluate the existing POD -> HTML converters
and wrap POD::Html around them, or just leave POD::Html alone and convert
installhtml to use the better module, than to write Yet Another POD -> HTML
Module.


-- 
Michael G Schwern [EMAIL PROTECTED] http://www.pobox.com/~schwern
Reality is that which, when you stop believing in it, doesn't go away.
-- Phillip K. Dick

Re: [PATCH] perlfunc.pod

[Scott R. Godin]

Michael G Schwern wrote:

On Mon, Jul 18, 2005 at 02:41:30PM -0400, Scott R. Godin wrote:

FAR better would be to use HTML 4.01 Strict instead of XHTML unless you 
(because of MathML or some other such) know WHY you need it.



Ok, is there a decent POD -> HTML 4.01 Strict module out there?


If the XHTML produced currently would pass a validation test, then it's 
highly likely that as HTML 4.01 Strict, it would also pass (provided one 
 removes the ' />' style tag-endings from things like '', etc.


However, I know that CGI.pm (which IIRC is part of the core) is 
perfectly capable of producing clean well-formed html, (though the 
default !DOCTYPE used by it is HTML 4.01 Transitional) through its 
function-oriented interface. (which in a quite nifty fashion, has the 
added benefit of *looking* almost like html, making it far easier to 
debug, too.)


I've had this itch to rip Pod::Html to shreds for a while now, and 
refactor it to do the job more cleanly. Would anyone object to my taking 
a whack at it?

Re: [PATCH] perlfunc.pod

[Russ Allbery]

Scott R Godin <[EMAIL PROTECTED]> writes:

> There's only one real problem with that, however.

> Sending XHTML as text/html means the browser is expecting tag-soup. NOT
> XHTML..

This is not true if you use XHTML 1.0.  Try it in Firefox.  You'll see
that the browser reports that it's in standards compliance mode.

That being said, there really isn't much of a reason to use XHTML rather
than HTML 4.0 unless one just wants to for personal reasons.  I use it for
my own reasons, but it's primarily as a science experiment, and it's
probably not the right mode to run general software in.

-- 
Russ Allbery ([EMAIL PROTECTED]) 

Re: [PATCH] perlfunc.pod

[Michael G Schwern]

On Mon, Jul 18, 2005 at 02:41:30PM -0400, Scott R. Godin wrote:
> FAR better would be to use HTML 4.01 Strict instead of XHTML unless you 
> (because of MathML or some other such) know WHY you need it.

Ok, is there a decent POD -> HTML 4.01 Strict module out there?


-- 
Michael G Schwern [EMAIL PROTECTED] http://www.pobox.com/~schwern
Ahh email, my old friend.  Do you know that revenge is a dish that is best 
served cold?  And it is very cold on the Internet!

Re: [PATCH] perlfunc.pod

[Scott R. Godin]

Offer Kaye wrote:

On 7/12/05, Michael G Schwern wrote:


Patch Pod::Html?  Sorry, I have to.. umm.. I have to rearrange my sock
drawer.  On Pluto.




As an alternative to taking long interplanetary trips, consider using
Pod::Xhtml instead of Pod::Html. It's better. Really.

Cheers,


There's only one real problem with that, however.

Sending XHTML as text/html means the browser is expecting tag-soup. NOT 
XHTML..


sending it properly as application/xhtml+xml means MSIE can't understand 
it *at all*. (MSIE 6 doesn't grok xml, period)


FAR better would be to use HTML 4.01 Strict instead of XHTML unless you 
(because of MathML or some other such) know WHY you need it.


further detailed exposition: http://hixie.ch/advocacy/xhtml

Re: [PATCH] perlfunc.pod

[Michael G Schwern]

On Sat, Jul 16, 2005 at 11:43:48AM +0300, Offer Kaye wrote:
> As an alternative to taking long interplanetary trips, consider using
> Pod::Xhtml instead of Pod::Html. It's better. Really.

Maybe we should consider emborging this or another POD -> HTML converter to
finally end Pod::Html's Reign of Terror.

If only there was a POD KOMMISSAR here to help us decide!


-- 
Michael G Schwern [EMAIL PROTECTED] http://www.pobox.com/~schwern
'All anyone gets in a mirror is themselves,' she said. 'But what you
gets in a good gumbo is everything.'
-- "Witches Abroad" by Terry Prachett

Re: [PATCH] perlfunc.pod

[Offer Kaye]

On 7/12/05, Michael G Schwern wrote:
> 
> Patch Pod::Html?  Sorry, I have to.. umm.. I have to rearrange my sock
> drawer.  On Pluto.
> 

As an alternative to taking long interplanetary trips, consider using
Pod::Xhtml instead of Pod::Html. It's better. Really.

Cheers,
-- 
Offer Kaye

Re: [PATCH] perlfunc.pod

[Scott R. Godin]

Michael G Schwern wrote:

On Tue, Jul 12, 2005 at 08:55:33AM +0100, Steve Hay wrote:


Didn't we conclude it would be better to give Pod::Html the same foo()
recognition magic that Pod::Man has and not have to put C<> around every
function?



Patches welcome!



Patch Pod::Html?  Sorry, I have to.. umm.. I have to rearrange my sock 
drawer.  On Pluto.




Whoof, you ain't jokin', Son. I looked in there briefly, awhile back, 
while looking over the Pod::Pdf and pod2html/Pod::Html docs to see if I 
could re-do a better version of pod2pdf but gave it up. THEN I looked 
closer at Pod::Html =8-o


with CGI.pm being part of the perl core, it would seem to me to make far 
more sense to take advantage of its ability (with the function-oriented 
interface) to generate clean html on the fly, as part of the refactoring.


I mean, it WOULD be really swell to have clean & compliant 'html 4.01 
Strict' (+ inline/external CSS2) doc generation... :)


um.. yeah.. I'll be .. right back.. sometime. :)

Re: [PATCH] perlfunc.pod

[Michael G Schwern]

On Tue, Jul 12, 2005 at 08:55:33AM +0100, Steve Hay wrote:
> >Didn't we conclude it would be better to give Pod::Html the same foo()
> >recognition magic that Pod::Man has and not have to put C<> around every
> >function?
> >
> Patches welcome!

Patch Pod::Html?  Sorry, I have to.. umm.. I have to rearrange my sock 
drawer.  On Pluto.

-- 
Michael G Schwern [EMAIL PROTECTED] http://www.pobox.com/~schwern
Just call me 'Moron Sugar'.
http://www.somethingpositive.net/sp05182002.shtml

Re: [PATCH] perlfunc.pod

[Steve Hay]

Michael G Schwern wrote:

>On Mon, Jul 11, 2005 at 04:45:39PM +0100, Steve Hay wrote:
>  
>
>>OTOH, functions are perhaps better written as C because this 
>>causes them to be linked when converted to HTML.
>>
>>
>
>Didn't we conclude it would be better to give Pod::Html the same foo()
>recognition magic that Pod::Man has and not have to put C<> around every
>function?
>
Patches welcome!




Radan Computational Ltd.

The information contained in this message and any files transmitted with it are 
confidential and intended for the addressee(s) only.  If you have received this 
message in error or there are any problems, please notify the sender 
immediately.  The unauthorized use, disclosure, copying or alteration of this 
message is strictly forbidden.  Note that any views or opinions presented in 
this email are solely those of the author and do not necessarily represent 
those of Radan Computational Ltd.  The recipient(s) of this message should 
check it and any attached files for viruses: Radan Computational will accept no 
liability for any damage caused by any virus transmitted by this email.

Re: [PATCH] perlfunc.pod

[Michael G Schwern]

On Mon, Jul 11, 2005 at 09:15:51PM +0200, Piotr Fusik wrote:
> > -sequence of commands indicated by BLOCK.  When modified by a loop
> > +sequence of commands indicated by BLOCK.  When modified by the
> C loop
> >
> > Which isn't true.  do handles both "while" and "until".  I think the
> original
> > wording should hold.  Possibly perlsyn clarifies what a "loop
> modifier" is.
>
> Oh, I just forgot about "until". But I wanted to clarify that do {}
> isn't special for "for"/"foreach" modifiers
> (they are loop modifiers, aren't they?).

Good point.  I guess they are.

-- 
Michael G Schwern [EMAIL PROTECTED] http://www.pobox.com/~schwern
'All anyone gets in a mirror is themselves,' she said. 'But what you
gets in a good gumbo is everything.'
-- "Witches Abroad" by Terry Prachett

Re: [PATCH] perlfunc.pod

[Michael G Schwern]

On Mon, Jul 11, 2005 at 09:29:27PM +0200, Piotr Fusik wrote:
> > Didn't we conclude it would be better to give Pod::Html the same foo()
> > recognition magic that Pod::Man has and not have to put C<> around
> every
> > function?
>
> ActivePerl HTMLs have links to functions even where there are no
> surrounding C<>.
> There is a small drawback, however: "element(s)" appears as a link.

Pod::Man takes the more conservative approach and only italizes foo() and
not foo(arg).

foo(\d[a-z]*) is also given special treatment and considered to be a man 
page.  It also puts simple variables $foo @foo and %foo in a fixed-width
font.

These extra transforms are in the appropriately named Pod::Man::guesswork().


-- 
Michael G Schwern [EMAIL PROTECTED] http://www.pobox.com/~schwern
'All anyone gets in a mirror is themselves,' she said. 'But what you
gets in a good gumbo is everything.'
-- "Witches Abroad" by Terry Prachett

Re: [PATCH] perlfunc.pod

[Piotr Fusik]

> Didn't we conclude it would be better to give Pod::Html the same foo()
> recognition magic that Pod::Man has and not have to put C<> around
every
> function?
>
ActivePerl HTMLs have links to functions even where there are no
surrounding C<>.
There is a small drawback, however: "element(s)" appears as a link.

Re: [PATCH] perlfunc.pod

[Piotr Fusik]

> -sequence of commands indicated by BLOCK.  When modified by a loop
> +sequence of commands indicated by BLOCK.  When modified by the
C loop
>
> Which isn't true.  do handles both "while" and "until".  I think the
original
> wording should hold.  Possibly perlsyn clarifies what a "loop
modifier" is.
>
Oh, I just forgot about "until". But I wanted to clarify that do {}
isn't special for "for"/"foreach" modifiers
(they are loop modifiers, aren't they?).

Re: [PATCH] perlfunc.pod

[Michael G Schwern]

On Mon, Jul 11, 2005 at 04:45:39PM +0100, Steve Hay wrote:
> OTOH, functions are perhaps better written as C because this 
> causes them to be linked when converted to HTML.

Didn't we conclude it would be better to give Pod::Html the same foo()
recognition magic that Pod::Man has and not have to put C<> around every
function?


-- 
Michael G Schwern [EMAIL PROTECTED] http://www.pobox.com/~schwern
'All anyone gets in a mirror is themselves,' she said. 'But what you
gets in a good gumbo is everything.'
-- "Witches Abroad" by Terry Prachett

Re: [PATCH] perlfunc.pod

[Steve Hay]

Piotr Fusik wrote:

>Here are some cosmetic changes of perlfunc:
>
>1. Documented no-operand versions of chdir, eval, exit, gmtime.
>2. Normalized C to foo().
>3. Normalized $foo to C<$foo>.
>4. Changed "=item import" to "=item import (LIST)".
>
A recent discussion on this list concluded that variables are currently 
best written in POD as simply $foo, not C<$foo> (nor I<$foo> as used to 
be recommended in perlpod).

OTOH, functions are perhaps better written as C because this 
causes them to be linked when converted to HTML.

So I've applied parts 1. and 4. above as change 25112.  Thanks.




Radan Computational Ltd.

The information contained in this message and any files transmitted with it are 
confidential and intended for the addressee(s) only.  If you have received this 
message in error or there are any problems, please notify the sender 
immediately.  The unauthorized use, disclosure, copying or alteration of this 
message is strictly forbidden.  Note that any views or opinions presented in 
this email are solely those of the author and do not necessarily represent 
those of Radan Computational Ltd.  The recipient(s) of this message should 
check it and any attached files for viruses: Radan Computational will accept no 
liability for any damage caused by any virus transmitted by this email.

Re: [PATCH] perlfunc.pod

[Michael G Schwern]

On Sat, Jul 09, 2005 at 04:21:05PM +0200, Piotr Fusik wrote:
> Here are some cosmetic changes of perlfunc:
> 
> 1. Documented no-operand versions of chdir, eval, exit, gmtime.
> 2. Normalized C to foo().
> 3. Normalized $foo to C<$foo>.
> 4. Changed "=item import" to "=item import (LIST)".

This isn't all that was done.  I see an additional change right away:

@@ -1198,7 +1200,7 @@
 =item do BLOCK
 
 Not really a function.  Returns the value of the last command in the
-sequence of commands indicated by BLOCK.  When modified by a loop
+sequence of commands indicated by BLOCK.  When modified by the C loop
 modifier, executes the BLOCK once before testing the loop condition.
 (On other statements the loop modifiers test the conditional first.)
 

Which isn't true.  do handles both "while" and "until".  I think the original
wording should hold.  Possibly perlsyn clarifies what a "loop modifier" is.

To avoid slips like this in the future, broad formatting changes should be 
provided separate of any other changes.  Several smaller, simpler patches 
are easier to review.


-- 
Michael G Schwern [EMAIL PROTECTED] http://www.pobox.com/~schwern
Reality is that which, when you stop believing in it, doesn't go away.
-- Phillip K. Dick

[PATCH] perlfunc.pod

[Piotr Fusik]

Here are some cosmetic changes of perlfunc:

1. Documented no-operand versions of chdir, eval, exit, gmtime.
2. Normalized C to foo().
3. Normalized $foo to C<$foo>.
4. Changed "=item import" to "=item import (LIST)".

Bye,
Piotr



perlfunc.patch.gz
Description: GNU Zip compressed data

Re: [PATCH] perlfunc.pod: ioctl.ph

[Alexey Tourbin]

On Thu, Jun 09, 2005 at 10:25:50AM +0200, Rafael Garcia-Suarez wrote:
> > --- perl-5.9.3.24699/pod/perlfunc.pod-  2005-06-03 09:56:55 +
> > +++ perl-5.9.3.24699/pod/perlfunc.pod   2005-06-08 09:33:00 +
> > @@ -2315,9 +2315,9 @@ functions will serve you better than wil
> >  
> >  Implements the ioctl(2) function.  You'll probably first have to say
> >  
> > -require "ioctl.ph";# probably in /usr/local/lib/perl/ioctl.ph
> > +require "sys/ioctl.ph";# probably in 
> > $Config{sitearch}/sys/ioctl.ph
> 
> Thanks, applied as change #24771, except that I replaced sitearch by archlib
> in the above example line.

Well, h2ph uses installsitearch by default, but many vendors ship
pre-generated *.ph files in archlib.


pgpnrgKVHRoSw.pgp
Description: PGP signature

Re: [PATCH] perlfunc.pod: ioctl.ph

[Rafael Garcia-Suarez]

Alexey Tourbin wrote:
> Hello,
> 
> Unlike "sys/ioctl.ph", "ioctl.ph" is uncommon.  Modern Linux have only
> /usr/include/sys/ioctl.h, not /usr/include/ioctl.h.  Besides this,
> "sys/ioctl.ph" is mentioned in perlfaq5.pod and perlfaq8.pod.
> 
> --- perl-5.9.3.24699/pod/perlfunc.pod-2005-06-03 09:56:55 +
> +++ perl-5.9.3.24699/pod/perlfunc.pod 2005-06-08 09:33:00 +
> @@ -2315,9 +2315,9 @@ functions will serve you better than wil
>  
>  Implements the ioctl(2) function.  You'll probably first have to say
>  
> -require "ioctl.ph";  # probably in /usr/local/lib/perl/ioctl.ph
> +require "sys/ioctl.ph";  # probably in $Config{sitearch}/sys/ioctl.ph

Thanks, applied as change #24771, except that I replaced sitearch by archlib
in the above example line.

[PATCH] perlfunc.pod: ioctl.ph

[Alexey Tourbin]

Hello,

Unlike "sys/ioctl.ph", "ioctl.ph" is uncommon.  Modern Linux have only
/usr/include/sys/ioctl.h, not /usr/include/ioctl.h.  Besides this,
"sys/ioctl.ph" is mentioned in perlfaq5.pod and perlfaq8.pod.

--- perl-5.9.3.24699/pod/perlfunc.pod-  2005-06-03 09:56:55 +
+++ perl-5.9.3.24699/pod/perlfunc.pod   2005-06-08 09:33:00 +
@@ -2315,9 +2315,9 @@ functions will serve you better than wil
 
 Implements the ioctl(2) function.  You'll probably first have to say
 
-require "ioctl.ph";# probably in /usr/local/lib/perl/ioctl.ph
+require "sys/ioctl.ph";# probably in $Config{sitearch}/sys/ioctl.ph
 
-to get the correct function definitions.  If F doesn't
+to get the correct function definitions.  If F doesn't
 exist or doesn't have the correct definitions you'll have to roll your
 own, based on your C header files such as F<<  >>.
 (There is a Perl script called B that comes with the Perl kit that
End of patch


pgpEcpwhnQCI8.pgp
Description: PGP signature

Re: [PATCH] perlfunc.pod: incomplete select description

[Rafael Garcia-Suarez]

Hernan Perez Masci wrote:
> 
> I'm attaching a patch to add the other missing comment to the same pod file 
> (the one already patched by Rafael).

Thanks, applied to bleadperl as change #24224.

Re: [PATCH] perlfunc.pod: incomplete select description

[Spider Boardman]

On Fri, 8 Apr 2005 13:50:00 -0500, Steve Peters wrote (in part):

sp> Does the Linux specific warning belong in perlfunc.pod or should it be
sp> in perlport.pod instead?

It's not specific to Linux.  Multiple Unix variants are subject to the
same warning.

-- 
Spider Boardman (at home) [EMAIL PROTECTED]
The management (my cats) made me say this.http://orb.dynalias.net/~spider/
PGP public key fingerprint: 96 72 D2 C6 E0 92 32 89  F6 B2 C2 A0 1C AB 1F DC

Re: [PATCH] perlfunc.pod: incomplete select description

[Steve Peters]

On Fri, Apr 08, 2005 at 03:28:28PM -0300, Hernan Perez Masci wrote:
> Hello,
> 
> I have detected two missing comments about the behaviour of select(2) system 
> call, in the description of the select function in perlfunc.pod. Rafael 
> Garcia-Suarez has already added one of these comments to the pod file in 
> bleadperl (see perl-documentation mailling list archive for further 
> information).
> 
> I'm attaching a patch to add the other missing comment to the same pod file 
> (the one already patched by Rafael).
> 
> Regards,
> Hernan A. Perez Masci.

> --- perlfunc.pod  2005-04-07 10:12:49.0 -0300
> +++ perlfunc.pod.patched  2005-04-08 14:55:29.0 -0300
> @@ -4606,6 +4606,12 @@
>  On error, C behaves like the select(2) system call : it returns
>  -1 and sets C<$!>.
>  
> +Note: on Linux, the select(2) system call may report a socket file
> +descriptor as "ready for reading", when actually no data is available,
> +thus a subsequent read blocks. It can be avoided using always the
> +O_NONBLOCK flag on the socket. See select(2) and fcntl(2) for further
> +details.
> +
>  B: One should not attempt to mix buffered I/O (like C
>  or ) with C, except as permitted by POSIX, and even
>  then only on POSIX systems.  You have to use C instead.

Does the Linux specific warning belong in perlfunc.pod or should it be in
perlport.pod instead?

Steve Peters
[EMAIL PROTECTED]

[PATCH] perlfunc.pod: incomplete select description

[Hernan Perez Masci]

Hello,

I have detected two missing comments about the behaviour of select(2) system 
call, in the description of the select function in perlfunc.pod. Rafael 
Garcia-Suarez has already added one of these comments to the pod file in 
bleadperl (see perl-documentation mailling list archive for further 
information).

I'm attaching a patch to add the other missing comment to the same pod file 
(the one already patched by Rafael).

Regards,
Hernan A. Perez Masci.
--- perlfunc.pod	2005-04-07 10:12:49.0 -0300
+++ perlfunc.pod.patched	2005-04-08 14:55:29.0 -0300
@@ -4606,6 +4606,12 @@
 On error, C behaves like the select(2) system call : it returns
 -1 and sets C<$!>.
 
+Note: on Linux, the select(2) system call may report a socket file
+descriptor as "ready for reading", when actually no data is available,
+thus a subsequent read blocks. It can be avoided using always the
+O_NONBLOCK flag on the socket. See select(2) and fcntl(2) for further
+details.
+
 B: One should not attempt to mix buffered I/O (like C
 or ) with C, except as permitted by POSIX, and even
 then only on POSIX systems.  You have to use C instead.

Re: [PATCH perlfunc.pod] split on an empty string

[Abigail]

On Fri, May 11, 2001 at 11:36:04AM -0400, Benjamin Sugars wrote:
>  
>  If LIMIT is specified and positive, it represents the maximum number
> -of fields the EXPR will be split into, though the number of fields 
> -returned depends on the number of occurrences of PATTERN within EXPR.
> -If LIMIT is unspecified or zero, trailing null fields are stripped
> -(which potential users of C would do well to remember).  If LIMIT
> -is negative, it is treated as if an arbitrarily large LIMIT had been 
> -specified.  Note that splitting an EXPR that evaluates to the empty
> -string always returns the empty list, regardless of the LIMIT specified.
> +of fields the EXPR will be split into, though the actual number of
> +fields returned depends on the number of times PATTERN matches within
> +EXPR.  If LIMIT is unspecified or zero, trailing null fields are
> +stripped (which potential users of C would do well to remember).
> +If LIMIT is negative, it is treated as if an arbitrarily large LIMIT
> +had been specified.  Note that splitting an EXPR that evaluates to the
> +empty string always returns the empty list, regardless of the LIMIT
> +specified.


Hmmm. How many times does 'aba' match in 'abababababababa'? The phrase
"the number of times PATTERN matches within EXPR" is ambigious; it should
probably mention non-overlapping matches.


Abigail