Re: adding pages to ActivePerl HTML documentation tree

activeperl_at_listserv.ActiveState.com:

I wrote:
>> What is the correct way to add links into perltoc.html? E.g. is
>> there a tool that builds this file, or do I just hack it with my
>> editor and/or a script?

michael higgins wrote:
>This does it:
>perl -MActivePerl::DocTools -e "ActivePerl::DocTools::WriteTOC()"

Jonathan D Johnston wrote:
> 1) Drop new HTML doc(s) in the appropriate dir(s) under Perl/html/ .
> 2) Execute the following Perl one-liner:
> perl -MActivePerl::DocTools -e "ActivePerl::DocTools::WriteTOC()"

DH wrote:
> Hi. I am PodMaster. Here's some reading material
> http://perlmonks.com/index.pl?node_id=287965
> http://perlmonks.thepen.com/287965.html

Thanks for the replies! :-)

Solution follows.

David

--
#! /usr/bin/perl -w
#######################################################################
# $Id: gen_html.pl,v 1.5 2003/09/19 01:12:33 dpchrist Exp $
#
# Perl script to generate HTML documentation for Prima 1.12 installed
# into ActivePerl 806.  Run this script from the root of your unzipped
# archive tree after you have run Prima's ms_install.pl.
#
# Copyright 2003 by David Christensen <dpchrist_at_holgerdanske.com>
#
# This program is free software; you can redistribute it and/or modify
# it under the same terms as Perl itself. 
#######################################################################
# uses:
#----------------------------------------------------------------------
use warnings;
use strict;
use ActivePerl::DocTools;
use File::Basename;
use File::Copy;
use File::Find;
use File::Spec::Functions qw( :ALL );
#######################################################################
# configuration variables -- change these to match your Perl
# installation:
#----------------------------------------------------------------------
##### root of installed Prima.pm and Prima::* modules -- note forward
##### slashes:
my $perl_site_lib = 'C:/Perl/site/lib';
##### root where Prima HTML documents should go -- note forward
##### slashes:
my $perl_html = 'C:/Perl/html/site/lib';
##### ActivePerl's table of contents file -- note forward slashes:
my $perl_html_perltoc = 'C:/Perl/html/perltoc.html';
##### full path to ActivePerl's pod2html utility -- note backslashes:
my $pod2html = 'C:\Perl\bin\pod2html.bat';
##### some .pm files don't have pod, and generate an empty HTML page.
##### script will unlink generated pages that are smaller than this
##### threshold:
my $empty_html_size = 500;
#######################################################################
# file-scope lexicals:
#----------------------------------------------------------------------
my $overwrite   = 0;
#######################################################################
# subroutines:
#----------------------------------------------------------------------
sub gen_html
{
    my $src_path = shift;
    
    my @dirs = splitdir(dirname($src_path));
    foreach my $dir (splitdir($perl_site_lib)) {
        shift @dirs if $dirs[0] eq $dir;
    }
    
    my $dest_dir = catdir($perl_html, @dirs);
    unless (-d $dest_dir) {
        mkdir $dest_dir
            or die "error making directory '$dest_dir': $!";
    }
    my $file = basename $src_path;
    $file =~ s/pm$/html/;
    my $dest_path = catfile($dest_dir, $file);
    if (-f $dest_path && $overwrite !~ /^a/) {
        print "file '$dest_path' already exists. ",
            "Overwrite (yes|all|No|exit)? ";
        $overwrite = <>;
        exit(0) if $overwrite =~ /^e/i;
        return unless $overwrite =~ /^y/i || $overwrite =~ /^a/i;
    }
    $src_path  =~ s|/|\\|og;
    $dest_path =~ s|/|\\|og;
    my $line = "$pod2html -htmlroot=file:///$perl_html "
             . "$src_path > $dest_path";
    print "$line\n";
    system $line and die "system error: $!";
    if (-s $dest_path < $empty_html_size) {
        unlink $dest_path;
    }
}
#----------------------------------------------------------------------
sub wanted
{
    return unless $_ =~ /\.pm$/;
    
    gen_html($File::Find::name);
}
#######################################################################
# main script:
#----------------------------------------------------------------------
my $prima_pm    = catfile($perl_site_lib, 'Prima.pm');
my $prima_dir   = catdir($perl_site_lib, 'Prima');
die "This script only works under Microsoft Windows"
    unless $^O =~ /MSWin32/;
die "ActivePerl not found -- install ActiveState Perl "
  . "and/or check this script's configuration variables"
    unless -d $perl_site_lib;
die "Prima modules not found -- install Prima "
  . "and/or check this script's configuration variables"
    unless -f $prima_pm
        && -d $prima_dir;
gen_html($prima_pm);
find(\&wanted, ($prima_dir));
(my $save_file = $perl_html_perltoc) =~ s|(\.html)|.sav$1|;
if (-f $save_file) {
    print "file `$save_file` already exists.  Overwrite (yes|Exit)?";
    my $answer = <>;
    exit(0) unless $answer =~ /^y/i;
}
print "copying '$perl_html_perltoc' to '$save_file'\n";
copy($perl_html_perltoc, $save_file);
print "generating new table of contents '$perl_html_perltoc'\n";
ActivePerl::DocTools::WriteTOC();
#######################################################################