\documentstyle[a4,makeidx,verbatim,texhelp,fancyhea,mysober,mytitle]{report}%
\title{Manual for wxHelp 1.40:\\A hypertext help system for wxWindows}%
\author{Julian Smart}%
\date{October 1993}%
\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) 1993 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 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.

\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 3.1

\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.txt
\end{verbatim}

If you specify the -edit switch, wxHelp will start up in Edit mode.

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.

\section{Command buttons}

\begin{itemize}
\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}

\chapter{Editing}
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}

If you start wxHelp with the -edit switch you will get more
functionality and some extra menus.

You can now highlight blocks of text by dragging with the left mouse
button, and assigning new block types to them using the Blocks menu.
If you change your mind after selecting a block, deselect the block
before dragging again or you'll have two overlapping selected blocks!
Dragging is fiddly - the rectangle must be just within the block.

Select/deselect a marked block with shift left-click: it will be
marked in cyan (or inverted on a monochrome display) if selected.

Link block A to block B by selecting B, going back to A, right-clicking
on A and selecting the Link block to selection menu item. Use
this menu to unlink or clear the block.

Find out the block type and when the block is linked with CONTROL
left-click.

You can also link blocks to blocks which are in another file, after
loading a file, selecting a block, going back the previous section
(using the Back button) and linking as per usual.

The usual way to proceed is to take an ASCII file with section
headings, then mark it up.  Or you could generate the .xlp file
automatically (as with the wxWindows help file, reconstructed from the
Latex manual.)

\section{File format}

A help file consists of plain ASCII text, with blocks marked with
codes as in the following:

\begin{verbatim}
  \hy-X{Y}{Text}
\end{verbatim}

where X is the block type and Y is the block identifier (unique within
a file).  The block type indicates the style of the block (font,
colour, section), where the mapping between type and style is defined
in a table in wxhelp.cc.  See the file {\tt wxhlpblk.h} for a list
of block type constants; you may include this file into programs which
generate help files (for example).

Note that blocks may be nested, in which case any styles in an inner
block which have been the assigned `default' characteristic will
inherit the style from the outer block.

At the end of a file there is an optional index section, for example:

\begin{verbatim}
\hyindex{
"wxWindows Help"
101 102 "wx.xlp"
114 115
117 118
120 121
123 124
}
\end{verbatim}

The first line indicates the start of the index, the second line is
a title for the help file, subsequent lines (until a closing curly bracket)
indicate the link between two block identifiers, with an optional filename
after each pair of (long) integers.

\section{Generation of wxHelp files}

The program {\bf tex2help} generates {\tt .xlp} files from LaTeX
documents; in particular, it is used on {\tt classes.tex} from the
wxWindows user manual and hyText user manual. The utility makes use of
the library {\bf tex2any} which handles parsing and traversal of LaTeX
file structure, allowing the conversion utility to simply output
appropriate block information and text to files. Unfortunately I do
not have time to document these programs, but examination of the
source should give an idea of what's going on.

The file {\tt wxhlpblk.h} contains block type definitions used by
wxHelp and may be included by generators to ensure blocks of the
appropriate type are generated.

\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.xlp''.

\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}

\end{document}