| 1 | #!/import/archperf/ws/devtools/4/v9/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 | |