WinhelpCGI - read windows help files from web browser

Abstract

WinhelpCGI publishes windows help files (.HLP) and Multimedia Viewer 2.0 titles (.MVB) from a web server to be readable from any web browser without requiring Windows at all.

It is especially useful to read Windows help files on linux machines.

Concept

Windows Help files (extension .hlp) are help files intented for use with Microsoft Windows 3.1, 95, 98 and NT. A somewhat limited Version of the winhelp viewer is also available for the Apple Macintosh. The file format of those files has never been officially documented by Microsoft, however some programmers found out about it. Thus commercial software is available to convert Windows help files back to source code, to printable handbooks or to HTML.

Running as CGI program on the web Server (Usually Apache), winhelpcgi performs on-the fly conversion of help topics into HTML pages readable from any web browser such as Lynx, Mozilla or Netscape. Embedded bitmap and metafile images are converted into PNG type images visible in the web browser.

WinHelpCGI is able to

display graphics as PNG links
convert WinHelp jumps to HTML links
follow the browse sequences of a file (Next/Previous buttons),
displaying a list of all topics available in a help file,
search for keywords in one help file
search for keywords in all available help files.
search for a search string in all topic titles of one help file
display help files on any machine offering an HTML browser
display an overview of all help files available including filename, title and copyright
display a lisst of all keywords defined in one help file.

News

Starting from Version 0.99 on, winhelpcgi can be used to actually publish Windows Help files on the Internet! This goal has been achieved by implementing the following enhancements:

Security issues that prevented public use in versions before 0.99 have been solved.
Support for Metafile images
Include concept for navigation has been added.
Enhanced Formatting of HTML files.
Using gettext for internationalization support (by now translated to german and english)

An online example illustrates the new possibilities.

Publishing Windows Help files

Using winhelpcgi you may publish your Windows Help file without spending any effort into file conversion. Just upload the winhelpcgi.cgi binary any the .hlp file you developed for your Windows-type application to a directory on your web server and point a link to the winhelpcgi.cgi binary, the content is available for reading without any additional work. After updating the .hlp file, just upload it to the web server and your web version will always be up-to-date.

Requirements

Web-Server with CGI-Support (usually Apache) running on a Linux, AIX, Solaris, MacOS X, OpenBSD or NetWare
libpng library Version 2
A Web browser. A current up-to-date web browser with CSS2 support give sbest results.
libwmf version 0.2.8 or newer:http://download.sourceforge.net/wvware/ (recommended, else Metafiles won't display)

Operating systems

winhelpcgi is available in source code and should compile for most unix-type operating systems. We have provided binaries created by cross-compilation for download for various operating systems:

OS	Binary-download available
GNU/Linux on i386 CPU with glibc 2.2 or newer	1.0rc2
GNU/Linux on powerpc CPU with glibc 2.2 or newer	1.0rc1
GNU/Linux on alpha CPU with glibc 2.2 or newer	no
Solaris on Sparc CPU	0.92
Solaris on Intel CPU	0.92
Novell Netware 6 on Intel/AMD CPU with Apache 2 server	0.92
MacOS X (Darwin)	1.0rc1
OpenBSD Port	http://www.freshports.org/www/winhelpcgi/

Installing

Binaries: Debian Woody

A fully preconfigured debian archive is available for download and has been tested with Debian Linux 3.0 (woody). It also includes two example .hlp files from our Windows product lines. The package automatically creates a menu item in the Debian menu. You might also use our apt-get source for really simple automatics installation.

apt-get install apache mozilla
dpkg -i libwmf*.deb winhelpcgi*.deb
mozilla http://localhost/cgi-bin/winhelpcgi.cgi

Binaries: SuSE 8.2 and SuSE 9.0

Preconfigured RPM archives for SuSE versions 8.2 and 9.0 and available for download. The packages require libwmf and apache to be installed. You can do the following:

yast2 --install apache libwmf
rpm -i winhelpcgi*.rpm
/etc/init.d/apache start
konqueror http://localhost/cgi-bin/winhelpcgi.cgi

Source code

For other Linux distributions you install the binary winhelpcgi.cgi or you can get the source code and compile it yourself. Compiling should be straightforward using the usual ./configure approach. The CGI-Program and the help files should be placed in a CGI-Enabled directory on your Apache web server.

It is recommended to install libwmf, since without it winhelpcgi will not be able to display metafile images from the .hlp file.

   tar xzf winhelpcgi*.tar.gz
   cd winhelpcgi-*
   ./configure
   make

This will result in binary winhelp/winhelpcgi.cgi and po/de.gmo being built from the source code. You have to place those binaries on your web server where they can executed as CGI-Programs. For example is /usr/lib/cgi-bin is prepared for CGI execution, you might use:

   TARGET=/usr/lib/cgi-bin
   mkdir -p $TARGET/locale/de/LC_MESSAGES
   cp winhelpcgi/winhelpcgi.cgi $TARGET
   cp po/de.gmo $TARGET/locale/de/LC_MESSAGES/winhelpcgi.mo

Adding your help files

To add your help files to winhelpcgi, just place them into a subdirectory of the directory where you copied winhelpcgi, winhelpcgi will scan all subdirectories for help files. You may also symlink files or even directories.

   TARGET=/usr/lib/cgi-bin
   mkdir $TARGET/helpfiles
   cp /somewhere/myfile.hlp $TARGET/helpfiles

Licensing

winhelpcgi is free software licensed under the GNU public license version 2. We'd be happy if noone would use this source code to produce any Windows software.

Alternatives

We know about the following alternative means of reaching similar aims:

Current versions of the free Windows emulator wine include a program called winhelp to read Windows help files the way winhelp.exe does on windows. However it does not display all help files, it seems to be limited to Windows 3.1 help files? Wine is only available for Linux on the intel platform.
You may convert your help file to source code or to a printable document using our Help to RTF utility (also available for linux).
You may convert your help file to a set of HTML files on a Windows machine and read the HTML version on linux later.

Copyright of WinHelpCGI

Redistribution of this document and the winhelpcgi is permitted under the terms of the GNU GPL (General Public License).