Online-Publishing of Windows Help files

Overview

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.

Benefits

Why would you want to publish windows help files online?

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 environment.

Note that "publishing" a help file generally means you need to have permissions from the copyright-owner of the help file to do so.

Online-Module

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 up-to-date.
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 winhelpcgi

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 server

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 the winhelpcgi.cgi program. To ask the apache web server to run the CGI program, add a file called .htaccess to the directory containing winhelpcgi.cgi. This file should have the following contents.

# Allow execution of CGI programs in the directory containing .htaccess (and it's subdirectories)
Options +ExecCGI

# Trigger CGI execution based on filename-extension ".cgi"
AddHandler cgi-script .cgi

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:

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 be started.

Customizing HTML output

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 This link points to an external server

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 scripts

winhelpcgi.cgi searches 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:

helpfiles/example/example.hlp.en.sed
helpfiles/example/example.hlp.sed
winhelpcgi.cgi.en.sed
winhelpcgi.cgi.sed

As soon as one of those file exists, it is used as a sed script. The following is an example;

Example: Referencing 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
/^<head>/ a\
<link rel="SHORTCUT ICON" href="/favicon.ico">\
<link rel="stylesheet" href="/css.css">

Note that winhelpcgi always places <head> and <body> in the beginning of a line.

Example: Setting the background color

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 parameters.

# Remove background color setting from the <body...> tag
s/^<body[^>]*>/<body>/

Example: Modifying 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
s/Windows/Window\$/g
s/Microsoft/Micro\$oft/g

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 requiring 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
s,<a href="mailto:[^"]*">\(.*\)</a>,\1,

# Next make strings of the type alpha@alpha.alpha mailto links
s,\([[:alnum:]][[:alnum:]]*@[[:alnum:]][[:alnum:]][[:alnum:].]*[[:alnum:]][[:alnum:]]\),<a href="mailto:\1">\1</a>,g

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

# First remove all existing links
s,<a href="http://[^"]*">\(.*\)</a>,\1,

# Next make strings of the type http://alpha mailto links
s,\(>[^<]*\)\(http://[[:alnum:]./?%]*\),\1<a href="\2">\2</a>,g

As you can see, sed is extremely powerful to implement most modifications you might think of.

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
Redirect seeother /ti/winhelpcgi/winhelpcgi.cgi/helpfiles/german/davinci4.hlp/png/bm1.png http://www.herdsoft.com/img/logo.png

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.

Non-Root environments

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.

Preparing libwmf

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 script:

./configure \
  --prefix=/tmp \
  --with-expat --without-x --without-jpeg \
  --with-gsfontmap="/usr/share/ghostscript/7.05/lib/Fontmap.GS" \
  --with-gsfonts="/usr/share/ghostscript/fonts" \
  --with-fontdir="fonts"

make

The resulting files libwmf.a and libwmflite.a will now be able to find their fonts in the local fonts subdirectory.

Compiling a shared binary

To create a version of winhelpcgi.cgi that does not depend on unneccessary files, it is easiest to call make with the special parameter AM_CFLAGS="-s -static" when comping winhelpcgi.cgi. This will usually work;

cd winhelpcgi*
./configure
make AM_CFLAGS="-g -static"

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:

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

Search integration

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 --addhlptitle.