document xsubpp SCOPE:

[p5sagit/p5-mst-13.2.git] / pod / perlrun.pod

diff --git a/pod/perlrun.pod b/pod/perlrun.pod
index 7169515..3761398 100644 (file)
--- a/pod/perlrun.pod
+++ b/pod/perlrun.pod
@@ -4,10 +4,16 @@ perlrun - how to execute the Perl interpreter
 
 =head1 SYNOPSIS
 
-B<perl>        [B<-acdhnpPsSTuUvw>] [B<-0[octal>]] [B<-D[number/list]>]
-       [B<-F regexp>] [B<-i[extension>]] [B<-I<lt>dir<gt>>]
-       [B<-l[octal]>] [B<-x[dir]>]
-       [programfile | B<-e command>] [argument ...]
+B<perl>        S<[ B<-sTuU> ]>
+       S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]>
+       S<[ B<-cw> ] [ B<-d>[:I<debugger>] ] [ B<-D>[I<number/list>] ]>
+       S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal>] ]>
+       S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ]>
+       S<[ B<-P> ]>
+       S<[ B<-S> ]>
+       S<[ B<-x>[I<dir>] ]>
+       S<[ B<-i>[I<extension>] ]>
+       S<[ B<-e> I<'command'> ] [ B<--> ] [ I<programfile> ] [ I<argument> ]...>
 
 =head1 DESCRIPTION
 
@@ -92,7 +98,7 @@ Switches include:
 
 =over 5
 
-=item B<-0>I<digits>
+=item B<-0>[I<digits>]
 
 specifies the record separator (C<$/>) as an octal number.  If there are
 no digits, the null character is the separator.  Other switches may
@@ -134,7 +140,7 @@ your program.
 
 runs the script under the Perl debugger.  See L<perldebug>.
 
-=item B<-d:foo>
+=item B<-d:>I<foo>
 
 runs the script under the control of a debugging or tracing module
 installed as Devel::foo. E.g., B<-d:DProf> executes the script using the
@@ -177,12 +183,17 @@ Multiple B<-e> commands may
 be given to build up a multi-line script.  
 Make sure to use semicolons where you would in a normal program.
 
-=item B<-F>I<regexp>
+=item B<-F>I<pattern>
 
-specifies a regular expression to split on if B<-a> is also in effect.
-If regexp has C<//> around it, the slashes will be ignored.
+specifies the pattern to split on if B<-a> is also in effect.  The
+pattern may be surrounded by C<//>, C<""> or C<''>, otherwise it will be
+put in single quotes.
 
-=item B<-i>I<extension>
+=item B<-h>
+
+prints a summary of the options.
+
+=item B<-i>[I<extension>]
 
 specifies that files processed by the C<E<lt>E<gt>> construct are to be edited
 in-place.  It does this by renaming the input file, opening the output
@@ -226,11 +237,12 @@ example in L<perlfunc/eof>).
 
 =item B<-I>I<directory>
 
-may be used in conjunction with B<-P> to tell the C preprocessor where
-to look for include files.  By default /usr/include and /usr/lib/perl
-are searched.
+Directories specified by B<-I> are prepended to the search path for
+modules (@INC), and also tells the C preprocessor where to search for
+include files.  The C preprocessor is invoked with B<-P>; by default it
+searches /usr/include and /usr/lib/perl.
 
-=item B<-l>I<octnum>
+=item B<-l>[I<octnum>]
 
 enables automatic line-ending processing.  It has two effects:  first,
 it automatically chomps the line terminator when used with B<-n> or
@@ -249,9 +261,13 @@ separator if the B<-l> switch is followed by a B<-0> switch:
 
 This sets $\ to newline and then sets $/ to the null character.
 
-=item B<-m>I<module>
+=item B<-m>[B<->]I<module>
+
+=item B<-M>[B<->]I<module>
 
-=item B<-M>I<module>
+=item B<-M>[B<->]I<'module ...'>
+
+=item B<-[mM]>[B<->]I<module=arg[,arg]...>
 
 C<-m>I<module> executes C<use> I<module> C<();> before executing your
 script.
@@ -264,15 +280,12 @@ If the first character after the C<-M> or C<-m> is a dash (C<->)
 then the 'use' is replaced with 'no'.
 
 A little built-in syntactic sugar means you can also say
-C<-mmodule=foo> or C<-Mmodule=foo> as a shortcut for
-C<-M'module qw(foo)'>.  Note that using the C<=> form
+C<-mmodule=foo,bar> or C<-Mmodule=foo,bar> as a shortcut for
+C<-M'module qw(foo bar)'>.  This avoids the need to use quotes when
+importing symbols.  The actual code generated by C<-Mmodule=foo,bar> is
+C<use module split(/,/,q{foo,bar})>.  Note that the C<=> form
 removes the distinction between C<-m> and C<-M>.
 
-To avoid the need to use quotes when importing more that one symbol
-with the C<=> form, the text following the C<=> is split into a list
-on commas (C<,>) rather than whitespace. The actual code generated
-by C<-Mmodule=foo,bar> is C<use module split(/,/,q{foo,bar})>.
-
 =item B<-n>
 
 causes Perl to assume the following loop around your script, which
@@ -396,13 +409,13 @@ prints the version and patchlevel of your Perl executable.
 prints summary of the major perl configuration values and the current
 value of @INC.
 
-=item B<-V:name>
+=item B<-V:>I<name>
 
 Prints to STDOUT the value of the named configuration variable.
 
 =item B<-w>
 
-prints warnings about identifiers that are mentioned only once, and
+prints warnings about variable names that are mentioned only once, and
 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