document xsubpp SCOPE:

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

diff --git a/pod/perlrun.pod b/pod/perlrun.pod
index 1e1a0cb..3761398 100644 (file)
--- a/pod/perlrun.pod
+++ b/pod/perlrun.pod
@@ -4,7 +4,16 @@ perlrun - how to execute the Perl interpreter
 
 =head1 SYNOPSIS
 
-B<perl> [switches] filename args
+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
 
@@ -89,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
@@ -131,10 +140,10 @@ 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., -d:DProf executes the script using the
+installed as Devel::foo. E.g., B<-d:DProf> executes the script using the
 Devel::DProf profiler.  See L<perldebug>.
 
 =item B<-D>I<number>
@@ -174,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
@@ -223,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
@@ -246,14 +261,30 @@ 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>[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.
 
-executes C<use> I<module> C<;> before executing your script. You can
-also do C<-M'Foo qw(Bar Baz)'>.
+C<-M>I<module> executes C<use> I<module> C<;> before executing your
+script.  You can use quotes to add extra code after the module name,
+e.g., C<-M'module qw(foo bar)'>.
 
-=item B<-m>I<module>
+If the first character after the C<-M> or C<-m> is a dash (C<->)
+then the 'use' is replaced with 'no'.
 
-executes C<use> I<module> C<();> before executing your script.
+A little built-in syntactic sugar means you can also say
+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>.
 
 =item B<-n>
 
@@ -378,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