perl 5.003_06: pod/perldiag.pod

Date: Wed, 11 Sep 1996 11:55:18 -0500
From: "Daniel S. Lewart" <lewart@vadds.cvm.uiuc.edu>
Subject: POD spelling patches

Date: Fri, 20 Sep 1996 15:08:33 +0100 (BST)
From: "Joseph S. Myers" <jsm28@hermes.cam.ac.uk>
Subject: Pod typos, pod2man bugs, and miscellaneous installation comments

Here is a patch for various typos and other defects in the Perl
5.003_05 pods, including the pods embedded in library modules.

Date: Thu, 03 Oct 1996 16:31:46 -0400 (EDT)
From: Charles Bailey <bailey@HMIVAX.HUMGEN.UPENN.EDU>
Subject: VMS patches to 5.003_05

1 files changed, 92 insertions, 81 deletions

diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index 2698b3f46d..02502e554b 100644
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -16,7 +16,7 @@ desperation):
     (A) An alien error message (not generated by Perl).
 
 Optional warnings are enabled by using the B<-w> switch.  Warnings may
-be captured by setting C<$^Q> to a reference to a routine that will be
+be captured by setting C<$SIG{__WARN__}> to a reference to a routine that will be
 called on each warning instead of printing it.  See L<perlvar>.
 Trappable errors may be trapped using the eval operator.  See
 L<perlfunc/eval>.
@@ -37,7 +37,7 @@ if you want to localize a package variable.
 
 (S) A lexical variable has been redeclared in the same scope, effectively
 eliminating all access to the previous instance.  This is almost always
-a typographical error.  Note that the earlier variable will still exist 
+a typographical error.  Note that the earlier variable will still exist
 until the end of the scope or until all closure referents to it are
 destroyed.
 
@@ -60,7 +60,7 @@ way.  See L<perlfunc/unpack>.
 =item %s (...) interpreted as function
 
 (W) You've run afoul of the rule that says that any list operator followed
-by parentheses turns into a function, with all the list operators arguments 
+by parentheses turns into a function, with all the list operators arguments
 found inside the parens.  See L<perlop/Terms and List Operators (Leftward)>.
 
 =item %s argument is not a HASH element
@@ -110,25 +110,25 @@ before it could possibly have been used.
 =item %s: Command not found.
 
 (A) You've accidentally run your script through B<csh> instead
-of Perl.  Check the <#!> line, or manually feed your script
+of Perl.  Check the E<lt>#!E<gt> line, or manually feed your script
 into Perl yourself.
 
 =item %s: Expression syntax.
 
 (A) You've accidentally run your script through B<csh> instead
-of Perl.  Check the <#!> line, or manually feed your script
+of Perl.  Check the E<lt>#!E<gt> line, or manually feed your script
 into Perl yourself.
 
 =item %s: Undefined variable.
 
 (A) You've accidentally run your script through B<csh> instead
-of Perl.  Check the <#!> line, or manually feed your script
+of Perl.  Check the E<lt>#!E<gt> line, or manually feed your script
 into Perl yourself.
 
 =item %s: not found
 
-(A) You've accidentally run your script through the Bourne shell 
-instead of Perl.  Check the <#!> line, or manually feed your script
+(A) You've accidentally run your script through the Bourne shell
+instead of Perl.  Check the E<lt>#!E<gt> line, or manually feed your script
 into Perl yourself.
 
 =item B<-P> not allowed for setuid/setgid script
@@ -234,7 +234,7 @@ when it shouldn't have been, or that memory has been corrupted.
 =item Attempt to use reference as lvalue in substr
 
 (W) You supplied a reference as the first argument to substr() used
-as an lvalue, which is pretty strange.  Perhaps you forgot to 
+as an lvalue, which is pretty strange.  Perhaps you forgot to
 dereference it first.  See L<perlfunc/substr>.
 
 =item Bad arg length for %s, is %d, should be %d
@@ -288,10 +288,10 @@ wasn't a symbol table entry.
 (P) An internal request asked to add a hash entry to something that
 wasn't a symbol table entry.
 
