diff options
author | Ingo Schwarze <schwarze@cvs.openbsd.org> | 2016-04-19 08:06:53 +0000 |
---|---|---|
committer | Ingo Schwarze <schwarze@cvs.openbsd.org> | 2016-04-19 08:06:53 +0000 |
commit | 0a851c56f2f6d600c64a908b72be7e46e48faf62 (patch) | |
tree | adafae912dab3a6f27c2f8b2d07b3228e2d93a39 /gnu/usr.bin/perl | |
parent | 3a465ba6a77e965eb76a408d43163642ff78c05f (diff) |
In pod2man(1), enable UTF-8 output by default and provide a --no-utf8
command line option to disable it. The new default improves the
formatting of Perl manuals using UTF-8 characters (for example
perlunicook(1)) with man(1) and mandoc(1) no matter which locale
the user has set.
Issue discovered by and fix OK by afresh1@.
Trying to push this change upstream would make no sense. It's the
right thing to do only because we decided to not support any other
locales except ASCII and UTF-8. A system trying to provide arbitrary
locales simply cannot handle manuals containing UTF-8 characters
at build time, so the change would produce wrong results.
Diffstat (limited to 'gnu/usr.bin/perl')
-rw-r--r-- | gnu/usr.bin/perl/cpan/podlators/scripts/pod2man.PL | 116 |
1 files changed, 81 insertions, 35 deletions
diff --git a/gnu/usr.bin/perl/cpan/podlators/scripts/pod2man.PL b/gnu/usr.bin/perl/cpan/podlators/scripts/pod2man.PL index 08bdde24c82..3e4b576e102 100644 --- a/gnu/usr.bin/perl/cpan/podlators/scripts/pod2man.PL +++ b/gnu/usr.bin/perl/cpan/podlators/scripts/pod2man.PL @@ -37,7 +37,7 @@ print OUT <<'!NO!SUBS!'; # pod2man -- Convert POD data to formatted *roff input. # -# Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010 +# Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2012, 2013 # Russ Allbery <rra@stanford.edu> # # This program is free software; you may redistribute it and/or modify it @@ -51,6 +51,9 @@ use Pod::Usage qw(pod2usage); use strict; +# Clean up $0 for error reporting. +$0 =~ s%.*/%%; + # Insert -- into @ARGV before any single dash argument to hide it from # Getopt::Long; we want to interpret it as meaning stdin. my $stdin; @@ -59,12 +62,13 @@ my $stdin; # 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'; +$options{utf8} = 1; Getopt::Long::config ('bundling_override'); -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; +GetOptions (\%options, 'center|c=s', 'date|d=s', 'errors=s', 'fixed=s', + 'fixedbold=s', 'fixeditalic=s', 'fixedbolditalic=s', 'help|h', + 'lax|l', 'name|n=s', 'nourls', '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. @@ -80,33 +84,50 @@ delete $options{verbose}; # compatibility. delete $options{lax}; +# If neither stderr nor errors is set, default to errors = die. +if (!defined $options{stderr} && !defined $options{errors}) { + $options{errors} = 'die'; +} + # Initialize and run the formatter, pulling a pair of input and output off at -# a time. +# a time. For each file, we check whether the document was completely empty +# and, if so, will remove the created file and exit with a non-zero exit +# status. my $parser = Pod::Man->new (%options); +my $status = 0; my @files; do { @files = splice (@ARGV, 0, 2); print " $files[1]\n" if $verbose; $parser->parse_from_file (@files); + if ($parser->{CONTENTLESS}) { + $status = 1; + warn "$0: unable to format $files[0]\n"; + if (defined ($files[1]) and $files[1] ne '-') { + unlink $files[1] unless (-s $files[1]); + } + } } while (@ARGV); +exit $status; __END__ +=for stopwords +en em --stderr stderr --utf8 --no-utf8 UTF-8 +overdo markup MT-LEVEL Allbery Solaris +URL troff troff-specific formatters uppercased Christiansen --nourls + =head1 NAME pod2man - Convert POD data to formatted *roff input -=for stopwords -en em --stderr stderr --utf8 UTF-8 overdo markup MT-LEVEL Allbery Solaris -URL troff troff-specific formatters uppercased Christiansen - =head1 SYNOPSIS -pod2man [B<--center>=I<string>] [B<--date>=I<string>] +pod2man [B<--center>=I<string>] [B<--date>=I<string>] [B<--errors>=I<style>] [B<--fixed>=I<font>] [B<--fixedbold>=I<font>] [B<--fixeditalic>=I<font>] - [B<--fixedbolditalic>=I<font>] [B<--name>=I<name>] [B<--official>] - [B<--quotes>=I<quotes>] [B<--release>[=I<version>]] - [B<--section>=I<manext>] [B<--stderr>] [B<--utf8>] [B<--verbose>] + [B<--fixedbolditalic>=I<font>] [B<--name>=I<name>] [B<--nourls>] + [B<--official>] [B<--quotes>=I<quotes>] [B<--release>[=I<version>]] + [B<--section>=I<manext>] [B<--stderr>] [B<--no-utf8>] [B<--verbose>] [I<input> [I<output>] ...] pod2man B<--help> @@ -159,6 +180,16 @@ Set the left-hand footer string to this value. By default, the modification date of the input file will be used, or the current date if input comes from C<STDIN>. +=item B<-errors>=I<style> + +Set the error handling style. C<die> says to throw an exception on any +POD formatting error. C<stderr> says to report errors on standard error, +but not to throw an exception. C<pod> says to include a POD ERRORS +section in the resulting documentation summarizing the errors. C<none> +ignores POD errors entirely, as much as possible. + +The default is C<die>. + =item B<--fixed>=I<font> The fixed-width font to use for verbatim text and code. Defaults to @@ -206,6 +237,21 @@ Note that this option is probably not useful when converting multiple POD files at once. The convention for Unix man pages for commands is for the man page title to be in all-uppercase even if the command isn't. +=item B<--nourls> + +Normally, LZ<><> formatting codes with a URL but anchor text are formatted +to show both the anchor text and the URL. In other words: + + L<foo|http://example.com/> + +is formatted as: + + foo <http://example.com/> + +This flag, if given, suppresses the URL when anchor text is given, so this +example would be formatted as just C<foo>. This can produce less +cluttered output in cases where the URLs are not particularly important. + =item B<-o>, B<--official> Set the default header to indicate that this page is part of the standard @@ -248,26 +294,17 @@ 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. +By default, B<pod2man> dies if any errors are detected in the POD input. +If B<--stderr> is given and no B<--errors> flag is present, errors are +sent to standard error, but B<pod2man> does not abort. This is equivalent +to C<--errors=stderr> and is supported for backward compatibility. =item B<-u>, B<--utf8> -By default, B<pod2man> produces the most conservative possible *roff -output to try to ensure that it will work with as many different *roff -implementations as possible. Many *roff implementations cannot handle -non-ASCII characters, so this means all non-ASCII characters are converted -either to a *roff escape sequence that tries to create a properly accented -character (at least for troff output) or to C<X>. - -This option says to instead output literal UTF-8 characters. If your -*roff implementation can handle it, this is the best output format to use -and avoids corruption of documents containing non-ASCII characters. -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. +This option allows B<pod2man> to output literal UTF-8 characters. +On OpenBSD, it is enabled by default and can be disabled with +B<--no-utf8>, in which case non-ASCII characters are converted +either to *roff escape sequences or to C<X>. 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 @@ -281,6 +318,16 @@ Print out the name of each output file as it is being generated. =back +=head1 EXIT STATUS + +As long as all documents processed result in some output, even if that +output includes errata (a C<POD ERRORS> section generated with +C<--errors=pod>), B<pod2man> will exit with status 0. If any of the +documents being processed do not result in an output document, B<pod2man> +will exit with status 1. If there are syntax errors in a POD document +being processed and the error handling style is set to the default of +C<die>, B<pod2man> will abort immediately with exit status 255. + =head1 DIAGNOSTICS If B<pod2man> fails with errors, see L<Pod::Man> and L<Pod::Simple> for @@ -329,15 +376,14 @@ B<pod2man> by Larry Wall and Tom Christiansen. =head1 COPYRIGHT AND LICENSE -Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010 Russ Allbery -<rra@stanford.edu>. +Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2012, 2013 Russ +Allbery <rra@stanford.edu>. This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself. =cut !NO!SUBS! -#'# (cperl-mode) close OUT or die "Can't close $file: $!"; chmod 0755, $file or die "Can't reset permissions for $file: $!\n"; |