maintenance/pod.pl

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