From: Cary D. Renzema Date: Wed, 26 Mar 1997 23:53:22 +0000 (-0800) Subject: Pod updates X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=5695b28edc67a3f45e8a0f25755d07afef3660ac;p=p5sagit%2Fp5-mst-13.2.git Pod updates Here are some fixes for the pod files. p5p-msgid: <199703262353.PAA01819@macs.mxim.com> --- diff --git a/pod/perl.pod b/pod/perl.pod index 2c1dde2..139fd5d 100644 --- a/pod/perl.pod +++ b/pod/perl.pod @@ -52,7 +52,7 @@ of sections: perlpod Perl plain old documentation perlbook Perl book information - perlembed Perl how to embed perl in your C or C++ app + perlembed Perl how to embed perl in your C or C++ application perlapio Perl internal IO abstraction interface perlxs Perl XS application programming interface perlxstut Perl XS tutorial diff --git a/pod/perlcall.pod b/pod/perlcall.pod index 1ff71fc..67b59cd 100644 --- a/pod/perlcall.pod +++ b/pod/perlcall.pod @@ -164,7 +164,7 @@ accessible from the stack - think of the case where only one value is returned as being a list with only one element. Any other items that were returned will not exist by the time control returns from the I function. The section I shows an example of this behaviour. +context> shows an example of this behavior. =head2 G_ARRAY @@ -293,7 +293,7 @@ from the stack. =back -See I for details of using G_EVAL. +See I for details on using G_EVAL. =head2 G_KEEPERR @@ -565,7 +565,7 @@ Next, we come to XPUSHs. This is where the parameters actually get pushed onto the stack. In this case we are pushing a string and an integer. -See the L for details +See L for details on how the XPUSH macros work. =item 6. @@ -672,7 +672,7 @@ allocated to the Perl stack has been reallocated whilst in the I call. If you are making use of the Perl stack pointer in your code you must -always refresh the your local copy using SPAGAIN whenever you make use +always refresh the local copy using SPAGAIN whenever you make use of the I functions or any other Perl internal function. =item 4. @@ -834,7 +834,7 @@ then the output will be Value 1 = 3 In this case the main point to note is that only the last item in the -list returned from the subroutine, I actually made it back to +list is returned from the subroutine, I actually made it back to I. @@ -1420,22 +1420,22 @@ will be more like this ... event handler --> perl_call --> perl | - event handler <-- perl_call --<--+ + event handler <-- perl_call <----+ ... event handler --> perl_call --> perl | - event handler <-- perl_call --<--+ + event handler <-- perl_call <----+ ... event handler --> perl_call --> perl | - event handler <-- perl_call --<--+ + event handler <-- perl_call <----+ In this case the flow of control can consist of only the repeated sequence event handler --> perl_call --> perl -for the practically the complete duration of the program. This means +for practically the complete duration of the program. This means that control may I drop back to the surrounding scope in Perl at the extreme left. diff --git a/pod/perldata.pod b/pod/perldata.pod index f0837b3..b51e657 100644 --- a/pod/perldata.pod +++ b/pod/perldata.pod @@ -369,7 +369,7 @@ surrounding whitespace) on the terminating line. Here's a line or two. THIS - and here another. + and here's another. THAT Just don't forget that you have to put a semicolon on the end @@ -401,12 +401,12 @@ assigns the entire list value to array foo, but assigns the value of variable bar to variable foo. Note that the value of an actual array in a scalar context is the length of the array; the -following assigns to $foo the value 3: +following assigns the value 3 to $foo: @foo = ('cc', '-E', $bar); $foo = @foo; # $foo gets 3 -You may have an optional comma before the closing parenthesis of an +You may have an optional comma before the closing parenthesis of a list literal, so that you can say: @foo = ( @@ -434,7 +434,7 @@ interpolating an array with no elements is the same as if no array had been interpolated at that point. A list value may also be subscripted like a normal array. You must -put the list in parentheses to avoid ambiguity. Examples: +put the list in parentheses to avoid ambiguity. For example: # Stat returns list value. $time = (stat($file))[8]; diff --git a/pod/perldiag.pod b/pod/perldiag.pod index e0a23b0..d530508 100644 --- a/pod/perldiag.pod +++ b/pod/perldiag.pod @@ -383,7 +383,7 @@ will be considered a block that loops once. See L. there isn't a current block. Note that an "if" or "else" block doesn't count as a "loopish" block, as doesn't a block given to sort(). You can usually double the curlies to get the same effect though, because the inner -curlies will be considered a block that loops once. See L. +curlies will be considered a block that loops once. See L. =item Can't "redo" outside a block @@ -391,7 +391,7 @@ curlies will be considered a block that loops once. See L. there isn't a current block. Note that an "if" or "else" block doesn't count as a "loopish" block, as doesn't a block given to sort(). You can usually double the curlies to get the same effect though, because the inner -curlies will be considered a block that loops once. See L. +curlies will be considered a block that loops once. See L. =item Can't bless non-reference value @@ -400,7 +400,7 @@ encapsulation of objects. See L. =item Can't break at that line -(S) A warning intended for while running within the debugger, indicating +(S) A warning intended to only be printed while running within the debugger, indicating the line number specified wasn't the location of a statement that could be stopped at. @@ -1376,7 +1376,7 @@ this error was triggered? =item No command into which to pipe on command line (F) An error peculiar to VMS. Perl handles its own command line redirection, -and found a '|' at the end of the command line, so it doesn't know whither you +and found a '|' at the end of the command line, so it doesn't know where you want to pipe the output from this command. =item No DB::DB routine defined @@ -1416,7 +1416,7 @@ from which to read data for stdin. (F) An error peculiar to VMS. Perl handles its own command line redirection, and found a lone 'E' at the end of the command line, so it doesn't know -whither you wanted to redirect stdout. +where you wanted to redirect stdout. =item No output file after E or EE on command line @@ -1959,8 +1959,8 @@ 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 not set. This doesn't make much sense. +(F) Oddly, the suidperl program was invoked on a script without a setuid +or setgid bit set. This doesn't make much sense. =item Search pattern not terminated @@ -1970,7 +1970,7 @@ construct. Remember that bracketing delimiters count nesting level. =item seek() on unopened file (W) You tried to use the seek() function on a filehandle that was either -never opened or has been closed since. +never opened or has since been closed. =item select not implemented @@ -2096,7 +2096,7 @@ See L. =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. +on a filehandle that was either never opened or has since been closed. =item Statement unlikely to be reached @@ -2189,7 +2189,7 @@ Check your logic flow. =item tell() on unopened file (W) You tried to use the tell() function on a filehandle that was either -never opened or has been closed since. +never opened or has since been closed. =item Test on unopened file E%sE @@ -2412,7 +2412,7 @@ supplying the bad switch on your behalf.) (W) A file operation was attempted on a filename, and that operation failed, PROBABLY because the filename contained a newline, PROBABLY -because you forgot to chop() or chomp() it off. See L. +because you forgot to chop() or chomp() it off. See L. =item Unsupported directory function "%s" called diff --git a/pod/perlform.pod b/pod/perlform.pod index 4e55e02..92663b1 100644 --- a/pod/perlform.pod +++ b/pod/perlform.pod @@ -7,7 +7,7 @@ perlform - Perl formats Perl has a mechanism to help you generate simple reports and charts. To facilitate this, Perl helps you code up your output page close to how it will look when it's printed. It can keep -track of things like how many lines on a page, what page you're on, when to +track of things like how many lines are on a page, what page you're on, when to print page headers, etc. Keywords are borrowed from FORTRAN: format() to declare and write() to execute; see their entries in L. Fortunately, the layout is much more legible, more like @@ -30,7 +30,7 @@ Output record formats are declared as follows: . If name is omitted, format "STDOUT" is defined. FORMLIST consists of -a sequence of lines, each of which may be of one of three types: +a sequence of lines, each of which may be one of three types: =over 4 @@ -277,8 +277,8 @@ Here's one strategy: If you have a fixed-size footer, you can get footers by checking $FORMAT_LINES_LEFT before each write() and print the footer yourself if necessary. -Here's another strategy; open a pipe to yourself, using C -(see L) and always write() to MESELF instead of +Here's another strategy; open a pipe to yourself, using C +(see L) and always write() to MYSELF instead of STDOUT. Have your child process massage its STDIN to rearrange headers and footers however you like. Not very convenient, but doable. diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index c4de4a3..96df297 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -420,7 +420,7 @@ an C>) frame. Furthermore, when called from within the DB package, caller returns more detailed information: it sets the list variable @DB::args to be the -arguments with which that subroutine was invoked. +arguments with which the subroutine was invoked. =item chdir EXPR @@ -1020,7 +1020,7 @@ and 4 likewise behave in the same way: they run the code '$x', which does nothing but return the value of C<$x>. (Case 4 is preferred for purely visual reasons, but it also has the advantage of compiling at compile-time instead of at run-time.) Case 5 is a place where -normally you I like to use double quotes, except that in that +normally you I like to use double quotes, except that in this particular situation, you can just use symbolic references instead, as in case 6. @@ -1540,7 +1540,7 @@ see L.) If EXPR is omitted, uses $_. There is no built-in import() function. It is merely an ordinary method (subroutine) defined (or inherited) by modules that wish to export names to another module. The use() function calls the import() method -for the package used. See also L, L, and L. +for the package used. See also L, L, and L. =item index STR,SUBSTR,POSITION @@ -2571,7 +2571,7 @@ call of stdio. FILEHANDLE may be an expression whose value gives the name of the filehandle. The values for WHENCE are 0 to set the file pointer to POSITION, 1 to set the it to current plus POSITION, and 2 to set it to EOF plus offset. You may use the values SEEK_SET, SEEK_CUR, and SEEK_END for -this from POSIX module. Returns 1 upon success, 0 otherwise. +this from the POSIX module. Returns 1 upon success, 0 otherwise. On some systems you have to do a seek whenever you switch between reading and writing. Amongst other things, this may have the effect of calling @@ -3384,7 +3384,7 @@ is available will be written. An OFFSET may be specified to write the data from some part of the string other than the beginning. A negative OFFSET specifies writing -from that many bytes counting backwards from the end of the string. +that many bytes counting backwards from the end of the string. =item tell FILEHANDLE @@ -3521,8 +3521,8 @@ digits. See also L, if all you have is a string. =item undef -Undefines the value of EXPR, which must be an lvalue. Use on only a -scalar value, an entire array or hash, or a subroutine name (using +Undefines the value of EXPR, which must be an lvalue. Use only on a +scalar value, an entire array, an entire hash, or a subroutine name (using "&"). (Using undef() will probably not do what you expect on most predefined variables or DBM list values, so don't do that.) Always returns the undefined value. You can omit the EXPR, in which case @@ -3793,7 +3793,7 @@ examples. Writes a formatted record (possibly multi-line) to the specified file, using the format associated with that file. By default the format for -a file is the one having the same name is the filehandle, but the +a file is the one having the same name as the filehandle, but the format for the current output channel (see the select() function) may be set explicitly by assigning the name of the format to the C<$~> variable. diff --git a/pod/perlguts.pod b/pod/perlguts.pod index 866cafb..4a535a9 100644 --- a/pod/perlguts.pod +++ b/pod/perlguts.pod @@ -679,9 +679,9 @@ entry of the same type of magic is deleted. Note that this can be overridden, and multiple instances of the same type of magic can be associated with an SV. -The C and C arguments are used to associate a string with -the magic, typically the name of a variable. C is stored in the -C field and if C is non-null and C >= 0 a malloc'd +The C and C arguments are used to associate a string with +the magic, typically the name of a variable. C is stored in the +C field and if C is non-null and C >= 0 a malloc'd copy of the name is stored in C field. The sv_magic function uses C to determine which, if any, predefined diff --git a/pod/perlmod.pod b/pod/perlmod.pod index 2f1ae5b..1174e76 100644 --- a/pod/perlmod.pod +++ b/pod/perlmod.pod @@ -77,8 +77,8 @@ use the C<*name> typeglob notation. In fact, the following have the same effect, though the first is more efficient because it does the symbol table lookups at compile time: - local(*main::foo) = *main::bar; local($main::{'foo'}) = - $main::{'bar'}; + local(*main::foo) = *main::bar; + local($main::{'foo'}) = $main::{'bar'}; You can use this to print out all the variables in a package, for instance. Here is F from the Perl library: @@ -862,7 +862,8 @@ your system man(1) command. If that fails, try the I program. =head2 Extension Modules -Extension modules are written in C (or a mix of Perl and C) and get +Extension modules are written in C (or a mix of Perl and C) and may be +statically linked or in general are dynamically loaded into Perl if and when you need them. Supported extension modules include the Socket, Fcntl, and POSIX modules. diff --git a/pod/perlobj.pod b/pod/perlobj.pod index 07a71dc..45fd24a 100644 --- a/pod/perlobj.pod +++ b/pod/perlobj.pod @@ -48,7 +48,7 @@ The C<{}> constructs a reference to an anonymous hash containing no key/value pairs. The bless() takes that reference and tells the object it references that it's now a Critter, and returns the reference. This is for convenience, because the referenced object itself knows that -it has been blessed, and its reference to it could have been returned +it has been blessed, and the reference to it could have been returned directly, like this: sub new { @@ -347,8 +347,8 @@ because it would have to do too much lookahead otherwise, just like any other postfix dereference in the language. The left side of -E is not so limited, because it's an infix operator, not a postfix operator. -That means that below, A and B are equivalent to each other, and C and D -are equivalent, but AB and CD are different: +That means that in the following, A and B are equivalent to each other, and +C and D are equivalent, but A/B and C/D are different: A: method $obref->{"fieldname"} B: (method $obref)->{"fieldname"} diff --git a/pod/perlop.pod b/pod/perlop.pod index c4a342b..8b48eaf 100644 --- a/pod/perlop.pod +++ b/pod/perlop.pod @@ -42,7 +42,7 @@ In the following sections, these operators are covered in precedence order. =head2 Terms and List Operators (Leftward) -Any TERM is of highest precedence of Perl. These includes variables, +A TERM has the highest precedence in Perl. They includes variables, quote and quote-like operators, any expression in parentheses, and any function whose arguments are parenthesized. Actually, there aren't really functions in this sense, just list operators and unary @@ -56,7 +56,7 @@ just like a normal function call. In the absence of parentheses, the precedence of list operators such as C, C, or C is either very high or very low depending on -whether you look at the left side of operator or the right side of it. +whether you are looking at the left side or the right side of the operator. For example, in @ary = (1, 3, sort 4, 2); @@ -915,7 +915,8 @@ Translates all occurrences of the characters found in the search list with the corresponding character in the replacement list. It returns the number of characters replaced or deleted. If no string is specified via the =~ or !~ operator, the $_ string is translated. (The -string specified with =~ must be a scalar variable, an array element, +string specified with =~ must be a scalar variable, an array element, a +hash element, or an assignment to one of those, i.e., an lvalue.) For B devotees, C is provided as a synonym for C. If the SEARCHLIST is delimited by bracketing quotes, the REPLACEMENTLIST has its own pair of diff --git a/pod/perlre.pod b/pod/perlre.pod index 74a8bd9..90aa9a8 100644 --- a/pod/perlre.pod +++ b/pod/perlre.pod @@ -107,12 +107,10 @@ modifier to C<{1,}>, and the "?" modifier to C<{0,1}>. n and m are limited to integral values less than 65536. By default, a quantified sub-pattern is "greedy", that is, it will match as -many times as possible without causing the rest of the pattern not to match. -The standard quantifiers are all "greedy", in that they match as many -occurrences as possible (given a particular starting location) without -causing the pattern to fail. If you want it to match the minimum number -of times possible, follow the quantifier with a "?" after any of them. -Note that the meanings don't change, just the "gravity": +many times as possible while still allowing the rest of the pattern to match. +If you want to match the minimum number of times possible, follow the +quantifier with a "?". Note that the meanings don't change, just the +"gravity": *? Match 0 or more times +? Match 1 or more times diff --git a/pod/perlref.pod b/pod/perlref.pod index 7b522ee..01b4832 100644 --- a/pod/perlref.pod +++ b/pod/perlref.pod @@ -23,7 +23,6 @@ destructed. See L for more about objects. (In a sense, everything in Perl is an object, but we usually reserve the word for references to objects that have been officially "blessed" into a class package.) - A symbolic reference contains the name of a variable, just as a symbolic link in the filesystem contains merely the name of a file. The C<*glob> notation is a kind of symbolic reference. Hard references @@ -36,14 +35,14 @@ dereferencing. When a scalar is holding a reference, it always behaves as a scalar. It doesn't magically start being an array or a hash unless you tell it so explicitly by dereferencing it. -References can be constructed several ways. +References can be constructed in several ways. =over 4 =item 1. By using the backslash operator on a variable, subroutine, or value. -(This works much like the & (address-of) operator works in C.) Note +(This works much like the & (address-of) operator in C.) Note that this typically creates I reference to a variable, because there's already a reference to the variable in the symbol table. But the symbol table reference might go away, and you'll still have the @@ -69,7 +68,7 @@ brackets: $arrayref = [1, 2, ['a', 'b', 'c']]; Here we've constructed a reference to an anonymous array of three elements -whose final element is itself reference to another anonymous array of three +whose final element is itself a reference to another anonymous array of three elements. (The multidimensional syntax described later can be used to access this. For example, after the above, C<$arrayref-E[2][1]> would have the value "b".) @@ -138,8 +137,8 @@ context even when it's called outside of the context. In human terms, it's a funny way of passing arguments to a subroutine when you define it as well as when you call it. It's useful for setting up little bits of code to run later, such as callbacks. You can even -do object-oriented stuff with it, though Perl provides a different -mechanism to do that already--see L. +do object-oriented stuff with it, though Perl already provides a different +mechanism to do that--see L. You can also think of closure as a way to write a subroutine template without using eval. (In fact, in version 5.000, eval was the I way to get diff --git a/pod/perlrun.pod b/pod/perlrun.pod index a2e0764..fc6d52d 100644 --- a/pod/perlrun.pod +++ b/pod/perlrun.pod @@ -44,7 +44,7 @@ beginning, unless you've specified a B<-x> switch, in which case it scans for the first line starting with #! and containing the word "perl", and starts there instead. This is useful for running a script embedded in a larger message. (In this case you would indicate the end -of the script using the __END__ token.) +of the script using the C<__END__> token.) The #! line is always examined for switches as the line is being parsed. Thus, if you're on a machine that allows only one argument diff --git a/pod/perlsyn.pod b/pod/perlsyn.pod index 77dcc59..9caae6a 100644 --- a/pod/perlsyn.pod +++ b/pod/perlsyn.pod @@ -39,13 +39,13 @@ as the my if you expect to be able to access those private variables. Declaring a subroutine allows a subroutine name to be used as if it were a list operator from that point forward in the program. You can declare a -subroutine (prototyped to take one scalar parameter) without defining it by saying just: +subroutine without defining it by just saying: - sub myname ($); + sub myname; $me = myname $0 or die "can't get myname"; -Note that it functions as a list operator though, not as a unary -operator, so be careful to use C instead of C<||> there. +Though note that it functions as a list operator, not as a unary +operator, so be sure to use C instead of C<||> in this case. Subroutines declarations can also be loaded up with the C statement or both loaded and imported into your namespace with a C statement. diff --git a/pod/perltrap.pod b/pod/perltrap.pod index fd91182..6600ba7 100644 --- a/pod/perltrap.pod +++ b/pod/perltrap.pod @@ -20,8 +20,8 @@ The English module, loaded via use English; -allows you to refer to special variables (like $RS) as -though they were in B; see L for details. +allows you to refer to special variables (like $/ ($RS)) with their +B equivalent; see L for details. =item * @@ -57,8 +57,8 @@ comparisons. =item * Reading an input line does not split it for you. You get to split it -yourself to an array. And the split() operator has different -arguments. +to an array yourself. And the split() operator has different +arguments than B's. =item * diff --git a/pod/perlvar.pod b/pod/perlvar.pod index 1406858..7b76666 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -459,7 +459,7 @@ the syntax error "at"?) Note that warning messages are not collected in this variable. You can, however, set up a routine to process warnings by setting C<$SIG{__WARN__}> -below. +as described below. =item $PROCESS_ID diff --git a/pod/perlxs.pod b/pod/perlxs.pod index ebead84..7338bb0 100644 --- a/pod/perlxs.pod +++ b/pod/perlxs.pod @@ -319,7 +319,7 @@ above, this keyword does not affect the way the compiler handles RETVAL. =head2 The NO_INIT Keyword The NO_INIT keyword is used to indicate that a function -parameter is being used as only an output value. The B +parameter is being used only as an output value. The B compiler will normally generate code to read the values of all function parameters from the argument stack and assign them to C variables upon entry to the function. NO_INIT @@ -328,7 +328,7 @@ output rather than for input and that they will be handled before the function terminates. The following example shows a variation of the rpcb_gettime() function. -This function uses the timep variable as only an output variable and does +This function uses the timep variable only as an output variable and does not care about its initial contents. bool_t