A mechanism for inlineable OP equivalents of XSUBs is a TODO.

[p5sagit/p5-mst-13.2.git] / pod / pod2man.PL

diff --git a/pod/pod2man.PL b/pod/pod2man.PL
index c98f8de..25df0df 100644 (file)
--- a/pod/pod2man.PL
+++ b/pod/pod2man.PL
@@ -58,14 +58,15 @@ use vars qw($running_under_some_shell);
 my $stdin;
 @ARGV = map { $_ eq '-' && !$stdin++ ? ('--', $_) : $_ } @ARGV;
 
-# Parse our options, trying to retain backwards compatibility with pod2man but
+# Parse our options, trying to retain backward compatibility with pod2man but
 # allowing short forms as well.  --lax is currently ignored.
 my %options;
+$options{errors} = 'pod';
 Getopt::Long::config ('bundling_override');
-GetOptions (\%options, 'section|s=s', 'release|r:s', 'center|c=s',
-            'date|d=s', 'fixed=s', 'fixedbold=s', 'fixeditalic=s',
-            'fixedbolditalic=s', 'name|n=s', 'official|o', 'quotes|q=s',
-            'lax|l', 'help|h', 'verbose|v', 'utf8|u') or exit 1;
+GetOptions (\%options, 'center|c=s', 'date|d=s', 'fixed=s', 'fixedbold=s',
+            'fixeditalic=s', 'fixedbolditalic=s', 'help|h', 'lax|l',
+            'name|n=s', 'official|o', 'quotes|q=s', 'release|r:s',
+            'section|s=s', 'stderr', 'verbose|v', 'utf8|u') or exit 1;
 pod2usage (0) if $options{help};
 
 # Official sets --center, but don't override things explicitly set.
@@ -77,7 +78,7 @@ if ($options{official} && !defined $options{center}) {
 my $verbose = $options{verbose};
 delete $options{verbose};
 
-# This isn't a valid Pod::Man option and is only accepted for backwards
+# This isn't a valid Pod::Man option and is only accepted for backward
 # compatibility.
 delete $options{lax};
 
@@ -98,15 +99,16 @@ __END__
 pod2man - Convert POD data to formatted *roff input
 
 =for stopwords
-en em --utf8 UTF-8 overdo markup MT-LEVEL Allbery
+en em --stderr stderr --utf8 UTF-8 overdo markup MT-LEVEL Allbery Solaris
+URL troff troff-specific formatters uppercased Christiansen
 
 =head1 SYNOPSIS
 
-pod2man [B<--section>=I<manext>] [B<--release>[=I<version>]]
-    [B<--center>=I<string>] [B<--date>=I<string>] [B<--fixed>=I<font>]
-    [B<--fixedbold>=I<font>] [B<--fixeditalic>=I<font>]
+pod2man [B<--center>=I<string>] [B<--date>=I<string>]
+    [B<--fixed>=I<font>] [B<--fixedbold>=I<font>] [B<--fixeditalic>=I<font>]
     [B<--fixedbolditalic>=I<font>] [B<--name>=I<name>] [B<--official>]
-    [B<--lax>] [B<--quotes>=I<quotes>] [B<--verbose>]
+    [B<--quotes>=I<quotes>] [B<--release>[=I<version>]]
+    [B<--section>=I<manext>] [B<--stderr>] [B<--utf8>] [B<--verbose>]
     [I<input> [I<output>] ...]
 
 pod2man B<--help>
@@ -125,8 +127,8 @@ files can be processed in the same B<pod2man> invocation (saving module
 load and compile times) by providing multiple pairs of I<input> and
 I<output> files on the command line.
 
-B<--section>, B<--release>, B<--center>, B<--date>, and B<--official> can be
-used to set the headers and footers to use; if not given, Pod::Man will
+B<--section>, B<--release>, B<--center>, B<--date>, and B<--official> can
+be used to set the headers and footers to use; if not given, Pod::Man will
 assume various defaults.  See below or L<Pod::Man> for details.
 
 B<pod2man> assumes that your *roff formatters have a fixed-width font
@@ -189,9 +191,9 @@ Print out usage information.
 
 =item B<-l>, B<--lax>
 
-No longer used.  B<pod2man> used to check its input for validity as a manual
-page, but this should now be done by L<podchecker(1)> instead.  Accepted for
-backwards compatibility; this option no longer does anything.
+No longer used.  B<pod2man> used to check its input for validity as a
+manual page, but this should now be done by L<podchecker(1)> instead.
+Accepted for backward compatibility; this option no longer does anything.
 
 =item B<-n> I<name>, B<--name>=I<name>
 
@@ -246,6 +248,13 @@ that are reliably consistent are 1, 2, and 3.
 By default, section 1 will be used unless the file ends in C<.pm>, in
 which case section 3 will be selected.
 
+=item B<--stderr>
+
+By default, B<pod2man> puts any errors detected in the POD input in a POD
+ERRORS section in the output manual page.  If B<--stderr> is given, errors
+are sent to standard error instead and the POD ERRORS section is
+suppressed.
+
 =item B<-u>, B<--utf8>
 
 By default, B<pod2man> produces the most conservative possible *roff
@@ -262,6 +271,12 @@ However, be warned that *roff source with literal UTF-8 characters is not
 supported by many implementations and may even result in segfaults and
 other bad behavior.
 
+Be aware that, when using this option, the input encoding of your POD
+source must be properly declared unless it is US-ASCII or Latin-1.  POD
+input without an C<=encoding> command will be assumed to be in Latin-1,
+and if it's actually in UTF-8, the output will be double-encoded.  See
+L<perlpod(1)> for more information on the C<=encoding> command.
+
 =item B<-v>, B<--verbose>
 
 Print out the name of each output file as it is being generated.
@@ -538,8 +553,8 @@ section numbering conventions.
 
 =head1 SEE ALSO
 
-L<Pod::Man>, L<Pod::Simple>, L<man(1)>, L<nroff(1)>, L<podchecker(1)>,
-L<troff(1)>, L<man(7)>
+L<Pod::Man>, L<Pod::Simple>, L<man(1)>, L<nroff(1)>, L<perlpod(1)>,
+L<podchecker(1)>, L<troff(1)>, L<man(7)>
 
 The man page documenting the an macro set may be L<man(5)> instead of
 L<man(7)> on your system.