%% LyX 1.1 created this file.  For more info, see http://www.lyx.org/.
%% Do not edit unless you really know what you are doing.
\documentclass[oneside,english]{book}
\usepackage[T1]{fontenc}
\usepackage[latin1]{inputenc}
\usepackage{geometry}
\geometry{verbose,letterpaper,tmargin=0.5in,bmargin=0.5in,lmargin=1.25in,rmargin=1.25in}
\usepackage{babel}
\setlength\parskip{\medskipamount}
\setlength\parindent{0pt}
\usepackage{url}

\makeatletter

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% LyX specific LaTeX commands.
\providecommand{\LyX}{L\kern-.1667em\lower.25em\hbox{Y}\kern-.125emX\@}
\newenvironment{LyXParagraphIndent}[1]%
{
  \begin{list}{}{%
    \setlength\topsep{0pt}%
    \addtolength{\leftmargin}{#1}
    \setlength\parsep{0pt plus 1pt}%
  }
  \item[]
}
{\end{list}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Textclass specific LaTeX commands.
 \newenvironment{lyxcode}
   {\begin{list}{}{
     \setlength{\rightmargin}{\leftmargin}
     \raggedright
     \setlength{\itemsep}{0pt}
     \setlength{\parsep}{0pt}
     \normalfont\ttfamily}%
    \item[]}
   {\end{list}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% User specified LaTeX commands.

\usepackage{html}

\newcommand{\doubledash}{-\hspace{0.1em}-}
\newcommand{\doubledashb}{-\/-}

\begin{htmlonly}

\renewenvironment{lyxcode}
  {\begin{list}{}{
    \setlength{\rightmargin}{\leftmargin}
    \raggedright
    \setlength{\itemsep}{0pt}
    \setlength{\parsep}{0pt}
    \ttfamily}%
   \item[] 
   \begin{ttfamily}}
   {\end{ttfamily}
    \end{list} }

\newenvironment{LyXParagraphIndent}[1]%
{\begin{quote}}
{\end{quote}}

\renewcommand{\LyX}{LyX}

\renewcommand{\doubledash}{\rawhtml &#45;&#45;\endrawhtml}
\renewcommand{\doubledashb}{\rawhtml &#45;&#45;\endrawhtml}

\end{htmlonly}

\makeatother
\begin{document}

\title{Portable Spell Checker Interface Library}


\author{Kevin Atkinson \textit{}\\
\textit{kevina at users sourceforge net}}


\date{Version 0.12.2}

\maketitle
\tableofcontents{}


\chapter{Introduction}


\section{Goal}

The goal of the library is to provide a generic interface to Spell
checker libraries installed on the system.


\chapter{Getting Started}


\section{Obtaining}

The latest version of pspell can always be found at the pspell home
page at \url{http://pspell.sourceforge.net/}


\section{Support}

Support for Pspell can be found on the Pspell mailing lists. Instructions
for joining the various mailing lists (and an archive of them) can
be found off the Pspell home page at \url{http://pspell.sourceforge.net}.


\section{Installation}


\subsection{Generic Install Instructions}

To install the library simply type

\begin{lyxcode}
./configure\\
make\\
make~install
\end{lyxcode}
Then install at least one pspell module. You can find more information
about available modules from the Pspell home page. This is all that
should be required for Pspell to function properly.

If you run into problems you can try disabling the building of shared
libraries with \doubledash{}disable-shared and/or the ltdl library which is used
for dynamically loading pspell modules with \doubledash{}disable-ltdl. If you
do so you will then need to manually link in the necessary modules
by doing the following:

\begin{lyxcode}
cd~modules\\
./add-modules\\
cd~..\\
make\\
make~install
\end{lyxcode}
However this has not been known to work properly on most platforms.
If you are just installing Pspell so that you can compile and use
the Aspell utility then you should be okay as Aspell does not need
any of Pspell modules linked in. However, if you are trying to use
Pspell with an application that actually used the Pspell library such
as PHP, AbiWord or the like then you will likely run into problems.

By default a static library is also created you can turn this of by
passing the parameter \doubledash{}disable-static to configure. You can control
what C and C++ compiler is used by setting the environmental variable
CC and CXX respectfully before running configure and you can control
what flags are passed to the C and C++ compile via the environmental
variable CFLAGS and CXXFLAGS respectfully.


\subsection{General Problems}

Aspell does not use a released version of GNU Libtool. In previous
versions of aspell this will often create problems if you inadvertently
modify a file which causes Libtool to be called. However, as of Pspell
.12.2 this so no longer be a problem and automake, autoconf, or libtool
should not be called unless you specifically call them or if you configure
Aspell with \doubledash{}enable-maintainer-mode. If you do notice any of these
programs being called (and you did not configure with \doubledash{}enable-maintainer-mode)
please let me know about it. If you have a need to modify configure.in
or any of the Makefile.am's you should install the multi-language-branch
of the CVS version of libtool.


\subsection{Problems with Libltdl}

Pspell also requires libltdl, Libtool's portable {}``dlopen{}''
wrapper library, in order to function properly. If configure does
not find libltdl installed on your system it will generally compile
it and install it with the rest of Pspell. However, this can create
problems if the compile environment is different than the environment
that Pspell runs under. For example if configure was able to find
libltdl at compile time but libltdl is no longer visible at runtime
you will run into problems. The easiest thing to do here is copy the
libltdl library found when compiling Pspell into the library directly
Pspell was installed in. Another potently source of problems is the
fact that the version of Libltdl found in the Pspell distribution
is not the same as the one found in the released version of Libtool.
In fact the two, while being source code compatible, are not binary
compatible. This should normally not be a problem because if configure
finds libltdl already installed on your system it will use that one.
However, this might cause problems if the compile environment is different
than the environment that Pspell runs under.


\subsection{Upgrading from Pspell .11.2}

\label{new_size_parm}Pspell .12 breaks binary and source code compatibility
with Pspell .11. Many of the PspellManager functions now also have
a length parameter specifying the length of the word. A length of
-1 means that the string is null terminated. This unfortunately breaks
source code compatibility. To upgrade to Pspell .12 either define
the variable USE\_ORIGINAL\_MANAGER\_FUNCS before pspell.h in included
or simply add a length of -1 after each word passed in. Please see
manager.h for the exact phototype of the functions. Defining the variable
USE\_ORIGINAL\_MANAGER\_FUNCS will allow your code to work with both
Pspell .11 and .12.


\section{Helping Out}

Right now the area I need the most help in is better shared library
support and on the ispell module. If you are interested in helping
out please contact me at kevina@users.sourceforge.net.

If you wish to work on Pspell you will need the multi-language-branch
of the CVS version of libtool. You will also need autoconf and automake.
The released version of autoconf has a small bug in it which will
cause it to think {}``.C{}'' is the extension of executables. To
fix this you need to apply the patch {}``autoconf-exeext.patch{}''
which can be found in the pspell distribution.


\chapter{Keeping in Touch}

Even though you the LGPL license gives you the right to use Pspell
in your application without ever notifying me, Kevin Atkinson, the
sole author of Pspell---please don't. If you are using, or planning
on using, Pspell in your project please at very least send me an email
at kevina at users sourceforge net. It doesn't have to me anything
fancy. A simple {}``I am planning on using Pspell in my project X.
For more information please see Y.{}'' will suffice. I will greatly
appreciate it. I put a lot of unpaid time into Pspell and Aspell and
would appreciate simply knowing where it is being used.


\chapter{Library Interface}


\section{Overview}

The Pspell library contains two main classes and several helper classes.
The two main classes are PspellConfig and PspellMaster. The PspellConfig
class is used to set initial defaults and to change spell checker
specific options. The PspellManager class does most of the real work.
It is responsible for managing the dictionaries, checking if a word
is in the dictionary, and coming up with suggestions among other things.
There are many helper classes the important ones are PspellWordList,
PspellMutableWordList, Pspell{*}Emulation. The PspellWordList classes
is used for accessing the suggestion list, as well as the personal
and suggestion word list currently in use. The PspellMutableWordList
is used to manage the personal, and perhaps other, word lists. The
Pspell{*}Emulation classes are used for iterating through a list.

A C and C++ Interface is provided. I recommend using the C interface,
even if your program is in C++, to avoid some of the nasty issues
associated with C++ linkage. In general one can only use C++ linkage
if both the library and the program were created with the same compiler.
I may eventually provide C++ wrapper classes, including a few STL
like one, for the C library and remove the existing C++ interface
all together.

The mapping between the C and C++ interface is pretty straightforward
and from C++ to C goes as follows:

\begin{quote}
<class name in lowercase with underscores>\_<method name>({[}const{]}
<Class> {*}, <other parameters if any>)
\end{quote}
For example {}``PspellManager::lang\_name() const{}'' would become
{}``pspell\_manager\_lang\_name(const PspellManager {*}){}''. 

Methods that return a bool will instead return an int in the C interface.


\section{Usage}

To use pspell your application should include {}``pspell/pspell.h{}''.
In order to insure that all the necessary libraries are linked in
libtool should be used to perform the linking. When using libtool
simply linking with {}``-lpspell{}'' should be all that is necessary.
When using shared libraries you might be able to simply link {}``-lpspell{}'',
but this is not recommended. This version of Pspell uses the CVS version
of libtool (multi-language-branch) however released versions of libtool
should also work.

When your application first starts you should get a new configuration
class with the command:

\begin{lyxcode}
PspellConfig~{*}~spell\_config~=~new\_pspell\_config();
\end{lyxcode}
which will create a new PspellConfig class. It is allocated with new
and it is your responsibility to delete it with delete\_pspell\_config.
The standard C++ delete can be used if the compiler is compatible
with the one used to create the Pspell library. Once you have the
config class you should set some variables. The most important one
is the language variable. To do so use the command:

\begin{lyxcode}
pspell\_config\_replace(spell\_config,~\char`\"{}language-tag\char`\"{},~\char`\"{}en\_US\char`\"{});
\end{lyxcode}
which will set the default language to use to American English. The
language is expected to be the standard two letter ISO 639 language
code, with an optional two letter ISO 3166 country code after an underscore.
You can set the preferred spelling via the {}``spelling{}'' option,
any extra info via the {}``jargon{}'' option, and the encoding via
the {}``encoding{}'' option. Other things you might want to set
is the preferred spell checker to use, the search path for dictionary's,
and the like see section \ref{options} for the available options.

When ever a new document is created a new PspellManager class should
also be created. There should be one manager class per document. To
create a new manager class use the new\_pspell\_manager and then cast
it up using to\_pspell\_manager like so.

\begin{lyxcode}
PspellCanHaveError~{*}~possible\_err~=~new\_pspell\_manager(spell\_config);\\
PspellManager~{*}~spell\_checker~=~0;\\
if~(pspell\_error\_number(possible\_err)~!=~0)\\
~~puts(pspell\_error\_message(possible\_err));\\
else\\
~~spell\_checker~=~to\_pspell\_manager(possible\_err);
\end{lyxcode}
which will create a new PspellManager class using the defaults found
in spell\_config. If C++ is being used AND the compiler is compatible
with the one used to create the Pspell library a normal cast can be
used instead of to\_pspell\_manager.

If for some reason you want to use different defaults simply clone
spell\_config and change the setting like so:

\begin{lyxcode}
PspellConfig~{*}~spell\_config2~=~pspell\_config\_clone(spell\_config);\\
pspell\_config\_replace(spell\_config2,~\char`\"{}language-tag\char`\"{},\char`\"{}nl\char`\"{});\\
possible\_err~=~new\_pspell\_manager(spell\_config2);\\
delete\_pspell\_config(spell\_config2);
\end{lyxcode}
Once again in C++ delete\_pspell\_config can be replaced with a simple
C++ delete. Once the manager class is created you can use the check
method to see if a word in the document is correct like so:

\begin{lyxcode}
int~correct~=~pspell\_manager\_check(spell\_checker,~<word>,~<size>);
\end{lyxcode}
<word> can is expected to a const char {*} character string. If the
encoding is set to be {}``machine unsigned 16{}'' or {}``machine
unsigned 32{}''. <word> is expected to be a cast from either const
u16int {*} or const u32int{*} respectfully. U16int and u32int are
generally unsigned short and unsigned int respectfully. <size> is
the length of the string or -1 if the sting is null terminated. If
the string is a cast from const u16int {*} or const u32int {*} then
size is the amount of space in bytes the string takes up after being
casted to const char {*} and not the true size of the string. Pspell\_manager\_check
will return 0 is it is not found and non-zero otherwise.

If the word is not correct than the suggest method can be used to
come up with likely replacements.

\begin{lyxcode}
PspellWordList~{*}~suggestions~=~pspell\_manager\_suggest(spell\_checker,~\\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<word>,~<size>);\\
PspellStringEmulation~{*}~elements~=~pspell\_word\_list\_elements(suggestions);\\
const~char~{*}~word;\\
while~(~(word~=~pspell\_string\_emulation\_next(pspell\_elements)~!=~NULL~)~\{\\
~~//~add~to~suggestion~list\\
\}\\
delete\_pspell\_string\_emulation(elements);
\end{lyxcode}
Notice how \texttt{elements} is deleted but \texttt{suggestions} is
not. The value returned by suggestions is only valid to the next call
to suggest. Once a replacement is made the store\_repl method should
be used to communicate the replacement pair back to the spell checker
(see section \ref{storerepl} for why). It usage is as follows:

\begin{lyxcode}
pspell\_manager\_store\_repl(spell\_checker,~\\
~~~~~~~~~~~~~~~~~~~~~~~~~~<misspelled~word>,~<size>,\\
~~~~~~~~~~~~~~~~~~~~~~~~~~<correctly~spelled~word>,~<size>);
\end{lyxcode}
If the user decided to add the word to the session or personal dictionary
the the word can be be added using the add\_to\_session or add\_to\_personal
methods respectfully like so:

\begin{lyxcode}
pspell\_manager\_add\_to\_session|personal(spell\_checker,~<word>,~<size>);
\end{lyxcode}
It is better to let the spell checker manage these words rather than
doing it your self so that the words have a change of appearing in
the suggestion list.

Finally, when the document is closed the PspellManager class should
be deleted like so.

\begin{lyxcode}
delete\_pspell\_manager(spell\_checker);
\end{lyxcode}
The standard C++ delete should NOT be used here because it will not
unload any shared libraries pulled in my when the manager class is
created.


\section{Class Reference}

Methods that return a bool generally return false on error and true
other wise. To find out what went wrong use the error\_number and
error\_message methods. Unless otherwise stated methods that return
a const char {*} will return null on error. The charter string returned
is only valid until the next method which returns a const char {*}
is called.

All methods are virtual and abstract, thus these classes are really
abstract base classes. Therefore you cannot simply store the object
directly. In order to make copies of the objects use the clone and
assign methods if they are provided.

For the details of the various classes please see the header files.
In the future I will generate class references using some automated
tool.


\section{Available Options\label{options}}

The following options are available to control which word list Pspell
selects.

\begin{description}
\item [language-tag~<string>]the language code which consists of the two
letter ISO 639 language code and an optional two letter ISO 3166 country
code after a dash or underscore.
\item [spelling~<string>]the requested spelling for languages with more
than one spelling such as English. Known values are {}``american{}'',
{}``britsh{}'', and {}``canadian{}''. This information is normally
inferred from the language-tag option. For example the language tag
{}``en\_GB{}'' will set spelling to {}``british{}''.
\item [jargon~<string>]an extra information to distinguish two different
words lists that have the same language-tag and spelling.
\item [word-list-path~<list>]search path for word list information files
\item [module-search-order~<list>]list of available modules, modules that
come first on this list have a higher priority
\end{description}
The following options control the behavior of the selected module.
Not all modules support all options.

\begin{description}
\item [encoding~<string>]encoding that words are expected to be in. Valid
values are {}``utf-8{}'', {}``iso8859-{*}{}'', {}``koi8-r{}'',
{}``viscii{}'', {}``cp1252{}'', {}``machine unsigned 16{}'',
{}``machine unsigned 32{}''. 
\item [ignore~<int>]ignore all words which are not at least as long as
the value for this setting
\item [personal~<file>]file name of the personal word list to use. Start
it with {}``./{}'' to look for the file in the current directory
rather than the home directory.
\item [repl~<file>]file name of the replacement word list to use. Start
it with {}``./{}'' to look for the file in the current directory
rather than the home directory.
\item [save-repl~<boolean>]save the replacement word list on calls to save\_all\_word\_lists.
\item [ignore-repl~<boolean>]ignore calls to Manager::store\_replacement.
\item [sug-mode~<string>]the suggestion mode, known values are fast, normal,
and bad-spellers
\item [run-together~<boolean>]consider run-together words as legal compounds.
\end{description}
The following options may be examined to tell exactly what word list
or module was selected

\begin{description}
\item [master]the full path of the word list selected
\item [master-flags]any special flags that were passed on to the module
\item [module]the module selected
\end{description}
The options, \textbf{spelling} and \textbf{jargon} can also be examined.

<string> options may be set to anything, including in some cases an
empty string. <int> options must be set to a valid integer string.
<boolean> options must be set to {}``true{}'' or {}``false{}''.
<list> options can not be set directly, you must use the option add-<option>
to add an item to the list, rem-<option> to remove an item, or rem-all-<option>
to remove all the items. In the case of rem-all-<option> the value
should be an empty string. Although the standard retrieve method will
work for a string, it should not be used as the format of the string
is implementation dependent. Use the retrieve\_list method instead.


\section{Format of the PWLI Files}

In order for Pspell to know which word lists to use each word list
must have at least one PWLI file in the pspell data directory which
is normally /usr/local/share/pspell/, use {}``pspell-config pkgdatadir{}''
to find out what it is on your system.

Each PWLI has the the following name:

\begin{quote}
<language>{[}-{[}<spelling>{]}{[}-<jargon>{]}{]}-<module>.pwli
\end{quote}
Where <language> is the two letter language code, <spelling> is the
particular spelling your interested in if the languages has multiple
spelling in different parts of the world such as English, <jargon>
is any extra informations to distinguish the word list from other
ones with the same language and spelling, and <module> is the pspell
module the main word list is for.

For example:

\begin{quote}
en-aspell.pwli\\
en-american-aspell.pwli\\
en-american-medical-ispell.pwli\\
en-american-xlg-ispell.pwli\\
de\doubledash{}medical-ispell.pwli
\end{quote}
Notice how if the spelling is left out but the jargon is not there
needs to be two dashes between the language and the jargon.

Each PWLI file then contains exactly one line which contains the full
path of the main word list, white space, then any additional options
to pass onto the module.


\section{Examples}

Two simple examples are included in the examples directory. Pspell
must be installed before they will compile and at least one pspell
module must be installed before they will run. To build the C example
type {}``make example-c{}'' and to build the C++ examples type {}``make
example-cxx{}''.


\section{Rational}


\subsection{store\_repl method\label{storerepl}}

This method is needed because Aspell (\url{http://aspell.sourceforge.net/})
is able to learn from users misspellings. For example on the first
pass a user misspells beginning as beging so aspell suggests:

\begin{quote}
begging, begin, being, Beijing, bagging, ....
\end{quote}
However the user then tries \char`\"{}begning\char`\"{} and aspell
suggests

\begin{quote}
beginning, beaning, begging, ... 
\end{quote}
so the user selects beginning. However than, latter on in the document
the user misspelles it as begng (NOT beging). Normally aspell will
suggest.

\begin{quote}
began, begging, begin, begun, ....
\end{quote}
However becuase it knows the user mispelled beginning as beging it
will instead suggest:

\begin{quote}
beginning, began, begging, begin, begun ...
\end{quote}
I myself often misspelled beginning (and still do) as something close
to begging and two many times wind up writing sentences such as \char`\"{}begging
with ....\char`\"{}.


\chapter{Status}


\section{Current\label{current}}

This version of Pspell is still incomplete.

The PspellMutableWordList and STL like helper classes are nonexistent
and building of the shared libraries does not work nearly as well
as it should.


\section{Future}

Future version of this library will of course be more complete.

Future versions of the interface will provide better support for multi-lingual
documents as well as methods for spell checking whole regions of text.
Letting the spell checker check whole region of text will allow the
spell checker to skip over formating commands, URLs, and the like.

I also plan on coming up with a Pspell utility that will, among other
things, function as a drop in replacement for {}``ispell -a{}''
so that Pspell can be used in place of Ispell.


\chapter{Feedback}

As always feedback is most appreciated. I can be contacted at kevina@users.sourceforge.net.


\chapter{Changelog}


\section*{Changes from .12.1 to .12.2 (May 29, 2001)}

\begin{itemize}
\item Portibility fixes to allow Pspell to compile with older compilers.
\item Added a hack to deal with Libtool's interdependencies problem. See
bug \#416981 for more info.
\item Added the configure option AM\_MAINTAINER\_MODE to avoid enableing
rules which often causes generated build files to be rebuild with
the wrong version of libtool by default. I don't know why I didn't
think to do this a long time ago.
\end{itemize}

\section*{Changes from .12 to .12.1 (April 5, 2001)}

\begin{itemize}
\item Added a hack to that Pspell will properly compile as a shared library
under Solaris.
\item Fixed a problem on Win32 which involves path names which begin with
<Drive Letter>:.
\item Removed excuse semicolon (;) after {}``\#endif{}'' in one of the
header files.
\end{itemize}

\section*{Changes from .11.2 to .12 (January 28, 2001)}

\begin{itemize}
\item Added a length parameter to many Pspell functions which should cut
down on unnecessary copying of words with some programs that use Pspell.
Unfortunately this also breaks sourcecode compatibility. But it is
easy to fix, see section \ref{new_size_parm} for what to do.
\item Added support for mapping the county code to a spelling for the English
language. For example the language tag {}``en\_GB{}'' will now get
the British dictionary if it is available.
\item Rewrote the {}``Usage{}'' section of the manual to use the C interface
instead of the C++ one as I recommend using the C interface even in
C++ code to avoid some of the nasty issues associated with C++ linkage.
\item Libltdl is now enabled by default.
\item Switched to the multi-language branch of libtool.
\item Added support for iso-8859-13 and 14.
\item Fixed a memory leak in PspellStringMap which fixes a bug \#126245
reported for Aspell.
\item Bug fixes.
\end{itemize}

\section*{Changes from .11.1 to .11.2 (August 19, 2000)}

\begin{itemize}
\item Changed my email from kevinatk@home.com to kevina@users.sourceforge.net
please make a note of the new email address.
\item Added the {}``repl{}'', {}``save-repl{}'', {}``ignore-repl{}''
options.
\end{itemize}

\section*{Changes from .11.0.2 to .11.1 (August 3, 2000)}

\begin{itemize}
\item Compile fixes for better C++ compliance and less warning when compiled
with -Wall.
\item Fixed some bug in the configuration classes which caused aspell's
dont-strip-accents not to work when specified on the command line.
\item Added {}``personal{}'' option to change the personal word list.
\end{itemize}

\section*{Changes from .11.0.1 to .11.0.2 (June 18, 2000)}

\begin{itemize}
\item Compile fixes so pspell will compile with the very latest gcc version
(CVS Version)
\item Included libltdl so it will compile with \doubledash{}enable-ltdl
\end{itemize}

\section*{Changes from .11 to .11.0.1 (June 11, 2000)}

\begin{itemize}
\item Fixed a bug in PspellConfigImpl::merge that caused the Aspell module
to core dump.
\end{itemize}

\section*{Changes from .10 to .11 (June 11, 2000)}

\begin{itemize}
\item Added support for searching for the word list to use based on the
language, and other information. This included support for other modules
other than Aspell.
\item Added support for linking modules in a compile time so that Pspell
will also work with static libraries and on system where libltdl does
not work.
\item Temporary disabled using the libltdl library as it will only work
well with C++ libraries on Linux. This means that all modules must
be linked in at compile time using the {}``./add-modules{}'' script.
If you want to enable it use {}``\doubledash{}enable-ltdl{}'' when running
configure.
\item Added support for non {}``iso-8859-1{}'' encodings. The {}``machine
unsigned 16{}'' and {}``machine unsigned 32{}'' encoding are still
untested however.
\item Switched to the HEAD branch of libtool as the multi-language branch
was causing too many problems.
\item Fixed it so that the manual will install in the correct location.
\item Bug Fixes.
\end{itemize}

\section*{Changes to .10 (April 2, 2000)}

\begin{itemize}
\item Initial release.
\end{itemize}

\chapter{Copyright}

Copyrighted 2001 by Kevin Atkinson under the LGPL. Certain parts of
the library, as indicated at the top of the source file, may be under
a weaker license. Individual modules are under there own independent
license.


\section{LGPL}

{\centering GNU LIBRARY GENERAL PUBLIC LICENSE \\
Version 2, June 1991\par}

Copyright (C) 1991 Free Software Foundation, Inc. 

\begin{quote}
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 
\end{quote}
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.

{[}This is the first released version of the library GPL. It is numbered
2 because it goes with version 2 of the ordinary GPL.{]}

{\centering Preamble\par}

The licenses for most software are designed to take away your freedom
to share and change it. By contrast, the GNU General Public Licenses
are intended to guarantee your freedom to share and change free software
--- to make sure the software is free for all its users.

This license, the Library General Public License, applies to some
specially designated Free Software Foundation software, and to any
other libraries whose authors decide to use it. You can use it for
your libraries, too.

When we speak of free software, we are referring to freedom, not price.
Our General Public Licenses are designed to make sure that you have
the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get
it if you want it, that you can change the software or use pieces
of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone
to deny you these rights or to ask you to surrender the rights. These
restrictions translate to certain responsibilities for you if you
distribute copies of the library, or if you modify it.

For example, if you distribute copies of the library, whether gratis
or for a fee, you must give the recipients all the rights that we
gave you. You must make sure that they, too, receive or can get the
source code. If you link a program with the library, you must provide
complete object files to the recipients so that they can relink them
with the library, after making changes to the library and recompiling
it. And you must show them these terms so they know their rights.

Our method of protecting your rights has two steps: (1) copyright
the library, and (2) offer you this license which gives you legal
permission to copy, distribute and/or modify the library.

Also, for each distributor's protection, we want to make certain that
everyone understands that there is no warranty for this free library.
If the library is modified by someone else and passed on, we want
its recipients to know that what they have is not the original version,
so that any problems introduced by others will not reflect on the
original authors' reputations.

Finally, any free program is threatened constantly by software patents.
We wish to avoid the danger that companies distributing free software
will individually obtain patent licenses, thus in effect transforming
the program into proprietary software. To prevent this, we have made
it clear that any patent must be licensed for everyone's free use
or not licensed at all.

Most GNU software, including some libraries, is covered by the ordinary
GNU General Public License, which was designed for utility programs.
This license, the GNU Library General Public License, applies to certain
designated libraries. This license is quite different from the ordinary
one; be sure to read it in full, and don't assume that anything in
it is the same as in the ordinary license.

The reason we have a separate public license for some libraries is
that they blur the distinction we usually make between modifying or
adding to a program and simply using it. Linking a program with a
library, without changing the library, is in some sense simply using
the library, and is analogous to running a utility program or application
program. However, in a textual and legal sense, the linked executable
is a combined work, a derivative of the original library, and the
ordinary General Public License treats it as such.

Because of this blurred distinction, using the ordinary General Public
License for libraries did not effectively promote software sharing,
because most developers did not use the libraries. We concluded that
weaker conditions might promote sharing better.

However, unrestricted linking of non-free programs would deprive the
users of those programs of all benefit from the free status of the
libraries themselves. This Library General Public License is intended
to permit developers of non-free programs to use free libraries, while
preserving your freedom as a user of such programs to change the free
libraries that are incorporated in them. (We have not seen how to
achieve this as regards changes in header files, but we have achieved
it as regards changes in the actual functions of the Library.) The
hope is that this will lead to faster development of free libraries.

The precise terms and conditions for copying, distribution and modification
follow. Pay close attention to the difference between a \char`\"{}work
based on the library\char`\"{} and a \char`\"{}work that uses the
library\char`\"{}. The former contains code derived from the library,
while the latter only works together with the library.

Note that it is possible for a library to be covered by the ordinary
General Public License rather than by this special one.

{\centering GNU LIBRARY GENERAL PUBLIC LICENSE\\
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION\par}

0. This License Agreement applies to any software library which contains
a notice placed by the copyright holder or other authorized party
saying it may be distributed under the terms of this Library General
Public License (also called \char`\"{}this License\char`\"{}). Each
licensee is addressed as \char`\"{}you\char`\"{}.

A \char`\"{}library\char`\"{} means a collection of software functions
and/or data prepared so as to be conveniently linked with application
programs (which use some of those functions and data) to form executables.

The \char`\"{}Library\char`\"{}, below, refers to any such software
library or work which has been distributed under these terms. A \char`\"{}work
based on the Library\char`\"{} means either the Library or any derivative
work under copyright law: that is to say, a work containing the Library
or a portion of it, either verbatim or with modifications and/or translated
straightforwardly into another language. (Hereinafter, translation
is included without limitation in the term \char`\"{}modification\char`\"{}.)

\char`\"{}Source code\char`\"{} for a work means the preferred form
of the work for making modifications to it. For a library, complete
source code means all the source code for all modules it contains,
plus any associated interface definition files, plus the scripts used
to control compilation and installation of the library.

Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope. The act of running
a program using the Library is not restricted, and output from such
a program is covered only if its contents constitute a work based
on the Library (independent of the use of the Library in a tool for
writing it). Whether that is true depends on what the Library does
and what the program that uses the Library does. 1. You may copy and
distribute verbatim copies of the Library's complete source code as
you receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice
and disclaimer of warranty; keep intact all the notices that refer
to this License and to the absence of any warranty; and distribute
a copy of this License along with the Library.

You may charge a fee for the physical act of transferring a copy,
and you may at your option offer warranty protection in exchange for
a fee.

2. You may modify your copy or copies of the Library or any portion
of it, thus forming a work based on the Library, and copy and distribute
such modifications or work under the terms of Section 1 above, provided
that you also meet all of these conditions:

\begin{LyXParagraphIndent}{0.5in}
a) The modified work must itself be a software library.

b) You must cause the files modified to carry prominent notices stating
that you changed the files and the date of any change.

c) You must cause the whole of the work to be licensed at no charge
to all third parties under the terms of this License.

d) If a facility in the modified Library refers to a function or a
table of data to be supplied by an application program that uses the
facility, other than as an argument passed when the facility is invoked,
then you must make a good faith effort to ensure that, in the event
an application does not supply such function or table, the facility
still operates, and performs whatever part of its purpose remains
meaningful.

\end{LyXParagraphIndent}

(For example, a function in a library to compute square roots has
a purpose that is entirely well-defined independent of the application.
Therefore, Subsection 2d requires that any application-supplied function
or table used by this function must be optional: if the application
does not supply it, the square root function must still compute square
roots.)

These requirements apply to the modified work as a whole. If identifiable
sections of that work are not derived from the Library, and can be
reasonably considered independent and separate works in themselves,
then this License, and its terms, do not apply to those sections when
you distribute them as separate works. But when you distribute the
same sections as part of a whole which is a work based on the Library,
the distribution of the whole must be on the terms of this License,
whose permissions for other licensees extend to the entire whole,
and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is
to exercise the right to control the distribution of derivative or
collective works based on the Library.

In addition, mere aggregation of another work not based on the Library
with the Library (or with a work based on the Library) on a volume
of a storage or distribution medium does not bring the other work
under the scope of this License.

3. You may opt to apply the terms of the ordinary GNU General Public
License instead of this License to a given copy of the Library. To
do this, you must alter all the notices that refer to this License,
so that they refer to the ordinary GNU General Public License, version
2, instead of to this License. (If a newer version than version 2
of the ordinary GNU General Public License has appeared, then you
can specify that version instead if you wish.) Do not make any other
change in these notices.

Once this change is made in a given copy, it is irreversible for that
copy, so the ordinary GNU General Public License applies to all subsequent
copies and derivative works made from that copy.

This option is useful when you wish to copy part of the code of the
Library into a program that is not a library.

4. You may copy and distribute the Library (or a portion or derivative
of it, under Section 2) in object code or executable form under the
terms of Sections 1 and 2 above provided that you accompany it with
the complete corresponding machine-readable source code, which must
be distributed under the terms of Sections 1 and 2 above on a medium
customarily used for software interchange.

If distribution of object code is made by offering access to copy
from a designated place, then offering equivalent access to copy the
source code from the same place satisfies the requirement to distribute
the source code, even though third parties are not compelled to copy
the source along with the object code.

5. A program that contains no derivative of any portion of the Library,
but is designed to work with the Library by being compiled or linked
with it, is called a \char`\"{}work that uses the Library\char`\"{}.
Such a work, in isolation, is not a derivative work of the Library,
and therefore falls outside the scope of this License.

However, linking a \char`\"{}work that uses the Library\char`\"{}
with the Library creates an executable that is a derivative of the
Library (because it contains portions of the Library), rather than
a \char`\"{}work that uses the library\char`\"{}. The executable is
therefore covered by this License. Section 6 states terms for distribution
of such executables.

When a \char`\"{}work that uses the Library\char`\"{} uses material
from a header file that is part of the Library, the object code for
the work may be a derivative work of the Library even though the source
code is not. Whether this is true is especially significant if the
work can be linked without the Library, or if the work is itself a
library. The threshold for this to be true is not precisely defined
by law.

If such an object file uses only numerical parameters, data structure
layouts and accessors, and small macros and small inline functions
(ten lines or less in length), then the use of the object file is
unrestricted, regardless of whether it is legally a derivative work.
(Executables containing this object code plus portions of the Library
will still fall under Section 6.)

Otherwise, if the work is a derivative of the Library, you may distribute
the object code for the work under the terms of Section 6. Any executables
containing that work also fall under Section 6, whether or not they
are linked directly with the Library itself.

6. As an exception to the Sections above, you may also compile or
link a \char`\"{}work that uses the Library\char`\"{} with the Library
to produce a work containing portions of the Library, and distribute
that work under terms of your choice, provided that the terms permit
modification of the work for the customer's own use and reverse engineering
for debugging such modifications.

You must give prominent notice with each copy of the work that the
Library is used in it and that the Library and its use are covered
by this License. You must supply a copy of this License. If the work
during execution displays copyright notices, you must include the
copyright notice for the Library among them, as well as a reference
directing the user to the copy of this License. Also, you must do
one of these things:

\begin{LyXParagraphIndent}{0.5in}
a) Accompany the work with the complete corresponding machine-readable
source code for the Library including whatever changes were used in
the work (which must be distributed under Sections 1 and 2 above);
and, if the work is an executable linked with the Library, with the
complete machine-readable \char`\"{}work that uses the Library\char`\"{},
as object code and/or source code, so that the user can modify the
Library and then relink to produce a modified executable containing
the modified Library. (It is understood that the user who changes
the contents of definitions files in the Library will not necessarily
be able to recompile the application to use the modified definitions.)

b) Accompany the work with a written offer, valid for at least three
years, to give the same user the materials specified in Subsection
6a, above, for a charge no more than the cost of performing this distribution.

c) If distribution of the work is made by offering access to copy
from a designated place, offer equivalent access to copy the above
specified materials from the same place.

d) Verify that the user has already received a copy of these materials
or that you have already sent this user a copy.

\end{LyXParagraphIndent}

For an executable, the required form of the \char`\"{}work that uses
the Library\char`\"{} must include any data and utility programs needed
for reproducing the executable from it. However, as a special exception,
the source code distributed need not include anything that is normally
distributed (in either source or binary form) with the major components
(compiler, kernel, and so on) of the operating system on which the
executable runs, unless that component itself accompanies the executable.

It may happen that this requirement contradicts the license restrictions
of other proprietary libraries that do not normally accompany the
operating system. Such a contradiction means you cannot use both them
and the Library together in an executable that you distribute.

7. You may place library facilities that are a work based on the Library
side-by-side in a single library together with other library facilities
not covered by this License, and distribute such a combined library,
provided that the separate distribution of the work based on the Library
and of the other library facilities is otherwise permitted, and provided
that you do these two things:

\begin{LyXParagraphIndent}{0.5in}
a) Accompany the combined library with a copy of the same work based
on the Library, uncombined with any other library facilities. This
must be distributed under the terms of the Sections above.

b) Give prominent notice with the combined library of the fact that
part of it is a work based on the Library, and explaining where to
find the accompanying uncombined form of the same work.

\end{LyXParagraphIndent}

8. You may not copy, modify, sublicense, link with, or distribute
the Library except as expressly provided under this License. Any attempt
otherwise to copy, modify, sublicense, link with, or distribute the
Library is void, and will automatically terminate your rights under
this License. However, parties who have received copies, or rights,
from you under this License will not have their licenses terminated
so long as such parties remain in full compliance.

9. You are not required to accept this License, since you have not
signed it. However, nothing else grants you permission to modify or
distribute the Library or its derivative works. These actions are
prohibited by law if you do not accept this License. Therefore, by
modifying or distributing the Library (or any work based on the Library),
you indicate your acceptance of this License to do so, and all its
terms and conditions for copying, distributing or modifying the Library
or works based on it.

10. Each time you redistribute the Library (or any work based on the
Library), the recipient automatically receives a license from the
original licensor to copy, distribute, link with or modify the Library
subject to these terms and conditions. You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties
to this License.

11. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do
not excuse you from the conditions of this License. If you cannot
distribute so as to satisfy simultaneously your obligations under
this License and any other pertinent obligations, then as a consequence
you may not distribute the Library at all. For example, if a patent
license would not permit royalty-free redistribution of the Library
by all those who receive copies directly or indirectly through you,
then the only way you could satisfy both it and this License would
be to refrain entirely from distribution of the Library.

If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended
to apply, and the section as a whole is intended to apply in other
circumstances.

It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the integrity
of the free software distribution system which is implemented by public
license practices. Many people have made generous contributions to
the wide range of software distributed through that system in reliance
on consistent application of that system; it is up to the author/donor
to decide if he or she is willing to distribute software through any
other system and a licensee cannot impose that choice.

This section is intended to make thoroughly clear what is believed
to be a consequence of the rest of this License.

12. If the distribution and/or use of the Library is restricted in
certain countries either by patents or by copyrighted interfaces,
the original copyright holder who places the Library under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded. In such case, this License incorporates
the limitation as if written in the body of this License.

13. The Free Software Foundation may publish revised and/or new versions
of the Library General Public License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Library
specifies a version number of this License which applies to it and
\char`\"{}any later version\char`\"{}, you have the option of following
the terms and conditions either of that version or of any later version
published by the Free Software Foundation. If the Library does not
specify a license version number, you may choose any version ever
published by the Free Software Foundation.

14. If you wish to incorporate parts of the Library into other free
programs whose distribution conditions are incompatible with these,
write to the author to ask for permission. For software which is copyrighted
by the Free Software Foundation, write to the Free Software Foundation;
we sometimes make exceptions for this. Our decision will be guided
by the two goals of preserving the free status of all derivatives
of our free software and of promoting the sharing and reuse of software
generally.

{\centering NO WARRANTY\par}

15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
PARTIES PROVIDE THE LIBRARY \char`\"{}AS IS\char`\"{} WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY (INCLUDING
BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE
OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE LIBRARY
TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER
PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

{\centering END OF TERMS AND CONDITIONS\par}

{\centering How to Apply These Terms to Your New Libraries\par}

If you develop a new library, and you want it to be of the greatest
possible use to the public, we recommend making it free software that
everyone can redistribute and change. You can do so by permitting
redistribution under these terms (or, alternatively, under the terms
of the ordinary General Public License).

To apply these terms, attach the following notices to the library.
It is safest to attach them to the start of each source file to most
effectively convey the exclusion of warranty; and each file should
have at least the \char`\"{}copyright\char`\"{} line and a pointer
to where the full notice is found.

\begin{quote}
<one line to give the library's name and a brief idea of what it does.>\\
Copyright (C) <year> <name of author>

This library is free software; you can redistribute it and/or modify
it under the terms of the GNU Library General Public License as published
by the Free Software Foundation; either version 2 of the License,
or (at your option) any later version.

This library is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
License for more details.

You should have received a copy of the GNU Library General Public
License along with this library; if not, write to the Free Foundation,
Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
\end{quote}
Also add information on how to contact you by electronic and paper
mail.

You should also get your employer (if you work as a programmer) or
your school, if any, to sign a \char`\"{}copyright disclaimer\char`\"{}
for the library, if necessary. Here is a sample; alter the names:

\begin{quote}
Yoyodyne, Inc., hereby disclaims all copyright interest in the library
`Frob' (a library for tweaking knobs) written by James Random Hacker.

<signature of Ty Coon>, 1 April 1990 Ty Coon, President of Vice
\end{quote}
That's all there is to it!
\end{document}