-=item Badly places ()'s
+=item Badly placed ()'s
 
 (A) You've accidentally run your script through B<csh> instead
-of Perl.  Check the <#!> line, or manually feed your script
+of Perl.  Check the E<lt>#!E<gt> line, or manually feed your script
 into Perl yourself.
 
 =item BEGIN failed--compilation aborted
@@ -423,7 +423,7 @@ They must have ordinary identifiers as names.
 from a deleted (but still opened) file.  You have to say B<-i>C<.bak>, or some
 such.
 
-=item Can't do inplace edit: %s > 14 characters
+=item Can't do inplace edit: %s E<gt> 14 characters
 
 (S) There isn't enough room in the filename to make a backup name for the file.
 
@@ -455,7 +455,7 @@ your sysadmin why he and/or she removed it.
 (F) This machine doesn't have either waitpid() or wait4(), so only waitpid()
 without flags is emulated.
 
-=item Can't do {n,m} with n > m
+=item Can't do {n,m} with n E<gt> m
 
 (F) Minima must be less than or equal to maxima.  If you really want
 your regexp to match something 0 times, just put {0}.  See L<perlre>.
@@ -598,25 +598,25 @@ Usually this is because you don't have read permission for the file.
 
 (W) You tried to say C<open(CMD, "|cmd|")>, which is not supported.  You can
 try any of several modules in the Perl library to do this, such as
-"open2.pl".  Alternately, direct the pipe's output to a file using ">",
+"open2.pl".  Alternately, direct the pipe's output to a file using "E<gt>",
 and then read it in under a different file handle.
 
 =item Can't open error file %s as stderr
 
 (F) An error peculiar to VMS.  Perl does its own command line redirection, and
-couldn't open the file specified after '2>' or '2>>' on the command line for
-writing.
+couldn't open the file specified after '2E<gt>' or '2E<gt>E<gt>' on the
+command line for writing.
 
 =item Can't open input file %s as stdin
 
 (F) An error peculiar to VMS.  Perl does its own command line redirection, and
-couldn't open the file specified after '<' on the command line for reading.
+couldn't open the file specified after 'E<lt>' on the command line for reading.
 
 =item Can't open output file %s as stdout
 
 (F) An error peculiar to VMS.  Perl does its own command line redirection, and
-couldn't open the file specified after '>' or '>>' on the command line for
-writing.
+couldn't open the file specified after 'E<gt>' or 'E<gt>E<gt>' on the command
+line for writing.
 
 =item Can't open output pipe (name: %s)
 
@@ -699,7 +699,7 @@ code calling sv_upgrade.
 =item Can't use "my %s" in sort comparison
 
 (F) The global variables $a and $b are reserved for sort comparisons.
-You mentioned $a or $b in the same line as the <=> or cmp operator,
+You mentioned $a or $b in the same line as the E<lt>=E<gt> or cmp operator,
 and the variable had earlier been declared as a lexical variable.
 Either qualify the sort variable with the package name, or rename the
 lexical variable.
@@ -759,7 +759,7 @@ Perhaps you need to copy the value to a temporary, and repeat that.
 
 =item Cannot open temporary file
 
-(F) The create routine failed for some reaon while trying to process
+(F) The create routine failed for some reason while trying to process
 a B<-e> switch.  Maybe your /tmp partition is full, or clobbered.
 
 =item chmod: mode argument is missing initial 0
@@ -771,7 +771,7 @@ a B<-e> switch.  Maybe your /tmp partition is full, or clobbered.
 not realizing that 777 will be interpreted as a decimal number, equivalent
 to 01411.  Octal constants are introduced with a leading 0 in Perl, as in C.
 
-=item Close on unopened file <%s>
+=item Close on unopened file E<lt>%sE<gt>
 
 (W) You tried to close a filehandle that was never opened.
 
@@ -861,17 +861,17 @@ case the conversion routines don't handle.  Drat.
 
 =item Exiting eval via %s
 
-(W) You are exiting an eval by unconventional means, such as a
+(W) You are exiting an eval by unconventional means, such as
 a goto, or a loop control statement.
 
 =item Exiting subroutine via %s
 
