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