Update usage summary and -M description; style changes in =items

1 files changed, 37 insertions, 24 deletions

diff --git a/pod/perlrun.pod b/pod/perlrun.pod
index 7169515c54..4f6294cc69 100644
--- 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,7 +409,7 @@ 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.