-(W) You are exiting a subroutine by unconventional means, such as a
+(W) You are exiting a subroutine by unconventional means, such as
 a goto, or a loop control statement.
 
 =item Exiting substitution via %s
 
-(W) You are exiting a substitution by unconventional means, such as a
+(W) You are exiting a substitution by unconventional means, such as
 a return, a goto, or a loop control statement.
 
 =item Fatal VMS error at %s, line %d
@@ -896,15 +896,17 @@ the FileHandle package.
 
 (W) You tried to write on a read-only filehandle.  If you
 intended it to be a read-write filehandle, you needed to open it with
-"+<" or "+>" or "+>>" instead of with "<" or nothing.  If you only
-intended to write the file, use ">" or ">>".  See L<perlfunc/open>.
+"+E<lt>" or "+E<gt>" or "+E<gt>E<gt>" instead of with "E<lt>" or nothing.  If
+you only intended to write the file, use "E<gt>" or "E<gt>E<gt>".  See
+L<perlfunc/open>.
 
 =item Filehandle only opened for input
 
 (W) You tried to write on a read-only filehandle.  If you
 intended it to be a read-write filehandle, you needed to open it with
-"+<" or "+>" or "+>>" instead of with "<" or nothing.  If you only
-intended to write the file, use ">" or ">>".  See L<perlfunc/open>.
+"+E<lt>" or "+E<gt>" or "+E<gt>E<gt>" instead of with "E<lt>" or nothing.  If
+you only intended to write the file, use "E<gt>" or "E<gt>E<gt>".  See
+L<perlfunc/open>.
 
 =item Final $ should be \$ or $name
 
@@ -996,12 +998,14 @@ an emergency basis to prevent a core dump.
 (D) Really old Perl let you omit the % on hash names in some spots.  This
 is now heavily deprecated.
 
-=item Name "%s::%s" used only once: possible typo
+=item Ill-formed logical name |%s| in prime_env_iter
 
-(W) Typographical errors often show up as unique variable names.  If you
-had a good reason for having a unique name, then just mention it
-again somehow to suppress the message (the C<use vars> pragma is
-provided for just this purpose).
+(W) A warning peculiar to VMS.  A logical name was encountered when preparing
+to iterate over %ENV which violates the syntactic rules governing logical
+names.  Since it cannot be translated normally, it is skipped, and will not
+appear in %ENV.  This may be a benign occurence, as some software packages
+might directly modify logical name tables and introduce non-standard names,
+or it may indicate that a logical name table has been corrupted.
 
 =item Illegal division by zero
 
@@ -1024,7 +1028,7 @@ of the octal number stopped before the 8 or 9.
 
 =item Insecure dependency in %s
 
-(F) You tried to do something that the tainting mechanism didn't like. 
+(F) You tried to do something that the tainting mechanism didn't like.
 The tainting mechanism is turned on when you're running setuid or setgid,
 or when you specify B<-T> to turn it on explicitly.  The tainting mechanism
 labels all data that's derived directly or indirectly from the user,
@@ -1035,13 +1039,13 @@ for more information.
 =item Insecure directory in %s
 
 (F) You can't use system(), exec(), or a piped open in a setuid or setgid
-script if $ENV{PATH} contains a directory that is writable by the world.
+script if C<$ENV{PATH}> contains a directory that is writable by the world.
 See L<perlsec>.
 
 =item Insecure PATH
 
 (F) You can't use system(), exec(), or a piped open in a setuid or
-setgid script if $ENV{PATH} is derived from data supplied (or
+setgid script if C<$ENV{PATH}> is derived from data supplied (or
 potentially supplied) by the user.  The script must set the path to a
 known value, using trustworthy data.  See L<perlsec>.
 
@@ -1113,7 +1117,7 @@ assume that an unbackslashed @ interpolates an array.)
 =item Method for operation %s not found in package %s during blessing
 
 (F) An attempt was made to specify an entry in an overloading table that
