1#!perl 2 3use Config; 4use File::Basename qw(&basename &dirname); 5use Cwd; 6 7# List explicitly here the variables you want Configure to 8# generate. Metaconfig only looks for shell variables, so you 9# have to mention them as if they were shell variables, not 10# %Config entries. Thus you write 11# $startperl 12# to ensure Configure will look for $Config{startperl}. 13 14# This forces PL files to create target in same directory as PL file. 15# This is so that make depend always knows where to find PL derivatives. 16$origdir = cwd; 17chdir dirname($0); 18$file = basename($0, '.PL'); 19$file .= '.com' if $^O eq 'VMS'; 20 21open OUT,">$file" or die "Can't create $file: $!"; 22 23print "Extracting $file (with variable substitutions)\n"; 24 25# In this section, perl variables will be expanded during extraction. 26# You can use $Config{...} to use Configure variables. 27 28print OUT <<"!GROK!THIS!"; 29$Config{startperl} 30 eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}' 31 if \$running_under_some_shell; 32!GROK!THIS! 33 34# In the following, perl variables are not expanded during extraction. 35 36print OUT <<'!NO!SUBS!'; 37 38# pod2man -- Convert POD data to formatted *roff input. 39# 40# Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2012, 2013 41# Russ Allbery <rra@stanford.edu> 42# 43# This program is free software; you may redistribute it and/or modify it 44# under the same terms as Perl itself. 45 46require 5.004; 47 48use Getopt::Long qw(GetOptions); 49use Pod::Man (); 50use Pod::Usage qw(pod2usage); 51 52use strict; 53 54# Clean up $0 for error reporting. 55$0 =~ s%.*/%%; 56 57# Insert -- into @ARGV before any single dash argument to hide it from 58# Getopt::Long; we want to interpret it as meaning stdin. 59my $stdin; 60@ARGV = map { $_ eq '-' && !$stdin++ ? ('--', $_) : $_ } @ARGV; 61 62# Parse our options, trying to retain backward compatibility with pod2man but 63# allowing short forms as well. --lax is currently ignored. 64my %options; 65Getopt::Long::config ('bundling_override'); 66GetOptions (\%options, 'center|c=s', 'date|d=s', 'errors=s', 'fixed=s', 67 'fixedbold=s', 'fixeditalic=s', 'fixedbolditalic=s', 'help|h', 68 'lax|l', 'name|n=s', 'nourls', 'official|o', 'quotes|q=s', 69 'release|r:s', 'section|s=s', 'stderr', 'verbose|v', 'utf8|u') 70 or exit 1; 71pod2usage (0) if $options{help}; 72 73# Official sets --center, but don't override things explicitly set. 74if ($options{official} && !defined $options{center}) { 75 $options{center} = 'Perl Programmers Reference Guide'; 76} 77 78# Verbose is only our flag, not a Pod::Man flag. 79my $verbose = $options{verbose}; 80delete $options{verbose}; 81 82# This isn't a valid Pod::Man option and is only accepted for backward 83# compatibility. 84delete $options{lax}; 85 86# If neither stderr nor errors is set, default to errors = die. 87if (!defined $options{stderr} && !defined $options{errors}) { 88 $options{errors} = 'die'; 89} 90 91# Initialize and run the formatter, pulling a pair of input and output off at 92# a time. For each file, we check whether the document was completely empty 93# and, if so, will remove the created file and exit with a non-zero exit 94# status. 95my $parser = Pod::Man->new (%options); 96my $status = 0; 97my @files; 98do { 99 @files = splice (@ARGV, 0, 2); 100 print " $files[1]\n" if $verbose; 101 $parser->parse_from_file (@files); 102 if ($parser->{CONTENTLESS}) { 103 $status = 1; 104 warn "$0: unable to format $files[0]\n"; 105 if (defined ($files[1]) and $files[1] ne '-') { 106 unlink $files[1] unless (-s $files[1]); 107 } 108 } 109} while (@ARGV); 110exit $status; 111 112__END__ 113 114=for stopwords 115en em --stderr stderr --utf8 UTF-8 overdo markup MT-LEVEL Allbery Solaris 116URL troff troff-specific formatters uppercased Christiansen --nourls 117 118=head1 NAME 119 120pod2man - Convert POD data to formatted *roff input 121 122=head1 SYNOPSIS 123 124pod2man [B<--center>=I<string>] [B<--date>=I<string>] [B<--errors>=I<style>] 125 [B<--fixed>=I<font>] [B<--fixedbold>=I<font>] [B<--fixeditalic>=I<font>] 126 [B<--fixedbolditalic>=I<font>] [B<--name>=I<name>] [B<--nourls>] 127 [B<--official>] [B<--quotes>=I<quotes>] [B<--release>[=I<version>]] 128 [B<--section>=I<manext>] [B<--stderr>] [B<--utf8>] [B<--verbose>] 129 [I<input> [I<output>] ...] 130 131pod2man B<--help> 132 133=head1 DESCRIPTION 134 135B<pod2man> is a front-end for Pod::Man, using it to generate *roff input 136from POD source. The resulting *roff code is suitable for display on a 137terminal using nroff(1), normally via man(1), or printing using troff(1). 138 139I<input> is the file to read for POD source (the POD can be embedded in 140code). If I<input> isn't given, it defaults to C<STDIN>. I<output>, if 141given, is the file to which to write the formatted output. If I<output> 142isn't given, the formatted output is written to C<STDOUT>. Several POD 143files can be processed in the same B<pod2man> invocation (saving module 144load and compile times) by providing multiple pairs of I<input> and 145I<output> files on the command line. 146 147B<--section>, B<--release>, B<--center>, B<--date>, and B<--official> can 148be used to set the headers and footers to use; if not given, Pod::Man will 149assume various defaults. See below or L<Pod::Man> for details. 150 151B<pod2man> assumes that your *roff formatters have a fixed-width font 152named C<CW>. If yours is called something else (like C<CR>), use 153B<--fixed> to specify it. This generally only matters for troff output 154for printing. Similarly, you can set the fonts used for bold, italic, and 155bold italic fixed-width output. 156 157Besides the obvious pod conversions, Pod::Man, and therefore pod2man also 158takes care of formatting func(), func(n), and simple variable references 159like $foo or @bar so you don't have to use code escapes for them; complex 160expressions like C<$fred{'stuff'}> will still need to be escaped, though. 161It also translates dashes that aren't used as hyphens into en dashes, makes 162long dashes--like this--into proper em dashes, fixes "paired quotes," and 163takes care of several other troff-specific tweaks. See L<Pod::Man> for 164complete information. 165 166=head1 OPTIONS 167 168=over 4 169 170=item B<-c> I<string>, B<--center>=I<string> 171 172Sets the centered page header to I<string>. The default is "User 173Contributed Perl Documentation", but also see B<--official> below. 174 175=item B<-d> I<string>, B<--date>=I<string> 176 177Set the left-hand footer string to this value. By default, the modification 178date of the input file will be used, or the current date if input comes from 179C<STDIN>. 180 181=item B<-errors>=I<style> 182 183Set the error handling style. C<die> says to throw an exception on any 184POD formatting error. C<stderr> says to report errors on standard error, 185but not to throw an exception. C<pod> says to include a POD ERRORS 186section in the resulting documentation summarizing the errors. C<none> 187ignores POD errors entirely, as much as possible. 188 189The default is C<die>. 190 191=item B<--fixed>=I<font> 192 193The fixed-width font to use for verbatim text and code. Defaults to 194C<CW>. Some systems may want C<CR> instead. Only matters for troff(1) 195output. 196 197=item B<--fixedbold>=I<font> 198 199Bold version of the fixed-width font. Defaults to C<CB>. Only matters 200for troff(1) output. 201 202=item B<--fixeditalic>=I<font> 203 204Italic version of the fixed-width font (actually, something of a misnomer, 205since most fixed-width fonts only have an oblique version, not an italic 206version). Defaults to C<CI>. Only matters for troff(1) output. 207 208=item B<--fixedbolditalic>=I<font> 209 210Bold italic (probably actually oblique) version of the fixed-width font. 211Pod::Man doesn't assume you have this, and defaults to C<CB>. Some 212systems (such as Solaris) have this font available as C<CX>. Only matters 213for troff(1) output. 214 215=item B<-h>, B<--help> 216 217Print out usage information. 218 219=item B<-l>, B<--lax> 220 221No longer used. B<pod2man> used to check its input for validity as a 222manual page, but this should now be done by L<podchecker(1)> instead. 223Accepted for backward compatibility; this option no longer does anything. 224 225=item B<-n> I<name>, B<--name>=I<name> 226 227Set the name of the manual page to I<name>. Without this option, the manual 228name is set to the uppercased base name of the file being converted unless 229the manual section is 3, in which case the path is parsed to see if it is a 230Perl module path. If it is, a path like C<.../lib/Pod/Man.pm> is converted 231into a name like C<Pod::Man>. This option, if given, overrides any 232automatic determination of the name. 233 234Note that this option is probably not useful when converting multiple POD 235files at once. The convention for Unix man pages for commands is for the 236man page title to be in all-uppercase even if the command isn't. 237 238=item B<--nourls> 239 240Normally, LZ<><> formatting codes with a URL but anchor text are formatted 241to show both the anchor text and the URL. In other words: 242 243 L<foo|http://example.com/> 244 245is formatted as: 246 247 foo <http://example.com/> 248 249This flag, if given, suppresses the URL when anchor text is given, so this 250example would be formatted as just C<foo>. This can produce less 251cluttered output in cases where the URLs are not particularly important. 252 253=item B<-o>, B<--official> 254 255Set the default header to indicate that this page is part of the standard 256Perl release, if B<--center> is not also given. 257 258=item B<-q> I<quotes>, B<--quotes>=I<quotes> 259 260Sets the quote marks used to surround CE<lt>> text to I<quotes>. If 261I<quotes> is a single character, it is used as both the left and right 262quote; if I<quotes> is two characters, the first character is used as the 263left quote and the second as the right quoted; and if I<quotes> is four 264characters, the first two are used as the left quote and the second two as 265the right quote. 266 267I<quotes> may also be set to the special value C<none>, in which case no 268quote marks are added around CE<lt>> text (but the font is still changed for 269troff output). 270 271=item B<-r>, B<--release> 272 273Set the centered footer. By default, this is the version of Perl you run 274B<pod2man> under. Note that some system an macro sets assume that the 275centered footer will be a modification date and will prepend something like 276"Last modified: "; if this is the case, you may want to set B<--release> to 277the last modified date and B<--date> to the version number. 278 279=item B<-s>, B<--section> 280 281Set the section for the C<.TH> macro. The standard section numbering 282convention is to use 1 for user commands, 2 for system calls, 3 for 283functions, 4 for devices, 5 for file formats, 6 for games, 7 for 284miscellaneous information, and 8 for administrator commands. There is a lot 285of variation here, however; some systems (like Solaris) use 4 for file 286formats, 5 for miscellaneous information, and 7 for devices. Still others 287use 1m instead of 8, or some mix of both. About the only section numbers 288that are reliably consistent are 1, 2, and 3. 289 290By default, section 1 will be used unless the file ends in C<.pm>, in 291which case section 3 will be selected. 292 293=item B<--stderr> 294 295By default, B<pod2man> dies if any errors are detected in the POD input. 296If B<--stderr> is given and no B<--errors> flag is present, errors are 297sent to standard error, but B<pod2man> does not abort. This is equivalent 298to C<--errors=stderr> and is supported for backward compatibility. 299 300=item B<-u>, B<--utf8> 301 302By default, B<pod2man> produces the most conservative possible *roff 303output to try to ensure that it will work with as many different *roff 304implementations as possible. Many *roff implementations cannot handle 305non-ASCII characters, so this means all non-ASCII characters are converted 306either to a *roff escape sequence that tries to create a properly accented 307character (at least for troff output) or to C<X>. 308 309This option says to instead output literal UTF-8 characters. If your 310*roff implementation can handle it, this is the best output format to use 311and avoids corruption of documents containing non-ASCII characters. 312However, be warned that *roff source with literal UTF-8 characters is not 313supported by many implementations and may even result in segfaults and 314other bad behavior. 315 316Be aware that, when using this option, the input encoding of your POD 317source must be properly declared unless it is US-ASCII or Latin-1. POD 318input without an C<=encoding> command will be assumed to be in Latin-1, 319and if it's actually in UTF-8, the output will be double-encoded. See 320L<perlpod(1)> for more information on the C<=encoding> command. 321 322=item B<-v>, B<--verbose> 323 324Print out the name of each output file as it is being generated. 325 326=back 327 328=head1 EXIT STATUS 329 330As long as all documents processed result in some output, even if that 331output includes errata (a C<POD ERRORS> section generated with 332C<--errors=pod>), B<pod2man> will exit with status 0. If any of the 333documents being processed do not result in an output document, B<pod2man> 334will exit with status 1. If there are syntax errors in a POD document 335being processed and the error handling style is set to the default of 336C<die>, B<pod2man> will abort immediately with exit status 255. 337 338=head1 DIAGNOSTICS 339 340If B<pod2man> fails with errors, see L<Pod::Man> and L<Pod::Simple> for 341information about what those errors might mean. 342 343=head1 EXAMPLES 344 345 pod2man program > program.1 346 pod2man SomeModule.pm /usr/perl/man/man3/SomeModule.3 347 pod2man --section=7 note.pod > note.7 348 349If you would like to print out a lot of man page continuously, you probably 350want to set the C and D registers to set contiguous page numbering and 351even/odd paging, at least on some versions of man(7). 352 353 troff -man -rC1 -rD1 perl.1 perldata.1 perlsyn.1 ... 354 355To get index entries on C<STDERR>, turn on the F register, as in: 356 357 troff -man -rF1 perl.1 358 359The indexing merely outputs messages via C<.tm> for each major page, 360section, subsection, item, and any C<XE<lt>E<gt>> directives. See 361L<Pod::Man> for more details. 362 363=head1 BUGS 364 365Lots of this documentation is duplicated from L<Pod::Man>. 366 367=head1 SEE ALSO 368 369L<Pod::Man>, L<Pod::Simple>, L<man(1)>, L<nroff(1)>, L<perlpod(1)>, 370L<podchecker(1)>, L<perlpodstyle(1)>, L<troff(1)>, L<man(7)> 371 372The man page documenting the an macro set may be L<man(5)> instead of 373L<man(7)> on your system. 374 375The current version of this script is always available from its web site at 376L<http://www.eyrie.org/~eagle/software/podlators/>. It is also part of the 377Perl core distribution as of 5.6.0. 378 379=head1 AUTHOR 380 381Russ Allbery <rra@stanford.edu>, based I<very> heavily on the original 382B<pod2man> by Larry Wall and Tom Christiansen. 383 384=head1 COPYRIGHT AND LICENSE 385 386Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2012, 2013 Russ 387Allbery <rra@stanford.edu>. 388 389This program is free software; you may redistribute it and/or modify it 390under the same terms as Perl itself. 391 392=cut 393!NO!SUBS! 394 395close OUT or die "Can't close $file: $!"; 396chmod 0755, $file or die "Can't reset permissions for $file: $!\n"; 397exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':'; 398chdir $origdir; 399