Windows Help files
This document describes how to publish Windows Helpfiles in winhelp
format (usually having an extension of .hlp) online for use by an
intranet or by the www using a CGI-Type server extension called winhelpcgi.
Why would you want to publish windows help files online?
Note that "publishing" a help file generally means you need to have
permissions from the copyright-owner of the help file to do so.
- Application developers can document the total functionality of
the application by publishing the help file.
- When answering questions of users you may simply include a link
to the published help file in your E-Mail so users won't have to find
the explanation themselfs.
- The big amount of Informations available in your applications
online help attracts attention from users searching in online search
engines to your application.
- Users of older versions of your applications will be able to read
the documentation of the new version before buying it.
- Users of other operating systems like MacOS X, Solaris or Linux
are able to read your helpfile.
- Integrate informations from your help files with informations
from other sources in different formats into a single search
The conventional method of online publishing of help files was to
convert the .HLP file or it's source code to HTML format and publish
that copy. Our newer approach to this is to use the winhelpcgi.cgi converter
program on the webserver to make the unmodified .HLP file readable on
the browser. This has the following advantages:
- After updating your .hlp file, you just need to upload the .hlp
file and .cnt file to your webserver and the webserver is immediatly
- When doing a static conversion of the helpfile topics to HTML the
converter cannot know which topics are needed as popups, so
popup-formatting is generally bad.
- The Microsoft HTML Help Workshop we used before to do the
conversion produced HTML files of poor quality.
The basic concept of
First you need to install the winhelpcgi
application on your webserver. Depending on your access webserver you
might prefer to install one of our preconfigured packages for SuSE
linux or Debian Linux or just upload the files from the binary .tar.gz
file. You do not need to have root access to your webserver, just
uploading the files should do. But you need to have permission to use
CGI binary files.
In a second step you copy the unmodified .HLP files and .CNT files from
your help files into a directory on your webserver. Usually you'll
upload to the subdirectory helpfiles
of the directory where you installed the winhelpcgi binaries.
To access the help file, you may then enter the url of the winhelpcgi.cgi binary file in
your webserver, just as if you would like to download that binary. If
your webserver is properly configured to execute CGI programs, you'll
see the list of available helpfiles created by winhelpcgi.cgi.
Configuring the web
If you get an error message instead or the system really offers a
download of the program binary, you first need to modify your server
configuration for that directory. What exactly needs to be done depends
to some extent on the configuration used by your internet service
provider. Some providers expect binary CGI programs like winhelpcgi.cgi to be placed in
a special directory called cgi-bin.
If a directory of that name exists on your server, copy winhelpcgi.cgi there. Depending
on the configuration, cgi-bin
might be in some "unexpected" place.
In other cases, you just need to tell your webserver how to treat
CGI-Programs by changing the configuration of the directory containing
program. To ask the apache web
server to run the CGI program, add a file called .htaccess to the directory
This file should have the following contents.
# Allow execution of CGI programs in the directory containing .htaccess (and it's subdirectories)
Remember to set the file permissions for all files (including the .htaccess file) so that every
unknown user is able to read/execute the files. If you have shell
access, the right command is:
# Trigger CGI execution based on filename-extension ".cgi"
AddHandler cgi-script .cgi
chmod -R go+rX /directory/containing/winhelpcgi/
If you now try to access winhelpcgi.cgi
using your web browser and you still get an error message, you need to
contact your internet service provider to ask him to change the server
configuration to allow execution of CGI binaries.
Be sure to use a winhelpcgi.cgi
from a specialized "non-root"
download from our webserver. Other binaries - including those you
have compiled yourself on a different machine - depend on various
libraries that might not be installed on your web server so it cannot
Surely you want to adopt the HTML output from winhelpcgi to the layout
of other pages on your webserver. The method we've implemented in winhelpcgi.cgi is a
postprocessing stage using the sed
program. That means that winhelpcgi.cgi
first creates the HTML output without any consideration of your
webserver layout. Then it searches it's directories for sed scriptfiles
with informations how to postprocess your file. Sed is very powerfull
allowing complex string manipulations and copying of the contents of
other files. To configure the postprocessing, you need to write .sed scriptfiles and possibly
include files matching your needs.
Filenames of .sed
for the sed scripts in it's own directory and in the directory
congtaining the .hlp file currently displayed. It also considers the
language settings from the client. When displaying file helpfiles/example.hlp and the
user has choosen english language in his browser prferences, winhelpcgi.cgi is searching for
sed script in the following locations:
As soon as one of those file exists, it is used as a sed script. The
following is an example;
site .css files
To reference your files cascading stype sheet definitions, we need to
place some <link ...>
tag between the <head>
and the </head>
tags. So write a sed script named winhelpcgi.cgi.sed
and copy it in the directory containing winhelpcgi.cgi. We start with
the following contents:
# Refernce out style sheet and our webserver icon
Note that winhelpcgi always places <head> and <body> in the beginning
of a line.
<link rel="SHORTCUT ICON" href="/favicon.ico">\
<link rel="stylesheet" href="/css.css">
Example: Setting the
By default, winhelpcgi.cgi
defines the page to use the background color of the help file. Using
the sed script, you may now override this behaviour by modifiying the
body tag. Assuming that you have the background color defined in your
stylesheet anyway, we just make the body tag a simple tag without
# Remove background color setting from the <body...> tag
the Page Content
In this example we'll change the content of the page. We let winhelpcgi.cgi change every
occurence of "Windows" to "Window$":
# Modify the text as a simple example
Example: Make the
text "Order Form" a link
In this example we'd like to make all occurences of the Text "Order
Form" a link. However since this text might also occur in the
<head> section or other locations, we need to make sure we won't
place the link inside of another tag. So our regular expression
searches for a location that is not itself part of any tag by reqiring
that there is no < character between the string "Order Form" and the
end of the last tag preceding it.
# Make order forms alive
s,\(>[^<]*\)\(Order Form\),\1<a href="/order/">\2</a>,i
Example: Make E-Mail
addresses mailto links
The following defintions will make everything that looks like a typical
E-Mail address a mailto link.
# Make E-Mail addresses alive
# First remove all existing mailto links
# Next make strings of the type firstname.lastname@example.org mailto links
Example: Make http://
addresses to links
The following defintions will make everything that looks like a typical
E-Mail address a mailto link.
# Make http://links alive
As you can see, sed is extremely powerful to implement most
modifications you might think of.
# First remove all existing links
# Next make strings of the type http://alpha mailto links
Using http redirects
Another useful way of modifying the HTML layout are "redirects". A
redirect is a way to tell the browser to use a different page than the
one it requested. As an example we might want the browser to use a
different logo image from the one defined in the help file. Redirects
are defined in the .htaccess file of the directory containing the
requested file, in this cas in the directory containing the winhelpcgi.cgi application:
# Redirect the logo image
When the client now wants to access the bm1.png image, apache will tell
it to get http://www.herdsoft.com/img/logo.png
instead. This method can also be used to link to HTML pages.
Redirect seeother /ti/winhelpcgi/winhelpcgi.cgi/helpfiles/german/davinci4.hlp/png/bm1.png http://www.herdsoft.com/img/logo.png
If winhelpcgi.cgi is to
be used in an environment without root permissions, special
considerations have to be taken. It is best to use a "non-root" download
that we have prepared. The following instructions are to be used if you
want to compile a non-root binary from sourcecode yourself.
While you might link libwmf as static library with your compiled
application, it requires a set of files in addtion to the libwmf
program binary code. The location where those files are to be found is
stored within the compiled libwmf binary. Normal binaries from a
regular linux distribution contain filenames like/usr/share/ghostscript/7.05/lib/Fontmap.GS
which only root can modify. You need to compile a modified version of
libwmf to make it search it's font at a location a non-root user has
write permissions. This is achieved by special parameters used when
calling the configure
The resulting files libwmf.a
and libwmflite.a will now
be able to find their fonts in the local fonts subdirectory.
--with-expat --without-x --without-jpeg \
Compiling a shared
To create a version of winhelpcgi.cgi that does not depend on
unneccessary files, it is easiest to call make with the special parameter
when comping winhelpcgi.cgi.
This will usually work;
However it will also link statically against the system library glibc
which is not quite perfect since glibc might not find it's locale data,
then. So it is better to define linkage exactly:
make AM_CFLAGS="-g -static"
gcc -s -L lib -Wl,--rpath=lib -o winhelpcgi.cgi \
dib2png.o wmf2png.o wc_html.o wc_kwsrch.o winhelpcgi.o includes.o hlp2tar.o stringbuffer.o\
virtchmfs.o ../libhlpaccess/libhlpaccess.a \
-Wl,--static -lwmf -lwmflite -lfreetype -lexpat -lpng -lz -Wl,--dy -lm
Most internet search engines create an index of the files to be
searched by downloading them using the http protocol. This is true for
the public serach engines such as google, and for local search engines
such as ht://dig.
If you use a file-based search engine line we do at http://www.herdsoft.com/ then you
might want to use the --tar
functionality of winhelpcgi.cgi
to transfer HTML files very fast from the converted help file to the
search engine using a pipe in tar format. The tar format is very easy
to implement. To avoid unneccessary work for winhelpcgi.cgi, cd to the
directory containing winhelpcgi.cgi
and use the command line switches --htmlonly