\documentstyle[a4,makeidx,verbatim,texhelp,fancyhea,mysober,mytitle]{report}%
\title{Manual for wxHelp 2.0:\\A hypertext help system for wxWindows}%
\author{Julian Smart}%
\date{February 1996}%
\parskip=10pt
\makeindex
\begin{document}%

\maketitle

\pagestyle{fancyplain}
\bibliographystyle{plain}
\pagenumbering{roman}
\setheader{{\it CONTENTS}}{}{}{}{}{{\it CONTENTS}}
\setfooter{\thepage}{}{}{}{}{\thepage}
\tableofcontents%

\chapter*{Copyright notice}
\setheader{{\it COPYRIGHT}}{}{}{}{}{{\it COPYRIGHT}}%
\setfooter{\thepage}{}{}{}{}{\thepage}

Copyright (c) 1996 Artificial Intelligence Applications Institute,
The University of Edinburgh.

Permission to use, copy, modify, and distribute this software and its
documentation for any purpose is hereby granted without fee, provided that the
above copyright notice, author statement and this permission notice appear in
all copies of this software and related documentation.

THE SOFTWARE IS PROVIDED ``AS-IS'' AND WITHOUT WARRANTY OF ANY KIND, EXPRESS,
IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

IN NO EVENT SHALL THE ARTIFICIAL INTELLIGENCE APPLICATIONS INSTITUTE OR
THE UNIVERSITY OF EDINBURGH OR ANDREW DAVISON OR JULIAN SMART BE LIABLE
FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY
KIND, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
PROFITS, WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY
THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE. 

wxHtml classes Copyright (c) Andrew Davison 1996.

\chapter{Introduction}
\pagenumbering{arabic}%
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}

\section{What is wxHelp?}

wxHelp is a help system for wxWindows programs running under X and Windows 3.
It allows the programmer to develop hypertext, browsable help which may be
invoked using the API supplied with wxWindows (see the wxWindows user manual
and {\bf wxHelpInstance} class).  Like Windows 3 help, it allows the user to
click on words and phrases to see more detail, and search for topics matching
a keyword. Unlike Windows 3 help, ASCII files may be marked up interactively
using edit mode, and the system runs under both X and Windows.

Version 2.0 of wxHelp uses HTML files instead of XLP files. It uses a special
index file, extension HTX, to allow searching on topics. HTX files can be generated
by hand, or by Tex2RTF using the htmlIndex option.

Many thanks to Andrew Davison who wrote the wxHtml classes used in wxHelp 2.

\section{How to use wxHelp}

When installing wxHelp, set the environment variable WXHELPFILES to
be the list of directories you wish wxHelp to search when loading a
file. wxHelp also searches the directories in the PATH variable.

To invoke wxHelp, start it on the command line with an optional
filename, e.g.

\begin{verbatim}
  % wxhelp -f help.html
\end{verbatim}

There is also a {\tt -server} switch for specifying the numeric identifier
used by programs connecting to wxHelp (see later).

A contents page should appear, with highlighted blocks of text, some
of which are mouseable (click with the left mouse button).  Clicking
on these takes you to other parts of the help file.

Above the main text area is a panel with buttons for commonly-used
operations, and a menu bar. When you load an HTML file, wxHelp looks for
a {\tt .htx} index file with the same root name, and loads it if found.

\section{Command buttons}

\begin{itemize}\itemsep=0pt
\item Contents -- displays the first section, normally a contents page.
\item Search -- pops up a dialog box. The user may type a string (or an asterisk)
into the text item, press {\bf Do Search}, and click one of the
matching section headings displayed in the listbox.
\item Back -- goes to the previously-visited section or block. This works across
different files, since the recorded history includes file names.
%\item \cinsert -- goes to the previous sequential section.
%\item \cextract -- goes to the next sequential section.
\end{itemize}

\section{File format}

The file format is HTML, plus an optional HTX index file.

For HTML syntax, see the sample file {\tt primer.htm}.

The HTX format is an ASCII file comprising of a number of lines
with the following syntax:

\begin{verbatim}
phrase|filename|label
\end{verbatim}

where {\tt phrase} is the indexed phrase, {\tt filename} is the HTML filename, and {\tt label} is
the HTML label to go to.

\section{Generation of wxHelp files}

The program {\bf Tex2RTF} generates {\tt .html} and {\tt .htx} files from LaTeX
documents. You can also create HTML files by hand, or using a number of tools now
available.

Tex2RTF is available at:

\begin{verbatim}
ftp.aiai.ed.ac.uk/pub/packages/tex2rtf
http://www.aiai.ed.ac.uk/~jacs/tex2rtf.html
\end{verbatim}

\chapter{Invoking wxHelp from programs}
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}

There are two main ways in which wxHelp may be used by other
applications. The simplest is via the API (Application Programmer's
Interface) included with the wxWindows system, as documented in
the reference manual under {\bf wxHelpInstance}. The other method is
to use the DDE (Dynamic Data Exchange) commands on which the API is
built. The only reason for doing this might be to access wxHelp from
non-wxWindows applications running under Windows 3.1 (such as Visual
Basic programs).

Under UNIX, the service name (the identifier for connecting to a DDE
server) is generated at random by the API and passed to wxHelp when
running it by specifying the {\tt -server} switch. This is not fool-proof
but usually doesn't result in a socket clash.

Under Windows, the service name is always assumed to be ``4000'',
since there is only ever one instance of wxHelp running under Windows
(a restriction of large model programming).

Listed below are the commands that wxHelp implements by means of a string
sent to it using the {\bf Execute} DDE command. Each string comprises an initial
command letter followed by a space, followed by an argument, for example
``f help.html''.

\begin{itemize}
\item {\bf b}\\
Display block command. The argument is interpreted as a long integer
indicating the block id at which the file is to be displayed.
\item {\bf f}\\
Load file command. The argument is interpreted as a filename, and the
current directory, WXHELPFILES variable and finally PATH variable are
searched for the file. If the file is still loaded, it is not
reloaded, so this command may be used to ensure that a subsequent
display command refers to the correct file.
\item {\bf k}\\
Keyword search command. The argument is interpreted as a string for matching
against section headings. If only one matching section is found, it is displayed,
otherwise the search dialog is shown for the user to make a selection.
\item {\bf s}\\
Display section command. The argument is interpreted as an integer
starting from 1 indicating the section number to be displayed. -1
means display from the top (by convention, the contents page).
\end{itemize}

\chapter{Problems with wxHelp}
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}

Here are some of the problems yet to be resolved.

\begin{itemize}\itemsep=0pt
\item When you click on a link that doesn't exist, wxHelp hangs.
\item Sometimes links are not sensitive.
\item Scrollbars can be incorrectly set.
\item On UNIX (Solaris 1.x and 2.x), often crashes in OnEvent when clicking on
a link. Needs a bit
of work...
\end{itemize}

\end{document}
