bin/pod2usage

   1 #!/usr/bin/perl
   2     eval 'exec perl -S $0 "$@"'
   3         if 0;
   4
   5 #############################################################################
   6 # pod2usage -- command to print usage messages from embedded pod docs
   7 #
   8 # Copyright (c) 1996-2000 by Bradford Appleton. All rights reserved.
   9 # This file is part of "PodParser". PodParser is free software;
  10 # you can redistribute it and/or modify it under the same terms
  11 # as Perl itself.
  12 #############################################################################
  13
  14 use strict;
  15 use diagnostics;
  16
  17 =head1 NAME
  18
  19 pod2usage - print usage messages from embedded pod docs in files
  20
  21 =head1 SYNOPSIS
  22
  23 =over 12
  24
  25 =item B<pod2usage>
  26
  27 [B<-help>]
  28 [B<-man>]
  29 [B<-exit>S< >I<exitval>]
  30 [B<-output>S< >I<outfile>]
  31 [B<-verbose> I<level>]
  32 [B<-pathlist> I<dirlist>]
  33 I<file>
  34
  35 =back
  36
  37 =head1 OPTIONS AND ARGUMENTS
  38
  39 =over 8
  40
  41 =item B<-help>
  42
  43 Print a brief help message and exit.
  44
  45 =item B<-man>
  46
  47 Print this command's manual page and exit.
  48
  49 =item B<-exit> I<exitval>
  50
  51 The exit status value to return.
  52
  53 =item B<-output> I<outfile>
  54
  55 The output file to print to. If the special names "-" or ">&1" or ">&STDOUT"
  56 are used then standard output is used. If ">&2" or ">&STDERR" is used then
  57 standard error is used.
  58
  59 =item B<-verbose> I<level>
  60
  61 The desired level of verbosity to use:
  62
  63     1 : print SYNOPSIS only
  64     2 : print SYNOPSIS sections and any OPTIONS/ARGUMENTS sections
  65     3 : print the entire manpage (similar to running pod2text)
  66
  67 =item B<-pathlist> I<dirlist>
  68
  69 Specifies one or more directories to search for the input file if it
  70 was not supplied with an absolute path. Each directory path in the given
  71 list should be separated by a ':' on Unix (';' on MSWin32 and DOS).
  72
  73 =item I<file>
  74
  75 The pathname of a file containing pod documentation to be output in
  76 usage mesage format (defaults to standard input).
  77
  78 =back
  79
  80 =head1 DESCRIPTION
  81
  82 B<pod2usage> will read the given input file looking for pod
  83 documentation and will print the corresponding usage message.
  84 If no input file is specifed than standard input is read.
  85
  86 B<pod2usage> invokes the B<pod2usage()> function in the B<Pod::Usage>
  87 module. Please see L<Pod::Usage/pod2usage()>.
  88
  89 =head1 SEE ALSO
  90
  91 L<Pod::Usage>, L<pod2text(1)>
  92
  93 =head1 AUTHOR
  94
  95 Please report bugs using L<http://rt.cpan.org>.
  96
  97 Brad Appleton E<lt>bradapp@enteract.comE<gt>
  98
  99 Based on code for B<pod2text(1)> written by
 100 Tom Christiansen E<lt>tchrist@mox.perl.comE<gt>
 101
 102 =cut
 103
 104 use Pod::Usage;
 105 use Getopt::Long;
 106
 107 ## Define options
 108 my %options = ();
 109 my @opt_specs = (
 110     "help",
 111     "man",
 112     "exit=i",
 113     "output=s",
 114     "pathlist=s",
 115     "verbose=i",
 116 );
 117
 118 ## Parse options
 119 GetOptions(\%options, @opt_specs)  ||  pod2usage(2);
 120 pod2usage(1)  if ($options{help});
 121 pod2usage(VERBOSE => 2)  if ($options{man});
 122
 123 ## Dont default to STDIN if connected to a terminal
 124 pod2usage(2) if ((@ARGV == 0) && (-t STDIN));
 125
 126 @ARGV = ("-")  unless (@ARGV > 0);
 127 if (@ARGV > 1) {
 128     print STDERR "pod2usage: Too many filenames given\n\n";
 129     pod2usage(2);
 130 }
 131
 132 my %usage = ();
 133 $usage{-input}    = shift(@ARGV);
 134 $usage{-exitval}  = $options{"exit"}      if (defined $options{"exit"});
 135 $usage{-output}   = $options{"output"}    if (defined $options{"output"});
 136 $usage{-verbose}  = $options{"verbose"}   if (defined $options{"verbose"});
 137 $usage{-pathlist} = $options{"pathlist"}  if (defined $options{"pathlist"});
 138
 139 pod2usage(\%usage);
 140
 141