htmlhelp.pm

ARM上的如果你对底层感兴趣

#####################################################################
# Library       HtmlHelp.pm
# Title         HtmlHelp.pm
# Version       1.0.1
# Orig Date     5/27/98
# Release Date  9/16/98
# Author        David Grove (pete) [[e-mail]]
# Company       ActiveState Tool Corp. -
#                   Professional Tools for Perl Developers
#####################################################################
# Description   Miscelaneous routines for working with Microsoft's
#               HtmlHelp system.
#####################################################################
# REVISION HISTORY
#
# 1.0.0         First final release, went out with 502
# 1.0.1         Temporary, removed CSS insertion in favor of just
#               adding a link to the css, since it's being built
#               on the user's machine now; and temporarily added
#               the hardcoded contents of the main toc to the
#               built toc until I have time to build it codewise.

=head1 TITLE

HtmlHelp.pm

=head1 SYNOPSIS

Routines to create HtmlHelp from HTML or POD source (including the
pod in PM library files) using Microsoft's HtmlHelp compiler. This
creates the intermediate project files and from those creates the
htmlhelp windows 32-bit help files.

Along with this libaray comes a set of programs that can be used
either as-is or as examples for perl development. Each of the public
functions in this libray is represented by one such script.

=head1 USAGE

There are two "builds" of perl help, the core build (build for core
Perl and it's packages), and the packages build (build from a devel
directory of directories which contain blib directories to draw
upon). These are run by different people on different machines at
different times in different situations, so they are mostly separate
until the time comes within this module to actuall build the helpfiles.
There is also a build (html index) that works on the user's computer
after installing a new module.

For the core build

   perl makehelp.pl

for the package build

   perl makepackages.pl

for the html index build

   perl makehtmlindex.pl

The functions in this module can also be called programmatically

=head1 FUNCTIONS

The individual functions that were designed with working with
html help files rather than the Perl htmlhelp documentation are
deprecated in favor of doing things with a single command. Some
of them need work in order to work again.

=over 4

=item MakeHelp

Turns a single html page into htmlhelp document.

=item MakeHelpFromDir

Turns a directory's worth of html pages into a single htmlhelp document.

=item MakeHelpFromTree

Turns a tree's worth of html pages into a single htmlhelp document.

=item MakeHelpFromHash

Creates an htmlhelp document where the labels on the folders are passed
into the program. Useful for labels like Tk::Whatsis::Gizmo to replace
the default ones looking like c:\perl\lib\site\Tk\Whatsis\Gizmo.

=item MakeHelpFromPod

Turns a single pod or pm document into htmlhelp document.

=item MakeHelpFromPodDir

Turns a dir's worth of pod or pm into a single htmlhelp document.

=item MakeHelpFromPodTree

Turns a tree's worth of pod or pm into a single htmlhelp document.

=item MakeHelpFromPodHash

Like MaheHelpFromHash() but for pod instead of html.

=item MakePerlHtmlIndex

Creates an HTML version of an index or TOC for perl help.

=item MakePerlHtml

Does everything for perl HTML works.

=back

=head1 CONFIG.PM

This library makes use of Config.pm to know where to get its stuff.

=head1 HHC.EXE

This library makes use of the HtmlHelp compiler by microsoft.

=head1 VARIABLES

=over4

=item $HtmlHelp::CSS

Determines the stylesheet to be used for the htmlhelp files. Default
is the ActiveState common stylesheet. This variable can be set to
an empty string to allow for just plain old HTML with nothing fancy.

Default is perl.css.

=item $HtmlHelp::COMPILER

Complete path and file name of the HtmlHelp compiler from Microsoft.
This is REQUIRED for this library to run. It defaults to it's install
directory within <lib>/HtmlHelp. Feel free to move this in $COMPILER
if you have the HtmlHelp workshop from Microsoft and you want to
use the compiler from a different location.

=item $HtmlHelp::FULLTEXTSEARCH

Whether to create full text search. Defaults to true.

=item $HtmlHelp::CLEANUP

Whether to clean up temporary files (and html files if building
from raw pod) after building the htmlhelp. This can be useful,
for example, when you need to keep the intermediate files created
by the process for inclusion into a collective help file.

=back

=head1 TARGET AUDIENCE

Mostly this module is created for internal use for ActiveState Tool
Corp., but since it is a part of the standard distrib for Win32 Perl
then I expect it to be used or tried by the general public. However,
no support for this module is available for the public; and it may
be changed at any time.

=head1 INSTALLATION

First of all, this is designed for use with the Perl Resource
Kit. Use with other versions of perl should be considered
unsupported. Perl should be fully installed and configured to
use this thing

Next, Config.pm must be fully configured. Using Config.pm allows
me to program remotely for tools at ActiveState corporate office.
There were some early problems with Config.pm with the PRK and
build 500 of Perl for Win32. These need to be corrected to use
this library.

Perl needs to have $Config{privliv}\..\Html and also
$Config{privlib}\..\HtmlHelp to use this library. These should be
created before doing anything. Copy the html files and gif
files from this library to the Html directory. All other
files will be created during run.

Finally, copy all the files to $Config{privlib}\HtmlHelp, and the
file HtmlHelp.pm to $Config{privlib}. The former is the normal site
for the htmlhelp compiler (hhc.exe), and it is expected there.

