Pod updates
Cary D. Renzema [Wed, 26 Mar 1997 23:53:22 +0000 (15:53 -0800)]
Here are some fixes for the pod files.

p5p-msgid: <199703262353.PAA01819@macs.mxim.com>

17 files changed:
pod/perl.pod
pod/perlcall.pod
pod/perldata.pod
pod/perldiag.pod
pod/perlform.pod
pod/perlfunc.pod
pod/perlguts.pod
pod/perlmod.pod
pod/perlobj.pod
pod/perlop.pod
pod/perlre.pod
pod/perlref.pod
pod/perlrun.pod
pod/perlsyn.pod
pod/perltrap.pod
pod/perlvar.pod
pod/perlxs.pod

index 2c1dde2..139fd5d 100644 (file)
@@ -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
index 1ff71fc..67b59cd 100644 (file)
@@ -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<perl_call_*> function.  The section I<Returning a list in a scalar
-context> 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<Using G_EVAL> for details of using G_EVAL.
+See I<Using G_EVAL> 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<perlguts/"XSUBs and the Argument Stack"> for details
+See L<perlguts/"XSUBs and the Argument Stack"> 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<perl_call_pv> 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<perl_call_*> 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<Adder> actually made it back to
+list is returned from the subroutine, I<AddSubtract> actually made it back to
 I<call_AddSubScalar>.
 
 
@@ -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<never> drop back to the surrounding scope in Perl at
 the extreme left.
 
index f0837b3..b51e657 100644 (file)
@@ -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];
index e0a23b0..d530508 100644 (file)
@@ -383,7 +383,7 @@ will be considered a block that loops once.  See L<perlfunc/last>.
 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<perlfunc/last>.
+curlies will be considered a block that loops once.  See L<perlfunc/next>.
 
 =item Can't "redo" outside a block
 
@@ -391,7 +391,7 @@ curlies will be considered a block that loops once.  See L<perlfunc/last>.
 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<perlfunc/last>.
+curlies will be considered a block that loops once.  See L<perlfunc/redo>.
 
 =item Can't bless non-reference value
 
@@ -400,7 +400,7 @@ encapsulation of objects.  See L<perlobj>.
 
 =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<gt>' 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<gt> or E<gt>E<gt> on command line
 
@@ -1959,8 +1959,8 @@ 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 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<perlfunc/split>.
 =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.
+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<lt>%sE<gt>
 
@@ -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<perlfunc/chop>.
+because you forgot to chop() or chomp() it off.  See L<perlfunc/chomp>.
 
 =item Unsupported directory function "%s" called
 
index 4e55e02..92663b1 100644 (file)
@@ -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<perlfunc>.  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<open(MESELF, "|-")> 
-(see L<perlfunc/open()>) and always write() to MESELF instead of
+Here's another strategy; open a pipe to yourself, using C<open(MYSELF, "|-")> 
+(see L<perlfunc/open()>) 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.
 
index c4de4a3..96df297 100644 (file)
@@ -420,7 +420,7 @@ an C<L<eval EXPR>>) 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<WOULD> like to use double quotes, except that in that
+normally you I<WOULD> 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<oct>.)  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</use>, L<perlmod>, and L<Exporter>.
+for the package used.  See also L</use()>, L<perlmod>, and L<Exporter>.
 
 =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<oct>, 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.
 
index 866cafb..4a535a9 100644 (file)
@@ -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<name> and C<namlem> arguments are used to associate a string with
-the magic, typically the name of a variable. C<namlem> is stored in the
-C<mg_len> field and if C<name> is non-null and C<namlem> >= 0 a malloc'd
+The C<name> and C<namlen> arguments are used to associate a string with
+the magic, typically the name of a variable. C<namlen> is stored in the
+C<mg_len> field and if C<name> is non-null and C<namlen> >= 0 a malloc'd
 copy of the name is stored in C<mg_ptr> field.
 
 The sv_magic function uses C<how> to determine which, if any, predefined
index 2f1ae5b..1174e76 100644 (file)
@@ -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<dumpvar.pl> from the Perl library:
@@ -862,7 +862,8 @@ your system man(1) command.  If that fails, try the I<perldoc> 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.
 
index 07a71dc..45fd24a 100644 (file)
@@ -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<gt> 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"}
index c4a342b..8b48eaf 100644 (file)
@@ -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<print>, C<sort>, or C<chmod> 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<sed> devotees,
 C<y> is provided as a synonym for C<tr>.  If the SEARCHLIST is
 delimited by bracketing quotes, the REPLACEMENTLIST has its own pair of
index 74a8bd9..90aa9a8 100644 (file)
@@ -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
index 7b522ee..01b4832 100644 (file)
@@ -23,7 +23,6 @@ destructed.  See L<perlobj> 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<ANOTHER> 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<gt>[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<perlobj>.
+do object-oriented stuff with it, though Perl already provides a different
+mechanism to do that--see L<perlobj>.
 
 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<only> way to get
index a2e0764..fc6d52d 100644 (file)
@@ -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
index 77dcc59..9caae6a 100644 (file)
@@ -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<or> instead of C<||> there.
+Though note that it functions as a list operator, not as a unary
+operator, so be sure to use C<or> instead of C<||> in this case.
 
 Subroutines declarations can also be loaded up with the C<require> statement
 or both loaded and imported into your namespace with a C<use> statement.
index fd91182..6600ba7 100644 (file)
@@ -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<awk>; see L<perlvar> for details.
+allows you to refer to special variables (like $/ ($RS)) with their
+B<awk> equivalent; see L<perlvar> 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<awk>'s.
 
 =item *
 
index 1406858..7b76666 100644 (file)
@@ -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
 
index ebead84..7338bb0 100644 (file)
@@ -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<xsubpp>
+parameter is being used only as an output value.  The B<xsubpp>
 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