-doesn't somehow point to a valid method.  See L<perlovl>.
+doesn't somehow point to a valid method.  See L<overload>.
 
 =item Might be a runaway multi-line %s string starting on line %d
 
@@ -1127,8 +1131,8 @@ ended earlier on the current line.
 
 =item Missing $ on loop variable
 
-(F) Apparently you've been programming in csh too much.  Variables are always
-mentioned with the $ in Perl, unlike in the shells, where it can vary from 
+(F) Apparently you've been programming in B<csh> too much.  Variables are always
+mentioned with the $ in Perl, unlike in the shells, where it can vary from
 one line to the next.
 
 =item Missing comma after first argument to %s function
@@ -1185,8 +1189,15 @@ be created for some peculiar reason.
 
 =item Multidimensional syntax %s not supported
 
-(W) Multidimensional arrays aren't written like $foo[1,2,3].  They're written
-like $foo[1][2][3], as in C.
+(W) Multidimensional arrays aren't written like C<$foo[1,2,3]>.  They're written
+like C<$foo[1][2][3]>, as in C.
+
+=item Name "%s::%s" used only once: possible typo
+
+(W) Typographical errors often show up as unique variable names.  If you
+had a good reason for having a unique name, then just mention it
+again somehow to suppress the message (the C<use vars> pragma is
+provided for just this purpose).
 
 =item Negative length
 
@@ -1250,29 +1261,29 @@ but for some reason the perl5db.pl file (or some facsimile thereof)
 didn't define a DB::sub routine to be called at the beginning of each
 ordinary subroutine call.
 
-=item No error file after 2> or 2>> on command line
+=item No error file after 2E<gt> or 2E<gt>E<gt> on command line
 
 (F) An error peculiar to VMS.  Perl handles its own command line redirection,
-and found a '2>' or a '2>>' on the command line, but can't find the name of the
-file to which to write data destined for stderr.
+and found a '2E<gt>' or a '2E<gt>E<gt>' on the command line, but can't find
+the name of the file to which to write data destined for stderr.
 
-=item No input file after < on command line
+=item No input file after E<lt> on command line
 
 (F) An error peculiar to VMS.  Perl handles its own command line redirection,
-and found a '<' on the command line, but can't find the name of the file from
-which to read data for stdin.
+and found a 'E<lt>' on the command line, but can't find the name of the file
+from which to read data for stdin.
 
-=item No output file after > on command line
+=item No output file after E<gt> on command line
 
 (F) An error peculiar to VMS.  Perl handles its own command line redirection,
-and found a lone '>' at the end of the command line, so it doesn't know whither
-you wanted to redirect stdout.
+and found a lone 'E<gt>' at the end of the command line, so it doesn't know
+whither you wanted to redirect stdout.
 
-=item No output file after > or >> on command line
+=item No output file after E<gt> or E<gt>E<gt> on command line
 
 (F) An error peculiar to VMS.  Perl handles its own command line redirection,
-and found a '>' or a '>>' on the command line, but can't find the name of the
-file to which to write data destined for stdout.
+and found a 'E<gt>' or a 'E<gt>E<gt>' on the command line, but can't find the
+name of the file to which to write data destined for stdout.
 
 =item No Perl script found in input
 
@@ -1352,7 +1363,7 @@ See also L<perlref>.
 =item Not a subroutine reference in %OVERLOAD
 
 (F) An attempt was made to specify an entry in an overloading table that
-doesn't somehow point to a valid subroutine.  See L<perlovl>.
+doesn't somehow point to a valid subroutine.  See L<overload>.
 
 =item Not an ARRAY reference
 
