0.15_27 commit

[bse.git] / site / docs / makedocs

#!perl -w
# Build HTML files from .pod and .pm files
# I'd love to do this as a makefile, but the targets have colons, which
# make hates (GNU make, anyway)
use strict;

my @targets =
  (
   'access.html',
   'bse.html',
   'bugs.html',
   'templates.html',
   'Generate.html',
   'Generate::Article.html',
   'Generate::Product.html',
   'Generate::Catalog.html',
   'search.html',
   'shop.html',
   'add.html',
   'shopadmin.html',
   'TODO.html',
   'config.html',
   'secure.html',
   'gen.html',
   'upgrade_mysql.html',
   'makedocs.html',
   'standard.html',
   'affiliate.html',
   'BSE::UI::Affiliate.html',
   'future_plans.html',
   'thumbnails.html',
   'formmail.html',
  );

my @exts = qw(.pod .pm .pl);
push(@exts, ''); # I should have put a .pl on makedocs

my @search =
  (
   './',
   '../cgi-bin/',
   '../cgi-bin/modules/',
   '../cgi-bin/admin/',
   '../util/',
  );

use Getopt::Std;
my %opts;
getopts("hn", \%opts);
$opts{h} and usage();
++$|;
for my $target (@targets) {
  # try to find the source
  my $base = $target;
  $base =~ s!::!/!g;
  my $source;
 SEARCH: for my $ext (@exts) {
    (my $file = $base) =~ s/\.html$/$ext/;
    for my $dir (@search) {
      if (-e $dir.$file) {
	$source = $dir.$file;
	last SEARCH;
      }
    }
  }
  $source or die "Cannot find source for $target\n";
  if (!-e $target || -M $target > -M $source) {
    my $cmd = "pod2html --infile=$source --outfile=$target --htmlroot=.";
    $cmd .= " --podpath=".join(":", @search);
    print $cmd,"\n";
    if (!$opts{n} and system $cmd) {
	die "** makedocs failed\n";
    }
  }
}

# remove the pod2html caches - I don't care much if this fails
unlink 'pod2html-dircache', 'pod2html-itemcache';

sub usage {
  print <<EOS;
Usage: $0      - make the documentation files
       $0 -n   - report what would be done to make the documentation files
       $0 -h   - produce this message
EOS
  exit;
}

__END__

=head1 NAME

makedocs - produces HTML documentation from POD for BSE

=head1 SYNOPSIS

  perl makedocs [-nh]

=head1 DESCRIPTION

Used during the BSE distribution build process to product HTML
versions of the POD documentation included with various parts of BSE.

Searches in various standard places for source pod/pl/pm files and
converts them into HTML.

=head1 OPTIONS

C<makedocs> is typically run without options.

=over

=item -n

Report the actions that would be taken without actually performing the
conversions.

=item -h

Produces a brief usage message.

=back

=head1 BUGS

We're keeping a dependency list in this file, it should be elsewhere,
maybe we could parse MANIFEST.

=head1 AUTHOR

Tony Cook <tony@develop-help.com>

=head1 REVISION

$Revision$

=head1 SEE ALSO

bse

=cut