bin/podchecker

   1 #!/usr/bin/perl
   2     eval 'exec perl -S $0 "$@"'
   3         if 0;
   4 #############################################################################
   5 # podchecker -- command to invoke the podchecker function in Pod::Checker
   6 #
   7 # Copyright (c) 1998-2000 by Bradford Appleton. All rights reserved.
   8 # This file is part of "PodParser". PodParser is free software;
   9 # you can redistribute it and/or modify it under the same terms
  10 # as Perl itself.
  11 #############################################################################
  12
  13 use strict;
  14 #use diagnostics;
  15
  16 =head1 NAME
  17
  18 podchecker - check the syntax of POD format documentation files
  19
  20 =head1 SYNOPSIS
  21
  22 B<podchecker> [B<-help>] [B<-man>] [B<-(no)warnings>] [I<file>S< >...]
  23
  24 =head1 OPTIONS AND ARGUMENTS
  25
  26 =over 8
  27
  28 =item B<-help>
  29
  30 Print a brief help message and exit.
  31
  32 =item B<-man>
  33
  34 Print the manual page and exit.
  35
  36 =item B<-warnings> B<-nowarnings>
  37
  38 Turn on/off printing of warnings. Repeating B<-warnings> increases the
  39 warning level, i.e. more warnings are printed. Currently increasing to
  40 level two causes flagging of unescaped "E<lt>,E<gt>" characters.
  41
  42 =item I<file>
  43
  44 The pathname of a POD file to syntax-check (defaults to standard input).
  45
  46 =back
  47
  48 =head1 DESCRIPTION
  49
  50 B<podchecker> will read the given input files looking for POD
  51 syntax errors in the POD documentation and will print any errors
  52 it find to STDERR. At the end, it will print a status message
  53 indicating the number of errors found.
  54
  55 Directories are ignored, an appropriate warning message is printed.
  56
  57 B<podchecker> invokes the B<podchecker()> function exported by B<Pod::Checker>
  58 Please see L<Pod::Checker/podchecker()> for more details.
  59
  60 =head1 RETURN VALUE
  61
  62 B<podchecker> returns a 0 (zero) exit status if all specified
  63 POD files are ok.
  64
  65 =head1 ERRORS
  66
  67 B<podchecker> returns the exit status 1 if at least one of
  68 the given POD files has syntax errors.
  69
  70 The status 2 indicates that at least one of the specified
  71 files does not contain I<any> POD commands.
  72
  73 Status 1 overrides status 2. If you want unambigouus
  74 results, call B<podchecker> with one single argument only.
  75
  76 =head1 SEE ALSO
  77
  78 L<Pod::Parser> and L<Pod::Checker>
  79
  80 =head1 AUTHORS
  81
  82 Please report bugs using L<http://rt.cpan.org>.
  83
  84 Brad Appleton E<lt>bradapp@enteract.comE<gt>,
  85 Marek Rouchal E<lt>marekr@cpan.orgE<gt>
  86
  87 Based on code for B<Pod::Text::pod2text(1)> written by
  88 Tom Christiansen E<lt>tchrist@mox.perl.comE<gt>
  89
  90 =cut
  91
  92
  93 use Pod::Checker;
  94 use Pod::Usage;
  95 use Getopt::Long;
  96
  97 ## Define options
  98 my %options;
  99
 100 ## Parse options
 101 GetOptions(\%options, qw(help man warnings+ nowarnings))  ||  pod2usage(2);
 102 pod2usage(1)  if ($options{help});
 103 pod2usage(-verbose => 2)  if ($options{man});
 104
 105 if($options{nowarnings}) {
 106   $options{warnings} = 0;
 107 }
 108 elsif(!defined $options{warnings}) {
 109   $options{warnings} = 1; # default is warnings on
 110 }
 111
 112 ## Dont default to STDIN if connected to a terminal
 113 pod2usage(2) if ((@ARGV == 0) && (-t STDIN));
 114
 115 ## Invoke podchecker()
 116 my $status = 0;
 117 @ARGV = qw(-) unless(@ARGV);
 118 for my $podfile (@ARGV) {
 119     if($podfile eq '-') {
 120       $podfile = "<&STDIN";
 121     }
 122     elsif(-d $podfile) {
 123       warn "podchecker: Warning: Ignoring directory '$podfile'\n";
 124       next;
 125     }
 126     my $errors =
 127       podchecker($podfile, undef, '-warnings' => $options{warnings});
 128     if($errors > 0) {
 129         # errors occurred
 130         $status = 1;
 131         printf STDERR ("%s has %d pod syntax %s.\n",
 132                        $podfile, $errors,
 133                        ($errors == 1) ? "error" : "errors");
 134     }
 135     elsif($errors < 0) {
 136         # no pod found
 137         $status = 2 unless($status);
 138         print STDERR "$podfile does not contain any pod commands.\n";
 139     }
 140     else {
 141         print STDERR "$podfile pod syntax OK.\n";
 142     }
 143 }
 144 exit $status;
 145