comment on

######################################################################
+####
# HelpDocupdate.pl                                                    
+   #
#                                                                     
+   #
# Update the new style Windows Help that is distributed with ActiverPe
+rl #
#                                                                     
+   #
# Requires: Windows, MS HTML Help WorkShop, ActivePerl build 630 or   
+   #
# higher                                                              
+   #
#                                                                     
+   #
# Author: Simon Flack, perl@simonflack.com                            
+   #
# Version: 0.1      21 December 2001                                  
+   #
######################################################################
+####

use strict;
use File::Find;
use Config;

my $HTML_Compiler = Win32::GetShortPathName('c:\Program Files\HTML Hel
+p Workshop\HHC.EXE');
my $OutFilenames = "ActivePerl";

#----------------------------------------------------------
# Main 
#----------------------------------------------------------

my @perl_help_files;
my %perl_help_docs;
my $perl_prefix = $Config{installprefix};

# Find all the Activeperl html files...
find(\&AddHTMLFiles, $Config{installhtmldir});

# Write the Help Project File
MakeHHP("$Config{installhtmldir}/$OutFilenames.hhp", @perl_help_files)
+;

# Write the Table of Contents
MakeHHC("$Config{installhtmldir}/$OutFilenames.hhc", \%perl_help_docs)
+;

# Compile the project
MakeHelp("$Config{installhtmldir}/$OutFilenames.hhp");


#----------------------------------------------------------
# Subroutines
#----------------------------------------------------------


sub AddHTMLFiles
{
    # This is the File::Find callback.
    # Adds to an array of files, and builds a hash for the module docs

    next unless $File::Find::name =~ /\.html?$/i;
    (my $file = $File::Find::name) =~ s[/][\\]g;
    
    push @perl_help_files, $file;
    
#return unless it's @INC (lib, site\lib, etc)
    $file =~ s#^\Q$Config{installhtmldir}\E\\?##;
    return unless $file =~ /^(lib\\site|lib|site\\lib)\\(.*)/i;
    my $module_doc_path = $2 or return;

    my $module_root = $1;

    my @module_doc_path_split = split /\\/, "modules\\$module_doc_path
+";
    shift @module_doc_path_split;
    
    PopulateHashTree(\%perl_help_docs, $module_root, @module_doc_path_
+split);
}

sub PopulateHashTree
{

    my ($hash_ref, $mod_root, @path) = @_;

    # This is really dirty, will fix...
    # Just populates a hash, it should be a recursive func probably.


    my $dirty_eval = '%{$hash_ref}';

    my $page = $path[-1];
    my $full_path = join '\\', $Config{installhtmldir}, $mod_root, @pa
+th;

    $path[-1] =~ s[\.html?$][]i;

    $dirty_eval .= qq[->{'$_'}] foreach @path;
    $dirty_eval .= qq[ = '$full_path'];

    eval $dirty_eval;
}

sub MakeHelp
{
    my $project_file = shift;
    print "Writing Help File... $perl_prefix\\Docs\\$OutFilenames.chm.
+..\n";
    system ($HTML_Compiler, $project_file) == 0 or die "There were err
+ors compiling the Help file";
}

sub MakeHHP
{
    # Generate the Help Project File
    my ($output_file, @doc_files) = @_;

    print "Writing Project File: $output_file...\n";

    my $hhp = <<EOT;
[OPTIONS]
Auto Index=Yes
Compatibility=1.1 or later
Compiled file=$perl_prefix\\Docs\\$OutFilenames.chm
Contents file=$Config{installhtmldir}\\$OutFilenames.hhc
Display compile progress=No
Full-text search=Yes
Language=0x809 English (United Kingdom)
Title=ActivePerl Documentation
Default topic=$Config{installhtmldir}\\perlmain.html


[FILES]
EOT

    foreach (@doc_files)
    {
        $hhp .= $_ . "\n";
    }

    open HPP, ">",  $output_file or die "can't write Project file";
    print HPP $hhp;
    close HPP;
}


sub MakeHHC
{

    my ($hhc_file, $perl_docs) = @_;
    
    print "Building Table of Contents: $hhc_file...\n";

    ###########################################################
    # ActiveState Documentation
    ###########################################################

    my $contents =  <<EOT;
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<HTML>
<HEAD>
<meta name="GENERATOR" content="Microsoft&reg; HTML Help Workshop 4.1"
+>
<!-- Sitemap 1.0 -->
</HEAD><BODY>
<UL>
<UL>
EOT

    # Now do the Active Perl Specific contents...

    $contents .= 
    help_folder("ActivePerl Documentation", "",  
        help_folder("Welcome to ActivePerl", "$Config{installhtmldir}\
+\perlmain.html", 
            help_topic("Release Notes", "$Config{installhtmldir}\\RELE
+ASE.html"),
            help_topic("Readme", "$Config{installhtmldir}\\readme.html
+"),
            help_topic("ActivePerl Change Log", "$Config{installhtmldi
+r}\\CHANGES.html"),
            help_topic("Copyright Information", "$Config{installhtmldi
+r}\\copyright.html"),
        ),
        help_topic("ASPN Perl", "$Config{installhtmldir}\\ASPNPerl\\AS
+PNPerl.html"),
        help_folder("Install Notes", "", 
            help_topic("Linux", "$Config{installhtmldir}\\faq\\Linux\\
+Install.html"),
            help_topic("Solaris", "$Config{installhtmldir}\\faq\\Solar
+is\\Install.html"),
            help_topic("Windows", "$Config{installhtmldir}\\faq\\Windo
+ws\\Install.html"),
        ),
        help_folder("ActivePerl Components", "", 
            help_topic("Overview", "$Config{installhtmldir}\\Component
+s\\Descriptions.html"),
            help_topic("Using PPM", "$Config{installhtmldir}\\faq\\Act
+ivePerl-faq2.html"),
            help_folder("Windows Specifics", "", 
                help_topic("Browser", "$Config{installhtmldir}\\site\\
+lib\\Win32\\OLE\\Browser\\Browser.html"),
                help_topic("PerlScript", "$Config{installhtmldir}\\Com
+ponents\\Windows\\PerlScript.html"),
                help_topic("PerlScript Examples", "$perl_prefix\\eg\\I
+EExamples\\index.htm"),
                help_topic("Perl for ISAPI", "$Config{installhtmldir}\
+\Components\\Windows\\PerlISAPI.html"),
                help_topic("PerlEz", "$Config{installhtmldir}\\lib\\si
+te\\Pod\\PerlEz.html"),
            ),
        ),
        help_folder("ActivePerl FAQ", "",
            help_topic("Introduction", "$Config{installhtmldir}\\faq\\
+ActivePerl-faq.html"),
            help_topic("Availability &amp; Install", "$Config{installh
+tmldir}\\faq\\Windows\\ActivePerl-Winfaq1.html"),
            help_topic("Using PPM", "$Config{installhtmldir}\\faq\\Act
+ivePerl-faq2.html"),
            help_topic("Docs &amp; Support", "$Config{installhtmldir}\
+\faq\\ActivePerl-faq3.html"),
            help_topic("Bundled Modules", "$Config{installhtmldir}\\fa
+q\\Modules-faq.html"),
            help_folder("Windows Specifics", "", 
                help_topic("Perl for ISAPI", "$Config{installhtmldir}\
+\faq\\Windows\\ActivePerl-Winfaq2.html"),
                help_topic("Windows 9x/Nt/2000", "$Config{installhtmld
+ir}\\faq\\Windows\\ActivePerl-Winfaq4.html"),
                help_topic("Quirks", "$Config{installhtmldir}\\faq\\Wi
+ndows\\ActivePerl-Winfaq5.html"),
                help_topic("Web Server Config", "$Config{installhtmldi
+r}\\faq\\Windows\\ActivePerl-Winfaq6.html"),
                help_topic("Web Programming", "$Config{installhtmldir}
+\\faq\\Windows\\ActivePerl-Winfaq7.html"),
                help_topic("Programming", "$Config{installhtmldir}\\fa
+q\\Windows\\ActivePerl-Winfaq8.html"),
                help_topic("Modules &amp; Samples", "$Config{installht
+mldir}\\faq\\Windows\\ActivePerl-Winfaq9.html"),
                help_topic("Embedding &amp; Extending", "$Config{insta
+llhtmldir}\\faq\\Windows\\ActivePerl-Winfaq10.html"),
                help_topic("Using OLE with Perl", "$Config{installhtml
+dir}\\faq\\Windows\\ActivePerl-Winfaq12.html"),
            ),
        ),
        help_folder("Windows Scripting", "", 
            help_topic("Active Server Pages", "$Config{installhtmldir}
+\\Windows\\ActiveServerPages.html"),
            help_topic("Windows Script Host", "$Config{installhtmldir}
+\\Windows\\WindowsScriptHost.html"),
            help_topic("Windows Script Components", "$Config{installht
+mldir}\\Windows\\WindowsScriptComponents.html"),
        ),
    ) . 
    "</UL>";


    ###########################################################
    # Core Documentation
    ###########################################################

    my @core;

    foreach (sort keys %{$perl_docs->{Pod}}) {
        next if ref ($perl_docs->{Pod}->{$_});
        next unless $_ =~ /^perl/;
        push @core, help_topic($_, "$perl_docs->{Pod}->{$_}");
    }

    $contents .= help_folder("Core Perl Documentation", "", @core);

    ###########################################################
    # Pragmas Documentation
    ###########################################################

    my @pragmas;

    foreach (sort keys %$perl_docs) {
        next if ref ($perl_docs->{$_});
        next if $_ =~ /^[A-Z]/;
        push @pragmas, help_topic ($_, "$perl_docs->{$_}");
    }

    $contents .= help_folder("Pragmas", "", @pragmas);

    ###########################################################
    # Module Documentation
    ###########################################################


    $contents .= help_folder("Modules", "", GenerateModuleDocs($perl_d
+ocs, '\\') );

    $contents .= "</BODY></HEAD></HTML>";

    open HHC, ">",  $hhc_file or die "can't write Contents file";
    print HHC $contents;
    close HHC;

    return;
}


sub help_topic
{
    # Returns the Markup for a help topic
    # Used in the HHC (contents) file
    my ($name, $url) = @_;
    return <<HELP_TOPIC;
    <LI> <OBJECT type="text/sitemap">
        <param name="Name" value="$name">
        <param name="Local" value="$url">
    </OBJECT>

HELP_TOPIC

}

sub help_folder
{
    # Returns the Markup for an expandable help folder. Can contain fo
+lders and topics, etc...
    # Used in the HHC (contents) file
    my ($name, $url, @contents) = @_;
    my $url_ref =     qq[ <param name="Local" value="$url">  \n] if $u
+rl;
    return <<HELP_FOLDER;
    <LI> <OBJECT type="text/sitemap">
        <param name="Name" value="$name">
        $url_ref
        <param name="ImageNumber" value="1">
        </OBJECT>
        <UL>
            @contents
        </UL>
HELP_FOLDER

}


sub GenerateModuleDocs
{
    # recursive subroutine. Builds up the module documentation.
    my ($module_branch, $path) = @_;

    my $module_topics;     # maintain a list of modules

    foreach my $module (sort keys %{$module_branch})
    {
        if (ref ($module_branch->{$module}) )
        {
            # It's a module with sub-classes, recurse
            $module_topics .= help_folder( $module, "", GenerateModule
+Docs($module_branch->{$module}, $module . '\\') )
        } else {
            # There are no sublclasses, just add topic
            next if $path =~ /^\\$/ && $module =~ /^[a-z]/;
            next if $path =~ /^\\Pod\\$/ && $module =~ /^perl/;
            $module_topics .= help_topic($module, $module_branch->{$mo
+dule});
        }
    }

    return $module_topics;
}
[download]
In reply to Refresh ActivePerl Documentation (New Windows Help Format) by $code or die
Are you posting in the right place? Check out Where do I post X? to know for sure.
Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
<code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>
Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
Want more info? How to link or How to display code and escape characters are good places to start.

There's more than one way to do things
	PerlMonks