Beefy Boxes and Bandwidth Generously Provided by pair Networks
Just another Perl shrine
 
PerlMonks  

Refresh ActivePerl Documentation (New Windows Help Format)

by $code or die (Deacon)
on Dec 21, 2001 at 21:31 UTC ( [id://133810]=sourcecode: print w/replies, xml ) Need Help??
Category: Win32 Stuff
Author/Contact Info Simon Flack $code or die [mailto://perl@simonflack.com]
Description:

As JMD noted in ActiveState Perl build 630, the latest versions of Active Perl no longer install the HTML document set that they used to. It is now bundled with a compiled Windows Help file that is not updated when you install a module with PPM.

There has also been discussion and criticism of this change in the ActiveState mailing lists. One solution is to install the ActivePerl HTML documents with "PPM install ActivePerl-HTML" While this restores the old functionality, one might miss the searchable index that the new help format provides.

This script combines both methods. It will update the compiled Windows Help File with the changes made to the old HTML documents.

It requires Microsoft's HTML Help Workshop, and it requires you to install ActivePerl-HTML with PPM.

Running this script should scan your ActivePerl HTML folder and create a new Windows Help file. Since the compilation of the help file takes 2-3 minutes, I have not written this as a PPM extension, but rather a standalone script to synchronise the documentation periodically.

To run the script, install ActivePerl-HTML, the MS HTML Help Workshop, and make sure that $HTML_Compiler matches the path to HHC.exe.

There are some crufty bits of code that I will remove soon, but it works.

Note: the Help compiler will report several errors. Those errors are within the html documents themselves rather than the project files we write to compile the help file. It should be safe to ignore those errors, unless you want to clean up the module documentation.

######################################################################
+####
# 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;
}
Replies are listed 'Best First'.
Re: Refresh ActivePerl Documentation (New Windows Help Format)
by Anonymous Monk on May 17, 2007 at 21:13 UTC
    very nice! i updated the "Active Perl Specific contents" for ActivePerl 5.8.8.820, see chm.kollm.org. thanks for this script! ax

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: sourcecode [id://133810]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others making s'mores by the fire in the courtyard of the Monastery: (6)
As of 2024-03-28 12:14 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found