site/docs/makedocs

   1 #!perl -w
   2 # Build HTML files from .pod and .pm files
   3 # I'd love to do this as a makefile, but the targets have colons, which
   4 # make hates (GNU make, anyway)
   5 use strict;
   6
   7 my @targets =
   8   (
   9    'access.html',
  10    'Article.html',
  11    'bse.html',
  12    'BSE::TB::SiteCommon.html',
  13    'BSE::TB::TagOwner.html',
  14    'bugs.html',
  15    'templates.html',
  16    'Generate.html',
  17    'Generate::Article.html',
  18    'Generate::Product.html',
  19    'Generate::Catalog.html',
  20    'Squirrel::Template.html',
  21    'search.html',
  22    'shop.html',
  23    'add.html',
  24    'shopadmin.html',
  25    'TODO.html',
  26    'config.html',
  27    'dynamic.html',
  28    'secure.html',
  29    'gen.html',
  30    'upgrade_mysql.html',
  31    'makedocs.html',
  32    'standard.html',
  33    'affiliate.html',
  34    'BSE::UI::Affiliate.html',
  35    'future_plans.html',
  36    'thumbnails.html',
  37    'formmail.html',
  38    'userupdate.html',
  39    'siteusers.html',
  40    'storages.html',
  41   );
  42
  43 my @exts = qw(.pod .pm .pl);
  44 push(@exts, ''); # I should have put a .pl on makedocs
  45
  46 my @search =
  47   (
  48    './',
  49    '../cgi-bin/',
  50    '../cgi-bin/modules/',
  51    '../cgi-bin/admin/',
  52    '../util/',
  53   );
  54
  55 use Getopt::Std;
  56 my %opts;
  57 getopts("hn", \%opts);
  58 $opts{h} and usage();
  59 ++$|;
  60 for my $target (@targets) {
  61   # try to find the source
  62   my $base = $target;
  63   $base =~ s!::!/!g;
  64   my $source;
  65  SEARCH: for my $ext (@exts) {
  66     (my $file = $base) =~ s/\.html$/$ext/;
  67     for my $dir (@search) {
  68       if (-e $dir.$file) {
  69         $source = $dir.$file;
  70         last SEARCH;
  71       }
  72     }
  73   }
  74   $source or die "Cannot find source for $target\n";
  75   if (!-e $target || -M $target > -M $source) {
  76     my $cmd = "pod2html --infile=$source --outfile=$target --htmlroot=.";
  77     $cmd .= " --podpath=".join(":", @search);
  78     print $cmd,"\n";
  79     if (!$opts{n} and system $cmd) {
  80         die "** makedocs failed\n";
  81     }
  82   }
  83 }
  84
  85 # remove the pod2html caches - I don't care much if this fails
  86 unlink 'pod2html-dircache', 'pod2html-itemcache';
  87
  88 sub usage {
  89   print <<EOS;
  90 Usage: $0      - make the documentation files
  91        $0 -n   - report what would be done to make the documentation files
  92        $0 -h   - produce this message
  93 EOS
  94   exit;
  95 }
  96
  97 __END__
  98
  99 =head1 NAME
 100
 101 makedocs - produces HTML documentation from POD for BSE
 102
 103 =head1 SYNOPSIS
 104
 105   perl makedocs [-nh]
 106
 107 =head1 DESCRIPTION
 108
 109 Used during the BSE distribution build process to product HTML
 110 versions of the POD documentation included with various parts of BSE.
 111
 112 Searches in various standard places for source pod/pl/pm files and
 113 converts them into HTML.
 114
 115 =head1 OPTIONS
 116
 117 C<makedocs> is typically run without options.
 118
 119 =over
 120
 121 =item -n
 122
 123 Report the actions that would be taken without actually performing the
 124 conversions.
 125
 126 =item -h
 127
 128 Produces a brief usage message.
 129
 130 =back
 131
 132 =head1 BUGS
 133
 134 We're keeping a dependency list in this file, it should be elsewhere,
 135 maybe we could parse MANIFEST.
 136
 137 =head1 AUTHOR
 138
 139 Tony Cook <tony@develop-help.com>
 140
 141 =head1 REVISION
 142
 143 $Revision$
 144
 145 =head1 SEE ALSO
 146
 147 bse
 148
 149 =cut
 150