@@ -1406,7 +1417,7 @@ since hash lists come in key/value pairs.
 =item Operation `%s' %s: no method found,
 
 (F) An attempt was made to use an entry in an overloading table that
-somehow no longer points to a valid method.  See L<perlovl>.
+somehow no longer points to a valid method.  See L<overload>.
 
 =item Operator or semicolon missing before %s
 
@@ -1648,7 +1659,7 @@ last argument of the previous construct, for example:
 (S) The subroutine being defined had a predeclared (forward) declaration
 with a different function prototype.
 
-=item Read on closed filehandle <%s>
+=item Read on closed filehandle E<lt>%sE<gt>
 
 (W) The filehandle you're reading from got itself closed sometime before now.
 Check your logic flow.
@@ -1707,8 +1718,8 @@ shifting or popping (for array variables).  See L<perlform>.
 
 (W) You've used an array slice (indicated by @) to select a single value of
 an array.  Generally it's better to ask for a scalar value (indicated by $).
-The difference is that $foo[&bar] always behaves like a scalar, both when
-assigning to it and when evaluating its argument, while @foo[&bar] behaves
+The difference is that C<$foo[&bar]> always behaves like a scalar, both when
+assigning to it and when evaluating its argument, while C<@foo[&bar]> behaves
 like a list when you assign to it, and provides a list context to its
 subscript, which can do weird things if you're only expecting one subscript.
 
@@ -1720,7 +1731,7 @@ L<perlref>.
 =item Script is not setuid/setgid in suidperl
 
 (F) Oddly, the suidperl program was invoked on a script with its setuid
-or setgid bit set.  This doesn't make much sense.
+or setgid bit not set.  This doesn't make much sense.
 
 =item Search pattern not terminated
 
@@ -1781,25 +1792,25 @@ in a location where the CGI server can't find it, basically, more or less.
 
 =item setegid() not implemented
 
-(F) You tried to assign to $), and your operating system doesn't support
+(F) You tried to assign to C<$)>, and your operating system doesn't support
 the setegid() system call (or equivalent), or at least Configure didn't
 think so.
 
 =item seteuid() not implemented
 
-(F) You tried to assign to $>, and your operating system doesn't support
+(F) You tried to assign to C<$E<gt>>, and your operating system doesn't support
 the seteuid() system call (or equivalent), or at least Configure didn't
 think so.
 
 =item setrgid() not implemented
 
-(F) You tried to assign to $(, and your operating system doesn't support
+(F) You tried to assign to C<$(>, and your operating system doesn't support
 the setrgid() system call (or equivalent), or at least Configure didn't
 think so.
 
 =item setruid() not implemented
 
-(F) You tried to assign to $<, and your operating system doesn't support
+(F) You tried to assign to C<$<lt>>, and your operating system doesn't support
 the setruid() system call (or equivalent), or at least Configure didn't
 think so.
 
@@ -1843,7 +1854,7 @@ or less than one element.  See L<perlfunc/sort>.
 more times than there are characters of input, which is what happened.)
 See L<perlfunc/split>.
 
-=item Stat on unopened file <%s>
+=item Stat on unopened file E<lt>%sE<gt>
 
 (W) You tried to use the stat() function (or an equivalent file test)
 on a filehandle that was either never opened or has been closed since.
@@ -1916,8 +1927,8 @@ if the error went away.  Sort of the cybernetic version of S<20 questions>.
 
 =item syntax error at line %d: `%s' unexpected
 
-(A) You've accidentally run your script through the Bourne shell 
-instead of Perl.  Check the <#!> line, or manually feed your script
+(A) You've accidentally run your script through the Bourne shell
+instead of Perl.  Check the E<lt>#!E<gt> line, or manually feed your script
 into Perl yourself.
 
 =item System V IPC is not implemented on this machine
@@ -1935,14 +1946,14 @@ Check your logic flow.
 (W) You tried to use the tell() function on a filehandle that was either
 never opened or has been closed since.
 
