This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
add Pod-Parser-1.08 (verbatim module =include tests elided owing
[perl5.git] / pod / pod2usage.PL
CommitLineData
360aca43
GS
1#!/usr/local/bin/perl
2
3use Config;
4use File::Basename qw(&basename &dirname);
5
6# List explicitly here the variables you want Configure to
7# generate. Metaconfig only looks for shell variables, so you
8# have to mention them as if they were shell variables, not
9# %Config entries. Thus you write
10# $startperl
11# to ensure Configure will look for $Config{startperl}.
12
13# This forces PL files to create target in same directory as PL file.
14# This is so that make depend always knows where to find PL derivatives.
15chdir(dirname($0));
16($file = basename($0)) =~ s/\.PL$//;
17$file =~ s/\.pl$//
18 if ($^O eq 'VMS' or $^O eq 'os2'); # "case-forgiving"
19
20open OUT,">$file" or die "Can't create $file: $!";
21
22print "Extracting $file (with variable substitutions)\n";
23
24# In this section, perl variables will be expanded during extraction.
25# You can use $Config{...} to use Configure variables.
26
27print OUT <<"!GROK!THIS!";
28$Config{'startperl'}
29 eval 'exec perl -S \$0 "\$@"'
30 if 0;
31!GROK!THIS!
32
33# In the following, perl variables are not expanded during extraction.
34
35print OUT <<'!NO!SUBS!';
36
37#############################################################################
38# pod2usage -- command to print usage messages from embedded pod docs
39#
40# Derived from Tom Christiansen's pod2text script.
41# (with extensive modifications)
42#
43# Copyright (c) 1996 Bradford Appleton. All rights reserved.
44# This file is part of "PodParser". PodParser is free software;
45# you can redistribute it and/or modify it under the same terms
46# as Perl itself.
47#############################################################################
48
49use strict;
50use diagnostics;
51
52=head1 NAME
53
54pod2usage - print usage messages from embedded pod docs in files
55
56=head1 SYNOPSIS
57
58=over 12
59
60=item B<pod2usage>
61
62[B<-help>]
63[B<-man>]
64[B<-exit>S< >I<exitval>]
65[B<-output>S< >I<outfile>]
66[B<-verbose> I<level>]
67[B<-pathlist> I<dirlist>]
68I<file>
69
70=back
71
72=head1 OPTIONS AND ARGUMENTS
73
74=over 8
75
76=item B<-help>
77
78Print a brief help message and exit.
79
80=item B<-man>
81
82Print this command's manual page and exit.
83
84=item B<-exit> I<exitval>
85
86The exit status value to return.
87
88=item B<-output> I<outfile>
89
90The output file to print to. If the special names "-" or ">&1" or ">&STDOUT"
91are used then standard output is used. If ">&2" or ">&STDERR" is used then
92standard error is used.
93
94=item B<-verbose> I<level>
95
96The desired level of verbosity to use:
97
98 1 : print SYNOPSIS only
99 2 : print SYNOPSIS sections and any OPTIONS/ARGUMENTS sections
100 3 : print the entire manpage (similar to running pod2text)
101
102=item B<-pathlist> I<dirlist>
103
104Specifies one or more directories to search for the input file if it
105was not supplied with an absolute path. Each directory path in the given
106list should be separated by a ':' on Unix (';' on MSWin32 and DOS).
107
108=item I<file>
109
110The pathname of a file containing pod documentation to be output in
111usage mesage format (defaults to standard input).
112
113=back
114
115=head1 DESCRIPTION
116
117B<pod2usage> will read the given input file looking for pod
118documentation and will print the corresponding usage message.
119If no input file is specifed than standard input is read.
120
121B<pod2usage> invokes the B<pod2usage()> function in the B<Pod::Usage>
122module. Please see L<Pod::Usage/pod2usage()>.
123
124=head1 SEE ALSO
125
126L<Pod::Usage>, L<pod2text(1)>
127
128=head1 AUTHOR
129
130Brad Appleton E<lt>bradapp@enteract.comE<gt>
131
132Based on code for B<pod2text(1)> written by
133Tom Christiansen E<lt>tchrist@mox.perl.comE<gt>
134
135=cut
136
137use Pod::Usage;
138use Getopt::Long;
139
140## Define options
141my %options = ();
142my @opt_specs = (
143 "help",
144 "man",
145 "exit=i",
146 "output=s",
147 "pathlist=s",
148 "verbose=i",
149);
150
151## Parse options
152GetOptions(\%options, @opt_specs) || pod2usage(2);
153pod2usage(1) if ($options{help});
154pod2usage(VERBOSE => 2) if ($options{man});
155
156## Dont default to STDIN if connected to a terminal
157pod2usage(2) if ((@ARGV == 0) && (-t STDIN));
158
159@ARGV = ("-") unless (@ARGV > 0);
160if (@ARGV > 1) {
161 print STDERR "pod2usage: Too many filenames given\n\n";
162 pod2usage(2);
163}
164
165my %usage = ();
166$usage{-input} = shift(@ARGV);
167$usage{-exitval} = $options{"exit"} if (defined $options{"exit"});
168$usage{-output} = $options{"output"} if (defined $options{"output"});
169$usage{-verbose} = $options{"verbose"} if (defined $options{"verbose"});
170$usage{-pathlist} = $options{"pathlist"} if (defined $options{"pathlist"});
171
172pod2usage(\%usage);
173
174
175!NO!SUBS!
176
177close OUT or die "Can't close $file: $!";
178chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
179exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';