diff options
| -rw-r--r-- | pod/perlcall.pod | 28 | ||||
| -rw-r--r-- | pod/perldata.pod | 18 | ||||
| -rw-r--r-- | pod/perldebug.pod | 8 | ||||
| -rw-r--r-- | pod/perlembed.pod | 8 | ||||
| -rw-r--r-- | pod/perlfunc.pod | 81 | ||||
| -rw-r--r-- | pod/perlipc.pod | 10 | ||||
| -rw-r--r-- | pod/perlpod.pod | 6 | ||||
| -rw-r--r-- | pod/perlref.pod | 6 | ||||
| -rw-r--r-- | pod/perlstyle.pod | 8 | ||||
| -rw-r--r-- | pod/perlsyn.pod | 6 | ||||
| -rw-r--r-- | pod/perltie.pod | 14 | ||||
| -rw-r--r-- | pod/perlxstut.pod | 17 |
12 files changed, 106 insertions, 104 deletions
diff --git a/pod/perlcall.pod b/pod/perlcall.pod index 996c9145d0..ac9229fbb1 100644 --- a/pod/perlcall.pod +++ b/pod/perlcall.pod @@ -29,7 +29,7 @@ called instead. The classic example of where callbacks are used is when writing an event driven program like for an X windows application. In this case -your register functions to be called whenever specific events occur, +you register functions to be called whenever specific events occur, e.g. a mouse button is pressed, the cursor moves into a window or a menu item is selected. @@ -131,26 +131,26 @@ OR'ed together. Calls the Perl subroutine in a scalar context. This is the default context flag setting for all the I<perl_call_*> functions. -This flag has 2 effects +This flag has 2 effects: =over 5 =item 1. -it indicates to the subroutine being called that it is executing in a +It indicates to the subroutine being called that it is executing in a scalar context (if it executes I<wantarray> the result will be false). =item 2. -it ensures that only a scalar is actually returned from the subroutine. +It ensures that only a scalar is actually returned from the subroutine. The subroutine can, of course, ignore the I<wantarray> and return a list anyway. If so, then only the last element of the list will be returned. =back -The value returned by the I<perl_call_*> function indicates how may +The value returned by the I<perl_call_*> function indicates how many items have been returned by the Perl subroutine - in this case it will be either 0 or 1. @@ -171,27 +171,27 @@ context> shows an example of this behaviour. Calls the Perl subroutine in a list context. -As with G_SCALAR, this flag has 2 effects +As with G_SCALAR, this flag has 2 effects: =over 5 =item 1. -it indicates to the subroutine being called that it is executing in an +It indicates to the subroutine being called that it is executing in an array context (if it executes I<wantarray> the result will be true). =item 2. -it ensures that all items returned from the subroutine will be +It ensures that all items returned from the subroutine will be accessible when control returns from the I<perl_call_*> function. =back -The value returned by the I<perl_call_*> function indicates how may +The value returned by the I<perl_call_*> function indicates how many items have been returned by the Perl subroutine. -If 0, the you have specified the G_DISCARD flag. +If 0, then you have specified the G_DISCARD flag. If not 0, then it will be a count of the number of items returned by the subroutine. These items will be stored on the Perl stack. The @@ -265,7 +265,7 @@ check the C<$@> variable as you would in a normal Perl script. The value returned from the I<perl_call_*> function is dependent on what other flags have been specified and whether an error has -occurred. Here are all the different cases that can occur +occurred. Here are all the different cases that can occur: =over 5 @@ -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 section L<perlguts/"XSUB'S and the Argument Stack"> for details +See the L<perlguts/"XSUBs and the Argument Stack"> for details on how the XPUSH macros work. =item 6. @@ -1135,7 +1135,7 @@ Similarly, with this code $ref = 47 ; CallSavedSub1() ; -you can expect one of these messages (which you actually get is dependant on +you can expect one of these messages (which you actually get is dependent on the version of Perl you are using) Not a CODE reference at ... @@ -1889,7 +1889,7 @@ L<perlxs>, L<perlguts>, L<perlembed> =head1 AUTHOR -Paul Marquess <pmarquess@bfsec.bt.co.uk> +Paul Marquess E<lt>F<pmarquess@bfsec.bt.co.uk>E<gt> Special thanks to the following people who assisted in the creation of the document. diff --git a/pod/perldata.pod b/pod/perldata.pod index a72616ac33..34fd199005 100644 --- a/pod/perldata.pod +++ b/pod/perldata.pod @@ -21,7 +21,7 @@ may be a chain of identifiers, separated by C<::> (or by C<'>, but that's deprecated); all but the last are interpreted as names of packages, in order to locate the namespace in which to look up the final identifier (see L<perlmod/Packages> for details). -It's possible to substutite for a simple identifier an expression +It's possible to substitute for a simple identifier an expression which produces a reference to the value at runtime; this is described in more detail below, and in L<perlref>. @@ -103,14 +103,14 @@ list context to each of its arguments. For example, if you say int( <STDIN> ) -the integer operation provides a scalar context for the <STDIN> +the integer operation provides a scalar context for the E<lt>STDINE<gt> operator, which responds by reading one line from STDIN and passing it back to the integer operation, which will then find the integer value of that line and return that. If, on the other hand, you say sort( <STDIN> ) -then the sort operation provides a list context for <STDIN>, which +then the sort operation provides a list context for E<lt>STDINE<gt>, which will proceed to read every line available up to the end of file, and pass that list of lines back to the sort routine, which will then sort those lines and return them as a list to whatever the context @@ -163,7 +163,7 @@ defined() operator to determine whether the value is defined or not. To find out whether a given string is a valid non-zero number, it's usually enough to test it against both numeric 0 and also lexical "0" (although this will cause B<-w> noises). That's because strings that aren't -numbers count as 0, just as they do in I<awk>: +numbers count as 0, just as they do in B<awk>: if ($str == 0 && $str ne "0") { warn "That doesn't look like a number"; @@ -204,9 +204,9 @@ last value, like the C comma operator.) The following is always true: scalar(@whatever) == $#whatever - $[ + 1; -Version 5 of Perl changed the semantics of $[: files that don't set -the value of $[ no longer need to worry about whether another -file changed its value. (In other words, use of $[ is deprecated.) +Version 5 of Perl changed the semantics of C<$[>: files that don't set +the value of C<$[> no longer need to worry about whether another +file changed its value. (In other words, use of C<$[> is deprecated.) So in general you can just assume that scalar(@whatever) == $#whatever + 1; @@ -254,7 +254,7 @@ on in the script. Variable substitution inside strings is limited to scalar variables, arrays, and array slices. (In other words, names beginning with $ or @, followed by an optional bracketed expression as a subscript.) The following code segment prints out "The -price is $100." +price is $Z<>100." $Price = '$100'; # not interpreted print "The price is $Price.\n"; # interpreted @@ -306,7 +306,7 @@ by saying C<no strict 'subs'>. Array variables are interpolated into double-quoted strings by joining all the elements of the array with the delimiter specified in the C<$"> -variable ($LIST_SEPARATOR in English), space by default. The following +variable (C<$LIST_SEPARATOR> in English), space by default. The following are equivalent: $temp = join($",@ARGV); diff --git a/pod/perldebug.pod b/pod/perldebug.pod index 32c2ebf78e..f77bc92a70 100644 --- a/pod/perldebug.pod +++ b/pod/perldebug.pod @@ -106,7 +106,7 @@ supplied that includes function calls, it too will be single-stepped. Next. Executes over subroutine calls, until it reaches the beginning of the next statement. -=item <CR> +=item E<lt>CRE<gt> Repeat last C<n> or C<s> command. @@ -338,12 +338,12 @@ be uniquely abbreviated by the first letter. See "Debugger Internals" below for more details. -=item < command +=item E<lt> command Set an action to happen before every debugger prompt. A multiline command may be entered by backslashing the newlines. -=item > command +=item E<gt> command Set an action to happen after the prompt when you've just given a command to return to executing the script. A multiline command may be @@ -581,7 +581,7 @@ If true, no I/O is performed until an interrupt. =item LineInfo -File or pipe to print line number info to. If it'sis a +File or pipe to print line number info to. If it is a pipe, then a short, "emacs like" message is used. Example rc file: diff --git a/pod/perlembed.pod b/pod/perlembed.pod index 646cd670a1..d636a151f4 100644 --- a/pod/perlembed.pod +++ b/pod/perlembed.pod @@ -16,12 +16,12 @@ Read L<perlcall> and L<perlxs>. =item B<Use a UNIX program from Perl?> -Read about backquotes and L<perlfunc/system> and L<perlfunc/exec>. +Read about backquotes and about C<system> and C<exec> in L<perlfunc>. =item B<Use Perl from Perl?> -Read about L<perlfunc/do> and L<perlfunc/eval> and L<perlmod/use> -and L<perlmod/require>. +Read about C<do> and C<eval> in L<perlfunc> and C<use> +and C<require> in L<perlmod>. =item B<Use C from C?> @@ -226,7 +226,7 @@ L<Fiddling with the Perl stack from your C program> =head2 Evaluating a Perl statement from your C program NOTE: This section, and the next, employ some very brittle techniques -for evaluting strings of Perl code. Perl 5.002 contains some nifty +for evaluating strings of Perl code. Perl 5.002 contains some nifty features that enable A Better Way (such as with L<perlguts/perl_eval_sv>). Look for updates to this document soon. diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 1c78aed356..6b378730e1 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -274,7 +274,7 @@ following a minus are interpreted as file tests. The C<-T> and C<-B> switches work as follows. The first block or so of the file is examined for odd characters such as strange control codes or -characters with the high bit set. If too many odd characters (>30%) +characters with the high bit set. If too many odd characters (E<gt>30%) are found, it's a C<-B> file, otherwise it's a C<-T> file. Also, any file containing null in the first block is considered a binary file. If C<-T> or C<-B> is used on a filehandle, the current stdio buffer is examined @@ -613,7 +613,7 @@ function to iterate over large DBM files. Example: dbmclose(%HIST); See also L<AnyDBM_File> for a more general description of the pros and -cons of the various dbm apparoches, as well as L<DB_File> for a particularly +cons of the various dbm approaches, as well as L<DB_File> for a particularly rich implementation. =item defined EXPR @@ -680,7 +680,7 @@ a hash key lookup: =item die LIST Outside of an eval(), prints the value of LIST to C<STDERR> and exits with -the current value of $! (errno). If $! is 0, exits with the value of +the current value of C<$!> (errno). If C<$!> is 0, exits with the value of C<($? E<gt>E<gt> 8)> (backtick `command` status). If C<($? E<gt>E<gt> 8)> is 0, exits with 255. Inside an eval(), the error message is stuffed into C<$@>, and the eval() is terminated with the undefined value; this makes die() @@ -890,7 +890,7 @@ being looked at when: Cases 1 and 2 above behave identically: they run the code contained in the variable $x. (Although case 2 has misleading double quotes making the reader wonder what else might be happening (nothing is).) Cases 3 and 4 -likewise behave in the same way: they run the code <$x>, which does +likewise behave in the same way: they run the code E<lt>$xE<gt>, which does nothing at all. (Case 4 is preferred for purely visual reasons.) Case 5 is a place where normally you I<WOULD> like to use double quotes, except that in that particular situation, you can just use symbolic references @@ -1061,7 +1061,7 @@ example: . $str = "widget"; - $num = $cost/$quantiy; + $num = $cost/$quantity; $~ = 'Something'; write; @@ -1271,7 +1271,7 @@ Returns the socket option requested, or undefined if there is an error. =item glob EXPR Returns the value of EXPR with filename expansions such as a shell -would do. This is the internal function implementing the <*.*> +would do. This is the internal function implementing the E<lt>*.*E<gt> operator, except it's easier to use. =item gmtime EXPR @@ -1356,7 +1356,7 @@ for the package used. See also L</use>, L<perlmod>, and L<Exporter>. Returns the position of the first occurrence of SUBSTR in STR at or after POSITION. If POSITION is omitted, starts searching from the beginning of -the string. The return value is based at 0 (or whatever you've set the $[ +the string. The return value is based at 0 (or whatever you've set the C<$[> variable to--but don't do that). If the substring is not found, returns one less than the base, ordinarily -1. @@ -1577,7 +1577,7 @@ is just a funny way to write Creates the directory specified by FILENAME, with permissions specified by MODE (as modified by umask). If it succeeds it returns 1, otherwise -it returns 0 and sets $! (errno). +it returns 0 and sets C<$!> (errno). =item msgctl ID,CMD,ARG @@ -1653,13 +1653,13 @@ Opens the file whose filename is given by EXPR, and associates it with FILEHANDLE. If FILEHANDLE is an expression, its value is used as the name of the real filehandle wanted. If EXPR is omitted, the scalar variable of the same name as the FILEHANDLE contains the filename. If the filename -begins with "<" or nothing, the file is opened for input. If the filename -begins with ">", the file is opened for output. If the filename begins -with ">>", the file is opened for appending. You can put a '+' in front -of the '>' or '<' to indicate that you want both read and write access to -the file; thus '+<' is usually preferred for read/write updates--the '+>' -mode would clobber the file first. These correspond to the fopen(3) modes -of 'r', 'r+', 'w', 'w+', 'a', and 'a+'. +begins with "E<lt>" or nothing, the file is opened for input. If the filename +begins with "E<gt>", the file is opened for output. If the filename begins +with "E<gt>E<gt>", the file is opened for appending. You can put a '+' in +front of the 'E<gt>' or 'E<lt>' to indicate that you want both read and write +access to the file; thus '+E<lt>' is usually preferred for read/write +updates--the '+E<gt>' mode would clobber the file first. These correspond to +the fopen(3) modes of 'r', 'r+', 'w', 'w+', 'a', and 'a+'. If the filename begins with "|", the filename is interpreted as a command to which output is to be piped, and if the filename ends with @@ -1668,7 +1668,7 @@ for more examples of this. as command which pipes input to us. (You may not have a raw open() to a command that pipes both in I<and> out, but see L<open2>, L<open3>, and L<perlipc/"Bidirectional Communication"> for alternatives.) -Opening '-' opens STDIN and opening '>-' opens STDOUT. Open returns +Opening '-' opens STDIN and opening 'E<gt>-' opens STDOUT. Open returns non-zero upon success, the undefined value otherwise. If the open involved a pipe, the return value happens to be the pid of the subprocess. @@ -1719,11 +1719,12 @@ Examples: } You may also, in the Bourne shell tradition, specify an EXPR beginning -with ">&", in which case the rest of the string is interpreted as the +with "E<gt>&", in which case the rest of the string is interpreted as the name of a filehandle (or file descriptor, if numeric) which is to be -duped and opened. You may use & after >, >>, <, +>, +>> and +<. The +duped and opened. You may use & after E<gt>, E<gt>E<gt>, E<lt>, +E<gt>, ++E<gt>E<gt> and +E<lt>. The mode you specify should match the mode of the original filehandle. -(Duping a filehandle does not take into acount any existing contents of +(Duping a filehandle does not take into account any existing contents of stdio buffers.) Here is a script that saves, redirects, and restores STDOUT and STDERR: @@ -1751,7 +1752,7 @@ STDERR: print STDERR "stderr 2\n"; -If you specify "<&=N", where N is a number, then Perl will do an +If you specify "E<lt>&=N", where N is a number, then Perl will do an equivalent of C's fdopen() of that file descriptor; this is more parsimonious of file descriptors. For example: @@ -1760,7 +1761,7 @@ parsimonious of file descriptors. For example: If you open a pipe on the command "-", i.e. either "|-" or "-|", then there is an implicit fork done, and the return value of open is the pid of the child within the parent process, and 0 within the child -process. (Use defined($pid) to determine whether the open was successful.) +process. (Use C<defined($pid)> to determine whether the open was successful.) The filehandle behaves normally for the parent, but i/o to that filehandle is piped from/to the STDOUT/STDIN of the child process. In the child process the filehandle isn't opened--i/o happens from/to @@ -1779,9 +1780,9 @@ The following pairs are more or less equivalent: See L<perlipc/"Safe Pipe Opens"> for more examples of this. Explicitly closing any piped filehandle causes the parent process to -wait for the child to finish, and returns the status value in $?. +wait for the child to finish, and returns the status value in C<$?>. Note: on any operation which may do a fork, unflushed buffers remain -unflushed in both processes, which means you may need to set $| to +unflushed in both processes, which means you may need to set C<$|> to avoid duplicate output. Using the FileHandle constructor from the FileHandle package, @@ -1951,7 +1952,7 @@ and classes. See L<perlsub> for other scoping issues. Opens a pair of connected pipes like the corresponding system call. Note that if you set up a loop of piped processes, deadlock can occur unless you are very careful. In addition, note that Perl's pipes use -stdio buffering, so you may need to set $| to flush your WRITEHANDLE +stdio buffering, so you may need to set C<$|> to flush your WRITEHANDLE after each command, depending on the application. See L<open2>, L<open3>, and L<perlipc/"Bidirectional Communication"> @@ -2091,7 +2092,7 @@ chdir() there, it would have been testing the wrong file. Returns the value of a symbolic link, if symbolic links are implemented. If not, gives a fatal error. If there is some system -error, returns the undefined value and sets $! (errno). If EXPR is +error, returns the undefined value and sets C<$!> (errno). If EXPR is omitted, uses $_. =item recv SOCKET,SCALAR,LEN,FLAGS @@ -2167,7 +2168,7 @@ not work across filesystem boundaries. Demands some semantics specified by EXPR, or by $_ if EXPR is not supplied. If EXPR is numeric, demands that the current version of Perl -($] or $PERL_VERSION) be equal or greater than EXPR. +(C<$]> or $PERL_VERSION) be equal or greater than EXPR. Otherwise, demands that a library file be included if it hasn't already been included. The file is included via the do-FILE mechanism, which is @@ -2265,7 +2266,7 @@ last occurrence at or before that position. =item rmdir FILENAME Deletes the directory specified by FILENAME if it is empty. If it -succeeds it returns 1, otherwise it returns 0 and sets $! (errno). If +succeeds it returns 1, otherwise it returns 0 and sets C<$!> (errno). If FILENAME is omitted, uses $_. =item s/// @@ -2398,7 +2399,7 @@ You can effect a 250-millisecond sleep this way: select(undef, undef, undef, 0.25); -B<WARNING>: Do not attempt to mix buffered I/O (like read() or <FH>) +B<WARNING>: Do not attempt to mix buffered I/O (like read() or E<lt>FHE<gt>) with select(). You have to use sysread() instead. =item semctl ID,SEMNUM,CMD,ARG @@ -2547,7 +2548,7 @@ of arrays are stripped out. If SUBNAME or BLOCK is omitted, sorts in standard string comparison order. If SUBNAME is specified, it gives the name of a subroutine that returns an integer less than, equal to, or greater than 0, depending on how the elements of the array are -to be ordered. (The <=> and cmp operators are extremely useful in such +to be ordered. (The E<lt>=E<gt> and cmp operators are extremely useful in such routines.) SUBNAME may be a scalar variable name, in which case the value provides the name of the subroutine to use. In place of a SUBNAME, you can provide a BLOCK as an anonymous, in-line sort @@ -2633,7 +2634,7 @@ Examples: $a->[2] cmp $b->[2] } map { [$_, /=(\d+)/, uc($_)] } @old; -If you're and using strict, you I<MUST NOT> declare $a +If you're using strict, you I<MUST NOT> declare $a and $b as lexicals. They are package globals. That means if you're in the C<main> package, it's @@ -2657,7 +2658,7 @@ Removes the elements designated by OFFSET and LENGTH from an array, and replaces them with the elements of LIST, if any. Returns the elements removed from the array. The array grows or shrinks as necessary. If LENGTH is omitted, removes everything from OFFSET onward. The -following equivalencies hold (assuming $[ == 0): +following equivalencies hold (assuming C<$[ == 0>): push(@a,$x,$y) splice(@a,$#a+1,0,$x,$y) pop(@a) splice(@a,-1) @@ -2830,7 +2831,7 @@ last stat or filetest are returned. Example: =item study -Takes extra time to study SCALAR ($_ if unspecified) in anticipation of +Takes extra time to study SCALAR (C<$_> if unspecified) in anticipation of doing many pattern matches on the string before it is next modified. This may or may not save time, depending on the nature and number of patterns you are searching on, and on the distribution of character @@ -2869,7 +2870,7 @@ runtime, you can build an entire loop as a string and eval that to avoid recompiling all your patterns all the time. Together with undefining $/ to input entire files as one record, this can be very fast, often faster than specialized programs like fgrep(1). The following -scans a list of files (@files) for a list of words (@words), and prints +scans a list of files (C<@files>) for a list of words (C<@words>), and prints out the names of those files that contain a match: $search = 'while (<>) { study;'; @@ -3169,8 +3170,8 @@ and then there's sub ordinal { unpack("c",$_[0]); } # same as ord() -In addition, you may prefix a field with a %<number> to indicate that -you want a <number>-bit checksum of the items instead of the items +In addition, you may prefix a field with a %E<lt>numberE<gt> to indicate that +you want a E<lt>numberE<gt>-bit checksum of the items instead of the items themselves. Default is a 16-bit checksum. For example, the following computes the same number as the System V sum program: @@ -3311,13 +3312,13 @@ If you know the exact length in bits, it can be used in place of the *. Waits for a child process to terminate and returns the pid of the deceased process, or -1 if there are no child processes. The status is -returned in $?. +returned in C<$?>. =item waitpid PID,FLAGS Waits for a particular child process to terminate and returns the pid of the deceased process, or -1 if there is no such child process. The -status is returned in $?. If you say +status is returned in C<$?>. If you say use POSIX ":wait_h"; ... @@ -3353,7 +3354,7 @@ 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 format for the current output channel (see the select() function) may be set -explicitly by assigning the name of the format to the $~ variable. +explicitly by assigning the name of the format to the C<$~> variable. Top of form processing is handled automatically: if there is insufficient room on the current page for the formatted record, the @@ -3361,9 +3362,9 @@ page is advanced by writing a form feed, a special top-of-page format is used to format the new page header, and then the record is written. By default the top-of-page format is the name of the filehandle with "_TOP" appended, but it may be dynamically set to the format of your -choice by assigning the name to the $^ variable while the filehandle is +choice by assigning the name to the C<$^> variable while the filehandle is selected. The number of lines remaining on the current page is in -variable $-, which can be set to 0 to force a new page. +variable C<$->, which can be set to 0 to force a new page. If FILEHANDLE is unspecified, output goes to the current default output channel, which starts out as STDOUT but may be changed by the diff --git a/pod/perlipc.pod b/pod/perlipc.pod index 5f600b47ae..ed80850541 100644 --- a/pod/perlipc.pod +++ b/pod/perlipc.pod @@ -1,6 +1,6 @@ =head1 NAME -perlipc - Perl interprocess communication (signals, fifos, pipes, safe subprocceses, sockets, and semaphores) +perlipc - Perl interprocess communication (signals, fifos, pipes, safe subprocesses, sockets, and semaphores) =head1 DESCRIPTION @@ -96,7 +96,7 @@ handlers: But that will be problematic for the more complicated handlers that need to re-install themselves. Because Perl's signal mechanism is currently -based on the signal(3) function from the C library, you may somtimes be so +based on the signal(3) function from the C library, you may sometimes be so misfortunate as to run on systems where that function is "broken", that is, it behaves in the old unreliable SysV way rather than the newer, more reasonable BSD and POSIX fashion. So you'll see defensive people writing @@ -341,7 +341,7 @@ And here's a safe pipe open for writing: Note that these operations are full Unix forks, which means they may not be correctly implemented on alien systems. Additionally, these are not true multithreading. If you'd like to learn more about threading, see the -F<modules> file mentioned below in the L<"SEE ALSO"> section. +F<modules> file mentioned below in the SEE ALSO section. =head2 Bidirectional Communication @@ -402,13 +402,13 @@ This way you don't have to have control over the source code of the program you're using. The F<Comm> library also has expect() and interact() functions. Find the library (and hopefully its successor F<IPC::Chat>) at your nearest CPAN archive as detailed -in the L<SEE ALSO> section below. +in the SEE ALSO section below. =head1 Sockets: Client/Server Communication While not limited to Unix-derived operating systems (e.g. WinSock on PCs provides socket support, as do some VMS libraries), you may not have -sockets on your system, in which this section probably isn't going to do +sockets on your system, in which case this section probably isn't going to do you much good. With sockets, you can do both virtual circuits (i.e. TCP streams) and datagrams (i.e. UDP packets). You may be able to do even more depending on your system. diff --git a/pod/perlpod.pod b/pod/perlpod.pod index dbeaf51a2b..ce02970013 100644 --- a/pod/perlpod.pod +++ b/pod/perlpod.pod @@ -42,7 +42,7 @@ the same paragraph as "=headn" forming the heading description. Item, over, and back require a little more explanation: Over starts a section specifically for the generation of a list using =item commands. At the end of your list, use =back to end it. You will probably want to give -"4" as the number to =over, as some formatters will use this for indention. +"4" as the number to =over, as some formatters will use this for indentation. This should probably be a default. Note also that there are some basic rules to using =item: don't use them outside of an =over/=back block, use at least one inside an =over/=back block, you don't _have_ to include the =back if @@ -51,11 +51,11 @@ items consistent: either use "=item *" for all of them, to produce bullets, or use "=item 1.", "=item 2.", etc., to produce numbered lists, or use "=item foo", "=item bar", etc., i.e., things that looks nothing like bullets or numbers. If you start with bullets or numbers, stick with them, as many -formatters you the first =item type to decide how to format the list. +formatters use the first =item type to decide how to format the list. And don't forget, when using any command, that that command lasts up until the end of the B<paragraph>, not the line. Hence in the examples below, you -can see the blank lines after each command to end it's paragraph. +can see the blank lines after each command to end its paragraph. Some examples of lists include: diff --git a/pod/perlref.pod b/pod/perlref.pod index 53e9f7da1a..a7c7f438d8 100644 --- a/pod/perlref.pod +++ b/pod/perlref.pod @@ -66,7 +66,7 @@ brackets: 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 elements. (The multidimensional syntax described later can be used to -access this. For example, after the above, $arrayref-E<gt>[2][1] would have +access this. For example, after the above, C<$arrayref-E<gt>[2][1]> would have the value "b".) Note that taking a reference to an enumerated list is not the same @@ -339,7 +339,7 @@ the whole block returns a reference to an array, which is then dereferenced by C<@{...}> and stuck into the double-quoted string. This chicanery is also useful for arbitrary expressions: - print "That yeilds @{[$n + 5]} widgets\n"; + print "That yields @{[$n + 5]} widgets\n"; =head2 Symbolic references @@ -451,7 +451,7 @@ converted into a string: $x{ \$a } = $a; If you try to dereference the key, it won't do a hard dereference, and -you won't accomplish what you're attemping. You might want to do something +you won't accomplish what you're attempting. You might want to do something more like $r = \@a; diff --git a/pod/perlstyle.pod b/pod/perlstyle.pod index e4a5aab41f..46c17ddae3 100644 --- a/pod/perlstyle.pod +++ b/pod/perlstyle.pod @@ -12,7 +12,7 @@ The most important thing is to run your programs under the B<-w> flag at all times. You may turn it off explicitly for particular portions of code via the C<$^W> variable if you must. You should also always run under C<use strict> or know the reason why not. -The <use sigtrap> and even <use diagnostics> pragmas may also prove +The C<use sigtrap> and even C<use diagnostics> pragmas may also prove useful. Regarding aesthetics of code lay out, about the only thing Larry @@ -88,7 +88,7 @@ Omit redundant punctuation as long as clarity doesn't suffer. =back -Larry has his reasons for each of these things, but he doen't claim that +Larry has his reasons for each of these things, but he doesn't claim that everyone else's mind works the same as his does. Here are some other more substantive style issues to think about: @@ -169,7 +169,7 @@ the system() function instead. For portability, when using features that may not be implemented on every machine, test the construct in an eval to see if it fails. If you know what version or patchlevel a particular feature was -implemented, you can test C<$]> ($PERL_VERSION in C<English>) to see if it +implemented, you can test C<$]> (C<$PERL_VERSION> in C<English>) to see if it will be there. The C<Config> module will also let you interrogate values determined by the B<Configure> program when Perl was installed. @@ -202,7 +202,7 @@ or nature of a variable. For example: $no_caps_here function scope my() or local() variables Function and method names seem to work best as all lowercase. -E.g., $obj->as_string(). +E.g., $obj-E<gt>as_string(). You can use a leading underscore to indicate that a variable or function should not be used outside the package that defined it. diff --git a/pod/perlsyn.pod b/pod/perlsyn.pod index c3ef4501dd..459795e7cd 100644 --- a/pod/perlsyn.pod +++ b/pod/perlsyn.pod @@ -196,7 +196,7 @@ which is Perl short-hand for the more explicitly written version: # now process $line } -Or here's a a simpleminded Pascal comment stripper (warning: assumes no { or } in strings) +Or here's a simpleminded Pascal comment stripper (warning: assumes no { or } in strings). LINE: while (<STDIN>) { while (s|({.*}.*){.*}|$1 |) {} @@ -304,7 +304,7 @@ Here's how a C programmer might code up a particular algorithm in Perl: # this is where that last takes me } -Whereas here's how a Perl programmer more confortable with the idiom might +Whereas here's how a Perl programmer more comfortable with the idiom might do it: OUTER: foreach $wid (@ary1) { @@ -492,7 +492,7 @@ and your documentation text freely, as in } Note that pod translators should only look at paragraphs beginning -with a pod diretive (it makes parsing easier), whereas the compiler +with a pod directive (it makes parsing easier), whereas the compiler actually knows to look for pod escapes even in the middle of a paragraph. This means that the following secret stuff will be ignored by both the compiler and the translators. diff --git a/pod/perltie.pod b/pod/perltie.pod index 41517ac73d..7c4314188a 100644 --- a/pod/perltie.pod +++ b/pod/perltie.pod @@ -274,7 +274,7 @@ there. For example: =item DESTROY this This method will be triggered when the tied variable needs to be destructed. -As with the sclar tie class, this is almost never needed in a +As with the scalar tie class, this is almost never needed in a language that does its own garbage collection, so this time we'll just leave it out. @@ -574,7 +574,7 @@ second argument which is the last key that had been accessed. This is useful if you're carrying about ordering or calling the iterator from more than one sequence, or not really storing things in a hash anywhere. -For our example, we our using a real hash so we'll just do the simple +For our example, we're using a real hash so we'll just do the simple thing, but we'll have to indirect through the LIST field. sub NEXTKEY { @@ -609,9 +609,9 @@ use the each() function to iterate over such. Example: =head2 Tying FileHandles -This is partially implemeted now. +This is partially implemented now. -A class implementing a tied filehandle should define the folowing methods: +A class implementing a tied filehandle should define the following methods: TIEHANDLE, PRINT and/or READLINE, and possibly DESTROY. It is especially useful when perl is embedded in some other program, @@ -627,7 +627,7 @@ In our example we're going to create a shouting handle. =item TIEHANDLE classname, LIST This is the constructor for the class. That means it is expected to -return a blessed reference of some sort. The refence can be used to +return a blessed reference of some sort. The reference can be used to hold some internal information. We won't use it in out example. sub TIEHANDLE { print "<shout>\n"; my $i; bless \$i, shift } @@ -635,7 +635,7 @@ hold some internal information. We won't use it in out example. =item PRINT this, LIST This method will be triggered every time the tied handle is printed to. -Beyond its self refence it also expects the list that was passed to +Beyond its self reference it also expects the list that was passed to the print function. sub PRINT { $r = shift; $$r++; print join($,,map(uc($_),@_)),$\ } @@ -688,4 +688,4 @@ source code to MLDBM. Tom Christiansen -TIEHANDLE by Sven Verdoolaege <skimo@dns.ufsia.ac.be> +TIEHANDLE by Sven Verdoolaege E<lt>F<skimo@dns.ufsia.ac.be>E<gt> diff --git a/pod/perlxstut.pod b/pod/perlxstut.pod index 85a8c71f3f..0c6cf3fb22 100644 --- a/pod/perlxstut.pod +++ b/pod/perlxstut.pod @@ -1,6 +1,6 @@ =head1 NAME -perlXStut - Tutorial for XSUB's +perlXStut - Tutorial for XSUBs =head1 DESCRIPTION @@ -33,7 +33,7 @@ read: =item * -In versions of 5.002 prior to version beta 3, then the line in the .xs file +In versions of 5.002 prior to version beta 3, the line in the .xs file about "PROTOTYPES: DISABLE" will cause a compiler error. Simply remove that line from the file. @@ -63,7 +63,7 @@ Some systems may have installed Perl version 5 as "perl5". =head2 DYNAMIC VERSUS STATIC It is commonly thought that if a system does not have the capability to -dynamically load a library, you cannot build XSUB's. This is incorrect. +dynamically load a library, you cannot build XSUBs. This is incorrect. You I<can> build them, but you must link the XSUB's subroutines with the rest of Perl, creating a new executable. This situation is similar to Perl 4. @@ -201,7 +201,7 @@ Now we run the script and we should see the following output: =head2 EXAMPLE 2 Now let's add to our extension a subroutine that will take a single argument -and return 0 if the argument is even, 1 if the argument is odd. +and return 1 if the argument is even, 0 if the argument is odd. Add the following to the end of Mytest.xs: @@ -261,7 +261,8 @@ h2xs creates a number of files in the extension directory. The file Makefile.PL is a perl script which will generate a true Makefile to build the extension. We'll take a closer look at it later. -The files <extension>.pm and <extension>.xs contain the meat of the extension. +The files E<lt>extensionE<gt>.pm and E<lt>extensionE<gt>.xs contain the meat +of the extension. The .xs file holds the C routines that make up the extension. The .pm file contains routines that tell Perl how to load your extension. @@ -445,7 +446,7 @@ section on the argument stack. =head2 WARNING In general, it's not a good idea to write extensions that modify their input -parameters, as in Example 3. However, in order to better accomodate calling +parameters, as in Example 3. However, in order to better accommodate calling pre-existing C routines, which often do modify their input parameters, this behavior is tolerated. The next example will show how to do this. @@ -684,7 +685,7 @@ usually 0. The "ST" is actually a macro that points to the n'th argument on the argument stack. ST(0) is thus the first argument passed to the XSUB, ST(1) is the second argument, and so on. -When you list the arguments to the XSUB in the .xs file, that tell xsubpp +When you list the arguments to the XSUB in the .xs file, that tells xsubpp which argument corresponds to which of the argument stack (i.e., the first one listed is the first argument, and so on). You invite disaster if you do not list them in the same order as the function expects them. @@ -726,7 +727,7 @@ and L<perlpod>. =head2 Author -Jeff Okamoto <okamoto@corp.hp.com> +Jeff Okamoto E<lt>F<okamoto@corp.hp.com>E<gt> Reviewed and assisted by Dean Roehrich, Ilya Zakharevich, Andreas Koenig, and Tim Bunce. |