-=item Test on unopened file <%s>
+=item Test on unopened file E<lt>%sE<gt>
 
 (W) You tried to invoke a file test operator on a filehandle that isn't
 open.  Check your logic.  See also L<perlfunc/-X>.
 
 =item That use of $[ is unsupported
 
-(F) Assignment to $[ is now strictly circumscribed, and interpreted as
+(F) Assignment to C<$[> is now strictly circumscribed, and interpreted as
 a compiler directive.  You may only say one of
 
     $[ = 0;
@@ -1964,7 +1975,7 @@ to the probings of Configure.
 
 (F) Configure couldn't find the crypt() function on your machine,
 probably because your vendor didn't supply it, probably because they
-think the U.S. Govermnment thinks it's a secret, or at least that they
+think the U.S. Government thinks it's a secret, or at least that they
 will continue to pretend that it is.  And if you quote me on that, I
 will deny it.
 
@@ -1989,7 +2000,7 @@ system call to call, silly dilly.
 =item Too many )'s
 
 (A) You've accidentally run your script through B<csh> instead
-of Perl.  Check the <#!> line, or manually feed your script
+of Perl.  Check the E<lt>#!E<gt> line, or manually feed your script
 into Perl yourself.
 
 =item Too many args to syscall
@@ -2023,8 +2034,8 @@ Configure knows about.
 =item Type of arg %d to %s must be %s (not %s)
 
 (F) This function requires the argument in that position to be of a
-certain type.  Arrays must be @NAME or @{EXPR}.  Hashes must be
-%NAME or %{EXPR}.  No implicit dereferencing is allowed--use the
+certain type.  Arrays must be @NAME or C<@{EXPR}>.  Hashes must be
+%NAME or C<%{EXPR}>.  No implicit dereferencing is allowed--use the
 {EXPR} forms as an explicit dereference.  See L<perlref>.
 
 =item umask: argument is missing initial 0
@@ -2156,7 +2167,7 @@ At least, Configure doesn't think so.
 (F) Your machine doesn't support the Berkeley socket mechanism, or at
 least that's what Configure thought.
 
-=item Unterminated <> operator
+=item Unterminated E<lt>E<gt> operator
 
 (F) The lexer saw a left angle bracket in a place where it was expecting
 a term, so it's looking for the corresponding right angle bracket, and not
@@ -2165,7 +2176,7 @@ the line, and you really meant a "less than".
 
 =item Use of $# is deprecated
 
-(D) This was an ill-advised attempt to emulate a poorly defined awk feature.
+(D) This was an ill-advised attempt to emulate a poorly defined B<awk> feature.
 Use an explicit printf() or sprintf() instead.
 
 =item Use of $* is deprecated
@@ -2186,7 +2197,7 @@ from C.  This usually means there's a better way to do it in Perl.
 because there's a better way to do it, and also because the old way has
 bad side effects.
 
-=item Use of bare << to mean <<"" is deprecated
+=item Use of bare E<lt>E<lt> to mean E<lt>E<lt>"" is deprecated
 
 (D) You are now encouraged to use the explicitly quoted form if you
 wish to use a blank line as the terminator of the here-document.
@@ -2245,12 +2256,12 @@ on the front of your variable.
 =item Variable syntax.
 
 (A) You've accidentally run your script through B<csh> instead
-of Perl.  Check the <#!> line, or manually feed your script
+of Perl.  Check the E<lt>#!E<gt> line, or manually feed your script
 into Perl yourself.
 
 =item Warning: unable to close filehandle %s properly.
 
-(S) The implicit close() done by an open() got an error indication on the 
+(S) The implicit close() done by an open() got an error indication on the
 close().  This usually indicates your filesystem ran out of disk space.
 
 =item Warning: Use of "%s" without parens is ambiguous
@@ -2329,13 +2340,13 @@ substitution, but stylistically it's better to use the variable form
 because other Perl programmers will expect it, and it works better
 if there are more than 9 backreferences.
 
-=item '|' and '<' may not both be specified on command line
+=item '|' and 'E<lt>' may not both be specified on command line
 
 (F) An error peculiar to VMS.  Perl does its own command line redirection, and
 found that STDIN was a pipe, and that you also tried to redirect STDIN using
-'<'.  Only one STDIN stream to a customer, please.
+'E<lt>'.  Only one STDIN stream to a customer, please.
 
-=item '|' and '>' may not both be specified on command line
+=item '|' and 'E<gt>' may not both be specified on command line
 
 (F) An error peculiar to VMS.  Perl does its own command line redirection, and
 thinks you tried to redirect stdout both to a file and into a pipe to another