To use this tool, you need to have the compiler's dll's installed
on your system. You should install the htmlhelp workshop from
microsoft for these. Otherwise you should get these dll's from
someone who has them. I think there's only one or two.

=head1 USAGE

=head2 Building HtmlHelp

Building HtmlHelp for main perl is done using the script
makehelp.pl. It requires no command line arguments because it
gets all its information from Config.pm.

Individual files are created as follows:

=over4

=item file2hhelp.pl for .html to .chm

=item dir2hhelp.pl for dir of .html to .chm

=item tree2hhelp.pl for tree of .html to .chm(s)

=item pod2hhelp.pl for .pod or .pm to .chm

=item podd2hhelp.pl for dir of .pod or .pm to .chm

=item podt2hhelp.pl for tree of .pod or .pm to .chm(s)

=back

If your forget the command line arguments for one of the
above, type:

  perl <scriptfile>

and it will tell you what command line arguments are needed.

=head2 Building HTML

Building HTML for main perl is doine using the script
makehtml.pl. It requires no command line arguemtns because it
gets all its information from Config.pm.

Individual html files can be built using the normal pod2html
script by Tom Christiansen. Building html from directories
and trees is not otherwise supported.

=head1 AUTHOR

David (pete) Grove
email: [e-mail]

=head1 FIRM

ActiveState Tool Corp.
Professional Tools for Perl Programmers

=cut

#####################################################################
package HtmlHelp;

#####################################################################
use Pod::WinHtml;               # My hack of TC's Pod::Html
use Config;
use File::Copy;
use File::Basename;

#####################################################################
# Variables
my $CLEANUP = 1;
my $MAKE_HTML_FOR_HHELP = 0;
my $FULLTEXTSEARCH = 1;
my $LIB = $Config{'privlib'};
my $SITELIB = $Config{'sitelib'};
my $HTMLHELP = $LIB; $HTMLHELP =~ s/(\\|\/)lib/\\HtmlHelp/i;
my $COMPILER = "$LIB/HtmlHelp/hhc.exe";
my $HTML = $LIB; $HTML =~ s/(\\|\/)lib/\\Html/i;
my $TEMP = "$HTMLHELP/Temp";
my $MERGE_PACKAGES = 0;

#####################################################################
# Function PreDeclarations
sub RunCompiler;
sub MakeHelpFromPod;
sub MakeHelpFromPodDir;
sub MakeHelpFromDir;
sub MakePerlHtml;
sub MakePerlHtmlIndexCaller;
sub MakePerlHtmlIndex;
sub GetHtmlFilesFromTree;
sub MakePerlHelp;
sub MakePerlHelpMain;
sub MakeHelpFromPodTree;
sub MakeHtmlTree;
sub MakeHelpFromTree;
sub GetHtmlFileTreeList;
sub MakeHelpFromHash;
sub MakeModuleTreeHelp;
sub MakeHelp;
sub BackSlash;
sub ExtractFileName;
sub ExtractFilePath;
sub MakePackageMainFromSingleDir;
sub MakePackageMain;
sub MakePackages;
sub CopyDirStructure;
sub GetFileListForPackage;
sub CreateHHP;
sub CreateHHC;
sub CreateHHCFromHash;
sub InsertMainToc_Temporary;

#####################################################################
# FUNCTION      RunCompiler
# RECEIVES      Project file to compile
# RETURNS       None
# SETS          None
# EXPECTS       $COMPILER, hhc and hhp files should be there
# PURPOSE       Runs the HtmlHelp compiler to create a chm file
sub RunCompiler {
    my $projfile = BackSlash(shift);
    my $compiler = BackSlash($COMPILER);

    print "Trying \"$compiler $projfile\"\n";
    qx($compiler $projfile);
}

#####################################################################
# FUNCTION      MakeHelpFromPod
# RECEIVES      Helpfile (no path), Working directory, Output
#               directory (path for chm file), Files to include
# RETURNS       Results from running MakeHelp
# SETS          None
# EXPECTS       None
# PURPOSE       Takes pod/pm files, turns them into html, and then
#               into Htmlhelp files.
sub MakeHelpFromPod {
    my ($helpfile, $workdir, $outdir, @podfiles) = @_;
    my $htmlfiles;
    my $htmlfile;
    my $podfile;

    foreach $podfile (@podfiles) {
        $htmlfile = $podfile;
        $htmlfile =~ s/([^\\\/]*)\....?$/$1\.html/;
        $htmlfile = "$htmlfile";
        push(@htmlfiles, $htmlfile);
        pod2html("--infile=$podfile", "--outfile=$htmlfile");
    }

    @htmlfiles = grep{-e $_} @htmlfiles;

    unless(@htmlfiles) {
        $! = "No html files were created";
        return 0;
    }

    return MakeHelp($helpfile, $workdir, $outdir, @htmlfiles);
}

#####################################################################
# FUNCTION      MakeHelpFromPodDir
# RECEIVES      Helpfile (no extension), Working directory, Output
#               directory (for the Helpfile), Directory to translate
# RETURNS       1|0
# SETS          None
# EXPECTS       None
# PURPOSE       Takes a directory's worth of pod/pm files and turns
#               them into html and then a single chm file
sub MakeHelpFromPodDir {
    my ($helpfile, $workdir, $outdir, $fromdir) = @_;
    my @podfiles;
    my $htmlfile;
    my @htmlfiles;