maintenance/pod.pl

   1 #!/usr/bin/perl -w
   2 # $Id$
   3 #
   4 =head1 NAME
   5
   6 pod.pl - check the POD documentation syntax in modules and scripts
   7
   8 =head1 SYNOPSIS
   9
  10 B<pod.pl> [B<-d|--dir> path ] [B<-v|--verbose>] B<-b|--blankline>
  11     [B<-?|-h|--help>]
  12
  13 =head1 DESCRIPTION
  14
  15 Checks Plain Old Documentation (POD) with highest possible stringency
  16 in every bioperl module and script in CVS modules 'core' and 'run'.
  17
  18 Amounts to same as running
  19
  20   podchecker -warnings -warnings
  21
  22 on every file.
  23
  24 You are expected to have checked out CVS module 'bioperl_all'.
  25 Otherwise, bioperl-run module is not found.
  26
  27
  28 =head2 Results
  29
  30 The results are written into file '/tmp/bioperl_pod_check' and
  31 displayed after the run. The output is filtered not to show
  32 confirmations of correct syntax. The result file is not removed.
  33
  34 The aim is to have as few warnings, and no errors, as possible.  Links
  35 to web URLs give a warning but that seems to be spurious, so they are
  36 filtered out.  Currently there are a few cases of "multiple occurrence
  37 of link target" in several modules which are harmless.
  38
  39 =head1 SEE ALSO
  40
  41 L<podchecker>, L<Pod::Checker>
  42
  43 =cut
  44
  45 use File::Find;
  46 use Pod::Checker;
  47 use Getopt::Long;
  48 use strict;
  49
  50 sub podcheck;
  51 sub blankline;
  52
  53 #
  54 ## Directories to check
  55 #
  56 my @dirs = qw( ../Bio/ ../../bioperl-run/Bio  ../scripts ../../bioperl-run/scripts . );
  57
  58 # command line options
  59 my ($verbose, $blankline, $dir, $help) = (0, undef, undef, undef);
  60 GetOptions(
  61            'v|verbose' => \$verbose,
  62            'dir:s' => \$dir,
  63            'blankline' => \$blankline,
  64            'h|help|?' => sub{ exec('perldoc',$0); exit(0) }
  65            );
  66
  67 # setup
  68 my $tmpfile = '/tmp/bioperl_pod_check';
  69 our %POD_CHECKER_OPTIONS = ( '-warnings' => 2 );
  70 our %FIND_OPTIONS = ( wanted => \&podcheck, no_chdir => 1 );
  71
  72 # run
  73 open (F, ">$tmpfile") || die "can't open file $tmpfile: $!";
  74 $FIND_OPTIONS{wanted} = \&blankline if $blankline;
  75
  76 if ($dir) {
  77     find \%FIND_OPTIONS, $dir;
  78 } else {
  79     find \%FIND_OPTIONS, @dirs;
  80 }
  81 close F;
  82 open (F, "grep -v OK $tmpfile|") || die "can't open file $tmpfile: $!";
  83 while (<F>) { print unless /http/ and /non-escaped/ }
  84
  85
  86 # this is where the action is
  87 sub podcheck {
  88     return unless /\.PLS$/ or /\.p[ml]$/ ;
  89     return unless -e $_;
  90     print "$_\n" if $verbose;
  91     my $checker = new Pod::Checker %POD_CHECKER_OPTIONS;
  92     $checker->parse_from_file($_, \*F);
  93     print "$_\tno POD\n" if $checker->num_errors() < 0;
  94 }
  95
  96 =head1 OPTIONS
  97
  98 =over 3
  99
 100 =item B<-d | --dir> path
 101
 102 Overides the default directories to check by one directory 'path' and
 103 all its subdirectories.
 104
 105 =item B<-b | --blankline>
 106
 107 Checks POD command paragraphs (lines starting with '=' character) for
 108 preceding nonblank lines. These lines are printed out with '++'.
 109
 110 Also, if verbose is turned on, it will report on lines whitespace
 111 characters which prevent paragrafs to be recognised by older POD
 112 parsers (marked with '+'). Modern perlpod parsers (5.6.0 and later, I
 113 suppose) allow for whitespace lines surrounding command lines, but
 114 since bioperl still supports older versions, these lines should be
 115 cleaned to contain only '\n' and no space or tab characters.
 116
 117
 118 See: L<perlpodspec>
 119
 120
 121 =cut
 122
 123 sub blankline {
 124     return unless /\.PLS$/ or /\.p[ml]$/ ;
 125     return unless -e $_;
 126     my $file = $_;
 127     open (F, $_) or warn "can't open file $_: $!" && return;
 128     local $/="";
 129     while (<F>) {
 130         print "$file: +|$1|\n" if /[ \t]\n(=[a-z][^\n]+$)/m and $verbose;
 131         print "$file: ++|$1|\n" if /\w\n(=[a-z][^\n]+$)/m and $verbose;
 132         print "$file:|$1|+\n" if /(^=[a-z][^\n]+)\n[\t ]/m;
 133         #print "$file:|$1|++\n" if /(^=[^\n]+)\n\w/m;
 134     }
 135     close F;
 136 }
 137
 138 __END__
 139
 140 =item B<-v | --verbose>
 141
 142 Show the progress through files during the POD checking.
 143
 144 =item B<-? | -h  | --help>
 145
 146 This help text.
 147
 148 =back
 149
 150 =head1 FEEDBACK
 151
 152 =head2 Mailing Lists
 153
 154 User feedback is an integral part of the evolution of this and other
 155 Bioperl modules. Send your comments and suggestions preferably to
 156 the Bioperl mailing list.  Your participation is much appreciated.
 157
 158   bioperl-l@bioperl.org                  - General discussion
 159   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
 160
 161 =head2 Reporting Bugs
 162
 163 Report bugs to the Bioperl bug tracking system to help us keep track
 164 of the bugs and their resolution. Bug reports can be submitted via the
 165 web:
 166
 167   http://bugzilla.open-bio.org/
 168
 169 =head1 AUTHOR - Heikki Lehvaslaiho
 170
 171 Email heikki-at-bioperl-dot-org
 172
 173 =cut
 174
 175
 176 # find . -name '*.pm' -print | xargs  perl -e '$/=""; while (<>) {$n = $1 if /^package\s+([\w:]+)/; print "$n:|$1|"  if  /(\s\s^=[^\n]+$)/m ; }'  ;
 177
 178 # find . -name '*.pm' -print | xargs  perl -e '$/=""; while (<>) {$n = $1 if /^package\s+([\w:]+)/; print "$n:|$1|\n"  if /(^=[^\n]+\n[\t ])/m ; }'  ;