From: Perl 5 Porters Date: Fri, 20 Sep 1996 14:08:33 +0000 (+0100) Subject: perl 5.003_06: pod/perldiag.pod X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=8b1a09fcd24050d96cf14909e04c7997d661c284;p=p5sagit%2Fp5-mst-13.2.git perl 5.003_06: pod/perldiag.pod Date: Wed, 11 Sep 1996 11:55:18 -0500 From: "Daniel S. Lewart" Subject: POD spelling patches Date: Fri, 20 Sep 1996 15:08:33 +0100 (BST) From: "Joseph S. Myers" 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 Subject: VMS patches to 5.003_05 --- diff --git a/pod/perldiag.pod b/pod/perldiag.pod index 2698b3f..02502e5 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. Trappable errors may be trapped using the eval operator. See L. @@ -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. =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. =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 instead -of Perl. Check the <#!> line, or manually feed your script +of Perl. Check the E#!E line, or manually feed your script into Perl yourself. =item %s: Expression syntax. (A) You've accidentally run your script through B instead -of Perl. Check the <#!> line, or manually feed your script +of Perl. Check the E#!E line, or manually feed your script into Perl yourself. =item %s: Undefined variable. (A) You've accidentally run your script through B instead -of Perl. Check the <#!> line, or manually feed your script +of Perl. Check the E#!E 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#!E 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. =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 instead -of Perl. Check the <#!> line, or manually feed your script +of Perl. Check the E#!E 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 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 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. @@ -598,25 +598,25 @@ Usually this is because you don't have read permission for the file. (W) You tried to say C, 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", 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' or '2EE' 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' 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' or 'EE' 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=E 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%sE (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. +"+E" or "+E" or "+EE" instead of with "E" or nothing. If +you only intended to write the file, use "E" or "EE". See +L. =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. +"+E" or "+E" or "+EE" instead of with "E" or nothing. If +you only intended to write the file, use "E" or "EE". See +L. =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 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. =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. @@ -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. +doesn't somehow point to a valid method. See L. =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 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 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 or 2EE 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' or a '2EE' 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 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' 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 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' 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 or EE 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' or a 'EE' 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. =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. +doesn't somehow point to a valid subroutine. See L. =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. +somehow no longer points to a valid method. See L. =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%sE (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. (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. =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>, 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<$>, 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. more times than there are characters of input, which is what happened.) See L. -=item Stat on unopened file <%s> +=item Stat on unopened file E%sE (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#!E 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%sE (W) You tried to invoke a file test operator on a filehandle that isn't open. Check your logic. See also L. =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 instead -of Perl. Check the <#!> line, or manually feed your script +of Perl. Check the E#!E 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. =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 EE 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 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 EE to mean EE"" 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 instead -of Perl. Check the <#!> line, or manually feed your script +of Perl. Check the E#!E 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' 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'. Only one STDIN stream to a customer, please. -=item '|' and '>' may not both be specified on command line +=item '|' and 'E' 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