diff options
Diffstat (limited to 'pod')
38 files changed, 1753 insertions, 405 deletions
diff --git a/pod/modpods/AnyDBMFile.pod b/pod/modpods/AnyDBMFile.pod index 7b579ca34c..5692144586 100644 --- a/pod/modpods/AnyDBMFile.pod +++ b/pod/modpods/AnyDBMFile.pod @@ -10,16 +10,23 @@ NDBM_File, ODBM_File, SDBM_File, GDBM_File - various DBM implementations =head1 DESCRIPTION -This module is a "pure virtual base class"--it has nothing of us its own. +This module is a "pure virtual base class"--it has nothing of its own. It's just there to inherit from one of the various DBM packages. It prefers ndbm for compatibility reasons with Perl 4, then Berkeley DB (See -L<DB_File>), GDBM, SDBM (which is always there -- it comes with Perl), and -finally ODBM. This way old programs that used to use NDBM via dbmopen() can still -do so, but new ones can reorder @ISA: +L<DB_File>), GDBM, SDBM (which is always there--it comes with Perl), and +finally ODBM. This way old programs that used to use NDBM via dbmopen() +can still do so, but new ones can reorder @ISA: @AnyDBM_File::ISA = qw(DB_File GDBM_File NDBM_File); -This makes it trivial to copy database formats: +Note, however, that an explicit use overrides the specified order: + + use GDBM_File; + @AnyDBM_File::ISA = qw(DB_File GDBM_File NDBM_File); + +will only find GDBM_File. + +Having multiple DBM implementations makes it trivial to copy database formats: use POSIX; use NDBM_File; use DB_File; tie %newhash, DB_File, $new_filename, O_CREAT|O_RDWR; diff --git a/pod/modpods/Basename.pod b/pod/modpods/Basename.pod index 11cb15ee77..b0f8229e3b 100644 --- a/pod/modpods/Basename.pod +++ b/pod/modpods/Basename.pod @@ -25,7 +25,7 @@ dirname - extract just the directory from a path =head1 DESCRIPTION These routines allow you to parse file specifications into useful -pieces according using the syntax of different operating systems. +pieces using the syntax of different operating systems. =over 4 diff --git a/pod/modpods/Benchmark.pod b/pod/modpods/Benchmark.pod index bdb3f05700..6b7d949336 100644 --- a/pod/modpods/Benchmark.pod +++ b/pod/modpods/Benchmark.pod @@ -8,7 +8,7 @@ timethese - run several chunks of code several times timeit - run a chunk of code and see how long it goes -=head1 SYNOPSYS +=head1 SYNOPSIS timethis ($count, "code"); diff --git a/pod/modpods/Cwd.pod b/pod/modpods/Cwd.pod index ac4e24f74d..042db8112e 100644 --- a/pod/modpods/Cwd.pod +++ b/pod/modpods/Cwd.pod @@ -5,10 +5,10 @@ getcwd - get pathname of current working directory =head1 SYNOPSIS require Cwd; - $dir = Cwd::getcwd()' + $dir = Cwd::getcwd(); use Cwd; - $dir = getcwd()' + $dir = getcwd(); use Cwd 'chdir'; chdir "/tmp"; diff --git a/pod/modpods/Dynaloader.pod b/pod/modpods/Dynaloader.pod index 9810dad205..344fb6944a 100644 --- a/pod/modpods/Dynaloader.pod +++ b/pod/modpods/Dynaloader.pod @@ -59,7 +59,7 @@ search for libraries etc. Directories are searched in order: $dl_library_path[0], [1], ... etc @dl_library_path is initialised to hold the list of 'normal' directories -(F</usr/lib>, etc) determined by B<Configure> (C<$Config{'libpth'}.). This should +(F</usr/lib>, etc) determined by B<Configure> (C<$Config{'libpth'}>). This should ensure portability across a wide range of platforms. @dl_library_path should also be initialised with any other directories @@ -172,7 +172,7 @@ order to deal with symbolic names for files (i.e., VMS's Logical Names). To support these systems a dl_expandspec() function can be implemented either in the F<dl_*.xs> file or code can be added to the autoloadable -dl_expandspec(0 function in F<DynaLoader.pm). See F<DynaLoader.pm> for more +dl_expandspec(0 function in F<DynaLoader.pm>). See F<DynaLoader.pm> for more information. =item dl_load_file() diff --git a/pod/modpods/Exporter.pod b/pod/modpods/Exporter.pod index 03e6a1c92d..050fafa4ba 100644 --- a/pod/modpods/Exporter.pod +++ b/pod/modpods/Exporter.pod @@ -4,7 +4,7 @@ Exporter - module to control namespace manipulations import - import functions into callers namespace -=head1 SYNOPSYS +=head1 SYNOPSIS package WhatEver; require Exporter; @@ -12,7 +12,7 @@ import - import functions into callers namespace @EXPORT = qw(func1, $foo, %tabs); @EXPORT_OK = qw(sin cos); ... - use Whatever; + use WhatEver; use WhatEver 'sin'; =head1 DESCRIPTION @@ -22,7 +22,7 @@ control what they will export into their user's namespace. The WhatEver module above has placed in its export list the function C<func1()>, the scalar C<$foo>, and the hash C<%tabs>. When someone decides to -C<use WhatEver>, they get those identifier grafted +C<use WhatEver>, they get those identifiers grafted onto their own namespace. That means the user of package whatever can use the function func1() instead of fully qualifying it as WhatEver::func1(). diff --git a/pod/modpods/Find.pod b/pod/modpods/Find.pod index 81b46a9879..40a2aed300 100644 --- a/pod/modpods/Find.pod +++ b/pod/modpods/Find.pod @@ -2,7 +2,7 @@ find - traverse a file tree -=head1 SYNOPSYS +=head1 SYNOPSIS use File::Find; find(\&wanted, '/foo','/bar'); @@ -10,7 +10,7 @@ find - traverse a file tree =head1 DESCRIPTION -The wanted() function does whatever verificationsyou want. $dir contains +The wanted() function does whatever verifications you want. $dir contains the current directory name, and $_ the current filename within that directory. $name contains C<"$dir/$_">. You are chdir()'d to $dir when the function is called. The function may set $prune to prune the tree. diff --git a/pod/modpods/Finddepth.pod b/pod/modpods/Finddepth.pod index 022ddaf9f4..c6512655d1 100644 --- a/pod/modpods/Finddepth.pod +++ b/pod/modpods/Finddepth.pod @@ -2,7 +2,7 @@ finddepth - traverse a directory structure depth-first -=head1 SYNOPSYS +=head1 SYNOPSIS use File::Finddepth; finddepth(\&wanted, '/foo','/bar'); @@ -10,7 +10,5 @@ finddepth - traverse a directory structure depth-first =head2 DESCRIPTION -This is just like C<File::Find>, except that it does a depthfirst -search uses finddepth() rather than find(), and performs a -depth-first search. - +This is just like C<File::Find>, except that it does a depth-first +search and uses finddepth() rather than find(). diff --git a/pod/modpods/Getopt.pod b/pod/modpods/Getopt.pod index 2f607257ba..9cda9ec03f 100644 --- a/pod/modpods/Getopt.pod +++ b/pod/modpods/Getopt.pod @@ -10,7 +10,8 @@ GetOptions - extended getopt processing use Getopt::Std; getopt('oDI'); # -o, -D & -I take arg. Sets opt_* as a side effect. - getopts('oif:'); # likewise, but all of them + getopts('oif:'); # -o & -i are boolean flags, -f takes an argument + # Sets opt_* as a side effect. use Getopt::Long; $result = GetOptions (...option-descriptions...); diff --git a/pod/modpods/MakeMaker.pod b/pod/modpods/MakeMaker.pod index 4db758fb20..0655729598 100644 --- a/pod/modpods/MakeMaker.pod +++ b/pod/modpods/MakeMaker.pod @@ -10,7 +10,7 @@ MakeMaker - generate a Makefile for Perl extension This utility is designed to write a Makefile for an extension module from a Makefile.PL. It splits the task of generating the Makefile into several -subroutines that can be individually overridden. Each subroutines returns +subroutines that can be individually overridden. Each subroutine returns the text it wishes to have written to the Makefile. The best way to learn to use this is to look at how some of the diff --git a/pod/modpods/Open2.pod b/pod/modpods/Open2.pod index 19f0369cfd..942f68446d 100644 --- a/pod/modpods/Open2.pod +++ b/pod/modpods/Open2.pod @@ -30,4 +30,14 @@ It assumes it's going to talk to something like B<bc>, both writing to it and reading from it. This is presumably safe because you "know" that commands like B<bc> will read a line at a time and output a line at a time. Programs like B<sort> that read their entire input stream first, -however, are quite apt to cause deadlock. See L<open3> for an alternative. +however, are quite apt to cause deadlock. + +The big problem with this approach is that if you don't have control +over source code being run in the the child process, you can't control what it does +with pipe buffering. Thus you can't just open a pipe to "cat -v" and continually +read and write a line from it. + +=head1 SEE ALSO + +See L<open3> for an alternative that handles STDERR as well. + diff --git a/pod/modpods/POSIX.pod b/pod/modpods/POSIX.pod index 30539ad36f..110e46b21b 100644 --- a/pod/modpods/POSIX.pod +++ b/pod/modpods/POSIX.pod @@ -21,7 +21,7 @@ F<POSIX.pm> module. =head1 EXAMPLES - printf "EENTR is %d\n", EINTR; + printf "EINTR is %d\n", EINTR; POSIX::setsid(0); @@ -39,8 +39,8 @@ source of wisdom. A few functions are not implemented because they are C specific. If you attempt to call these, they will print a message telling you that they -aren't implemented because they're, supplying the Perl equivalent if one -exists. For example, trying to access the setjmp() call will elicit the +aren't implemented, and suggest using the Perl equivalent should one +exist. For example, trying to access the setjmp() call will elicit the message "setjmp() is C-specific: use eval {} instead". Furthermore, some evil vendors will claim 1003.1 compliance, but in fact diff --git a/pod/modpods/Ping.pod b/pod/modpods/Ping.pod index 01bc25c64f..fc52925118 100644 --- a/pod/modpods/Ping.pod +++ b/pod/modpods/Ping.pod @@ -12,7 +12,7 @@ Net::Ping, pingecho - check a host for upness This module contains routines to test for the reachability of remote hosts. Currently the only routine implemented is pingecho(). -pingecho() uses a TCP echo (I<NOT> an ICMP one) to determine if the +pingecho() uses a TCP echo (I<not> an ICMP one) to determine if the remote host is reachable. This is usually adequate to tell that a remote host is available to rsh(1), ftp(1), or telnet(1) onto. diff --git a/pod/modpods/less.pod b/pod/modpods/less.pod index bccc5341d1..37c962e90b 100644 --- a/pod/modpods/less.pod +++ b/pod/modpods/less.pod @@ -5,7 +5,7 @@ less - Perl pragma to request less of something from the compiler =head1 DESCRIPTION Currently unimplemented, this may someday be a compiler directive -to make certain trade-off, such as perhaps +to make certain trade-offs, such as perhaps use less 'memory'; use less 'CPU'; diff --git a/pod/modpods/strict.pod b/pod/modpods/strict.pod index e994ed2bc5..34a9c86934 100644 --- a/pod/modpods/strict.pod +++ b/pod/modpods/strict.pod @@ -16,9 +16,9 @@ strict - Perl pragma to restrict unsafe constructs =head1 DESCRIPTION If no import list is supplied, all possible restrictions are assumed. -(This the safest mode to operate in, but is sometimes too strict for -casual programming.) Currently, there are three possible things to be -strict about: "subs", "vars", or "refs". +(This is the safest mode to operate in, but is sometimes too strict for +casual programming.) Currently, there are three possible things to be +strict about: "subs", "vars", and "refs". =over 6 @@ -53,7 +53,7 @@ name without fully qualifying it. This disables the poetry optimization, generating a compile-time error if you -try to use a bareword identifiers that's not a subroutine. +try to use a bareword identifier that's not a subroutine. use strict 'subs'; $SIG{PIPE} = Plumber; # blows up diff --git a/pod/perl.pod b/pod/perl.pod index 9306d5c9c7..d0d15b157a 100644 --- a/pod/perl.pod +++ b/pod/perl.pod @@ -249,7 +249,7 @@ The B<-w> switch is not mandatory. Perl is at the mercy of your machine's definitions of various operations such as type casting, atof() and sprintf(). -If your stdio requires an seek or eof between reads and writes on a +If your stdio requires a seek or eof between reads and writes on a particular stream, so does Perl. (This doesn't apply to sysread() and syswrite().) diff --git a/pod/perlapi.pod b/pod/perlapi.pod index f76d877f9b..7519e875e0 100644 --- a/pod/perlapi.pod +++ b/pod/perlapi.pod @@ -947,5 +947,5 @@ File C<rpctest.pl>: Perl test program for the RPC extension. =head1 AUTHOR -Dean Roehrich <roehrich@cray.com> +Dean Roehrich C<roehrich@cray.com> September 27, 1994 diff --git a/pod/perlbook.pod b/pod/perlbook.pod index 441c43aabf..16f74df403 100644 --- a/pod/perlbook.pod +++ b/pod/perlbook.pod @@ -5,8 +5,8 @@ perlbook - Perl book information =head1 DESCRIPTION You can order Perl books from O'Reilly & Associates, 1-800-998-9938. -Local/overseas is 1-707-829-0515. If you can locate an O'Reilly order -form, you can also fax to 1-707-829-0104. I<Programming Perl> is a +Local/overseas is +1 707 829 0515. If you can locate an O'Reilly order +form, you can also fax to +1 707 829 0104. I<Programming Perl> is a reference work that covers nearly all of Perl (version 4, alas), while I<Learning Perl> is a tutorial that covers the most frequently used subset of the language. diff --git a/pod/perldata.pod b/pod/perldata.pod index 6b4f7a4053..4042ecf74e 100644 --- a/pod/perldata.pod +++ b/pod/perldata.pod @@ -40,7 +40,7 @@ Every variable type has its own namespace. You can, without fear of conflict, use the same name for a scalar variable, an array, or a hash (or, for that matter, a filehandle, a subroutine name, or a label). This means that $foo and @foo are two different variables. It also -means that $foo[1] is a part of @foo, not a part of $foo. This may +means that C<$foo[1]> is a part of @foo, not a part of $foo. This may seem a bit weird, but that's okay, because it is weird. Since variable and array references always start with '$', '@', or '%', @@ -203,9 +203,22 @@ price is $100." print "The price is $Price.\n"; # interpreted As in some shells, you can put curly brackets around the identifier to -delimit it from following alphanumerics. Also note that a +delimit it from following alphanumerics. In fact, an identifier +within such curlies is forced to be a string, as is any single +identifier within a hash subscript. Our earlier example, + + $days{'Feb'} + +can be written as + + $days{Feb} + +and the quotes will be assumed automatically. But anything more complicated +in the subscript will be interpreted as an expression. + +Note that a single-quoted string must be separated from a preceding word by a -space, since single quote is a valid (though discouraged) character in +space, since single quote is a valid (though deprecated) character in an identifier (see L<perlmod/Packages>). Two special literals are __LINE__ and __FILE__, which represent the @@ -218,7 +231,7 @@ filehandle may read data only from the main script, but not from any required file or evaluated string.) The two control characters ^D and ^Z are synonyms for __END__. -A word that doesn't have any other interpretation in the grammar will +A word that has no other interpretation in the grammar will be treated as if it were a quoted string. These are known as "barewords". As with filehandles and labels, a bareword that consists entirely of lowercase letters risks conflict with future reserved @@ -311,7 +324,7 @@ List values are denoted by separating individual values by commas (LIST) -In a context not requiring an list value, the value of the list +In a context not requiring a list value, the value of the list literal is the value of the final element, as with the C comma operator. For example, diff --git a/pod/perldiag.pod b/pod/perldiag.pod index 43b0f3f5b8..8cc2945336 100644 --- a/pod/perldiag.pod +++ b/pod/perldiag.pod @@ -14,8 +14,11 @@ desperation): (P) An internal error you should never see (trappable). (X) A very fatal error (non-trappable). -Optional warnings are enabled by using the B<-w> switch. Trappable -errors may be trapped using the eval operator. See L<perlfunc/eval>. +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 +called on each warning instead of printing it. See L<perlvar>. +Trappable errors may be trapped using the eval operator. See +L<perlfunc/eval>. Some of these messages are generic. Spots that vary are denoted with a %s, just as in a printf format. Note that some message start with a %s! @@ -128,6 +131,12 @@ the return value of your socket() call? See L<perlfunc/accept>. (F) msgsnd() requires a string at least as long as sizeof(long). +=item Ambiguous use of %s resolved as %s + +(W)(S) You said something that may not be interpreted the way +you thought. Normally it's pretty easy to disambiguate it by supplying +a missing quote, operator, paren pair or declaration. + =item Args must match #! line (F) The setuid emulator requires that the arguments Perl was invoked @@ -343,7 +352,8 @@ but then $foo no longer contains a glob. =item Can't create pipe mailbox -(F) An error peculiar to VMS. +(P) An error peculiar to VMS. The process is suffering from exhausted quotas +or other plumbing problems. =item Can't declare %s in my @@ -439,13 +449,32 @@ levels, the following is missing its final parenthesis: (F) A fatal error occurred while trying to fork while opening a pipeline. +=item Can't get filespec - stale stat buffer? + +(S) A warning peculiar to VMS. This arises because of the difference between +access checks under VMS and under the Unix model Perl assumes. Under VMS, +access checks are done by filename, rather than by bits in the stat buffer, so +that ACLs and other protections can be taken into account. Unfortunately, Perl +assumes that the stat buffer contains all the necessary information, and passes +it, instead of the filespec, to the access checking routine. It will try to +retrieve the filespec using the device name and FID present in the stat buffer, +but this works only if you haven't made a subsequent call to the CRTL stat() +routine, since the device name is overwritten with each call. If this warning +appears, the name lookup failed, and the access checking routine gave up and +returned FALSE, just to be conservative. (Note: The access checking routine +knows about the Perl C<stat> operator and file tests, so you shouldn't ever +see this warning in response to a Perl command; it arises only if some internal +code takes stat buffers lightly.) + =item Can't get pipe mailbox device name -(F) An error peculiar to VMS. +(P) An error peculiar to VMS. After creating a mailbox to act as a pipe, Perl +can't retrieve its name for later use. =item Can't get SYSGEN parameter value for MAXBUF -(F) An error peculiar to VMS. +(P) An error peculiar to VMS. Perl asked $GETSYI how big you want your +mailbox buffers to be, and didn't get an answer. =item Can't goto subroutine outside a subroutine @@ -454,6 +483,13 @@ call for another. It can't manufacture one out of whole cloth. In general you should only be calling it out of an AUTOLOAD routine anyway. See L<perlfunc/goto>. +=item Can't localize lexical variable %s + +(F) You used local on a variable name that was previous declared as a +lexical variable using "my". This is not allowed. If you want to +localize a package variable of the same name, qualify it with the +package name. + =item Can't locate %s in @INC (F) You said to do (or require, or use) a file that couldn't be found @@ -505,6 +541,28 @@ 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 ">", 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. + +=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. + +=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. + +=item Can't open output pipe (name: %s) + +(P) An error peculiar to VMS. Perl does its own command line redirection, and +couldn't open the pipe into which to send data destined for stdout. + =item Can't open perl script "%s": %s (F) The script you specified can't be opened for the indicated reason. @@ -514,6 +572,11 @@ and then read it in under a different file handle. (S) The rename done by the B<-i> switch failed for some reason, probably because you don't have write permission to the directory. +=item Can't reopen input pipe (name: %s) in binary mode + +(P) An error peculiar to VMS. Perl thought stdin was a pipe, and tried to +reopen it to accept binary data. Alas, it failed. + =item Can't reswap uid and euid (P) The setreuid() call failed for some reason in the setuid emulator @@ -568,14 +631,6 @@ message indicates that such a conversion was attempted. of upgradability. Upgrading to undef indicates an error in the code calling sv_upgrade. -=item Can't use %s as left arg of an implicit -> - -(F) The compiler tried to interpret a bracketed expression as a subscript -to an array reference. But to the left of the brackets was an expression -that didn't end in an arrow (->), or look like a subscripted expression. -Only subscripted expressions with multiple subscripts are allowed to omit -the intervening arrow. - =item Can't use %s for loop variable (F) Only a simple scalar variable may be used as a loop variable on a foreach. @@ -586,7 +641,15 @@ the intervening arrow. reference of the type needed. You can use the ref() function to test the type of the reference, if need be. -=item Can't use a string as %s ref while "strict refs" in use +=item Can't use \1 to mean $1 in expression + +(W) In an ordinary expression, backslash is a unary operator that creates +a reference to its argument. The use of backslash to indicate a backreference +to a matched substring is only valid as part of a regular expression pattern. +Trying to do this in ordinary Perl code produces a value that prints +out looking like SCALAR(0xdecaf). Use the $1 form instead. + +=item Can't use string ("%s") as %s ref while "strict refs" in use (F) Only hard references are allowed by "strict refs". Symbolic references are disallowed. See L<perlref>. @@ -609,6 +672,12 @@ the global variable) and it would be incredibly confusing to have variables in your program that looked like magical variables but weren't. +=item Can't use subscript on %s + +(F) The compiler tried to interpret a bracketed expression as a +subscript. But to the left of the brackets was an expression that +didn't look like an array reference, or anything else subscriptable. + =item Can't write to temp file for B<-e>: %s (F) The write routine failed for some reason while trying to process @@ -664,9 +733,22 @@ times than it has returned. This probably indicates an infinite recursion, unless you're writing strange benchmark programs, in which case it indicates something else. -=item Did you mean $ instead of %? +=item Did you mean $ or @ instead of %? -(W) You probably said %hash{$key} when you meant $hash{$key}. +(W) You probably said %hash{$key} when you meant $hash{$key} or @hash{@keys}. +On the other hand, maybe you just meant %hash and got carried away. + +=item Do you need to predeclare %s? + +(S) This is an educated guess made in conjunction with the message "%s +found where operator expected". It often means a subroutine or module +name is being referenced that hasn't been declared yet. This may be +because of ordering problems in your file, or because of a missing +"sub", "package", "require", or "use" statement. If you're +referencing something that isn't defined yet, you don't actually have +to define the subroutine or package before the current location. You +can use an empty "sub foo;" or "package FOO;" to enter a "forward" +declaration. =item Don't know how to handle magic of type '%s' @@ -686,6 +768,14 @@ been freed. (F) An untrapped exception was raised while executing an END subroutine. The interpreter is immediately exited. +=item Error converting file specification %s + +(F) An error peculiar to VMS. Since Perl may have to deal with file +specifications in either VMS or Unix syntax, it converts them to a +single form when it must operate on them directly. Either you've +passed an invalid file specification to Perl, or you've found a +case the conversion routines don't handle. Drat. + =item Execution of %s aborted due to compilation errors. (F) The final summary message when a Perl compilation fails. @@ -705,9 +795,12 @@ a goto, or a loop control statement. (W) You are exiting a substitution by unconventional means, such as a a return, a goto, or a loop control statement. -=item Fatal $PUTMSG error: %d +=item Fatal VMS error at %s, line %d -(F) An error peculiar to VMS. +(P) An error peculiar to VMS. Something untoward happened in a VMS system +service or RTL routine; Perl's exit status should provide more details. The +filename in "at %s" and the line number in "line %d" tell you which section of +the Perl source code is distressed. =item fcntl is not implemented @@ -789,6 +882,12 @@ on the Internet. (W) You tried to get a socket or peer socket name on a closed socket. Did you forget to check the return value of your socket() call? +=item getpwnam returned invalid UIC %#o for user "%s" + +(S) A warning peculiar to VMS. The call to C<sys$getuai> underlying the +C<getpwnam> operator returned an invalid UIC. + + =item Glob not terminated (F) The lexer saw a left angle bracket in a place where it was expecting @@ -838,6 +937,11 @@ don't take to this kindly. (F) You used an 8 or 9 in a octal number. +=item Illegal octal digit ignored + +(W) You may have tried to use an 8 or 9 in a octal number. Interpretation +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. @@ -861,6 +965,16 @@ setgid script if $ENV{PATH} is derived from data supplied (or potentially supplied) by the user. The script must set the path to a known value, using trustworthy data. See L<perlsec>. +=item Internal inconsistency in tracking vforks + +(S) A warning peculiar to VMS. Perl keeps track of the number +of times you've called C<fork> and C<exec>, in order to determine +whether the current call to C<exec> should be affect the current +script or a subprocess (see L<perlvms/exec>). Somehow, this count +has become scrambled, so Perl is making a guess and treating +this C<exec> as a request to terminate the Perl script +and execute the specified command. + =item internal disaster in regexp (P) Something went badly wrong in the regular expression parser. @@ -942,6 +1056,11 @@ one line to the next. (F) While certain functions allow you to specify a filehandle or an "indirect object" before the argument list, this ain't one of them. +=item Missing operator before %s? + +(S) This is an educated guess made in conjunction with the message "%s +found where operator expected". Often the missing operator is a comma. + =item Missing right bracket (F) The lexer counted more opening curly brackets (braces) than closing ones. @@ -1024,6 +1143,12 @@ See L<perlsec>. allowed to have a comma between that and the following arguments. Otherwise it'd be just another one of the arguments. +=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 +want to pipe the output from this command. + =item No DB::DB routine defined (F) The currently executing code was compiled with the B<-d> switch, @@ -1045,6 +1170,30 @@ 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 + +(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. + +=item No input file after < 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. + +=item No output file after > 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. + +=item No output file after > or >> 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. + =item No Perl script found in input (F) You called C<perl -x>, but no line was found in the file beginning @@ -1065,6 +1214,12 @@ your system. (F) The argument to B<-I> must follow the B<-I> immediately with no intervening space. +=item No such pipe open + +(P) An error peculiar to VMS. The internal routine my_pclose() tried to +close a pipe which hadn't been opened. This should have been caught earlier as +an attempt to close an unopened filehandle. + =item No such signal: SIG%s (W) You specified a signal name as a subscript to %SIG that was not recognized. @@ -1173,6 +1328,14 @@ since hash lists come in key/value pairs. (F) An attempt was made to use an entry in an overloading table that somehow no longer points to a valid method. See L<perlovl>. +=item Operator or semicolon missing before %s + +(S) You used a variable or subroutine call where the parser was +expecting an operator. The parser has assumed you really meant +to use an operator, but this is highly likely to be incorrect. +For example, if you say "*foo *foo" it will be interpreted as +if you said "*foo * 'foo'". + =item Out of memory for yacc stack (F) The yacc parser wanted to grow its stack so it could continue parsing, @@ -1350,6 +1513,12 @@ anyway? See L<perlfunc/require>. (F) The setuid emulator in suidperl decided you were up to no good. +=item pid %d not a child + +(W) A warning peculiar to VMS. Waitpid() was asked to wait for a process which +isn't a subprocess of the current process. While this is fine from VMS' +perspective, it's probably not what you intended. + =item POSIX getpgrp can't take an argument (F) Your C compiler uses POSIX getpgrp(), which takes no argument, unlike @@ -1458,6 +1627,11 @@ assigning to it and when evaluating its argument, while @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. +On the other hand, if you were actually hoping to treat the array +element as a list, you need to look into how references work, since +Perl will not magically convert between scalars and lists for you. See +L<perlref>. + =item Script is not setuid/setgid in suidperl (F) Oddly, the suidperl program was invoked on a script with its setuid @@ -1884,6 +2058,11 @@ you and for any luckless subroutine that you happen to call. You should use the new C<//m> and C<//s> modifiers now to do that without the dangerous action-at-a-distance effects of C<$*>. +=item Use of %s in printf format not supported + +(F) You attempted to use a feature of printf that is accessible only +from C. This usually means there's a better way to do it in Perl. + =item Use of %s is deprecated (D) The construct indicated is no longer recommended for use, generally @@ -1917,6 +2096,22 @@ when you meant to say ($one, $two) = (1, 2); +Another common error is to use ordinary parentheses to construct a list +reference when you should be using square or curly brackets, for +example, if you say + + $array = (1,2); + +when you should have said + + $array = [1,2]; + +The square brackets explicitly turn a list value into a scalar value, +while parentheses do not. So when a parenthesized list is evaluated in +a scalar context, the comma is treated like C's comma operator, which +throws away the left argument, which is not what you want. See +L<perlref> for more on this. + =item Warning: unable to close filehandle %s properly. (S) The implicit close() done by an open() got an error indication on the @@ -1998,5 +2193,26 @@ 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 + +(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. + +=item '|' and '>' 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 +command. You need to choose one or the other, though nothing's stopping you +from piping into a program or Perl script which 'splits' output into two +streams, such as + + open(OUT,">$ARGV[0]") or die "Can't write to $ARGV[0]: $!"; + while (<STDIN>) { + print; + print OUT; + } + close OUT; + =back diff --git a/pod/perlform.pod b/pod/perlform.pod index 38d7153e8b..99e0746c1a 100644 --- a/pod/perlform.pod +++ b/pod/perlform.pod @@ -8,9 +8,9 @@ Perl has a mechanism to help you generate simple reports and charts. To facilitate this, Perl helps you lay out your output page in your code in a fashion that's 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, when to -print page headers, etc. The keywords used are borrowed from FORTRAN: +print page headers, etc. Keywords are borrowed from FORTRAN: format() to declare and write() to execute; see their entries in -L<manfunc>. Fortunately, the layout is much more legible, more like +L<perlfunc>. Fortunately, the layout is much more legible, more like BASIC's PRINT USING statement. Think of it as a poor man's nroff(1). Formats, like packages and subroutines, are declared rather than executed, @@ -90,7 +90,7 @@ characters are legal to break on by changing the variable C<$:> (that's $FORMAT_LINE_BREAK_CHARACTERS if you're using the English module) to a list of the desired characters. -Since use of caret fields can produce variable length records. If the text +Using caret fields can produce variable length records. If the text to be formatted is short, you can suppress blank lines by putting a "~" (tilde) character anywhere in the line. The tilde will be translated to a space upon output. If you put a second tilde contiguous to the @@ -156,7 +156,7 @@ The current format name is stored in the variable C<$~> ($FORMAT_NAME), and the current top of form format name is in C<$^> ($FORMAT_TOP_NAME). The current output page number is stored in C<$%> ($FORMAT_PAGE_NUMBER), and the number of lines on the page is in C<$=> ($FORMAT_LINES_PER_PAGE). -Whether to autoflush output on this handle is stored in $<$|> +Whether to autoflush output on this handle is stored in C<$|> ($OUTPUT_AUTOFLUSH). The string output before each top of page (except the first) is stored in C<$^L> ($FORMAT_FORMFEED). These variables are set on a per-filehandle basis, so you'll need to select() into a different @@ -198,8 +198,8 @@ Much better! =head1 NOTES -Since the values line may contain arbitrary expression (for at fields, -not caret fields), you can farm out any more sophisticated processing +Since the values line may contain arbitrary expressions (for at fields, +not caret fields), you can farm out more sophisticated processing to other functions, like sprintf() or one of your own. For example: format Ident = @@ -291,13 +291,13 @@ For example: Or to make an swrite() subroutine which is to write() what sprintf() is to printf(), do this: - use English; use Carp; sub swrite { - croak "usage: swrite PICTURE ARGS" unless @ARG; - local($ACCUMULATOR); - formline(@ARG); - return $ACCUMULATOR; + croak "usage: swrite PICTURE ARGS" unless @_; + my $format = shift; + $^A = ""; + formline($format,@_); + return $^A; } $string = swrite(<<'END', 1, 2, 3); @@ -308,7 +308,6 @@ is to printf(), do this: =head1 WARNING -During the execution of a format, only global variables are visible, -or dynamically-scoped ones declared with local(). Lexically scoped -variables declared with my() are I<NOT> available, as they are not -considered to reside in the same lexical scope as the format. +Lexical variables (declared with "my") are not visible within a +format unless the format is declared within the scope of the lexical +variable. (They weren't visiblie at all before version 5.001.) diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index d5aa3aa0b3..42ec30fb55 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -234,12 +234,19 @@ Returns the context of the current subroutine call. In a scalar context, returns TRUE if there is a caller, that is, if we're in a subroutine or eval() or require(), and FALSE otherwise. In a list context, returns - ($package,$filename,$line) = caller; + ($package, $filename, $line) = caller; With EXPR, it returns some extra information that the debugger uses to print a stack trace. The value of EXPR indicates how many call frames to go back before the current one. + ($package, $filename, $line, + $subroutine, $hasargs, $wantargs) = caller($i); + +Furthermore, when called from within the DB package, caller returns more +detailed information: it sets sets the list variable @DB:args to be the +arguments with which that subroutine was invoked. + =item chdir EXPR Changes the working directory to EXPR, if possible. If EXPR is @@ -310,6 +317,9 @@ You can actually chop anything that's an lvalue, including an assignment: If you chop a list, each element is chopped. Only the value of the last chop is returned. +Note that chop returns the last character. To return all but the last +character, use C<substr($string, 0, -1)>. + =item chown LIST Changes the owner (and group) of a list of files. The first two @@ -371,7 +381,7 @@ Closes a directory opened by opendir(). Attempts to connect to a remote socket, just as the connect system call does. Returns TRUE if it succeeded, FALSE otherwise. NAME should be a -package address of the appropriate type for the socket. See example in +packed address of the appropriate type for the socket. See example in L<perlipc>. =item cos EXPR @@ -404,7 +414,7 @@ their own password: } Of course, typing in your own password to whoever asks you -for it is unwise at best. +for it is unwise. =item dbmclose ASSOC_ARRAY @@ -492,8 +502,8 @@ a hash key lookup: 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 -C<($? E<gt>E<gt> 8)> (`command` status). If C<($? E<gt>E<gt> 8)> is 0, -exits with 255. Inside an eval(), the error message is stuffed into C<$@>. +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. Equivalent examples: @@ -611,29 +621,33 @@ Returns 1 if the next read on FILEHANDLE will return end of file, or if FILEHANDLE is not open. FILEHANDLE may be an expression whose value gives the real filehandle name. (Note that this function actually reads a character and then ungetc()s it, so it is not very useful in an -interactive context.) An C<eof> without an argument returns the eof status -for the last file read. Empty parentheses () may be used to indicate +interactive context.) Do not read from a terminal file (or call +C<eof(FILEHANDLE)> on it) after end-of-file is reached. Filetypes such +as terminals may lose the end-of-file condition if you do. + +An C<eof> without an argument uses the last file read as argument. +Empty parentheses () may be used to indicate the pseudo file formed of the files listed on the command line, i.e. C<eof()> is reasonable to use inside a while (<>) loop to detect the end of only the last file. Use C<eof(ARGV)> or eof without the parentheses to test I<EACH> file in a while (<>) loop. Examples: + # reset line numbering on each input file + while (<>) { + print "$.\t$_"; + close(ARGV) if (eof); # Not eof(). + } + # insert dashes just before last line of last file while (<>) { if (eof()) { print "--------------\n"; + close(ARGV); # close or break; is needed if we + # are reading from the terminal } print; } - # reset line numbering on each input file - while (<>) { - print "$.\t$_"; - if (eof) { # Not eof(). - close(ARGV); - } - } - Practical hint: you almost never need to use C<eof> in Perl, because the input operators return undef when they run out of data. @@ -693,7 +707,7 @@ 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 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 particular situation, you can just use symbolic references +in that particular situation, you can just use symbolic references instead, as in case 6. =item exec LIST @@ -852,10 +866,14 @@ accumulator, C<$^A>. Eventually, when a write() is done, the contents of C<$^A> are written to some filehandle, but you could also read C<$^A> yourself and then set C<$^A> back to "". Note that a format typically does one formline() per line of form, but the formline() function itself -doesn't care how many newlines are embedded in the PICTURE. Be careful -if you put double quotes around the picture, since an "C<@>" character may -be taken to mean the beginning of an array name. formline() always -returns TRUE. +doesn't care how many newlines are embedded in the PICTURE. This means +that the ~ and ~~ tokens will treat the entire PICTURE as a single line. +You may therefore need to use multiple formlines to implement a single +record format, just like the format compiler. + +Be careful if you put double quotes around the picture, since an "C<@>" +character may be taken to mean the beginning of an array name. +formline() always returns TRUE. =item getc FILEHANDLE @@ -1018,7 +1036,7 @@ operator. =item gmtime EXPR Converts a time as returned by the time function to a 9-element array -with the time analyzed for the Greenwich timezone. Typically used as +with the time localized for the Greenwich timezone. Typically used as follows: @@ -1031,6 +1049,8 @@ the range 0..6. If EXPR is omitted, does C<gmtime(time())>. =item goto LABEL +=item goto EXPR + =item goto &NAME The goto-LABEL form finds the statement labeled with LABEL and resumes @@ -1042,6 +1062,12 @@ including out of subroutines, but it's usually better to use some other construct such as last or die. The author of Perl has never felt the need to use this form of goto (in Perl, that is--C is another matter). +The goto-EXPR form expects a label name, whose scope will be resolved +dynamically. This allows for computed gotos per FORTRAN, but isn't +necessarily recommended if you're optimizing for maintainability: + + goto ("FOO", "BAR", "GLARCH")[$i]; + The goto-&NAME form is highly magical, and substitutes a call to the named subroutine for the currently running subroutine. This is used by AUTOLOAD subroutines that wish to load another subroutine and then @@ -1081,7 +1107,7 @@ 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> below and L<perlmod>. +for the package used. See also L</use> and L<perlmod>. =item index STR,SUBSTR,POSITION @@ -1228,8 +1254,8 @@ it succeeded, FALSE otherwise. See example in L<perlipc>. =item local EXPR In general, you should be using "my" instead of "local", because it's -faster and safer. Format variables have to use "local" though, as -do any other variables whose local value must be visible to called +faster and safer. Format variables often use "local" though, as +do other variables whose current value must be visible to called subroutines. This is known as dynamic scoping. Lexical scoping is done with "my", which works more like C's auto declarations. @@ -1277,11 +1303,12 @@ parameters to a subroutine. Examples: } Note that local() is a run-time command, and so gets executed every -time through a loop. In Perl 4 it used up more stack storage each +time through a loop. In Perl 4 it used more stack storage each time until the loop was exited. Perl 5 reclaims the space each time through, but it's still more efficient to declare your variables outside the loop. +A local is simply a modifier on an lvalue expression. When you assign to a localized EXPR, the local doesn't change whether EXPR is viewed as a scalar or an array. So @@ -1435,17 +1462,37 @@ used to name the parameters to a subroutine. Examples: } # Outer @ARGV again visible -When you assign to the EXPR, the "my" doesn't change whether +The "my" is simply a modifier on something you might assign to. +So when you do assign to the EXPR, the "my" doesn't change whether EXPR is viewed as a scalar or an array. So - my($foo) = <STDIN>; + my ($foo) = <STDIN>; my @FOO = <STDIN>; both supply a list context to the righthand side, while my $foo = <STDIN>; -supplies a scalar context. +supplies a scalar context. But the following only declares one variable: + + my $foo, $bar = 1; + +That has the same effect as + + my $foo; + $bar = 1; + +The declared variable is not introduced (is not visible) until after +the current statement. Thus, + + my $x = $x; + +can be used to initialize the new $x with the value of the old $x, and +the expression + + my $x = 123 and $x == 123 + +is false unless the old $x happened to have the value 123. Some users may wish to encourage the use of lexically scoped variables. As an aid to catching implicit references to package variables, @@ -1947,8 +1994,8 @@ If EXPR is a bare word, the require assumes a "F<.pm>" extension for you, to make it easy to load standard modules. This form of loading of modules does not risk altering your namespace. -For a yet more powerful import facility, see the L</use()> below, and -also L<perlmod>. +For a yet-more-powerful import facility, see the L</use()> and +L<perlmod>. =item reset EXPR @@ -2020,7 +2067,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 is usin the POSIX module. Returns 1 upon success, 0 otherwise. +this is using the POSIX module. Returns 1 upon success, 0 otherwise. =item seekdir DIRHANDLE,POS @@ -2146,7 +2193,7 @@ implement setpgrp(2). =item setpriority WHICH,WHO,PRIORITY Sets the current priority for a process, a process group, or a user. -(See Lsetpriority(2)>.) Will produce a fatal error if used on a machine +(See setpriority(2).) Will produce a fatal error if used on a machine that doesn't implement setpriority(2). =item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL @@ -2330,7 +2377,8 @@ using C<??> as the pattern delimiters, but it still returns the array value.) The use of implicit split to @_ is deprecated, however. If EXPR is omitted, splits the $_ string. If PATTERN is also omitted, -splits on whitespace (C</[ \t\n]+/>). Anything matching PATTERN is taken +splits on whitespace (after skipping any leading whitespace). +Anything matching PATTERN is taken to be a delimiter separating the fields. (Note that the delimiter may be longer than one character.) If LIMIT is specified and is not negative, splits into no more than that many fields (though it may @@ -2340,7 +2388,7 @@ If LIMIT is negative, it is treated as if an arbitrarily large LIMIT had been specified. A pattern matching the null string (not to be confused with -a null pattern C<//., which is just one member of the set of patterns +a null pattern C<//>, which is just one member of the set of patterns matching a null string) will split the value of EXPR into separate characters at each point it matches that way. For example: @@ -2369,17 +2417,22 @@ produces the list value The pattern C</PATTERN/> may be replaced with an expression to specify patterns that vary at runtime. (To do runtime compilation only once, -use C</$variable/o>.) As a special case, specifying a space S<(' ')> will -split on white space just as split with no arguments does, but leading -white space does I<NOT> produce a null first field. Thus, split(' ') can -be used to emulate B<awk>'s default behavior, whereas C<split(/ /)> will -give you as many null initial fields as there are leading spaces. +use C</$variable/o>.) + +As a special case, specifying a PATTERN of space (C<' '>) will split on +white space just as split with no arguments does. Thus, split(' ') can +be used to emulate B<awk>'s default behavior, whereas C<split(/ /)> +will give you as many null initial fields as there are leading spaces. +A split on /\s+/ is like a split(' ') except that any leading +whitespace produces a null first field. A split with no arguments +really does a C<split(' ', $_)> internally. Example: open(passwd, '/etc/passwd'); while (<passwd>) { - ($login, $passwd, $uid, $gid, $gcos, $home, $shell) = split(/:/); + ($login, $passwd, $uid, $gid, $gcos, + $home, $shell) = split(/:/); ... } @@ -2495,7 +2548,10 @@ out the names of those files that contain a match: Extracts a substring out of EXPR and returns it. First character is at offset 0, or whatever you've set $[ to. If OFFSET is negative, starts that far from the end of the string. If LEN is omitted, returns -everything to the end of the string. You can use the substr() function +everything to the end of the string. If LEN is negative, leaves that +many characters off the end of the string. + +You can use the substr() function as an lvalue, in which case EXPR must be an lvalue. If you assign something shorter than LEN, the string will shrink, and if you assign something longer than LEN, the string will grow to accommodate it. To @@ -2580,15 +2636,15 @@ the corresponding system library routine. =item tie VARIABLE,PACKAGENAME,LIST This function binds a variable to a package that will provide the -implementation for the variable. VARIABLE is the name of the variable -to be enchanted. PACKAGENAME is the name of a package implementing -objects of correct type. Any additional arguments are passed to the -"new" method of the package. Typically these are arguments such as -might be passed to the dbm_open() function of C. +implementation for the variable. VARIABLE is the name of the variable to +be enchanted. PACKAGENAME is the name of a package implementing objects +of correct type. Any additional arguments are passed to the "new" method +of the package (meaning TIESCALAR, TIEARRAY, or TIEHASH). Typically these +are arguments such as might be passed to the dbm_open() function of C. Note that functions such as keys() and values() may return huge array -values when used on large DBM files. You may prefer to use the each() -function to iterate over large DBM files. Example: +values when used on large objects, like DBM files. You may prefer to +use the each() function to iterate over such. Example: # print out history file offsets tie(%HIST, NDBM_File, '/usr/lib/news/history', 1, 0); diff --git a/pod/perlipc.pod b/pod/perlipc.pod index a2f3f8b16d..5a43660fb2 100644 --- a/pod/perlipc.pod +++ b/pod/perlipc.pod @@ -34,10 +34,10 @@ Here's a sample TCP client. gethostbyname($hostname); ($name, $aliases, $type, $len, $thataddr) = gethostbyname($them); - $this = pack($sockaddr, &AF_INET, 0, $thisaddr); - $that = pack($sockaddr, &AF_INET, $port, $thataddr); + $this = pack($sockaddr, AF_INET, 0, $thisaddr); + $that = pack($sockaddr, AF_INET, $port, $thataddr); - socket(S, &PF_INET, &SOCK_STREAM, $proto) || die "socket: $!"; + socket(S, PF_INET, SOCK_STREAM, $proto) || die "socket: $!"; bind(S, $this) || die "bind: $!"; connect(S, $that) || die "connect: $!"; @@ -69,11 +69,11 @@ And here's a server: ($name, $aliases, $port) = getservbyname($port, 'tcp') unless $port =~ /^\d+$/; - $this = pack($sockaddr, &AF_INET, $port, "\0\0\0\0"); + $this = pack($sockaddr, AF_INET, $port, "\0\0\0\0"); select(NS); $| = 1; select(stdout); - socket(S, &PF_INET, &SOCK_STREAM, $proto) || die "socket: $!"; + socket(S, PF_INET, SOCK_STREAM, $proto) || die "socket: $!"; bind(S, $this) || die "bind: $!"; listen(S, 5) || die "connect: $!"; diff --git a/pod/perlmod.pod b/pod/perlmod.pod index d804b1e4ed..dc825d6386 100644 --- a/pod/perlmod.pod +++ b/pod/perlmod.pod @@ -6,8 +6,10 @@ perlmod - Perl modules (packages) =head2 Packages -Perl provides a mechanism for alternate namespaces to protect packages -from stomping on each others variables. By default, a Perl script starts +Perl provides a mechanism for alternative namespaces to protect packages +from stomping on each others variables. In fact, apart from certain magical +variables, there's really no such thing as a global variable in Perl. +By default, a Perl script starts compiling into the package known as C<main>. You can switch namespaces using the C<package> declaration. The scope of the package declaration is from the declaration itself to the end of the enclosing block (the same @@ -34,11 +36,11 @@ It would treat package C<INNER> as a totally separate global package. Only identifiers starting with letters (or underscore) are stored in a package's symbol table. All other symbols are kept in package C<main>. -In addition, the identifiers STDIN, STDOUT, STDERR, C<ARGV>, +In addition, the identifiers STDIN, STDOUT, STDERR, ARGV, ARGVOUT, ENV, INC and SIG are forced to be in package C<main>, even when used for other purposes than their built-in one. Note also that, if you have a package called C<m>, C<s> or C<y>, then you can't use -the qualified form of an identifier since it will be interpreted instead +the qualified form of an identifier because it will be interpreted instead as a pattern match, a substitution, or a translation. (Variables beginning with underscore used to be forced into package @@ -47,7 +49,7 @@ to use leading underscore to indicate private variables and method names.) Eval()ed strings are compiled in the package in which the eval() was compiled. (Assignments to C<$SIG{}>, however, assume the signal -handler specified is in the C<main. package. Qualify the signal handler +handler specified is in the C<main> package. Qualify the signal handler name if you wish to have a signal handler in a package.) For an example, examine F<perldb.pl> in the Perl library. It initially switches to the C<DB> package so that the debugger doesn't interfere with variables @@ -111,7 +113,7 @@ i.e., *dick = *richard; -causes variables, subroutines and filehandles accessible via the +causes variables, subroutines and file handles accessible via the identifier C<richard> to also be accessible via the symbol C<dick>. If you only want to alias a particular variable or subroutine, you can assign a reference instead: @@ -139,7 +141,7 @@ An C<END> subroutine is executed as late as possible, that is, when the interpreter is being exited, even if it is exiting as a result of a die() function. (But not if it's is being blown out of the water by a signal--you have to trap that yourself (if you can).) You may have -multiple C<END> blocks within a file--they wil execute in reverse +multiple C<END> blocks within a file--they will execute in reverse order of definition; that is: last in, first out (LIFO). Note that when you use the B<-n> and B<-p> switches to Perl, C<BEGIN> @@ -244,7 +246,7 @@ you're redefining the world and willing to take the consequences. A number of modules are included the the Perl distribution. These are described below, and all end in F<.pm>. You may also discover files in the library directory that end in either F<.pl> or F<.ph>. These are old -libaries supplied so that old programs that use them still run. The +libraries supplied so that old programs that use them still run. The F<.pl> files will all eventually be converted into standard modules, and the F<.ph> files made by B<h2ph> will probably end up as extension modules made by B<h2xs>. (Some F<.ph> values may already be available through the @@ -255,7 +257,7 @@ conversion, but it's just a mechanical process, so is far from bullet proof. They work somewhat like pragmas in that they tend to affect the compilation of your program, and thus will usually only work well when used within a -C<use>, or C<no>. These are locally scoped, so if an inner BLOCK +C<use>, or C<no>. These are locally scoped, so an inner BLOCK may countermand any of these by saying no integer; @@ -291,7 +293,7 @@ Perl pragma to predeclare sub names =head2 Standard Modules -The following modules are all expacted to behave in a well-defined +The following modules are all expected to behave in a well-defined manner with respect to namespace pollution because they use the Exporter module. See their own documentation for details. @@ -316,7 +318,7 @@ split a package for autoloading =item C<Basename> -parse file anme and path from a specification +parse file name and path from a specification =item C<Benchmark> @@ -411,11 +413,11 @@ dynamically loaded into Perl if and when you need them. Supported extension modules include the Socket, Fcntl, and POSIX modules. The following are popular C extension modules, which while available at -Perl 5.0 release time, do not come not bundled (at least, not completely) +Perl 5.0 release time, do not come bundled (at least, not completely) due to their size, volatility, or simply lack of time for adequate testing and configuration across the multitude of platforms on which Perl was beta-tested. You are encouraged to look for them in archie(1L), the Perl -FAQ or Meta-FAQ, the WWW page, and even their authors before randomly +FAQ or Meta-FAQ, the WWW page, and even with their authors before randomly posting asking for their present condition and disposition. There's no guarantee that the names or addresses below have not changed since printing, and in fact, they probably have! @@ -454,7 +456,7 @@ where. =item C<Sx> This extension module is a front to the Athena and Xlib libraries for Perl -GUI progamming, originally written by by Dominic Giampaolo +GUI programming, originally written by by Dominic Giampaolo <F<dbg@sgi.com>>, then and rewritten for Sx by FrE<eacute>dE<eacute>ric Chauveau <F<fmc@pasteur.fr>>. It's available for FTP from diff --git a/pod/perlobj.pod b/pod/perlobj.pod index e4f34ba48d..6bbaab4704 100644 --- a/pod/perlobj.pod +++ b/pod/perlobj.pod @@ -69,7 +69,7 @@ reference as an ordinary reference. Outside the class package, the reference is generally treated as an opaque value that may only be accessed through the class's methods. -A constructor may rebless a referenced object currently belonging to +A constructor may re-bless a referenced object currently belonging to another class, but then the new class is responsible for all cleanup later. The previous blessing is forgotten, as an object may only belong to one class at a time. (Although of course it's free to @@ -224,6 +224,13 @@ name with the package like this: $fred = Critter->MyCritter::find("Fred"); $fred->MyCritter::display('Height', 'Weight'); +Sometimes you want to call a method when you don't know the method name +ahead of time. You can use the arrow form, replacing the method name +with a simple scalar variable containing the method name: + + $method = $fast ? "findfirst" : "findbest"; + $fred->$method(@args); + =head2 Destructors When the last reference to an object goes away, the object is @@ -240,6 +247,21 @@ applies to reblessed objects--an object reference that is merely I<CONTAINED> in the current object will be freed and destroyed automatically when the current object is freed. +=head2 WARNING + +An indirect object is limited to a name, a scalar variable, or a block, +because it would have to do too much lookahead otherwise, just like any +other postfix dereference in the language. The left side of -> 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: + + A: method $obref->{"fieldname"} + B: (method $obref)->{"fieldname"} + C: $obref->{"fieldname"}->method() + D: method {$obref->{"fieldname"}} + =head2 Summary That's about all there is to it. Now you just need to go off and buy a diff --git a/pod/perlop.pod b/pod/perlop.pod index d33ce931c2..574e9238d8 100644 --- a/pod/perlop.pod +++ b/pod/perlop.pod @@ -454,7 +454,7 @@ is equivalent to $a += 2; $a *= 3; -=head2 +=head2 Comma Operator Binary "," is the comma operator. In a scalar context it evaluates its left argument, throws that value away, then evaluates its right @@ -463,6 +463,9 @@ argument and returns that value. This is just like C's comma operator. In a list context, it's just the list argument separator, and inserts both its arguments into the list. +The => digraph is simply a synonym for the comma operator. It's useful +for documenting arguments that come in pairs. + =head2 List Operators (Rightward) On the right side of a list operator, it has very low precedence, @@ -874,6 +877,12 @@ Examples: tr [\200-\377] [\000-\177]; # delete 8th bit +If multiple translations are given for a character, only the first one is used: + + tr/AAA/XYZ/ + +will translate any A to X. + Note that because the translation table is built at compile time, neither the SEARCHLIST nor the REPLACEMENTLIST are subjected to double quote interpolation. That means that if you want to use variables, you must use @@ -905,20 +914,20 @@ To pass a $ through to the shell you need to hide it with a backslash. The generalized form of backticks is C<qx//>. Evaluating a filehandle in angle brackets yields the next line from -that file (newline included, so it's never false until end of file, at which -time an undefined value is returned). Ordinarily you must assign that -value to a variable, but there is one situation where an automatic +that file (newline included, so it's never false until end of file, at +which time an undefined value is returned). Ordinarily you must assign +that value to a variable, but there is one situation where an automatic assignment happens. I<If and ONLY if> the input symbol is the only thing inside the conditional of a C<while> loop, the value is -automatically assigned to the variable C<$_>. (This may seem like an -odd thing to you, but you'll use the construct in almost every Perl -script you write.) Anyway, the following lines are equivalent to each -other: +automatically assigned to the variable C<$_>. The assigned value is +then tested to see if it is defined. (This may seem like an odd thing +to you, but you'll use the construct in almost every Perl script you +write.) Anyway, the following lines are equivalent to each other: - while ($_ = <STDIN>) { print; } + while (defined($_ = <STDIN>)) { print; } while (<STDIN>) { print; } for (;<STDIN>;) { print; } - print while $_ = <STDIN>; + print while defined($_ = <STDIN>); print while <STDIN>; The filehandles STDIN, STDOUT and STDERR are predefined. (The diff --git a/pod/perlovl.pod b/pod/perlovl.pod index db00f4dbf1..cdb3ba66c5 100644 --- a/pod/perlovl.pod +++ b/pod/perlovl.pod @@ -114,7 +114,7 @@ arrays, C<cmp> is used to compare values subject to %OVERLOAD. =item * I<Bit operations> - "&", "^", "|", "neg", "!", "~", + "&", "^", "|", "&=", "^=", "|=", "neg", "!", "~", "C<neg>" stands for unary minus. If the method for C<neg> is not specified, it can be autogenerated using on the method for subtraction. @@ -206,10 +206,7 @@ C<$OVERLOAD{"nomethod"}>, and if this is missing, raises an exception. =head2 Copy Constructor C<$OVERLOAD{"="}> is a reference to a function with three arguments, -i.e., it looks like a usual value of %OVERLOAD. What is special about -this subroutine is that it should not return a blessed reference into -a package (as most other methods are expected to), but rather a freshly made -copy of its dereferenced argument (see L<"BUGS">, though). This operation +i.e., it looks like a usual value of %OVERLOAD. This operation is called in the situations when a mutator is applied to a reference that shares its object with some other reference, such as @@ -287,7 +284,8 @@ value is scalar but not a reference. =head1 WARNING The restriction for the comparison operation is that even if, for example, -`C<cmp>' should return a blessed reference, the autogenerated `C<lt>' +`C<cmp>' should return a reference to a blessed object, the +autogenerated `C<lt>' function will produce only a standard logical value based on the numerical value of the result of `C<cmp>'. In particular, a working numeric conversion is needed in this case (possibly expressed in terms of @@ -351,12 +349,6 @@ induces diagnostic messages. Because it's used for overloading, the per-package associative array %OVERLOAD now has a special meaning in Perl. -Although the copy constructor is specially designed to make overloading -operations with references to an array simpler, as it now works it's -useless for this because a subroutine cannot return an array in the same -way as it returns a scalar (from the point of view of Perl -internals). Expect a change of interface for the copy constructor. - As shipped, %OVERLOAD is not inherited via the @ISA tree. A patch for this is available from the author. diff --git a/pod/perlre.pod b/pod/perlre.pod index 1324642f71..295b6bd518 100644 --- a/pod/perlre.pod +++ b/pod/perlre.pod @@ -297,11 +297,9 @@ first alternative includes everything from the last pattern delimiter the last alternative contains everything from the last "|" to the next pattern delimiter. For this reason, it's common practice to include alternatives in parentheses, to minimize confusion about where they -start and end. Note also that the pattern C<(fee|fie|foe)> differs -from the pattern C<[fee|fie|foe]> in that the former matches "fee", -"fie", or "foe" in the target string, while the latter matches -anything matched by the classes C<[fee]>, C<[fie]>, or C<[foe]> (i.e. -the class C<[feio]>). +start and end. Note however that "|" is interpreted as a literal with +square brackets, so if you write C<[fee|fie|foe]> you're really only +matching C<[feio|]>. Within a pattern, you may designate subpatterns for later reference by enclosing them in parentheses, and you may refer back to the I<n>th @@ -309,7 +307,7 @@ subpattern later in the pattern using the metacharacter \I<n>. Subpatterns are numbered based on the left to right order of their opening parenthesis. Note that a backreference matches whatever actually matched the subpattern in the string being examined, not the -rules for that subpattern. Therefore, C<([0|0x])\d*\s\1\d*> will +rules for that subpattern. Therefore, C<(0|0x)\d*\s\1\d*> will match "0x1234 0x4321",but not "0x1234 01234", since subpattern 1 -actually matched "0x", even though the rule C<[0|0x]> could +actually matched "0x", even though the rule C<0|0x> could potentially match the leading 0 in the second number. diff --git a/pod/perlref.pod b/pod/perlref.pod index 0ad25dfe66..f12cad4554 100644 --- a/pod/perlref.pod +++ b/pod/perlref.pod @@ -108,29 +108,54 @@ matter how many times you execute that line (unless you're in an C<eval("...")>), C<$coderef> will still have a reference to the I<SAME> anonymous subroutine.) -For those who worry about these things, the current implementation -uses shallow binding of local() variables; my() variables are not -accessible. This precludes true closures. However, you can work -around this with a run-time (rather than a compile-time) eval(): - - { - my $x = time; - $coderef = eval "sub { \$x }"; +Anonymous subroutines act as closures with respect to my() variables, +that is, variables visible lexically within the current scope. Closure +is a notion out of the Lisp world that says if you define an anonymous +function in a particular lexical context, it pretends to run in that +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>. + +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 +closures. You may wish to use "require 5.001" if you use closures.) + +Here's a small example of how closures works: + + sub newprint { + my $x = shift; + return sub { my $y = shift; print "$x, $y!\n"; }; } + $h = newprint("Howdy"); + $g = newprint("Greetings"); + + # Time passes... + + &$h("world"); + &$g("earthlings"); -Normally--if you'd used just C<sub{}> or even C<eval{}>--your unew sub -would only have been able to access the global $x. But because you've -used a run-time eval(), this will not only generate a brand new subroutine -reference each time called, it will all grant access to the my() variable -lexically above it rather than the global one. The particular $x -accessed will be different for each new sub you create. This mechanism -yields deep binding of variables. (If you don't know what closures, deep -binding, or shallow binding are, don't worry too much about it.) +This prints + + Howdy, world! + Greetings, earthlings! + +Note particularly that $x continues to refer to the value passed into +newprint() *despite* the fact that the "my $x" has seemingly gone out of +scope by the time the anonymous subroutine runs. That's what closure +is all about. + +This only applies to lexical variables, by the way. Dynamic variables +continue to work as they have always worked. Closure is not something +that most Perl programmers need trouble themselves about to begin with. =item 5. References are often returned by special subroutines called constructors. -Perl objects are just reference a special kind of object that happens to know +Perl objects are just references to a special kind of object that happens to know which package it's associated with. Constructors are just special subroutines that know how to create that association. They do so by starting with an ordinary reference, and it remains an ordinary reference @@ -217,7 +242,7 @@ cumbersome to use method 2. As a form of syntactic sugar, the two lines like that above can be written: $arrayref->[0] = "January"; - $hashref->{"KEY} = "VALUE"; + $hashref->{"KEY"} = "VALUE"; The left side of the array can be any expression returning a reference, including a previous dereference. Note that C<$array[$x]> is I<NOT> the @@ -325,6 +350,70 @@ invisible to this mechanism. For example: This will still print 10, not 20. Remember that local() affects package variables, which are all "global" to the package. +=head2 Not-so-symbolic references + +A new feature contributing to readability in 5.001 is that the brackets +around a symbolic reference behave more like quotes, just as they +always have within a string. That is, + + $push = "pop on "; + print "${push}over"; + +has always meant to print "pop on over", despite the fact that push is +a reserved word. This has been generalized to work the same outside +of quotes, so that + + print ${push} . "over"; + +and even + + print ${ push } . "over"; + +will have the same effect. (This would have been a syntax error in +5.000, though Perl 4 allowed it in the spaceless form.) Note that this +construct is I<not> considered to be a symbolic reference when you're +using strict refs: + + use strict 'refs'; + ${ bareword }; # Okay, means $bareword. + ${ "bareword" }; # Error, symbolic reference. + +Similarly, because of all the subscripting that is done using single +words, we've applied the same rule to any bareword that is used for +subscripting a hash. So now, instead of writing + + $array{ "aaa" }{ "bbb" }{ "ccc" } + +you can just write + + $array{ aaa }{ bbb }{ ccc } + +and not worry about whether the subscripts are reserved words. In the +rare event that you do wish to do something like + + $array{ shift } + +you can force interpretation as a reserved word by adding anything that +makes it more than a bareword: + + $array{ shift() } + $array{ +shift } + $array{ shift @_ } + +The B<-w> switch will warn you if it interprets a reserved word as a string. +But it will no longer warn you about using lowercase words, since the +string is effectively quoted. + +=head2 WARNING + +You may not (usefully) use a reference as the key to a hash. It will be +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. + =head2 Further Reading Besides the obvious documents, source code can be instructive. diff --git a/pod/perlrun.pod b/pod/perlrun.pod index 5179abccd4..37be506d62 100644 --- a/pod/perlrun.pod +++ b/pod/perlrun.pod @@ -123,7 +123,8 @@ An alternate delimiter may be specified using B<-F>. =item B<-c> causes Perl to check the syntax of the script and then exit without -executing it. +executing it. Actually, it will execute C<BEGIN> and C<use> blocks, +since these are considered part of the compilation. =item B<-d> @@ -361,8 +362,8 @@ scalar variables that are used before being set. Also warns about redefined subroutines, and references to undefined filehandles or filehandles opened readonly that you are attempting to write on. Also warns you if you use values as a number that doesn't look like numbers, using -a an array as though it were a scalar, if -your subroutines recurse more than 100 deep, and innumeriable other things. +an array as though it were a scalar, if +your subroutines recurse more than 100 deep, and innumerable other things. See L<perldiag> and L<perltrap>. =item B<-x> I<directory> diff --git a/pod/perlsec.pod b/pod/perlsec.pod index 0be4f52798..2bd659ebb1 100644 --- a/pod/perlsec.pod +++ b/pod/perlsec.pod @@ -108,7 +108,7 @@ so you must be careful with your patterns. This is the I<ONLY> mechanism for untainting user supplied filenames if you want to do file operations on them (unless you make C<$E<gt>> equal to C<$E<lt>> ). -For "Insecure PATH" messages, you need to set C<$ENV{'PATH}'> to a known +For "Insecure $ENV{PATH}" messages, you need to set C<$ENV{'PATH'}> to a known value, and each directory in the path must be non-writable by the world. A frequently voiced gripe is that you can get this message even if the pathname to an executable is fully qualified. But Perl can't diff --git a/pod/perlsub.pod b/pod/perlsub.pod index cfc8b5611f..1f5201a4c7 100644 --- a/pod/perlsub.pod +++ b/pod/perlsub.pod @@ -9,6 +9,10 @@ To declare subroutines: sub NAME; # A "forward" declaration. sub NAME BLOCK # A declaration and a definition. +To define an anonymous subroutine at runtime: + + $subref = sub BLOCK; + To import subroutines: use PACKAGE qw(NAME1 NAME2 NAME3); @@ -26,12 +30,12 @@ Any arguments passed to the routine come in as array @_, that is ($_[0], $_[1], ...). The array @_ is a local array, but its values are references to the actual scalar parameters. The return value of the subroutine is the value of the last expression evaluated, and can be -either an array value or a scalar value. Alternately, a return +either an array value or a scalar value. Alternatively, a return statement may be used to specify the returned value and exit the subroutine. To create local variables see the local() and my() operators. -A subroutine may called using the "&" prefix. The "&" is optional in Perl +A subroutine may be called using the "&" prefix. The "&" is optional in Perl 5, and so are the parens if the subroutine has been predeclared. (Note, however, that the "&" is I<NOT> optional when you're just naming the subroutine, such as when it's used as an argument to defined() or @@ -97,6 +101,17 @@ visible to subroutine instead. &foo(); # the same &foo; # pass no arguments--more efficient +If a module wants to create a private subroutine that cannot be called +from outside the module, it can declare a lexical variable containing +an anonymous sub reference: + + my $subref = sub { ... } + &$subref(1,2,3); + +As long as the reference is never returned by any function within the module, +no outside module can see the subroutine, since its name is not in any +package's symbol table. + =head2 Passing Symbol Table Entries [Note: The mechanism described in this section works fine in Perl 5, but diff --git a/pod/perlsyn.pod b/pod/perlsyn.pod index 3ddb493c8b..252e679b72 100644 --- a/pod/perlsyn.pod +++ b/pod/perlsyn.pod @@ -55,7 +55,7 @@ The only kind of simple statement is an expression evaluated for its side effects. Every simple statement must be terminated with a semicolon, unless it is the final statement in a block, in which case the semicolon is optional. (A semicolon is still encouraged there if the -block takes up more than one line, since you may add another line.) +block takes up more than one line, since you may eventually add another line.) Note that there are some operators like C<eval {}> and C<do {}> that look like compound statements, but aren't (they're just TERMs in an expression), and thus need an explicit termination @@ -106,7 +106,7 @@ The following compound statements may be used to control flow: LABEL while (EXPR) BLOCK LABEL while (EXPR) BLOCK continue BLOCK LABEL for (EXPR; EXPR; EXPR) BLOCK - LABEL foreach VAR (ARRAY) BLOCK + LABEL foreach VAR (LIST) BLOCK LABEL BLOCK continue BLOCK Note that, unlike C and Pascal, these are defined in terms of BLOCKs, @@ -164,13 +164,15 @@ is the same as The foreach loop iterates over a normal list value and sets the variable VAR to be each element of the list in turn. The variable is -implicitly local to the loop (unless declared previously with C<my>), -and regains its former value upon exiting the loop. The C<foreach> -keyword is actually a synonym for the C<for> keyword, so you can use -C<foreach> for readability or C<for> for brevity. If VAR is omitted, $_ -is set to each value. If ARRAY is an actual array (as opposed to an -expression returning a list value), you can modify each element of the -array by modifying VAR inside the loop. Examples: +implicitly local to the loop and regains its former value upon exiting +the loop. (If the variable was previously declared with C<my>, it uses +that variable instead of the global one, but it's still localized to +the loop.) The C<foreach> keyword is actually a synonym for the C<for> +keyword, so you can use C<foreach> for readability or C<for> for +brevity. If VAR is omitted, $_ is set to each value. If LIST is an +actual array (as opposed to an expression returning a list value), you +can modify each element of the array by modifying VAR inside the loop. +Examples: for (@ary) { s/foo/bar/; } diff --git a/pod/perltrap.pod b/pod/perltrap.pod index 51dac4770f..fa68a753c2 100644 --- a/pod/perltrap.pod +++ b/pod/perltrap.pod @@ -292,12 +292,22 @@ unary ones.) See L<perlop>. =item * -People have a hard type remembering that some functions +People have a hard time remembering that some functions default to $_, or @ARGV, or whatever, but that others which you might expect to do not. =item * +The <FH> construct is not the name of the filehandle, it is a readline +operation on that handle. The data read is only assigned to $_ if the +file read is the sole condition in a while loop: + + while (<FH>) { } + while ($_ = <FH>) { }.. + <FH>; # data discarded! + +=item * + Remember not to use "C<=>" when you need "C<=~>"; these two constructs are quite different: @@ -332,12 +342,13 @@ C<@> now always interpolates an array in double-quotish strings. Some programs may now need to use backslash to protect any C<@> that shouldn't interpolate. =item * + Barewords that used to look like strings to Perl will now look like subroutine calls if a subroutine by that name is defined before the compiler sees them. For example: sub SeeYa { die "Hasta la vista, baby!" } - $SIG{QUIT} = SeeYa; + $SIG{'QUIT'} = SeeYa; In Perl 4, that set the signal handler; in Perl 5, it actually calls the function! You may use the B<-w> switch to find such places. @@ -442,6 +453,12 @@ since this capability may be onerous for some modules to implement. =item * +The construct "this is $$x" used to interpolate the pid at that +point, but now tries to dereference $x. C<$$> by itself still +works fine, however. + +=item * + Some error messages will be different. =item * diff --git a/pod/perlvar.pod b/pod/perlvar.pod index bdf24f6c89..bfd04f74d4 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -38,9 +38,9 @@ new value for the FileHandle attribute in question. If not supplied, most of the methods do nothing to the current value, except for autoflush(), which will assume a 1 for you, just to be different. -A few of these variables are considered "read-only". This means that if you -try to assign to this variable, either directly or indirectly through -a reference. If you attempt to do so, you'll raise a run-time exception. +A few of these variables are considered "read-only". This means that if +you try to assign to this variable, either directly or indirectly through +a reference, you'll raise a run-time exception. =over 8 @@ -379,6 +379,9 @@ last eval() parsed and executed correctly (although the operations you invoked may have failed in the normal fashion). (Mnemonic: Where was 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 $SIG{__WARN__} below. + =item $PROCESS_ID =item $PID @@ -602,7 +605,23 @@ the Perl script. Here are some other examples: The one marked scary is problematic because it's a bareword, which means sometimes it's a string representing the function, and sometimes it's going to call the subroutine call right then and there! Best to be sure -and quote it or take a reference to it. *Plumber works too. See <perlsubs>. +and quote it or take a reference to it. *Plumber works too. See L<perlsubs>. + +Certain internal hooks can be also set using the %SIG hash. The +routine indicated by $SIG{__WARN__} is called when a warning message is +about to be printed. The warning message is passed as the first +argument. The presence of a __WARN__ hook causes the ordinary printing +of warnings to STDERR to be suppressed. You can use this to save warnings +in a variable, or turn warnings into fatal errors, like this: + + local $SIG{__WARN__} = sub { die $_[0] }; + eval $proggie; + +The routine indicated by $SIG{__DIE__} is called when a fatal exception +is about to be thrown. The error message is passed as the first +argument. When a __DIE__ hook routine returns, the exception +processing continues as it would have in the absence of the hook, +unless the hook routine itself exits via a goto, a loop exit, or a die. =back diff --git a/pod/pod2html b/pod/pod2html index 1bfc8f6a6a..a2cde18ce4 100644..100755 --- a/pod/pod2html +++ b/pod/pod2html @@ -1,209 +1,459 @@ -#!../perl +#!/usr/bin/perl +# +# pod2html - convert pod format to html +# +# usage: pod2html [podfiles] +# will read the cwd and parse all files with .pod extension +# if no arguments are given on the command line. +# +*RS = */; +*ERRNO = *!; + +use Carp; + +$gensym = 0; + +while ($ARGV[0] =~ /^-d(.*)/) { + shift; + $Debug{ lc($1 || shift) }++; +} + +# look in these pods for things not found within the current pod +@inclusions = qw[ + perlfunc perlvar perlrun perlop +]; + +# ck for podnames on command line +while ($ARGV[0]) { + push(@Pods,shift); +} +$A={}; + +# location of pods +$dir="."; # The beginning of the url for the anchors to the other sections. -chop($wd=`pwd`); -$type="<A HREF=\"file://localhost".$wd."/"; -$debug=0; -$/ = ""; -$p=\%p; -@exclusions=("perldebug","perlform","perlobj","perlstyle","perltrap","perlmod"); -$indent=0; -opendir(DIR,"."); -@{$p->{"pods"}}=grep(/\.pod$/,readdir(DIR)); -closedir(DIR); - -# learn the important stuff - -foreach $tmpod (@{$p->{"pods"}}){ - ($pod=$tmpod)=~s/\.pod$//; - $p->{"podnames"}->{$pod}=1; - next if grep(/$pod/,@exclusions); - open(POD,"<$tmpod"); - while(<POD>){ - s/B<([^<>]*)>/$1/g; # bold - s/I<([^<>]*)>/$1/g; # bold - if (s/^=//) { - s/\n$//s; - s/\n/ /g; - ($cmd, $_) = split(' ', $_, 2); - if ($cmd eq "item") { - ($what,$rest)=split(' ', $_, 2); - $what=~s#(-.).*#$1#; - $what=~s/\s*$//; - next if defined $p->{"items"}->{$what}; - $p->{"items"}->{$what} = $pod."_".$i++; - } - elsif($cmd =~ /^head/){ - $_=~s/\s*$//; - next if defined($p->{"headers"}->{$_}); - $p->{"headers"}->{$_} = $pod."_".$i++; - } - } - } +# Edit $type to suit. It's configured for relative url's now. +$type='<A HREF="'; +$debug = 0; + +unless(@Pods){ + opendir(DIR,$dir) or die "Can't opendir $dir: $ERRNO"; + @Pods = grep(/\.pod$/,readdir(DIR)); + closedir(DIR) or die "Can't closedir $dir: $ERRNO"; } +@Pods or die "expected pods"; -$/=""; - -# parse the pods, produce html -foreach $tmpod (@{$p->{"pods"}}){ - open(POD,"<$tmpod") || die "cant open $pod"; - ($pod=$tmpod)=~s/\.pod$//; - open(HTML,">$pod.html"); - print HTML "<!-- \$RCSfile\$\$Revision\$\$Date\$ -->\n"; - print HTML "<!-- \$Log\$ -->\n"; - print HTML "<HTML>\n"; - print HTML "<TITLE> \U$pod\E </TITLE>\n"; - $cutting = 1; - while (<POD>) { - if ($cutting) { - next unless /^=/; - $cutting = 0; +# loop twice through the pods, first to learn the links, then to produce html +for $count (0,1){ + foreach $podfh ( @Pods ) { + ($pod = $podfh) =~ s/\.pod$//; + Debug("files", "opening 2 $podfh" ); + $RS = "\n="; + open($podfh,"<".$podfh) || die "can't open $podfh: $ERRNO"; + @all=<$podfh>; + close($podfh); + $RS = "\n"; + $all[0]=~s/^=//; + for(@all){s/=$//;} + $Podnames{$pod} = 1; + $in_list=0; + $html=$pod.".html"; + if($count){ + #open(HTML,">&STDOUT") || die "can't create $html: $ERRNO"; + open(HTML,">$html") || die "can't create $html: $ERRNO"; + print HTML <<'HTML__EOQ', <<"HTML__EOQQ"; + <!-- $RCSfile$$Date$ --> + <!-- $Log$ --> + <HTML> +HTML__EOQ + <TITLE> \U$pod\E </TITLE> +HTML__EOQQ } - chop; - length || (print "\n") && next; - # Translate verabatim paragraph - - if (/^\s/) { - $unordered=0; - &pre_escapes; - &post_escapes; - @lines = split(/\n/); - if($lines[0]=~/^\s+(\w*)\t(.*)/){ # listing or unordered list - ($key,$rest)=($1,$2); - if(defined($p->{"podnames"}->{$key})){ - print HTML "\n<ul>\n"; - $unordered = 1; + + for($i=0;$i<=$#all;$i++){ + + $all[$i] =~ /^(\w+)\s*(.*)\n?([^\0]*)$/ ; + ($cmd, $title, $rest) = ($1,$2,$3); + if ($cmd eq "item") { + if($count ){ + ($depth) or &do_list("over",$all[$i],\$in_list,\$depth); + &do_item($title,$rest,$in_list); } else{ - print HTML "\n<listing>\n"; + # scan item + &scan_thing("item",$title,$pod); } - foreach $line (@lines){ - ($line =~ /^\s+(\w*)\t(.*)/) && (($key,$rest)=($1,$2)); - print HTML defined($p->{"podnames"}->{$key}) ? - "<li>$type$key.html\">$key<\/A>\t$rest\n" : "$line \n"; - } - print HTML $unordered ? "</ul>\n" : "</listing>\n"; - next; - }else{ # preformatted text - print HTML "<pre>\n"; - for(@lines){ - s/^/ /; - s/\t/ /g; - print HTML $_,"\n"; - } - print HTML "</pre>\n"; - next; - } - } - &pre_escapes; - s/S<([^<>]*)>/$1/g; # embedded special - $_ = &Do_refs($_,$pod); - s/Z<>/<p>/g; # ? - s/E<([^<>]*)>/\&$1\;/g; # embedded special - &post_escapes; - if (s/^=//) { - s/\n$//s; - s/\n/ /g; - ($cmd, $_) = split(' ', $_, 2); - if ($cmd eq 'cut') { - $cutting = 1; - } - elsif ($cmd eq 'head1') { - print HTML qq{<h2>$_</h2>\n}; - } - elsif ($cmd eq 'head2') { - print HTML qq{<h3>$_</h3>\n}; } - elsif ($cmd eq 'over') { - push(@indent,$indent); - $indent = $_ + 0; - print HTML qq{\n<dl>\n}; + elsif ($cmd =~ /^head([12])/){ + $num=$1; + if($count){ + &do_hdr($num,$title,$rest,$depth); + } + else{ + # header scan + &scan_thing($cmd,$title,$pod); # skip head1 + } } - elsif ($cmd eq 'back') { - $indent = pop(@indent); - warn "Unmatched =back\n" unless defined $indent; - $needspace = 1; - print HTML qq{\n</dl>\n\n}; + elsif ($cmd =~ /^over/) { + $depth and &do_list("over",$all[$i+1],\$in_list,\$depth); } - elsif ($cmd eq 'item') { - ($what,$rest)=split(' ', $_, 2); - $what=~s/\s*$//; - if($justdid ne $what){ - print HTML "\n<A NAME=\"".$p->{"items"}->{$what}."\"></A>\n"; - $justdid=$what; + elsif ($cmd =~ /^back/) { + if($count){ + ($depth) or next; # just skip it + &do_list("back",$all[$i+1],\$in_list,\$depth); + &do_rest("$title.$rest"); } - print HTML qq{<dt><B>$_</B> </dt>\n}; - $next_para=1; + } + elsif ($cmd =~ /^cut/) { + &do_rest($rest); } else { - warn "Unrecognized directive: $cmd\n"; + warn "unrecognized header: $cmd"; } } - else { - length || next; - $next_para && (print HTML qq{<dd>\n}); - print HTML "$_<p>"; - $next_para && (print HTML qq{</dd>\n<p>\n}) && ($next_para=0); + if($count){ + while($depth){ + &do_list("back",$all[$i+1],\$in_list,\$depth); + } + print HTML "\n</HTML>\n"; } } } -print HTML "\n</HTML>\n"; -######################################################################### - -sub pre_escapes { - s/\&/\&\;/g; - s/<</\<\;\<\;/g; - s/([^ESIBLCF])</$1\<\;/g; +sub do_list{ + my($which,$next_one,$list_type,$depth)=@_; + my($key); + if($which eq "over"){ + ($next_one =~ /^item\s+(.*)/ ) or warn "Bad list, $1\n"; + $key=$1; + if($key =~ /^1\.?/){ + $$list_type = "OL"; + } + elsif($key =~ /\*\s*$/){ + $$list_type="UL"; + } + elsif($key =~ /\*?\s*\w/){ + $$list_type="DL"; + } + else{ + warn "unknown list type for item $key"; + } + print HTML qq{\n}; + print HTML qq{<$$list_type>}; + $$depth++; + } + elsif($which eq "back"){ + print HTML qq{\n</$$list_type>\n}; + $$depth--; + } } -sub post_escapes{ - s/>>/\>\;\>\;/g; - s/([^"AIB])>/$1\>\;/g; +sub do_hdr{ + my($num,$title,$rest,$depth)=@_; + ($num == 1) and print HTML qq{<p><hr>\n}; + &process_thing(\$title,"NAME"); + print HTML qq{\n<H$num> }; + print HTML $title; + print HTML qq{</H$num>\n}; + &do_rest($rest); } -sub Do_refs{ -local($para,$pod)=@_; -foreach $char ("L","C","I","B"){ - next unless /($char<[^<>]*>)/; - local(@ar) = split(/($char<[^<>]*>)/,$para); - local($this,$key,$num); - for($this=0;$this<=$#ar;$this++){ - next unless $ar[$this] =~ /${char}<([^<>]*)>/; - $key=$1; +sub do_item{ + my($title,$rest,$list_type)=@_; + &process_thing(\$title,"NAME"); + if($list_type eq "DL"){ + print HTML qq{\n<DT><STRONG>\n}; + print HTML $title; + print HTML qq{\n</STRONG></DT>\n}; + print HTML qq{<DD>\n}; + } + else{ + print HTML qq{\n<LI>}; + ($list_type ne "OL") && (print HTML $title,"\n"); + } + &do_rest($rest); + print HTML ($list_type eq "DL" )? qq{</DD>} : qq{</LI>}; +} - if((defined($p->{"podnames"}->{$key})) && ($char eq "L")){ - $ar[$this] = "\n$type$key.html\">\nthe $key manpage<\/A>\n"; # +sub do_rest{ + my($rest)=@_; + my(@lines,$p,$q,$line,@paras,$inpre); + @paras=split(/\n\n+/,$rest); + for($p=0;$p<=$#paras;$p++){ + @lines=split(/\n/,$paras[$p]); + if($lines[0] =~ /^\s+\w*\t.*/){ # listing or unordered list + print HTML qq{<UL>}; + foreach $line (@lines){ + ($line =~ /^\s+(\w*)\t(.*)/) && (($key,$rem) = ($1,$2)); + print HTML defined($Podnames{$key}) ? + "<LI>$type$key.html\">$key<\/A>\t$rem</LI>\n" : + "<LI>$line</LI>\n"; + } + print HTML qq{</UL>\n}; } - elsif(defined($p->{"items"}->{$key})){ - ($pod2,$num)=split(/_/,$p->{"items"}->{$key},2); - $ar[$this] = (($pod2 eq $pod) && ($para=~/^\=item/)) ? - "\n<A NAME=\"".$p->{"items"}->{$key}."\">\n$key</A>\n" - : - "\n$type$pod2.html\#".$p->{"items"}->{$key}."\">$key<\/A>\n"; - } - elsif(defined($p->{"headers"}->{$key})){ - ($pod2,$num)=split(/_/,$p->{"headers"}->{$key},2); - $ar[$this] = (($pod eq $pod2) && ($para=~/^\=head/)) ? - "\n<A NAME=\"".$p->{"headers"}->{$key}."\">\n$key</A>\n" - : - "\n$type$pod2.html\#".$p->{"headers"}->{$key}."\">$key<\/A>\n"; + elsif($lines[0] =~ /^\s/){ # preformatted code + if($paras[$p] =~/>>|<</){ + print HTML qq{\n<PRE>\n}; + $inpre=1; + } + else{ + print HTML qq{\n<XMP>\n}; + $inpre=0; + } +inner: + while(defined($paras[$p])){ + @lines=split(/\n/,$paras[$p]); + foreach $q (@lines){ + if($paras[$p]=~/>>|<</){ + if($inpre){ + &process_thing(\$q,"HTML"); + } + else { + print HTML qq{\n</XMP>\n}; + print HTML qq{<PRE>\n}; + $inpre=1; + &process_thing(\$q,"HTML"); + } + } + while($q =~ s/\t+/' 'x (length($&) * 8 - length($`) % 8)/e){ + 1; + } + print HTML $q,"\n"; + } + last if $paras[$p+1] !~ /^\s/; + $p++; + } + print HTML ($inpre==1) ? (qq{\n</PRE>\n}) : (qq{\n</XMP>\n}); } - else{ - (warn "No \"=item\" or \"=head\" reference for $ar[$this] in $pod\n") if $debug; - if($char =~ /^[BCF]$/){ - $ar[$this]="<B>$key</B>"; + else{ # other text + @lines=split(/\n/,$paras[$p]); + foreach $line (@lines){ + &process_thing(\$line,"HTML"); + print HTML qq{$line\n}; } - elsif($char eq "L"){ - $ar[$this]=$key; + } + print HTML qq{<p>}; + } +} + +sub process_thing{ + my($thing,$htype)=@_; + &pre_escapes($thing); + &find_refs($thing,$htype); + &post_escapes($thing); +} + +sub scan_thing{ + my($cmd,$title,$pod)=@_; + $_=$title; + s/\n$//; + s/E<(.*?)>/&$1;/g; + # remove any formatting information for the headers + s/[SFCBI]<(.*?)>/$1/g; + # the "don't format me" thing + s/Z<>//g; + if ($cmd eq "item") { + + if (/^\*/) { return } # skip bullets + if (/^\d+\./) { return } # skip numbers + s/(-[a-z]).*/$1/i; + trim($_); + return if defined $A->{$pod}->{"Items"}->{$_}; + $A->{$pod}->{"Items"}->{$_} = gensym($pod, $_); + $A->{$pod}->{"Items"}->{(split(' ',$_))[0]}=$A->{$pod}->{"Items"}->{$_}; + Debug("items", "item $_"); + if (!/^-\w$/ && /([%\$\@\w]+)/ && $1 ne $_ + && !defined($A->{$pod}->{"Items"}->{$_}) && ($_ ne $1)) + { + $A->{$pod}->{"Items"}->{$1} = $A->{$pod}->{"Items"}->{$_}; + Debug("items", "item $1 REF TO $_"); + } + if ( m{^(tr|y|s|m|q[qwx])/.*[^/]} ) { + my $pf = $1 . '//'; + $pf .= "/" if $1 eq "tr" || $1 eq "y" || $1 eq "s"; + if ($pf ne $_) { + $A->{$pod}->{"Items"}->{$pf} = $A->{$pod}->{"Items"}->{$_}; + Debug("items", "item $pf REF TO $_"); + } + } + } + elsif ($cmd =~ /^head[12]/){ + return if defined($Headers{$_}); + $A->{$pod}->{"Headers"}->{$_} = gensym($pod, $_); + Debug("headers", "header $_"); + } + else { + warn "unrecognized header: $cmd"; + } +} + + +sub picrefs { + my($char, $bigkey, $lilkey,$htype) = @_; + my($key,$ref,$podname); + for $podname ($pod,@inclusions){ + for $ref ( "Items", "Headers" ) { + if (defined $A->{$podname}->{$ref}->{$bigkey}) { + $value = $A->{$podname}->{$ref}->{$key=$bigkey}; + Debug("subs", "bigkey is $bigkey, value is $value\n"); + } + elsif (defined $A->{$podname}->{$ref}->{$lilkey}) { + $value = $A->{$podname}->{$ref}->{$key=$lilkey}; + return "" if $lilkey eq ''; + Debug("subs", "lilkey is $lilkey, value is $value\n"); + } + } + if (length($key)) { + ($pod2,$num) = split(/_/,$value,2); + if($htype eq "NAME"){ + return "\n<A NAME=\"".$value."\">\n$bigkey</A>\n" } - elsif($char eq "I"){ - $ar[$this]="<I>$key</I>"; + else{ + return "\n$type$pod2.html\#".$value."\">$bigkey<\/A>\n"; } + } + } + if ($char =~ /[IF]/) { + return "<EM> $bigkey </EM>"; + } else { + return "<STRONG> $bigkey </STRONG>"; + } +} + +sub find_refs { + my($thing,$htype)=@_; + my($orig) = $$thing; + # LREF: a manpage(3f) we don't know about + $$thing=~s:L<([a-zA-Z][^\s\/]+)(\([^\)]+\))>:the I<$1>$2 manpage:g; + $$thing=~s/L<([^>]*)>/lrefs($1,$htype)/ge; + $$thing=~s/([CIBF])<(\W*?(-?\w*).*?)>/picrefs($1, $2, $3, $htype)/ge; + $$thing=~s/((\w+)\(\))/picrefs("I", $1, $2,$htype)/ge; + $$thing=~s/([\$\@%]([\w:]+|\W\b))/varrefs($1,$htype)/ge; + (($$thing eq $orig) && ($htype eq "NAME")) && + ($$thing=picrefs("I", $$thing, "", $htype)); +} + +sub lrefs { + my($page, $item) = split(m#/#, $_[0], 2); + my($htype)=$_[1]; + my($podname); + my($section) = $page =~ /\((.*)\)/; + my $selfref; + if ($page =~ /^[A-Z]/ && $item) { + $selfref++; + $item = "$page/$item"; + $page = $pod; + } elsif (!$item && $page =~ /[^a-z\-]/ && $page !~ /^\$.$/) { + $selfref++; + $item = $page; + $page = $pod; + } + $item =~ s/\(\)$//; + if (!$item) { + if (!defined $section && defined $Podnames{$page}) { + return "\n$type$page.html\">\nthe <EM> $page </EM> manpage<\/A>\n"; + } else { + warn "Bizarre entry $page/$item"; + return "the <EM> $_[0] </EM> manpage\n"; + } + } + + if ($item =~ s/"(.*)"/$1/ || ($item =~ /[^\w\/\-]/ && $item !~ /^\$.$/)) { + $text = "<EM> $item </EM>"; + $ref = "Headers"; + } else { + $text = "<EM> $item </EM>"; + $ref = "Items"; + } + for $podname ($pod, @inclusions){ + undef $value; + if ($ref eq "Items") { + if (defined($value = $A->{$podname}->{$ref}->{$item})) { + ($pod2,$num) = split(/_/,$value,2); + return (($pod eq $pod2) && ($htype eq "NAME")) + ? "\n<A NAME=\"".$value."\">\n$text</A>\n" + : "\n$type$pod2.html\#".$value."\">$text<\/A>\n"; + } + } + elsif($ref eq "Headers") { + if (defined($value = $A->{$podname}->{$ref}->{$item})) { + ($pod2,$num) = split(/_/,$value,2); + return (($pod eq $pod2) && ($htype eq "NAME")) + ? "\n<A NAME=\"".$value."\">\n$text</A>\n" + : "\n$type$pod2.html\#".$value."\">$text<\/A>\n"; + } + } + } + warn "No $ref reference for $item (@_)"; + return $text; +} + +sub varrefs { + my ($var,$htype) = @_; + for $podname ($pod,@inclusions){ + if ($value = $A->{$podname}->{"Items"}->{$var}) { + ($pod2,$num) = split(/_/,$value,2); + Debug("vars", "way cool -- var ref on $var"); + return (($pod eq $pod2) && ($htype eq "NAME")) # INHERIT $_, $pod + ? "\n<A NAME=\"".$value."\">\n$var</A>\n" + : "\n$type$pod2.html\#".$value."\">$var<\/A>\n"; } } - $para=join('',@ar); + Debug( "vars", "bummer, $var not a var"); + return "<STRONG> $var </STRONG>"; +} + +sub gensym { + my ($podname, $key) = @_; + $key =~ s/\s.*//; + ($key = lc($key)) =~ tr/a-z/_/cs; + my $name = "${podname}_${key}_0"; + $name =~ s/__/_/g; + while ($sawsym{$name}++) { + $name =~ s/_?(\d+)$/'_' . ($1 + 1)/e; + } + return $name; +} + +sub pre_escapes { + my($thing)=@_; + $$thing=~s/&/noremap("&")/ge; + $$thing=~s/<</noremap("<<")/eg; + $$thing=~s/(?:[^ESIBLCF])</noremap("<")/eg; + $$thing=~s/E<([^\/][^<>]*)>/\&$1\;/g; # embedded special } -$para; + +sub noremap { + my $hide = $_[0]; + $hide =~ tr/\000-\177/\200-\377/; + $hide; +} + +sub post_escapes { + my($thing)=@_; + $$thing=~s/[^GM]>>/\>\;\>\;/g; + $$thing=~s/([^"MGA])>/$1\>\;/g; + $$thing=~tr/\200-\377/\000-\177/; } -sub wait{1;} + +sub Debug { + my $level = shift; + print STDERR @_,"\n" if $Debug{$level}; +} + +sub dumptable { + my $t = shift; + print STDERR "TABLE DUMP $t\n"; + foreach $k (sort keys %$t) { + printf STDERR "%-20s <%s>\n", $t->{$k}, $k; + } +} +sub trim { + for (@_) { + s/^\s+//; + s/\s\n?$//; + } +} + + diff --git a/pod/pod2latex b/pod/pod2latex new file mode 100755 index 0000000000..9dbb2cd27b --- /dev/null +++ b/pod/pod2latex @@ -0,0 +1,632 @@ +#!/usr/bin/perl +# pod2latex, version 1.1 +# by Taro Kawagish (kawagish@imslab.co.jp), Jan 11, 1995. +# +# pod2latex filters Perl pod documents to LaTeX documents. +# +# What pod2latex does: +# 1. Pod file 'perl_doc_entry.pod' is filtered to 'perl_doc_entry.tex'. +# 2. Indented paragraphs are translated into +# '\begin{verbatim} ... \end{verbatim}'. +# 3. '=head1 heading' command is translated into '\section{heading}' +# 4. '=head2 heading' command is translated into '\subsection*{heading}' +# 5. '=over N' command is translated into +# '\begin{itemize}' if following =item starts with *, +# '\begin{enumerate}' if following =item starts with 1., +# '\begin{description}' if else. +# (indentation level N is ignored.) +# 6. '=item * heading' command is translated into '\item heading', +# '=item 1. heading' command is translated into '\item heading', +# '=item heading' command(other) is translated into '\item[heading]'. +# 7. '=back' command is translated into +# '\end{itemize}' if started with '\begin{itemize}', +# '\end{enumerate}' if started with '\begin{enumerate}', +# '\end{description}' if started with '\begin{description}'. +# 8. other paragraphs are translated into strings with TeX special characters +# escaped. +# 9. In heading text, and other paragraphs, the following translation of pod +# quotes are done, and then TeX special characters are escaped after that. +# I<text> to {\em text\/}, +# B<text> to {\bf text}, +# S<text> to text1, +# where text1 is a string with blank characters replaced with ~, +# C<text> to {\tt text2}, +# where text2 is a string with TeX special characters escaped to +# obtain a literal printout, +# E<text> (HTML escape) to TeX escaped string, +# L<text> to referencing string as is done by pod2man, +# F<file> to {\em file\/}, +# Z<> to a null string, +# 10. those headings are indexed: +# '=head1 heading' => \section{heading}\index{heading} +# '=head2 heading' => \subsection*{heading}\index{heading} +# only when heading does not match frequent patterns such as +# DESCRIPTION, DIAGNOSTICS,... +# '=item heading' => \item{heading}\index{heading} +# +# Usage: +# pod2latex perl_doc_entry.pod +# this will write to a file 'perl_doc_entry.tex'. +# +# To LaTeX: +# The following commands need to be defined in the preamble of the LaTeX +# document: +# \def\C++{{\rm C\kern-.05em\raise.3ex\hbox{\footnotesize ++}}} +# \def\underscore{\leavevmode\kern.04em\vbox{\hrule width 0.4em height 0.3pt}} +# and \parindent should be set zero: +# \setlength{\parindent}{0pt} +# +# Note: +# This script was written modifing pod2man. +# +# Bug: +# If HTML escapes E<text> other than E<amp>,E<lt>,E<gt>,E<quot> are used +# in C<>, translation will produce wrong character strings. +# Translation of HTML escapes of various European accents might be wrong. + + +$/ = ""; # record separator is blank lines +# TeX special characters. +##$tt_ables = "!@*()-=+|;:'\"`,./?<>"; +$backslash_escapables = "#\$%&{}_"; +$backslash_escapables2 = "#\$%&{}"; # except _ +##$nonverbables = "^\\~"; +##$bracketesc = "[]"; +##@tex_verb_fences = unpack("aaaaaaaaa","|#@!*+?:;"); + +@head1_freq_patterns # =head1 patterns which need not be index'ed + = ("AUTHOR","Author","BUGS","DATE","DESCRIPTION","DIAGNOSTICS", + "ENVIRONMENT","EXAMPLES","FILES","INTRODUCTION","NAME","NOTE", + "SEE ALSO","SYNOPSIS","WARNING"); + +$indent = 0; + +# parse the pods, produce LaTeX. + +open(POD,"<$ARGV[0]") || die "cant open $ARGV[0]"; +($pod=$ARGV[0]) =~ s/\.pod$//; +open(LATEX,">$pod.tex"); +&do_hdr(); + +$cutting = 1; +while (<POD>) { + if ($cutting) { + next unless /^=/; + $cutting = 0; + } + chop; + length || (print LATEX "\n") && next; + + # translate indented lines as a verabatim paragraph + if (/^\s/) { + @lines = split(/\n/); + print LATEX "\\begin{verbatim}\n"; + for (@lines) { + 1 while s + {^( [^\t]* ) \t ( \t* ) } + { $1 . ' ' x (8 - (length($1)%8) + 8*(length($2))) }ex; + print LATEX $_,"\n"; + } + print LATEX "\\end{verbatim}\n"; + next; + } + + # preserve '=item' line with pod quotes as they are. + if (/^=item/) { + ($bareitem = $_) =~ s/^=item\s*//; + } + + # check for things that'll hosed our noremap scheme; affects $_ + &init_noremap(); + + # expand strings "func()" as pod quotes. + if (!/^=item/) { + # first hide pod escapes. + # escaped strings are mapped into the ones with the MSB's on. + s/([A-Z]<[^<>]*>)/noremap($1)/ge; + + # func() is a reference to a perl function + s{\b([:\w]+\(\))}{I<$1>}g; + # func(n) is a reference to a man page + s{(\w+)(\([^\s,\051]+\))}{I<$1>$2}g; + # convert simple variable references +# s/([\$\@%][\w:]+)/C<$1>/g; +# s/\$[\w:]+\[[0-9]+\]/C<$&>/g; + + if (m{ ([\-\w]+\([^\051]*?[\@\$,][^\051]*?\)) + }x && $` !~ /([LCI]<[^<>]*|-)$/ && !/^=\w/) + { + warn "``$1'' should be a [LCI]<$1> ref"; + } + while (/(-[a-zA-Z])\b/g && $` !~ /[\w\-]$/) { + warn "``$1'' should be [CB]<$1> ref"; + } + + # put back pod quotes so we get the inside of <> processed; + $_ = &clear_noremap($_); + } + + + # process TeX special characters + + # First hide HTML quotes E<> since they can be included in C<>. + s/(E<[^<>]+>)/noremap($1)/ge; + + # Then hide C<> type literal quotes. + # String inside of C<> will later be expanded into {\tt ..} strings + # with TeX special characters escaped as needed. + s/(C<[^<>]*>)/&noremap($1)/ge; + + # Next escape TeX special characters including other pod quotes B< >,... + # + # NOTE: s/re/&func($str)/e evaluates $str just once in perl5. + # (in perl4 evaluation takes place twice before getting passed to func().) + + # - hyphen => --- + s/(\S+)(\s+)-+(\s+)(\S+)/"$1".&noremap(" --- ")."$4"/ge; + # '-', '--', "-" => '{\tt -}', '{\tt --}', "{\tt -}" +## s/("|')(\s*)(-+)(\s*)\1/&noremap("$1$2\{\\tt $3\}$4$1")/ge; +## changed Wed Jan 25 15:26:39 JST 1995 + # '-', '--', "-" => '$-$', '$--$', "$-$" + s/(\s+)(['"])(-+)([^'"\-]*)\2(\s+|[,.])/"$1$2".&noremap("\$$3\$")."$4$2$5"/ge; + s/(\s+)(['"])([^'"\-]*)(-+)(\s*)\2(\s+|[,.])/"$1$2$3".&noremap("\$$4\$")."$5$2$6"/ge; + # (--|-) => ($--$|$-$) + s/(\s+)\((-+)([=@%\$\+\\\|\w]*)(-*)([=@%\$\+\\\|\w]*)\)(\s+|[,.])/"$1\(".&noremap("\$$2\$")."$3".&noremap("\$$4\$")."$5\)$6"/ge; + # numeral - => $-$ + s/(\(|[0-9]+|\s+)-(\s*\(?\s*[0-9]+)/&noremap("$1\$-\$$2")/ge; + # -- in quotes => two separate - + s/B<([^<>]*)--([^<>]*)>/&noremap("B<$1\{\\tt --\}$2>")/ge; + + # backslash escapable characters except _. + s/([$backslash_escapables2])/&noremap("\\$1")/ge; + s/_/&noremap("\\underscore{}")/ge; # a litle thicker than \_. + # quote TeX special characters |, ^, ~, \. + s/\|/&noremap("\$|\$")/ge; + s/\^/&noremap("\$\\hat{\\hspace{0.4em}}\$")/ge; + s/\~/&noremap("\$\\tilde{\\hspace{0.4em}}\$")/ge; + s/\\/&noremap("\$\\backslash{}\$")/ge; + # quote [ and ] to be used in \item[] + s/([\[\]])/&noremap("{\\tt $1}")/ge; + # characters need to be treated differently in TeX + # keep * if an item heading + s/^(=item[ \t]+)[*]((.|\n)*)/"$1" . &noremap("*") . "$2"/ge; + s/[*]/&noremap("\$\\ast\$")/ge; # other * + + # hide other pod quotes. + s/([ABD-Z]<[^<>]*>)/&noremap($1)/ge; + + # escape < and > as math strings, + # now that we are done with hiding pod <> quotes. + s/</&noremap("\$<\$")/ge; + s/>/&noremap("\$>\$")/ge; + + # put it back so we get the <> processed again; + $_ = &clear_noremap($_); + + + # Expand pod quotes recursively: + # (1) type face directives [BIFS]<[^<>]*> to appropriate TeX commands, + # (2) L<[^<>]*> to reference strings, + # (3) C<[^<>]*> to TeX literal quotes, + # (4) HTML quotes E<> inside of C<> quotes. + + # Hide E<> again since they can be included in C<>. + s/(E<[^<>]+>)/noremap($1)/ge; + + $maxnest = 10; + while ($maxnest-- && /[A-Z]</) { + + # bold and italic quotes + s/B<([^<>]*)>/"{\\bf $1}"/eg; + s#I<([^<>]*)>#"{\\em $1\\/}"#eg; + + # files and filelike refs in italics + s#F<([^<>]*)>#"{\\em $1\\/}"#eg; + + # no break quote -- usually we want C<> for this + s/S<([^<>]*)>/&nobreak($1)/eg; + + # LREF: a manpage(3f) + s:L<([a-zA-Z][^\s\/]+)(\([^\)]+\))?>:the {\\em $1\\/}$2 manpage:g; + + # LREF: an =item on another manpage + s{ + L<([^/]+)/([:\w]+(\(\))?)> + } {the C<$2> entry in the I<$1> manpage}gx; + + # LREF: an =item on this manpage + s{ + ((?:L</([:\w]+(\(\))?)> + (,?\s+(and\s+)?)?)+) + } { &internal_lrefs($1) }gex; + + # LREF: a =head2 (head1?), maybe on a manpage, maybe right here + # the "func" can disambiguate + s{ + L<(?:([a-zA-Z]\S+?) /)?"?(.*?)"?> + }{ + do { + $1 # if no $1, assume it means on this page. + ? "the section on I<$2> in the I<$1> manpage" + : "the section on I<$2>" + } + }gex; + + s/Z<>/\\&/g; # the "don't format me" thing + + # comes last because not subject to reprocessing + s{ + C<([^<>]*)> + }{ + do { + ($str = $1) =~ tr/\200-\377/\000-\177/; #normalize hidden stuff + # expand HTML escapes if any; + # WARNING: if HTML escapes other than E<amp>,E<lt>,E<gt>, + # E<quot> are in C<>, they will not be printed correctly. + $str = &expand_HTML_escapes($str); + $strverb = &alltt($str); # Tex verbatim escape of a string. + &noremap("$strverb"); + } + }gex; + +# if ( /C<([^<>]*)/ ) { +# $str = $1; +# if ($str !~ /\|/) { # if includes | +# s/C<([^<>]*)>/&noremap("\\verb|$str|")/eg; +# } else { +# print STDERR "found \| in C<.*> at paragraph $.\n"; +# # find a character not contained in $str to use it as a +# # separator of the \verb +# ($chars = $str) =~ s/(\W)/\\$1/g; +# ## ($chars = $str) =~ s/([\$<>,\|"'\-^{}()*+?\\])/\\$1/g; +# @fence = grep(!/[ $chars]/,@tex_verb_fences); +# s/C<([^<>]*)>/&noremap("\\verb$fence[0]$str$fence[0]")/eg; +# } +# } + } + + + # process each pod command + if (s/^=//) { # if a command + s/\n/ /g; + ($cmd, $rest) = split(' ', $_, 2); + $rest =~ s/^\s*//; + $rest =~ s/\s*$//; + + if (defined $rest) { + &escapes; + } + + $rest = &clear_noremap($rest); + $rest = &expand_HTML_escapes($rest); + + if ($cmd eq 'cut') { + $cutting = 1; + $lastcmd = 'cut'; + } + elsif ($cmd eq 'head1') { # heading type 1 + $rest =~ s/^\s*//; $rest =~ s/\s*$//; + print LATEX "\n\\subsection*{$rest}"; + # put index entry + ($index = $rest) =~ s/^(An?\s+|The\s+)//i; # remove 'A' and 'The' + # index only those heads not matching the frequent patterns. + foreach $pat (@head1_freq_patterns) { + if ($index =~ /^$pat/) { + goto freqpatt; + } + } + print LATEX "%\n\\index{$index}\n" if ($index); + freqpatt: + $lastcmd = 'head1'; + } + elsif ($cmd eq 'head2') { # heading type 2 + $rest =~ s/^\s*//; $rest =~ s/\s*$//; + print LATEX "\n\\subsubsection*{$rest}"; + # put index entry + ($index = $rest) =~ s/^(An?\s+|The\s+)//i; # remove 'A' and 'The' + $index =~ s/^Example\s*[1-9][0-9]*\s*:\s*//; # remove 'Example :' + print LATEX "%\n\\index{$index}\n" if ($index); + $lastcmd = 'head2'; + } + elsif ($cmd eq 'over') { # 1 level within a listing environment + push(@indent,$indent); + $indent = $rest + 0; + $lastcmd = 'over'; + } + elsif ($cmd eq 'back') { # 1 level out of a listing environment + $indent = pop(@indent); + warn "Unmatched =back\n" unless defined $indent; + $listingcmd = pop(@listingcmd); + print LATEX "\n\\end{$listingcmd}\n" if ($listingcmd); + $lastcmd = 'back'; + } + elsif ($cmd eq 'item') { # an item paragraph starts + if ($lastcmd eq 'over') { # if we have just entered listing env + # see what type of list environment we are in. + if ($rest =~ /^[0-9]\.?/) { # if numeral heading + $listingcmd = 'enumerate'; + } elsif ($rest =~ /^\*\s*/) { # if * heading + $listingcmd = 'itemize'; + } elsif ($rest =~ /^[^*]/) { # if other headings + $listingcmd = 'description'; + } else { + warn "unknown list type for item $rest"; + } + print LATEX "\n\\begin{$listingcmd}\n"; + push(@listingcmd,$listingcmd); + } elsif ($lastcmd ne 'item') { + warn "Illegal '=item' command without preceding 'over':"; + warn "=item $bareitem"; + } + + if ($listingcmd eq 'enumerate') { + $rest =~ s/^[0-9]+\.?\s*//; # remove numeral heading + print LATEX "\n\\item"; + print LATEX "{\\bf $rest}" if $rest; + } elsif ($listingcmd eq 'itemize') { + $rest =~ s/^\*\s*//; # remove * heading + print LATEX "\n\\item"; + print LATEX "{\\bf $rest}" if $rest; + } else { # description item + print LATEX "\n\\item[$rest]"; + } + $lastcmd = 'item'; + $rightafter_item = 'yes'; + + # check if the item heading is short or long. + ($itemhead = $rest) =~ s/{\\bf (\S*)}/$1/g; + if (length($itemhead) < 4) { + $itemshort = "yes"; + } else { + $itemshort = "no"; + } + # write index entry + if ($pod =~ "perldiag") { # skip 'perldiag.pod' + goto noindex; + } + # strip out the item of pod quotes and get a plain text entry + $bareitem =~ s/\n/ /g; # remove newlines + $bareitem =~ s/\s*$//; # remove trailing space + $bareitem =~ s/[A-Z]<([^<>]*)>/$1/g; # remove <> quotes + ($index = $bareitem) =~ s/^\*\s+//; # remove leading '*' + $index =~ s/^(An?\s+|The\s+)//i; # remove 'A' and 'The' + $index =~ s/^\s*[1-9][0-9]*\s*[.]\s*$//; # remove numeral only + $index =~ s/^\s*\w\s*$//; # remove 1 char only's + # quote ", @ and ! with " to be used in makeindex. + $index =~ s/"/""/g; # quote " + $index =~ s/@/"@/g; # quote @ + $index =~ s/!/"!/g; # quote ! + ($rest2=$rest) =~ s/^\*\s+//; # remove * + $rest2 =~ s/"/""/g; # quote " + $rest2 =~ s/@/"@/g; # quote @ + $rest2 =~ s/!/"!/g; # quote ! + if ($pod =~ "(perlfunc|perlvar)") { # when doc is perlfunc,perlvar + # take only the 1st word of item heading + $index =~ s/^([^{}\s]*)({.*})?([^{}\s]*)\s+.*/\1\2\3/; + $rest2 =~ s/^([^{}\s]*)({.*})?([^{}\s]*)\s+.*/\1\2\3/; + } + if ($index =~ /[A-Za-z\$@%]/) { + # write \index{plain_text_entry@TeX_string_entry} + print LATEX "%\n\\index{$index\@$rest2}%\n"; + } + noindex: + ; + } + else { + warn "Unrecognized directive: $cmd\n"; + } + } + else { # if not command + &escapes; + $_ = &clear_noremap($_); + $_ = &expand_HTML_escapes($_); + + # if the present paragraphs follows an =item declaration, + # put a line break. + if ($lastcmd eq 'item' && + $rightafter_item eq 'yes' && $itemshort eq "no") { + print LATEX "\\hfil\\\\"; + $rightafter_item = 'no'; + } + print LATEX "\n",$_; + } +} + +print LATEX "\n"; +close(POD); +close(LATEX); + + +######################################################################### + +sub do_hdr { + print LATEX "% LaTeX document produced by pod2latex from \"$pod.pod\".\n"; + print LATEX "% The followings need be defined in the preamble of this document:\n"; + print LATEX "%\\def\\C++{{\\rm C\\kern-.05em\\raise.3ex\\hbox{\\footnotesize ++}}}\n"; + print LATEX "%\\def\\underscore{\\leavevmode\\kern.04em\\vbox{\\hrule width 0.4em height 0.3pt}}\n"; + print LATEX "%\\setlength{\\parindent}{0pt}\n"; + print LATEX "\n"; + $podq = &escape_tex_specials("\U$pod\E"); + print LATEX "\\section{$podq}%\n"; + print LATEX "\\index{$podq}"; + print LATEX "\n"; +} + +sub nobreak { + my $string = shift; + $string =~ s/ +/~/g; # TeX no line break + $string; +} + +sub noremap { + local($thing_to_hide) = shift; + $thing_to_hide =~ tr/\000-\177/\200-\377/; + return $thing_to_hide; +} + +sub init_noremap { + if ( /[\200-\377]/ ) { + warn "hit bit char in input stream"; + } +} + +sub clear_noremap { + local($tmp) = shift; + $tmp =~ tr/\200-\377/\000-\177/; + return $tmp; +} + +sub expand_HTML_escapes { + local($s) = $_[0]; + $s =~ s { E<([A-Za-z]+)> } + { + do { + exists $HTML_Escapes{$1} + ? do { $HTML_Escapes{$1} } + : do { + warn "Unknown escape: $& in $_"; + "E<$1>"; + } + } + }egx; + return $s; +} + +sub escapes { + # make C++ into \C++, which is to be defined as + # \def\C++{{\rm C\kern-.05em\raise.3ex\hbox{\footnotesize ++}}} + s/\bC\+\+/\\C++{}/g; +} + +# Translate a string into a TeX \tt string to obtain a verbatim print out. +# TeX special characters are escaped by \. +# This can be used inside of LaTeX command arguments. +# We don't use LaTeX \verb since it doesn't work inside of command arguments. +sub alltt { + local($str) = shift; + # other chars than #,\,$,%,&,{,},_,\,^,~ ([ and ] included). + $str =~ s/([^${backslash_escapables}\\\^\~]+)/&noremap("$&")/eg; + # chars #,\,$,%,&,{,} => \# , ... + $str =~ s/([$backslash_escapables2])/&noremap("\\$&")/eg; + # chars _,\,^,~ => \char`\_ , ... + $str =~ s/_/&noremap("\\char`\\_")/eg; + $str =~ s/\\/&noremap("\\char`\\\\")/ge; + $str =~ s/\^/\\char`\\^/g; + $str =~ s/\~/\\char`\\~/g; + + $str =~ tr/\200-\377/\000-\177/; # put back + $str = "{\\tt ".$str."}"; # make it a \tt string + return $str; +} + +sub escape_tex_specials { + local($str) = shift; + # other chars than #,\,$,%,&,{,}, _,\,^,~ ([ and ] included). + # backslash escapable characters #,\,$,%,&,{,} except _. + $str =~ s/([$backslash_escapables2])/&noremap("\\$1")/ge; + $str =~ s/_/&noremap("\\underscore{}")/ge; # \_ is too thin. + # quote TeX special characters |, ^, ~, \. + $str =~ s/\|/&noremap("\$|\$")/ge; + $str =~ s/\^/&noremap("\$\\hat{\\hspace{0.4em}}\$")/ge; + $str =~ s/\~/&noremap("\$\\tilde{\\hspace{0.4em}}\$")/ge; + $str =~ s/\\/&noremap("\$\\backslash{}\$")/ge; + # characters need to be treated differently in TeX + # * + $str =~ s/[*]/&noremap("\$\\ast\$")/ge; + # escape < and > as math string, + $str =~ s/</&noremap("\$<\$")/ge; + $str =~ s/>/&noremap("\$>\$")/ge; + $str =~ tr/\200-\377/\000-\177/; # put back + return $str; +} + +sub internal_lrefs { + local($_) = shift; + + s{L</([^>]+)>}{$1}g; + my(@items) = split( /(?:,?\s+(?:and\s+)?)/ ); + my $retstr = "the "; + my $i; + for ($i = 0; $i <= $#items; $i++) { + $retstr .= "C<$items[$i]>"; + $retstr .= ", " if @items > 2 && $i != $#items; + $retstr .= " and " if $i+2 == @items; + } + $retstr .= " entr" . ( @items > 1 ? "ies" : "y" ) + . " elsewhere in this document"; + + return $retstr; +} + +# map of HTML escapes to TeX escapes. +BEGIN { +%HTML_Escapes = ( + 'amp' => '&', # ampersand + 'lt' => '<', # left chevron, less-than + 'gt' => '>', # right chevron, greater-than + 'quot' => '"', # double quote + + "Aacute" => "\\'{A}", # capital A, acute accent + "aacute" => "\\'{a}", # small a, acute accent + "Acirc" => "\\^{A}", # capital A, circumflex accent + "acirc" => "\\^{a}", # small a, circumflex accent + "AElig" => '\\AE', # capital AE diphthong (ligature) + "aelig" => '\\ae', # small ae diphthong (ligature) + "Agrave" => "\\`{A}", # capital A, grave accent + "agrave" => "\\`{a}", # small a, grave accent + "Aring" => '\\u{A}', # capital A, ring + "aring" => '\\u{a}', # small a, ring + "Atilde" => '\\~{A}', # capital A, tilde + "atilde" => '\\~{a}', # small a, tilde + "Auml" => '\\"{A}', # capital A, dieresis or umlaut mark + "auml" => '\\"{a}', # small a, dieresis or umlaut mark + "Ccedil" => '\\c{C}', # capital C, cedilla + "ccedil" => '\\c{c}', # small c, cedilla + "Eacute" => "\\'{E}", # capital E, acute accent + "eacute" => "\\'{e}", # small e, acute accent + "Ecirc" => "\\^{E}", # capital E, circumflex accent + "ecirc" => "\\^{e}", # small e, circumflex accent + "Egrave" => "\\`{E}", # capital E, grave accent + "egrave" => "\\`{e}", # small e, grave accent + "ETH" => '\\OE', # capital Eth, Icelandic + "eth" => '\\oe', # small eth, Icelandic + "Euml" => '\\"{E}', # capital E, dieresis or umlaut mark + "euml" => '\\"{e}', # small e, dieresis or umlaut mark + "Iacute" => "\\'{I}", # capital I, acute accent + "iacute" => "\\'{i}", # small i, acute accent + "Icirc" => "\\^{I}", # capital I, circumflex accent + "icirc" => "\\^{i}", # small i, circumflex accent + "Igrave" => "\\`{I}", # capital I, grave accent + "igrave" => "\\`{i}", # small i, grave accent + "Iuml" => '\\"{I}', # capital I, dieresis or umlaut mark + "iuml" => '\\"{i}', # small i, dieresis or umlaut mark + "Ntilde" => '\\~{N}', # capital N, tilde + "ntilde" => '\\~{n}', # small n, tilde + "Oacute" => "\\'{O}", # capital O, acute accent + "oacute" => "\\'{o}", # small o, acute accent + "Ocirc" => "\\^{O}", # capital O, circumflex accent + "ocirc" => "\\^{o}", # small o, circumflex accent + "Ograve" => "\\`{O}", # capital O, grave accent + "ograve" => "\\`{o}", # small o, grave accent + "Oslash" => "\\O", # capital O, slash + "oslash" => "\\o", # small o, slash + "Otilde" => "\\~{O}", # capital O, tilde + "otilde" => "\\~{o}", # small o, tilde + "Ouml" => '\\"{O}', # capital O, dieresis or umlaut mark + "ouml" => '\\"{o}', # small o, dieresis or umlaut mark + "szlig" => '\\ss', # small sharp s, German (sz ligature) + "THORN" => '\\L', # capital THORN, Icelandic + "thorn" => '\\l',, # small thorn, Icelandic + "Uacute" => "\\'{U}", # capital U, acute accent + "uacute" => "\\'{u}", # small u, acute accent + "Ucirc" => "\\^{U}", # capital U, circumflex accent + "ucirc" => "\\^{u}", # small u, circumflex accent + "Ugrave" => "\\`{U}", # capital U, grave accent + "ugrave" => "\\`{u}", # small u, grave accent + "Uuml" => '\\"{U}', # capital U, dieresis or umlaut mark + "uuml" => '\\"{u}', # small u, dieresis or umlaut mark + "Yacute" => "\\'{Y}", # capital Y, acute accent + "yacute" => "\\'{y}", # small y, acute accent + "yuml" => '\\"{y}', # small y, dieresis or umlaut mark +); +} diff --git a/pod/pod2man b/pod/pod2man index 5b577738e3..b375b0184e 100755 --- a/pod/pod2man +++ b/pod/pod2man @@ -95,10 +95,10 @@ END print ".ft $CFont\n"; print <<'END'; 'if n "\c -'if t \\\\&\\\\$1\c -'if n \\\\&\\\\$1\c +'if t \\&\\$1\c +'if n \\&\\$1\c 'if n \&" -\\\\&\\\\$2 \\\\$3 \\\\$4 \\\\$5 \\\\$6 \\\\$7 +\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 '.ft R .. .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2 @@ -113,7 +113,7 @@ print <<'END'; . ds #] \fP .\} .if t \{\ -. ds #H ((1u-(\\\\\\\\n(.fu%2u))*.13m) +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& @@ -132,26 +132,26 @@ print <<'END'; . ds q .\} .if t \{\ -. ds ' \\\\k:\h'-(\\\\n(.wu*8/10-\*(#H)'\'\h"|\\\\n:u" -. ds ` \\\\k:\h'-(\\\\n(.wu*8/10-\*(#H)'\`\h'|\\\\n:u' -. ds ^ \\\\k:\h'-(\\\\n(.wu*10/11-\*(#H)'^\h'|\\\\n:u' -. ds , \\\\k:\h'-(\\\\n(.wu*8/10)',\h'|\\\\n:u' -. ds ~ \\\\k:\h'-(\\\\n(.wu-\*(#H-.1m)'~\h'|\\\\n:u' +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10' . ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m' -. ds / \\\\k:\h'-(\\\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' . ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10' .\} . \" troff and (daisy-wheel) nroff accents -.ds : \\\\k:\h'-(\\\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\\\n:u'\v'\*(#V' +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds v \\\\k:\h'-(\\\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\\\n:u'\*(#] -.ds _ \\\\k:\h'-(\\\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\\\n:u' -.ds . \\\\k:\h'-(\\\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\\\n:u' +.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#] +.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u' +.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u' .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#] -.ds o \\\\k:\h'-(\\\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\\\n:u'\*(#] +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\\\n:u' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e @@ -159,8 +159,8 @@ print <<'END'; .ds oe o\h'-(\w'o'u*4/10)'e .ds Oe O\h'-(\w'O'u*4/10)'E . \" corrections for vroff -.if v .ds ~ \\\\k:\h'-(\\\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\\\n:u' -.if v .ds ^ \\\\k:\h'-(\\\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\\\n:u' +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ @@ -246,7 +246,7 @@ while (<>) { } {I<$1>\\|$2}gx; # convert simple variable references - s/([\$\@%][\w:]+)/C<$1>/g; + s/(\s+)([\$\@%][\w:]+)/${1}C<$2>/g; if (m{ ( [\-\w]+ |