\documentstyle[a4wide,makeidx,verbatim,texhelp,fancyhea,mysober,mytitle]{report}
\input psbox.tex
% Remove this for processing with dvi2ps instead of dvips
%\special{!/@scaleunit 1 def}
\parskip=10pt%
\title{Manual for hyText 1.0: a hypertext library for wxWindows}
\author{Julian Smart\\Artificial Intelligence Applications Institute\\
University of Edinburgh\\EH1 1HN}
\date{April 1993}%
\makeindex%
\begin{document}%
%
\maketitle
%
\pagestyle{fancyplain}
\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 hyText?}

This manual describes in detail the operation of the hyText library.
hyText is a general-purpose hypertext library capable of displaying
text with arbitrary blocks highlighted using different fonts and
colours; an example of a hyText application is wxHelp.

This document is incomplete at present, but will be expanded when time
permits. Most information is contained in the class reference section.
The best way to use this library is to play with wxHelp, browse
through the class reference (also available on-line as hytext.xlp) and
then examine the wxHelp source ({\tt wxhelp.h} and {\tt wxhelp.cc}).

\section{Description}

The hyText class library is intended for wxWindows programmers who
need hypertext functionality, that is, the ability to display text
with highlighted words and phrases, with the ability to associate
functionality with these blocks (such as viewing further information).
A high-level API (Application Programming Interface) is provided
to make these kinds of application easy to write.

wxHelp is one such application. Other possible applications include
transcript editors and text output facilities within larger programs.

The main class in this library is {\bf wxHyperTextWindow}, which is a
type of canvas handles repainting, stores text, and supplies most of
the API for manipulating hypertext files.

Before files may be displayed, the programmer must define a mapping
between the integer block types and the font and colour styles which
characterise text blocks. See the class reference for details, and {\tt wxhelp.cc} for
examples.

\section{File format}

An hyText file (usual extension {\tt .xlp}) 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 (an instance of {\bf wxHyperTextMapping}).

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.

This index is only stored and read by hyText, and must be accessed by
the application in order to allow the user to actually traverse links.

\input classes.tex
%
\helpignore{\addcontentsline{toc}{chapter}{Index}
\printindex}
\end{document}