NAME
Pod2WinHlp - generate Windows Help and/or HTML Help from pod.
SYNOPSIS
pod2rtf perl.pod > perl.rtf
hcw perl_eg.hpjDESCRIPTION
Pod2WinHlp includes a script pod2rtf (also installed as pod2rtf.bat on Windows) that generates .rtf (topic) files from from one or more files containg POD documentation. With appropriate bits of the MS Windows Help Workshop(tm) those files may be turned into Windows help file(s) of type .hlp.
PRE REQUISITES
Perl modules
Pod::Rtf uses Brad Appleton's Pod::Parser and Pod::PlainText to parse the input pod files. Pod::Parser ships with perl 5.005_03, 5.6.0 and later versions and is also available from CPAN.
For HTML conversion you'll need a separate pod2html program and you can try either the one that comes with perl or Nick Ing-Simmons' Pod::HTML package from CPAN.
Help Compiler(s)
In order to generate the final rtf && hpj -> hlp transformation you'll need to have hcw.exe a.k.a. the "Help Workshop" that ships with Visual Studio wares such as MS Visual C++. On Windows NT 4 That might be in something like: C:\Program Files\DevStudio\VC\bin\hcw.exe, in other words a place that may not lie along your %PATH%. On Windows 3.11 the compiler was called hc31.exe, though this package was not tested with that compiler (and some quirks of how hcw handles rtf were accommodated by this translator).
Help viewer(s)
With WinHelp the operating system includes the WinHelp viewer, and every Windows user already has the WinHelp viewer installed.
HTML Help Workshop compilers
Be sure you have added hhc.exe and hha.dll to your path variable statement.
HTML Help viewer(s)
With HTML Help, the HTML Help viewer and its components are not included in Windows 95, Windows NT 4.0, or any earlier releases of Windows. (HTML Help is included with Microsoft Internet Explorer 4.0 and later releases.) I am not sure how this plays out with Windows 2000 or Millenium Edition.
The HTML Help (hh.exe) program runs whenever an end user opens a stand-alone compiled HTML help file. The program calls hhctrl.ocx and is used to open and run .chm files.
The HTML Help Run Time Components (hhrun.exe) must be redistributed with HTML Help. If you know your end user already has an installation of HTML Help, the HTML Help Update (hhupd.exe) should be redistributed.
COMPILING HELP
There is a sample .hpj file called perl_eg.hpj included in the kit. To compile help convert perlpod to perl.rtf in a directory with perl_eg.hpj then type:
hcw perl_eg.hpjat the command line. If any warnings crop up they should pertain only to unresolved cross-references (hyperlinking is not well handled yet). You can use perl_eg.hpj as a template for writing your own custom .hpj files if you would prefer.
Hopefully automatice generation of .hpj files will come with a later version of this kit. Note that it could be modelled on the index.html generator for PodtoHTML, or the perltoc document, e.g.
SEE ALSO
perlpod, for information on the pod format.
The Help that comes with Help Workshop and the HTML Help Workshop.
There do not appear to be many good references on RTF these days, though for RTF as used in .hlp files try Keith E. Bugg Building Windows Help Files R&D Books, Lawrence Kansas, (c) 1995. This latter book might be ISBN 0-87930-439-1, but it might not.
SEE ALSO
Pod::Rtf and pod2rtf do not currently handle hyperlinking very well. As part of sniffing pods in a file tree and indexing, Pod2WinHlp should eventually generate .hpj (project) and perhaps .cnt (table of contents), files automatically.
Alternatively, Pod2WinHlp may generate .html (topic), .hhc (table of contents), .hhk (index), and .hhp (project) files from one or more files containg POD documentation. With appropriate bits of the MS HTML Help Workshop(tm) those files may be turned into Windows HTML help file(s) of type .chm. (Especially since the whole .rtf -> .hlp type of help seems to be deprecated by Microsoft these days.)
AUTHOR and LICENSE
Copyright (c) 1999-2000 Peter Prymmer. All rights reserved. This package is free software you can redistribute it and/or modify it under the same terms as Perl itself.
Acknowledgements
Thanks to Nick Ing-Simmons for PodToHTML upon which much of this is based. Thanks to Brad Appleton for Pod::Parser. Thanks to Tom Christiansen for pod2text.