xref: /dports/math/gap/gap-4.11.0/pkg/GAPDoc-1.6.3/doc/gapdoc.tex

% generated by GAPDoc2LaTeX from XML source (Frank Luebeck)
\documentclass[a4paper,11pt]{report}

\usepackage[top=37mm,bottom=37mm,left=27mm,right=27mm]{geometry}
\sloppy
\pagestyle{myheadings}
\usepackage{amssymb}
\usepackage[latin1]{inputenc}
\usepackage{makeidx}
\makeindex
\usepackage{color}
\definecolor{FireBrick}{rgb}{0.5812,0.0074,0.0083}
\definecolor{RoyalBlue}{rgb}{0.0236,0.0894,0.6179}
\definecolor{RoyalGreen}{rgb}{0.0236,0.6179,0.0894}
\definecolor{RoyalRed}{rgb}{0.6179,0.0236,0.0894}
\definecolor{LightBlue}{rgb}{0.8544,0.9511,1.0000}
\definecolor{Black}{rgb}{0.0,0.0,0.0}

\definecolor{linkColor}{rgb}{0.0,0.0,0.554}
\definecolor{citeColor}{rgb}{0.0,0.0,0.554}
\definecolor{fileColor}{rgb}{0.0,0.0,0.554}
\definecolor{urlColor}{rgb}{0.0,0.0,0.554}
\definecolor{promptColor}{rgb}{0.0,0.0,0.589}
\definecolor{brkpromptColor}{rgb}{0.589,0.0,0.0}
\definecolor{gapinputColor}{rgb}{0.589,0.0,0.0}
\definecolor{gapoutputColor}{rgb}{0.0,0.0,0.0}

%%  for a long time these were red and blue by default,
%%  now black, but keep variables to overwrite
\definecolor{FuncColor}{rgb}{0.0,0.0,0.0}
%% strange name because of pdflatex bug:
\definecolor{Chapter }{rgb}{0.0,0.0,0.0}
\definecolor{DarkOlive}{rgb}{0.1047,0.2412,0.0064}


\usepackage{fancyvrb}

\usepackage{mathptmx,helvet}
\usepackage[T1]{fontenc}
\usepackage{textcomp}


\usepackage[
            pdftex=true,
            bookmarks=true,
            a4paper=true,
            pdftitle={Written with GAPDoc},
            pdfcreator={LaTeX with hyperref package / GAPDoc},
            colorlinks=true,
            backref=page,
            breaklinks=true,
            linkcolor=linkColor,
            citecolor=citeColor,
            filecolor=fileColor,
            urlcolor=urlColor,
            pdfpagemode={UseNone},
           ]{hyperref}

\newcommand{\maintitlesize}{\fontsize{50}{55}\selectfont}

% write page numbers to a .pnr log file for online help
\newwrite\pagenrlog
\immediate\openout\pagenrlog =\jobname.pnr
\immediate\write\pagenrlog{PAGENRS := [}
\newcommand{\logpage}[1]{\protect\write\pagenrlog{#1, \thepage,}}
%% were never documented, give conflicts with some additional packages

\newcommand{\GAP}{\textsf{GAP}}

%% nicer description environments, allows long labels
\usepackage{enumitem}
\setdescription{style=nextline}

%% depth of toc
\setcounter{tocdepth}{1}





%% command for ColorPrompt style examples
\newcommand{\gapprompt}[1]{\color{promptColor}{\bfseries #1}}
\newcommand{\gapbrkprompt}[1]{\color{brkpromptColor}{\bfseries #1}}
\newcommand{\gapinput}[1]{\color{gapinputColor}{#1}}


\begin{document}

\logpage{[ 0, 0, 0 ]}
\begin{titlepage}
\mbox{}\vfill

\begin{center}{\maintitlesize \textbf{\textsf{GAPDoc}\mbox{}}}\\
\vfill

\hypersetup{pdftitle=\textsf{GAPDoc}}
\markright{\scriptsize \mbox{}\hfill \textsf{GAPDoc} \hfill\mbox{}}
{\Huge ( Version 1.6.3 ) \mbox{}}\\[1cm]
{July 2019\mbox{}}\\[1cm]
\mbox{}\\[2cm]
{\Large \textbf{ Frank L{\"u}beck   \mbox{}}}\\
{\Large \textbf{ Max Neunh{\"o}ffer   \mbox{}}}\\
\hypersetup{pdfauthor= Frank L{\"u}beck   ;  Max Neunh{\"o}ffer   }
\end{center}\vfill

\mbox{}\\
{\mbox{}\\
\small \noindent \textbf{ Frank L{\"u}beck   }  Email: \href{mailto://Frank.Luebeck@Math.RWTH-Aachen.De} {\texttt{Frank.Luebeck@Math.RWTH-Aachen.De}}\\
  Homepage: \href{http://www.math.rwth-aachen.de/~Frank.Luebeck} {\texttt{http://www.math.rwth-aachen.de/\texttt{\symbol{126}}Frank.Luebeck}}}\\
{\mbox{}\\
\small \noindent \textbf{ Max Neunh{\"o}ffer   }  Email: \href{mailto://neunhoef at mcs.st-and.ac.uk} {\texttt{neunhoef at mcs.st-and.ac.uk}}\\
  Homepage: \href{http://www-groups.mcs.st-and.ac.uk/~neunhoef/} {\texttt{http://www-groups.mcs.st-and.ac.uk/\texttt{\symbol{126}}neunhoef/}}}\\
\end{titlepage}

\newpage\setcounter{page}{2}
{\small
\section*{Copyright}
\logpage{[ 0, 0, 1 ]}
 \index{License} {\copyright} 2000-2019 by Frank L{\"u}beck and Max Neunh{\"o}ffer

 \textsf{GAPDoc} is free software; you can redistribute it and/or modify it under the terms of
the \href{http://www.fsf.org/licenses/gpl.html} {GNU General Public License} as published by the Free Software Foundation; either version 2 of the License,
or (at your option) any later version. \mbox{}}\\[1cm]
\newpage

\def\contentsname{Contents\logpage{[ 0, 0, 2 ]}}

\tableofcontents
\newpage


\chapter{\textcolor{Chapter }{Introduction and Example}}\label{ch:intro}
\logpage{[ 1, 0, 0 ]}
\hyperdef{L}{X7D4EE663818DA109}{}
{
 The main purpose of the \textsf{GAPDoc} package is to define a file format for documentation of \textsf{GAP}-programs and -packages (see \cite{GAP4}). The problem is that such documentation should be readable in several output
formats. For example it should be possible to read the documentation inside
the terminal in which \textsf{GAP} is running (a text mode) and there should be a printable version in high
typesetting quality (produced by some version of {\TeX}). It is also popular to view \textsf{GAP}'s online help with a Web-browser via an HTML-version of the documentation.
Nowadays one can use {\LaTeX} and standard viewer programs to produce and view on the screen \texttt{dvi}- or \texttt{pdf}-files with full support of internal and external hyperlinks. Certainly there
will be other interesting document formats and tools in this direction in the
future.

 Our aim is to find a \emph{format for writing} the documentation which allows a relatively easy translation into the output
formats just mentioned and which hopefully makes it easy to translate to
future output formats as well.

 To make documentation written in the \textsf{GAPDoc} format directly usable, we also provide a set of programs, called converters,
which produce text-, hyperlinked {\LaTeX}- and HTML-output versions of a \textsf{GAPDoc} document. These programs are developed by the first named author. They run
completely inside \textsf{GAP}, i.e., no external programs are needed. You only need \texttt{latex} and \texttt{pdflatex} to process the {\LaTeX} output. These programs are described in Chapter{\nobreakspace}\ref{ch:conv}.
\section{\textcolor{Chapter }{XML}}\label{sec:XML}
\logpage{[ 1, 1, 0 ]}
\hyperdef{L}{X8590236E858F7E93}{}
{
 \index{XML} The definition of the \textsf{GAPDoc} format uses XML, the ``eXtendible Markup Language''. This is a standard (defined by the W3C consortium, see \href{http://www.w3c.org} {\texttt{http://www.w3c.org}}) which lays down a syntax for adding markup to a document or to some data. It
allows to define document structures via introducing markup \emph{elements} and certain relations between them. This is done in a \emph{document type definition}. The file \texttt{gapdoc.dtd} contains such a document type definition and is the central part of the \textsf{GAPDoc} package.

 The easiest way for getting a good idea about this is probably to look at an
example. The Appendix{\nobreakspace}\ref{app:3k+1} contains a short but complete \textsf{GAPDoc} document for a fictitious share package. In the next section we will go
through this document, explain basic facts about XML and the \textsf{GAPDoc} document type, and give pointers to more details in later parts of this
documentation.

 In the last Section{\nobreakspace}\ref{sec:faq} of this introductory chapter we try to answer some general questions about the
decisions which lead to the \textsf{GAPDoc} package. }


\section{\textcolor{Chapter }{A complete example}}\label{sec:3k+1expl}
\logpage{[ 1, 2, 0 ]}
\hyperdef{L}{X7B47AFA881BFC9DC}{}
{
 In this section we recall the lines from the example document in
Appendix{\nobreakspace}\ref{app:3k+1} and give some explanations.
\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml]
  <?xml version="1.0" encoding="UTF-8"?>
\end{Verbatim}
 This line just tells a human reader and computer programs that the file is a
document with XML markup and that the text is encoded in the UTF-8 character
set (other common encodings are ASCII or ISO-8895-X encodings).
\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml]
  <!--   A complete "fake package" documentation
  -->
\end{Verbatim}
 Everything in a XML file between ``\texttt{{\textless}!--}'' and ``\texttt{--{\textgreater}}'' is a comment and not part of the document content.
\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml]
  <!DOCTYPE Book SYSTEM "gapdoc.dtd">
\end{Verbatim}
 This line says that the document contains markup which is defined in the
system file \texttt{gapdoc.dtd} and that the markup obeys certain rules defined in that file (the ending \texttt{dtd} means ``document type definition''). It further says that the actual content of the document consists of an
element with name ``Book''. And we can really see that the remaining part of the file is enclosed as
follows:
\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml]
  <Book Name="3k+1">
    [...] (content omitted)
  </Book>
\end{Verbatim}
 This demonstrates the basics of the markup in XML. This part of the document
is an ``element''. It consists of the ``start tag'' \texttt{{\textless}Book Name="3k+1"{\textgreater}}, the ``element content'' and the ``end tag'' \texttt{{\textless}/Book{\textgreater}} (end tags always start with \texttt{{\textless}/}). This element also has an ``attribute'' \texttt{Name} whose ``value'' is \texttt{3k+1}.

 If you know HTML, this will look familiar to you. But there are some important
differences: The element name \texttt{Book} and attribute name \texttt{Name} are \emph{case sensitive}. The value of an attribute must \emph{always} be enclosed in quotes. In XML \emph{every} element has a start and end tag (which can be combined for elements defined as ``empty'', see for example \texttt{{\textless}TableOfContents/{\textgreater}} below).

 If you know {\LaTeX}, you are familiar with quite different types of markup, for example: The
equivalent of the \texttt{Book} element in {\LaTeX} is \texttt{\texttt{\symbol{92}}begin\texttt{\symbol{123}}document\texttt{\symbol{125}}
... \texttt{\symbol{92}}end\texttt{\symbol{123}}document\texttt{\symbol{125}}}. The sectioning in {\LaTeX} is not done by explicit start and end markup, but implicitly via heading
commands like \texttt{\texttt{\symbol{92}}section}. Other markup is done by using braces \texttt{\texttt{\symbol{123}}\texttt{\symbol{125}}} and putting some commands inside. And for mathematical formulae one can use
the \texttt{\$} for the start \emph{and} the end of the markup. In XML \emph{all} markup looks similar to that of the \texttt{Book} element.

 The content of the book starts with a title page.
\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml]
  <TitlePage>
    <Title>The <Package>ThreeKPlusOne</Package> Package</Title>
    <Version>Version 42</Version>
    <Author>Dummy Auth�r
      <Email>3kplusone@dev.null</Email>
    </Author>

    <Copyright>&copyright; 2000 The Author. <P/>
      You can do with this package what you want.<P/> Really.
    </Copyright>
  </TitlePage>
\end{Verbatim}
 The content of the \texttt{TitlePage} element consists again of elements. In Chapter{\nobreakspace}\ref{DTD} we describe which elements are allowed within a \texttt{TitlePage} and that their ordering is prescribed in this case. In the (stupid) name of
the author you see that a German umlaut is used directly (in ISO-latin1
encoding).

 Contrary to {\LaTeX}- or HTML-files this markup does not say anything about the actual layout of
the title page in any output version of the document. It just adds information
about the \emph{meaning} of pieces of text.

 Within the \texttt{Copyright} element there are two more things to learn about XML markup. The \texttt{{\textless}P/{\textgreater}} is a complete element. It is a combined start and end tag. This shortcut is
allowed for elements which are defined to be always ``empty'', i.e., to have no content. You may have already guessed that \texttt{{\textless}P/{\textgreater}} is used as a paragraph separator. Note that empty lines do not separate
paragraphs (contrary to {\LaTeX}).

 The other construct we see here is \texttt{\&copyright;}. This is an example of an ``entity'' in XML and is a macro for some substitution text. Here we use an entity as a
shortcut for a complicated expression which makes it possible that the term \emph{copyright} is printed as some text like \texttt{(C)} in text terminal output and as a copyright character in other output formats.
In \textsf{GAPDoc} we predefine some entities. Certain ``special characters'' must be typed via entities, for example ``{\textless}'', ``{\textgreater}'' and ``\&'' to avoid a misinterpretation as XML markup. It is possible to define
additional entities for your document inside the \texttt{{\textless}!DOCTYPE ...{\textgreater}} declaration, see{\nobreakspace}\ref{GDent}.

 Note that elements in XML must always be properly nested, as in this example.
A construct like \texttt{{\textless}a{\textgreater}{\textless}b{\textgreater}...{\textless}/a{\textgreater}{\textless}/b{\textgreater}} is \emph{not} allowed.
\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml]
  <TableOfContents/>
\end{Verbatim}
 This is another example of an ``empty element''. It just means that a table of contents for the whole document should be
included into any output version of the document.

 After this the main text of the document follows inside certain sectioning
elements:
\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml]
  <Body>
    <Chapter> <Heading>The <M>3k+1</M> Problem</Heading>
      <Section Label="sec:theory"> <Heading>Theory</Heading>
        [...] (content omitted)
      </Section>
      <Section> <Heading>Program</Heading>
        [...] (content omitted)
      </Section>
    </Chapter>
  </Body>
\end{Verbatim}
 These elements are used similarly to ``\texttt{\symbol{92}}chapter'' and ``\texttt{\symbol{92}}section'' in {\LaTeX}. But note that the explicit end tags are necessary here.

 The sectioning commands allow to assign an optional attribute ``Label''. This can be used for referring to a section inside the document.

 The text of the first section starts as follows. The whitespace in the text is
unimportant and the indenting is not necessary.
\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml]

        Let  <M>k \in  &NN;</M> be  a  natural number.  We consider  the
        sequence <M>n(i, k), i \in &NN;,</M> with <M>n(1, k) = k</M> and
        else
\end{Verbatim}
 Here we come to the interesting question how to type mathematical formulae in
a \textsf{GAPDoc} document. We did not find any alternative for writing formulae in {\TeX} syntax. (There is MATHML, but even simple formulae contain a lot of markup,
become quite unreadable and they are cumbersome to type. Furthermore there
seem to be no tools available which translate such formulae in a nice way into {\TeX} and text.) So, formulae are essentially typed as in {\LaTeX}. (Actually, it is also possible to type unicode characters of some
mathematical symbols directly, or via an entity like the \texttt{\&NN;} above.) There are three types of elements containing formulae: ``M'', ``Math'' and ``Display''. The first two are for in-text formulae and the third is for displayed
formulae. Here ``M'' and ``Math'' are equivalent, when translating a \textsf{GAPDoc} document into {\LaTeX}. But they are handled differently for terminal text (and HTML) output. For
the content of an ``M''-element there are defined rules for a translation into well readable terminal
text. More complicated formulae are in ``Math'' or ``Display'' elements and they are just printed as they are typed in text output. So, to
make a section well readable inside a terminal window you should try to put as
many formulae as possible into ``M''-elements. In our example text we used the notation \texttt{n(i, k)} instead of \texttt{n{\textunderscore}i(k)} because it is easier to read in text mode. See Sections{\nobreakspace}\ref{GDformulae} and{\nobreakspace}\ref{sec:misc} for more details.

 A few lines further on we find two non-internal references.
\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml]
        problem, see <Cite Key="Wi98"/> or
        <URL>http://mathsrv.ku-eichstaett.de/MGF/homes/wirsching/</URL>
\end{Verbatim}
 The first within the ``Cite''-element is the citation of a book. In \textsf{GAPDoc} we use the widely used Bib{\TeX} database format for reference lists. This does not use XML but has a well
documented structure which is easy to parse. And many people have collections
of references readily available in this format. The reference list in an
output version of the document is produced with the empty element
\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml]
  <Bibliography Databases="3k+1" />
\end{Verbatim}
 close to the end of our example file. The attribute ``Databases'' give the name(s) of the database (\texttt{.bib}) files which contain the references.

 Putting a Web-address into an ``URL''-element allows one to create a hyperlink in output formats which allow this.

 The second section of our example contains a special kind of subsection
defined in \textsf{GAPDoc}.
\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml]
        <ManSection>
          <Func Name="ThreeKPlusOneSequence" Arg="k[, max]"/>
          <Description>
            This  function computes  for a  natural number  <A>k</A> the
            beginning of the sequence  <M>n(i, k)</M> defined in section
            <Ref Sect="sec:theory"/>.  The sequence  stops at  the first
            <M>1</M>  or at  <M>n(<A>max</A>, k)</M>,  if <A>max</A>  is
            given.
  <Example>
  gap> ThreeKPlusOneSequence(101);
  "Sorry, not yet implemented. Wait for Version 84 of the package"
  </Example>
          </Description>
        </ManSection>
\end{Verbatim}
 A ``ManSection'' contains the description of some function, operation, method, filter and so
on. The ``Func''-element describes the name of a \emph{function} (there are also similar elements ``Oper'', ``Meth'', ``Filt'' and so on) and names for its arguments, optional arguments enclosed in square
brackets. See Section{\nobreakspace}\ref{sec:mansect} for more details.

 In the ``Description'' we write the argument names as ``A''-elements. A good description of a function should usually contain an example
of its use. For this there are some verbatim-like elements in \textsf{GAPDoc}, like ``Example'' above (here, clearly, whitespace matters which causes a slightly strange
indenting).

 The text contains an internal reference to the first section via the
explicitly defined label \texttt{sec:theory}.

 The first section also contains a ``Ref''-element which refers to the function described here. Note that there is no
explicit label for such a reference. The pair \texttt{{\textless}Func Name="ThreeKPlusOneSequence" Arg="k[, max]"/{\textgreater}} and \texttt{{\textless}Ref Func="ThreeKPlusOneSequence"/{\textgreater}} does the cross referencing (and hyperlinking if possible) implicitly via the
name of the function.

 Here is one further element from our example document which we want to
explain.
\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml]
  <TheIndex/>
\end{Verbatim}
 This is again an empty element which just says that an output version of the
document should contain an index. Many entries for the index are generated
automatically because the ``Func'' and similar elements implicitly produce such entries. It is also possible to
include explicit additional entries in the index. }


\section{\textcolor{Chapter }{Some questions}}\label{sec:faq}
\logpage{[ 1, 3, 0 ]}
\hyperdef{L}{X79A97B867F45E5C7}{}
{

\begin{description}
\item[{Are those XML files too ugly to read and edit?}]  Just have a look and decide yourself. The markup needs more characters than
most {\TeX} or {\LaTeX} markup. But the structure of the document is easier to see. If you configure
your favorite editor well, you do not need more key strokes for typing the
markup than in {\LaTeX}.
\item[{Why do we not use {\LaTeX} alone?}]  {\LaTeX} is good for writing books. But {\LaTeX} files are generally difficult to parse and to process to other output formats
like text for browsing in a terminal window or HTML (or new formats which may
become popular in the future). \textsf{GAPDoc} markup is one step more abstract than {\LaTeX} insofar as it describes meaning instead of appearance of text. The inner
workings of {\LaTeX} are too complicated to learn without pain, which makes it difficult to
overcome problems that occur occasionally.
\item[{Why XML and not a newly defined markup language?}]  XML is a well defined standard that is more and more widely used. Lots of
people have thought about it. Years of experience with SGML went into the
design. It is easy to explain, easy to parse and lots of tools are available,
there will be more in the future.
\end{description}
 }

 }


\chapter{\textcolor{Chapter }{How To Type a \textsf{GAPDoc} Document}}\label{HowEnter}
\logpage{[ 2, 0, 0 ]}
\hyperdef{L}{X7890CF967F3E2FED}{}
{
  In this chapter we give a more formal description of what you need to start to
type documentation in \textsf{GAPDoc} XML format. Many details were already explained by example in
Section{\nobreakspace}\ref{sec:3k+1expl} of the introduction.

 We do \emph{not} answer the question ``How to \emph{write} a \textsf{GAPDoc} document?'' in this chapter. You can (hopefully) find an answer to this question by
studying the example in the introduction, see{\nobreakspace}\ref{sec:3k+1expl}, and learning about more details in the reference Chapter{\nobreakspace}\ref{DTD}.

 The definite source for all details of the official XML standard with useful
annotations is:

 \href{http://www.xml.com/axml/axml.html} {\texttt{http://www.xml.com/axml/axml.html}}

 Although this document must be quite technical, it is surprisingly well
readable.


\section{\textcolor{Chapter }{General XML Syntax}}\label{EnterXML}
\logpage{[ 2, 1, 0 ]}
\hyperdef{L}{X7B3A544986A1A9EA}{}
{
  We will now discuss the pieces of text which can occur in a general XML
document. We start with those pieces which do not contribute to the actual
content of the document.
\subsection{\textcolor{Chapter }{Head of XML Document}}\label{XMLhead}
\logpage{[ 2, 1, 1 ]}
\hyperdef{L}{X84E8D39687638CF0}{}
{
  Each XML document should have a head which states that it is an XML document
in some encoding and which XML-defined language is used. In case of a \textsf{GAPDoc} document this should always look as in the following example.
\begin{Verbatim}[commandchars=@|A,fontsize=\small,frame=single,label=Example]
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE Book SYSTEM "gapdoc.dtd">
\end{Verbatim}
 See{\nobreakspace}\ref{XMLenc} for a remark on the ``encoding'' statement.

 (There may be local entity definitions inside the \texttt{DOCTYPE} statement, see Subsection{\nobreakspace}\ref{GDent} below.) }


\subsection{\textcolor{Chapter }{Comments}}\label{XMLcomment}
\logpage{[ 2, 1, 2 ]}
\hyperdef{L}{X780C79EB85C32138}{}
{
  A ``comment'' in XML starts with the character sequence ``\texttt{{\textless}!--}'' and ends with the sequence ``\texttt{--{\textgreater}}''. Between these sequences there must not be two adjacent dashes ``\texttt{--}''. }


\subsection{\textcolor{Chapter }{Processing Instructions}}\label{XMLprocinstr}
\logpage{[ 2, 1, 3 ]}
\hyperdef{L}{X82DBCCAD8358BB63}{}
{
  A ``processing instruction'' in XML starts with the character sequence ``\texttt{{\textless}?}'' followed by a name (``\texttt{xml}'' is only allowed at the very beginning of the document to declare it being an
XML document, see \ref{XMLhead}). After that any characters may follow, except that the ending sequence ``\texttt{?{\textgreater}}'' must not occur within the processing instruction. }

 {\nobreakspace}

 And now we turn to those parts of the document which contribute to its actual
content.
\subsection{\textcolor{Chapter }{Names in XML and Whitespace}}\label{XMLnames}
\logpage{[ 2, 1, 4 ]}
\hyperdef{L}{X7A0FB16C7FEC0B53}{}
{
  A ``name'' in XML (used for element and attribute identifiers, see below) must start with
a letter (in the encoding of the document) or with a colon ``\texttt{:}'' or underscore ``\texttt{{\textunderscore}}'' character. The following characters may also be digits, dots ``\texttt{.}'' or dashes ``\texttt{-}''.

 This is a simplified description of the rules in the standard, which are
concerned with lots of unicode ranges to specify what a ``letter'' is.

 Sequences only consisting of the following characters are considered as \emph{whitespace}: blanks, tabs, carriage return characters and new line characters. }


\subsection{\textcolor{Chapter }{Elements}}\label{XMLel}
\logpage{[ 2, 1, 5 ]}
\hyperdef{L}{X79B130FC7906FB4C}{}
{
  The actual content of an XML document consists of ``elements''. An element has some ``content'' with a leading ``start tag'' (\ref{XMLstarttag}) and a trailing ``end tag'' (\ref{XMLendtag}). The content can contain further elements but they must be properly nested.
One can define elements whose content is always empty, those elements can also
be entered with a single combined tag (\ref{XMLcombtag}). }


\subsection{\textcolor{Chapter }{Start Tags}}\label{XMLstarttag}
\logpage{[ 2, 1, 6 ]}
\hyperdef{L}{X7DD1DCB783588BD5}{}
{
  A ``start-tag'' consists of a less-than-character ``\texttt{{\textless}}'' directly followed (without whitespace) by an element name (see{\nobreakspace}\ref{XMLnames}), optional attributes, optional whitespace, and a greater-than-character ``\texttt{{\textgreater}}''.

 An ``attribute'' consists of some whitespace and then its name followed by an equal sign ``\texttt{=}'' which is optionally enclosed by whitespace, and the attribute value, which is
enclosed either in single or double quotes. The attribute value may not
contain the type of quote used as a delimiter or the character ``\texttt{{\textless}}'', the character ``\texttt{\&}'' may only appear to start an entity, see{\nobreakspace}\ref{XMLent}. We describe in{\nobreakspace}\ref{AttrValRules} how to enter special characters in attribute values.

 Note especially that no whitespace is allowed between the starting ``\texttt{{\textless}}'' character and the element name. The quotes around an attribute value cannot be
omitted. The names of elements and attributes are \emph{case sensitive}. }


\subsection{\textcolor{Chapter }{End Tags}}\label{XMLendtag}
\logpage{[ 2, 1, 7 ]}
\hyperdef{L}{X7E5A567E83005B62}{}
{
  An ``end tag'' consists of the two characters ``\texttt{{\textless}/}'' directly followed by the element name, optional whitespace and a
greater-than-character ``\texttt{{\textgreater}}''. }


\subsection{\textcolor{Chapter }{Combined Tags for Empty Elements}}\label{XMLcombtag}
\logpage{[ 2, 1, 8 ]}
\hyperdef{L}{X843A02A88514D919}{}
{
  Elements which always have empty content can be written with a single tag.
This looks like a start tag (see{\nobreakspace}\ref{XMLstarttag}) \emph{except} that the trailing greater-than-character ``\texttt{{\textgreater}}'' is substituted by the two character sequence ``\texttt{/{\textgreater}}''. }


\subsection{\textcolor{Chapter }{Entities}}\label{XMLent}
\logpage{[ 2, 1, 9 ]}
\hyperdef{L}{X78FB56C77B1F391A}{}
{
  An ``entity'' in XML is a macro for some substitution text. There are two types of entities.

 A ``character entity'' can be used to specify characters in the encoding of the document (can be
useful for entering non-ASCII characters which you cannot manage to type in
directly). They are entered with a sequence ``\texttt{\&\#}'', directly followed by either some decimal digits or an ``\texttt{x}'' and some hexadecimal digits, directly followed by a semicolon ``\texttt{;}''. Using such a character entity is just equivalent to typing the corresponding
character directly.

 Then there are references to ``named entities''. They are entered with an ampersand character ``\texttt{\&}'' directly followed by a name which is directly followed by a semicolon ``\texttt{;}''. Such entities must be declared somewhere by giving a substitution text. This
text is included in the document and the document is parsed again afterwards.
The exact rules are a bit subtle but you probably want to use this only in
simple cases. Predefined entities for \textsf{GAPDoc} are described in \ref{XMLspchar} and \ref{GDent}.

 }


\subsection{\textcolor{Chapter }{Special Characters in XML}}\label{XMLspchar}
\logpage{[ 2, 1, 10 ]}
\hyperdef{L}{X84A95A19801EDE76}{}
{
  We have seen that the less-than-character ``\texttt{{\textless}}'' and the ampersand character ``\texttt{\&}'' start a tag or entity reference in XML. To get these characters into the
document text one has to use entity references, namely ``\texttt{\&lt;}'' to get ``\texttt{{\textless}}'' and ``\texttt{\&amp;}'' to get ``\texttt{\&}''. Furthermore ``\texttt{\&gt;}'' must be used to get ``\texttt{{\textgreater}}'' when the string ``\texttt{]]{\textgreater}}'' appears in element content (and not as delimiter of a \texttt{CDATA} section explained below).

 Another possibility is to use a \texttt{CDATA} statement explained in{\nobreakspace}\ref{XMLcdata}. }


\subsection{\textcolor{Chapter }{Rules for Attribute Values}}\label{AttrValRules}
\logpage{[ 2, 1, 11 ]}
\hyperdef{L}{X7F49E7AD785AED22}{}
{
  Attribute values can contain entities which are substituted recursively. But
except for the entities \&lt; or a character entity it is not allowed that a
{\textless} character is introduced by the substitution (there is no XML
parsing for evaluating the attribute value, just entity substitutions). }


\subsection{\textcolor{Chapter }{\texttt{CDATA}}}\label{XMLcdata}
\logpage{[ 2, 1, 12 ]}
\hyperdef{L}{X82E77E707A062908}{}
{
  Pieces of text which contain many characters which can be misinterpreted as
markup can be enclosed by the character sequences ``\texttt{{\textless}![CDATA[}'' and ``\texttt{]]{\textgreater}}''. Everything between these sequences is considered as content of the document
and is not further interpreted as XML text. All the rules explained so far in
this section do \emph{not apply} to such a part of the document. The only document content which cannot be
entered directly inside a \texttt{CDATA} statement is the sequence ``\texttt{]]{\textgreater}}''. This can be entered as ``\texttt{]]\&gt;}'' outside the \texttt{CDATA} statement.
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  A nesting of tags like <a> <b> </a> </b> is not allowed.
\end{Verbatim}
 }


\subsection{\textcolor{Chapter }{Encoding of an XML Document}}\label{XMLenc}
\logpage{[ 2, 1, 13 ]}
\hyperdef{L}{X8709BD337DA09ED5}{}
{
  We suggest to use the UTF-8 encoding for writing \textsf{GAPDoc} XML documents. But the tools described in Chapter \ref{ch:conv} also work with ASCII or the various ISO-8859-X encodings (ISO-8859-1 is also
called latin1 and covers most special characters for western European
languages). }


\subsection{\textcolor{Chapter }{Well Formed and Valid XML Documents}}\label{XMLvalid}
\logpage{[ 2, 1, 14 ]}
\hyperdef{L}{X8561F07A81CABDD6}{}
{
  We want to mention two further important words which are often used in the
context of XML documents. A piece of text becomes a ``well formed'' XML document if all the formal rules described in this section are fulfilled.

 But this says nothing about the content of the document. To give this content
a meaning one needs a declaration of the element and corresponding attribute
names as well as of named entities which are allowed. Furthermore there may be
restrictions how such elements can be nested. This \emph{definition of an XML based markup language} is done in a ``document type definition''. An XML document which contains only elements and entities declared in such a
document type definition and obeys the rules given there is called ``valid (with respect to this document type definition)''.

 The main file of the \textsf{GAPDoc} package is \texttt{gapdoc.dtd}. This contains such a definition of a markup language. We are not going to
explain the formal syntax rules for document type definitions in this section.
But in Chapter{\nobreakspace}\ref{DTD} we will explain enough about it to understand the file \texttt{gapdoc.dtd} and so the markup language defined there. }

 }


\section{\textcolor{Chapter }{Entering \textsf{GAPDoc} Documents}}\label{EnterGD}
\logpage{[ 2, 2, 0 ]}
\hyperdef{L}{X7BDE59B17CF1D5D2}{}
{
  Here are some additional rules for writing \textsf{GAPDoc} XML documents.
\subsection{\textcolor{Chapter }{Other special characters}}\label{otherspecchar}
\logpage{[ 2, 2, 1 ]}
\hyperdef{L}{X79171E047B069F94}{}
{
  As \textsf{GAPDoc} documents are used to produce {\LaTeX} and HTML documents, the question arises how to deal with characters with a
special meaning for other applications (for example ``\texttt{\&}'', ``\texttt{\#}'', ``\texttt{\$}'', ``\texttt{\%}'', ``\texttt{\texttt{\symbol{126}}}'', ``\texttt{\texttt{\symbol{92}}}'', ``\texttt{\texttt{\symbol{123}}}'', ``\texttt{\texttt{\symbol{125}}}'', ``\texttt{{\textunderscore}}'', ``\texttt{\texttt{\symbol{94}}}'', ``\texttt{{\nobreakspace}}'' (this is a non-breakable space, ``\texttt{\texttt{\symbol{126}}}'' in {\LaTeX}) have a special meaning for {\LaTeX} and ``\texttt{\&}'', ``\texttt{{\textless}}'', ``\texttt{{\textgreater}}'' have a special meaning for HTML (and XML). In \textsf{GAPDoc} you can usually just type these characters directly, it is the task of the
converter programs which translate to some output format to take care of such
special characters. The exceptions to this simple rule are:
\begin{itemize}
\item  \& and {\textless} must be entered as \texttt{\&amp;} and \texttt{\&lt;} as explained in \ref{XMLspchar}.
\item The content of the \textsf{GAPDoc} elements \texttt{{\textless}M{\textgreater}}, \texttt{{\textless}Math{\textgreater}} and \texttt{{\textless}Display{\textgreater}} is {\LaTeX} code, see \ref{MathForm}.
\item The content of an \texttt{{\textless}Alt{\textgreater}} element with \texttt{Only} attribute contains code for the specified output type, see \ref{Alt}.
\end{itemize}
 Remark: In former versions of \textsf{GAPDoc} one had to use particular entities for all the special characters mentioned
above (\texttt{\&tamp;}, \texttt{\&hash;}, \texttt{\&dollar;}, \texttt{\&percent;}, \texttt{\&tilde;}, \texttt{\&bslash;}, \texttt{\&obrace;}, \texttt{\&cbrace;}, \texttt{\&uscore;}, \texttt{\&circum;}, \texttt{\&tlt;}, \texttt{\&tgt;}). These are no longer needed, but they are still defined for backwards
compatibility with older \textsf{GAPDoc} documents. }


\subsection{\textcolor{Chapter }{Mathematical Formulae}}\label{GDformulae}
\logpage{[ 2, 2, 2 ]}
\hyperdef{L}{X7EAE0C5A835F126F}{}
{
  Mathematical formulae in \textsf{GAPDoc} are typed as in {\LaTeX}. They must be the content of one of three types of \textsf{GAPDoc} elements concerned with mathematical formulae: ``\texttt{Math}'', ``\texttt{Display}'', and ``\texttt{M}'' (see Sections{\nobreakspace}\ref{Math} and{\nobreakspace}\ref{M} for more details). The first two correspond to {\LaTeX}'s math mode and display math mode. The last one is a special form of the ``\texttt{Math}'' element type, that imposes certain restrictions on the content. On the other
hand the content of an ``\texttt{M}'' element is processed in a well defined way for text terminal or HTML output.
The ``\texttt{Display}'' element also has an attribute such that its content is processed as in ``\texttt{M}'' elements.

 Note that the content of these element is {\LaTeX} code, but the special characters ``\texttt{{\textless}}'' and ``\texttt{\&}'' for XML must be entered via the entities described in{\nobreakspace}\ref{XMLspchar} or by using a \texttt{CDATA} statement, see{\nobreakspace}\ref{XMLcdata}.

 }


\subsection{\textcolor{Chapter }{More Entities}}\label{GDent}
\logpage{[ 2, 2, 3 ]}
\hyperdef{L}{X7BDFF6D37FBED400}{}
{
  In \textsf{GAPDoc} there are some more predefined entities: \begin{center}
\begin{tabular}{|l|l|}\hline
\texttt{\&GAP;}&
\textsf{GAP}\\
\hline
\texttt{\&GAPDoc;}&
\textsf{GAPDoc}\\
\hline
\texttt{\&TeX;}&
{\TeX}\\
\hline
\texttt{\&LaTeX;}&
{\LaTeX}\\
\hline
\texttt{\&BibTeX;}&
Bib{\TeX}\\
\hline
\texttt{\&MeatAxe;}&
\textsf{MeatAxe}\\
\hline
\texttt{\&XGAP;}&
\textsf{XGAP}\\
\hline
\texttt{\&copyright;}&
{\copyright}\\
\hline
\texttt{\&nbsp;}&
``{\nobreakspace}''\\
\hline
\texttt{\&ndash;}&
{\textendash}\\
\hline
\end{tabular}\\[2mm]
\textbf{Table: }Predefined Entities in the \textsf{GAPDoc} system\end{center}

 Here \texttt{\&nbsp;} is a non-breakable space character.

 Additional entities are defined for some mathematical symbols, see \ref{MathForm} for more details.

 One can define further local entities right inside the head
(see{\nobreakspace}\ref{XMLhead}) of a \textsf{GAPDoc} XML document as in the following example.
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  <?xml version="1.0" encoding="UTF-8"?>

  <!DOCTYPE Book SYSTEM "gapdoc.dtd"
    [ <!ENTITY MyEntity "some longish <E>text</E> possibly with markup">
    ]>
\end{Verbatim}
 These additional definitions go into the \texttt{{\textless}!DOCTYPE} tag in square brackets. Such new entities are used like this: \texttt{\&MyEntity;}

 }

 }

 }


\chapter{\textcolor{Chapter }{The Document Type Definition}}\label{DTD}
\logpage{[ 3, 0, 0 ]}
\hyperdef{L}{X7859CFF180D52D49}{}
{
  In this chapter we first explain what a ``document type definition'' is and then describe \texttt{gapdoc.dtd} in detail. That file together with the current chapter define how a \textsf{GAPDoc} document has to look like. It can be found in the main directory of the \textsf{GAPDoc} package and it is reproduced in Appendix{\nobreakspace}\ref{GAPDocdtd}.

 We do not give many examples in this chapter which is more intended as a
formal reference for all \textsf{GAPDoc} elements. Instead, we provide a separate help book, see{\nobreakspace} ??? . This uses all the constructs introduced in this chapter and you can easily
compare the source code and how it looks like in the different output formats.
Furthermore recall that many basic things about XML markup were already
explained by example in the introductory chapter{\nobreakspace}\ref{ch:intro}.
\section{\textcolor{Chapter }{What is a DTD?}}\logpage{[ 3, 1, 0 ]}
\hyperdef{L}{X7B76F6F786521F6B}{}
{
 A document type definition (DTD) is a formal declaration of how an XML
document has to be structured. It is itself structured such that programs that
handle documents can read it and treat the documents accordingly. There are
for example parsers and validity checkers that use the DTD to validate an XML
document, see{\nobreakspace}\ref{XMLvalid}.

 The main thing a DTD does is to specify which elements may occur in documents
of a certain document type, how they can be nested, and what attributes they
can or must have. So, for each element there is a rule.

 Note that a DTD can \emph{not} ensure that a document which is ``valid'' also makes sense to the converters! It only says something about the formal
structure of the document.

 For the remaining part of this chapter we have divided the elements of \textsf{GAPDoc} documents into several subsets, each of which will be discussed in one of the
next sections.

 See the following three subsections to learn by example, how a DTD works. We
do not want to be too formal here, but just enable the reader to understand
the declarations in \texttt{gapdoc.dtd}. For precise descriptions of the syntax of DTD's see again the official
standard in:

 {\nobreakspace}{\nobreakspace}\href{http://www.xml.com/axml/axml.html} {\texttt{http://www.xml.com/axml/axml.html}}

 }


\section{\textcolor{Chapter }{Overall Document Structure}}\logpage{[ 3, 2, 0 ]}
\hyperdef{L}{X7DB0F9E57879CC76}{}
{
 A \textsf{GAPDoc} document contains on its top level exactly one element with name \texttt{Book}. This element is declared in the DTD as follows:
\subsection{\textcolor{Chapter }{\texttt{{\textless}Book{\textgreater}}}}\logpage{[ 3, 2, 1 ]}
\hyperdef{L}{X7C7258A57B831934}{}
{
 \index{Book@\texttt{Book}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Book (TitlePage,
                  TableOfContents?,
                  Body,
                  Appendix*,
                  Bibliography?,
                  TheIndex?)>
  <!ATTLIST Book Name CDATA #REQUIRED>
\end{Verbatim}
 After the keyword \texttt{ELEMENT} and the name \texttt{Book} there is a list in parentheses. This is a comma separated list of names of
elements which can occur (in the given order) in the content of a \texttt{Book} element. Each name in such a list can be followed by one of the characters ``\texttt{?}'', ``\texttt{*}'' or ``\texttt{+}'', meaning that the corresponding element can occur zero or one time, an
arbitrary number of times, or at least once, respectively. Without such an
extra character the corresponding element must occur exactly once. Instead of
one name in this list there can also be a list of elements names separated by ``\texttt{|}'' characters, this denotes any element with one of the names (i.e., ``\texttt{|}'' means ``or'').

 So, the \texttt{Book} element must contain first a \texttt{TitlePage} element, then an optional \texttt{TableOfContents} element, then a \texttt{Body} element, then zero or more elements of type \texttt{Appendix}, then an optional \texttt{Bibliography} element, and finally an optional element of type \texttt{TheIndex}.

 Note that \emph{only} these elements are allowed in the content of the \texttt{Book} element. No other elements or text is allowed in between. An exception of this
is that there may be whitespace between the end tag of one and the start tag
of the next element - this should be ignored when the document is processed to
some output format. An element like this is called an element with ``element content''.

 The second declaration starts with the keyword \texttt{ATTLIST} and the element name \texttt{Book}. After that there is a triple of whitespace separated parameters (in general
an arbitrary number of such triples, one for each allowed attribute name). The
first (\texttt{Name}) is the name of an attribute for a \texttt{Book} element. The second (\texttt{CDATA}) is always the same for all of our declarations, it means that the value of
the attribute consists of ``character data''. The third parameter \texttt{\#REQUIRED} means that this attribute must be specified with any \texttt{Book} element. Later we will also see optional attributes which are declared as \texttt{\#IMPLIED}. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}TitlePage{\textgreater}}}}\logpage{[ 3, 2, 2 ]}
\hyperdef{L}{X842B421A7FBCDD2C}{}
{
 \index{TitlePage@\texttt{TitlePage}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT TitlePage (Title, Subtitle?, Version?, TitleComment?,
                       Author+, Date?, Address?, Abstract?, Copyright?,
                       Acknowledgements? , Colophon? )>
\end{Verbatim}
 Within this element information for the title page is collected. Note that
more than one author can be specified. The elements must appear in this order
because there is no sensible way to specify in a DTD something like ``the following elements may occur in any order but each exactly once''.

 Before going on with the other elements inside the \texttt{Book} element we explain the elements for the title page. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Title{\textgreater}}}}\label{Title}
\logpage{[ 3, 2, 3 ]}
\hyperdef{L}{X7BCC8E6F79021294}{}
{
 \index{Title@\texttt{Title}} \label{Text}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Title (%Text;)*>
\end{Verbatim}
 Here is the last construct you need to understand for reading \texttt{gapdoc.dtd}. The expression ``\texttt{\%Text;}'' is a so-called ``parameter entity''. It is something like a macro within the DTD. It is defined as follows: \label{InnerText}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ENTITY % Text "%InnerText; | List | Enum | Table">
\end{Verbatim}
 This means, that every occurrence of ``\texttt{\%Text;}'' in the DTD is replaced by the expression \label{Innertext}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  %InnerText; | List | Enum | Table
\end{Verbatim}
 which is then expanded further because of the following definition:
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ENTITY % InnerText "#PCDATA |
                        Alt |
                        Emph | E |
                        Par | P | Br |
                        Keyword | K | Arg | A | Quoted | Q | Code | C |
                        File | F | Button | B | Package |
                        M | Math | Display |
                        Example | Listing | Log | Verb |
                        URL | Email | Homepage | Address | Cite | Label |
                        Ref | Index" >
\end{Verbatim}
 These are the only two parameter entities we are using. They expand to lists
of element names which are explained in the sequel \emph{and} the keyword \texttt{\#PCDATA} (concatenated with the ``or'' character ``\texttt{|}'').

 So, the element (\texttt{Title}) is of so-called ``mixed content'': It can contain \emph{parsed character data} which does not contain further markup (\texttt{\#PCDATA}) or any of the other above mentioned elements. Mixed content must always have
the asterisk qualifier (like in \texttt{Title}) such that any sequence of elements (of the above list) and character data
can be contained in a \texttt{Title} element.

 The \texttt{\%Text;} parameter entity is used in all places in the DTD, where ``normal text'' should be allowed, including lists, enumerations, and tables, but \emph{no} sectioning elements.

 The \texttt{\%InnerText;} parameter entity is used in all places in the DTD, where ``inner text'' should be allowed. This means, that no structures like lists, enumerations,
and tables are allowed. This is used for example in headings.

 }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Subtitle{\textgreater}}}}\logpage{[ 3, 2, 4 ]}
\hyperdef{L}{X82E82AF48217CC14}{}
{
 \index{Subtitle@\texttt{Subtitle}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Subtitle (%Text;)*>
\end{Verbatim}
 Contains the subtitle of the document. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Version{\textgreater}}}}\label{Version}
\logpage{[ 3, 2, 5 ]}
\hyperdef{L}{X876962807DCC52B3}{}
{
 \index{Version@\texttt{Version}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Version (#PCDATA|Alt)*>
\end{Verbatim}
 Note that the version can only contain character data and no further markup
elements (except for \texttt{Alt}, which is necessary to resolve the entities described in \ref{GDent}). The converters will \emph{not} put the word ``Version'' in front of the text in this element. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}TitleComment{\textgreater}}}}\logpage{[ 3, 2, 6 ]}
\hyperdef{L}{X87E7CD5B79230B90}{}
{
 \index{TitleComment@\texttt{TitleComment}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT TitleComment (%Text;)*>
\end{Verbatim}
 Sometimes a title and subtitle are not sufficient to give a rough idea about
the content of a package. In this case use this optional element to specify an
additional text for the front page of the book. This text should be short, use
the \texttt{Abstract} element (see{\nobreakspace}\ref{elAbstract}) for longer explanations. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Author{\textgreater}}}}\logpage{[ 3, 2, 7 ]}
\hyperdef{L}{X8731459C7E4C56DA}{}
{
 \index{Author@\texttt{Author}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Author (%Text;)*>    <!-- There may be more than one Author! -->
\end{Verbatim}
 As noted in the comment there may be more than one element of this type. This
element should contain the name of an author and probably an \texttt{Email}-address and/or WWW-\texttt{Homepage} element for this author, see{\nobreakspace}\ref{elEmail} and{\nobreakspace}\ref{elHomepage}. You can also specify an individual postal address here, instead of using the \texttt{Address} element described below, see{\nobreakspace}\ref{elAddress}. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Date{\textgreater}}}}\logpage{[ 3, 2, 8 ]}
\hyperdef{L}{X8264A69D7DCDD773}{}
{
 \index{Date@\texttt{Date}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Date (#PCDATA)>
\end{Verbatim}
 Only character data is allowed in this element which gives a date for the
document. No automatic formatting is done. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Address{\textgreater}}}}\label{elAddress}
\logpage{[ 3, 2, 9 ]}
\hyperdef{L}{X7EEF65A07A094F65}{}
{
 \index{Date@\texttt{Address}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Address (#PCDATA|Alt|Br)*>
\end{Verbatim}
 This optional element can be used to specify a postal address of the author or
the authors. If there are several authors with different addresses then put
the \texttt{Address} elements inside the \texttt{Author} elements.

 Use the \texttt{Br} element (see{\nobreakspace}\ref{Br}) to mark the line breaks in the usual formatting of the address on a letter.

 Note that often it is not necessary to use this element because a postal
address is easy to find via a link to a personal web page. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Abstract{\textgreater}}}}\label{elAbstract}
\logpage{[ 3, 2, 10 ]}
\hyperdef{L}{X833110FE79628313}{}
{
 \index{Abstract@\texttt{Abstract}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Abstract (%Text;)*>
\end{Verbatim}
 This element contains an abstract of the whole book. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Copyright{\textgreater}}}}\logpage{[ 3, 2, 11 ]}
\hyperdef{L}{X84BBD8307E08E62F}{}
{
 \index{Copyright@\texttt{Copyright}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Copyright (%Text;)*>
\end{Verbatim}
 This element is used for the copyright notice. Note the \texttt{\&copyright;} entity as described in section \ref{GDent}. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Acknowledgements{\textgreater}}}}\logpage{[ 3, 2, 12 ]}
\hyperdef{L}{X8143972D7C17838E}{}
{
 \index{Acknowledgements@\texttt{Acknowledgements}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Acknowledgements (%Text;)*>
\end{Verbatim}
 This element contains the acknowledgements. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Colophon{\textgreater}}}}\logpage{[ 3, 2, 13 ]}
\hyperdef{L}{X7C09A3398059D18C}{}
{
 \index{Colophon@\texttt{Colophon}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Colophon (%Text;)*>
\end{Verbatim}
 The ``colophon'' page is used to say something about the history of a document. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}TableOfContents{\textgreater}}}}\logpage{[ 3, 2, 14 ]}
\hyperdef{L}{X7E97263A83DC26E9}{}
{
 \index{TableOfContents@\texttt{TableOfContents}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT TableOfContents EMPTY>
\end{Verbatim}
 This element may occur in the \texttt{Book} element after the \texttt{TitlePage} element. If it is present, a table of contents is generated and inserted into
the document. Note that because this element is declared to be \texttt{EMPTY} one can use the abbreviation
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  <TableOfContents/>
\end{Verbatim}
 to denote this empty element. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Bibliography{\textgreater}} }}\label{Bibliography}
\logpage{[ 3, 2, 15 ]}
\hyperdef{L}{X84F3DF21786A8751}{}
{
 \index{Bibliography@\texttt{Bibliography}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Bibliography EMPTY>
  <!ATTLIST Bibliography Databases CDATA #REQUIRED
                         Style CDATA #IMPLIED>
\end{Verbatim}
 This element may occur in the \texttt{Book} element after the last \texttt{Appendix} element. If it is present, a bibliography section is generated and inserted
into the document. The attribute \texttt{Databases} must be specified, the names of several data files can be specified, separated
by commas.

 Two kinds of files can be specified in \texttt{Databases}: The first are Bib{\TeX} files as defined in{\nobreakspace}\cite[Appendix B]{La85}. Such files must have a name with extension \texttt{.bib}, and in \texttt{Databases} the name must be given \emph{without} this extension. Note that such \texttt{.bib}-files should be in latin1-encoding (or ASCII-encoding). The second are files
in BibXMLext format as defined in Section{\nobreakspace}\ref{BibXMLformat}. These files must have an extension \texttt{.xml} and in \texttt{Databases} the \emph{full} name must be specified.

 We suggest to use the BibXMLext format because it allows to produce
potentially nicer bibliography entries in text and HTML documents.

 A bibliography style may be specified with the \texttt{Style} attribute. The optional \texttt{Style} attribute (for {\LaTeX} output of the document) must also be specified without the \texttt{.bst} extension (the default is \texttt{alpha}). See also section \ref{Cite} for a description of the \texttt{Cite} element which is used to include bibliography references into the text.

 }


\subsection{\textcolor{Chapter }{\texttt{{\textless}TheIndex{\textgreater}}}}\label{TheIndex}
\logpage{[ 3, 2, 16 ]}
\hyperdef{L}{X7C53615A8477F1E5}{}
{
 \index{TheIndex@\texttt{TheIndex}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT TheIndex EMPTY>
\end{Verbatim}
 This element may occur in the \texttt{Book} element after the \texttt{Bibliography} element. If it is present, an index is generated and inserted into the
document. There are elements in \textsf{GAPDoc} which implicitly generate index entries (e.g., \texttt{Func} (\ref{Func})) and there is an element \texttt{Index} (\ref{Index}) for explicitly adding index entries. }

 }


\section{\textcolor{Chapter }{Sectioning Elements}}\logpage{[ 3, 3, 0 ]}
\hyperdef{L}{X80E2AD7481DD69D9}{}
{
 A \textsf{GAPDoc} book is divided into \emph{chapters}, \emph{sections}, and \emph{subsections}. The idea is of course, that a chapter consists of sections, which in turn
consist of subsections. However for the sake of flexibility, the rules are not
too restrictive. Firstly, text is allowed everywhere in the body of the
document (and not only within sections). Secondly, the chapter level may be
omitted. The exact rules are described below.

 \emph{Appendices} are a flavor of chapters, occurring after all regular chapters. There is a
special type of subsection called ``\texttt{ManSection}''. This is a subsection devoted to the description of a function, operation or
variable. It is analogous to a manpage in the UNIX environment. Usually each
function, operation, method, and so on should have its own \texttt{ManSection}.

 Cross referencing is done on the level of \texttt{Subsection}s, respectively \texttt{ManSection}s. The topics in \textsf{GAP}'s online help are also pointing to subsections. So, they should not be too
long.

 We start our description of the sectioning elements ``top-down'':
\subsection{\textcolor{Chapter }{\texttt{{\textless}Body{\textgreater}}}}\logpage{[ 3, 3, 1 ]}
\hyperdef{L}{X7B38415687510D0A}{}
{
 \index{Body@\texttt{Body}} The \texttt{Body} element marks the main part of the document. It must occur after the \texttt{TableOfContents} element. There is a big difference between \emph{inside} and \emph{outside} of this element: Whereas regular text is allowed nearly everywhere in the \texttt{Body} element and its subelements, this is not true for the \emph{outside}. This has also implications on the handling of whitespace. \emph{Outside} superfluous whitespace is usually ignored when it occurs between elements. \emph{Inside} of the \texttt{Body} element whitespace matters because character data is allowed nearly
everywhere. Here is the definition in the DTD:
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Body  ( %Text;| Chapter | Section )*>
\end{Verbatim}
 The fact that \texttt{Chapter} and \texttt{Section} elements are allowed here leads to the possibility to omit the chapter level
entirely in the document. For a description of \texttt{\%Text;} see \ref{Text}.

 (Remark: The purpose of this element is to make sure that a \emph{valid} \textsf{GAPDoc} document has a correct overall structure, which is only possible when the top
element \texttt{Book} has element content.) }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Chapter{\textgreater}}}}\label{Chapter}
\logpage{[ 3, 3, 2 ]}
\hyperdef{L}{X7A86B2BA7D688B6B}{}
{
 \index{Chapter@\texttt{Chapter}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Chapter (%Text;| Heading | Section)*>
  <!ATTLIST Chapter Label CDATA #IMPLIED>    <!-- For reference purposes -->
\end{Verbatim}
 A \texttt{Chapter} element can have a \texttt{Label} attribute, such that this chapter can be referenced later on with a \texttt{Ref} element (see section \ref{Ref}). Note that you have to specify a label to reference the chapter as there is
no automatic labelling!

 \texttt{Chapter} elements can contain text (for a description of \texttt{\%Text;} see \ref{Text}), \texttt{Section} elements, and \texttt{Heading} elements.

 The following \emph{additional} rule cannot be stated in the DTD because we want a \texttt{Chapter} element to have mixed content. There must be \emph{exactly one} \texttt{Heading} element in the \texttt{Chapter} element, containing the heading of the chapter. Here is its definition: }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Heading{\textgreater}}}}\label{Heading}
\logpage{[ 3, 3, 3 ]}
\hyperdef{L}{X79825E1C821D0B79}{}
{
 \index{Heading@\texttt{Heading}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Heading (%InnerText;)*>
\end{Verbatim}
 This element is used for headings in \texttt{Chapter}, \texttt{Section}, \texttt{Subsection}, and \texttt{Appendix} elements. It may only contain \texttt{\%InnerText;} (for a description see \ref{InnerText}).

 Each of the mentioned sectioning elements must contain exactly one direct \texttt{Heading} element (i.e., one which is not contained in another sectioning element). }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Appendix{\textgreater}}}}\logpage{[ 3, 3, 4 ]}
\hyperdef{L}{X7C701B2779767556}{}
{
 \index{Appendix@\texttt{Appendix}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Appendix (%Text;| Heading | Section)*>
  <!ATTLIST Appendix Label CDATA #IMPLIED>   <!-- For reference purposes -->
\end{Verbatim}
 The \texttt{Appendix} element behaves exactly like a \texttt{Chapter} element (see \ref{Chapter}) except for the position within the document and the numbering. While
chapters are counted with numbers (1., 2., 3., ...) the appendices are counted
with capital letters (A., B., ...).

 Again there is an optional \texttt{Label} attribute used for references. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Section{\textgreater}}}}\logpage{[ 3, 3, 5 ]}
\hyperdef{L}{X844DC2B47FB37339}{}
{
 \index{Section@\texttt{Section}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Section (%Text;| Heading | Subsection | ManSection)*>
  <!ATTLIST Section Label CDATA #IMPLIED>    <!-- For reference purposes -->
\end{Verbatim}
 A \texttt{Section} element can have a \texttt{Label} attribute, such that this section can be referenced later on with a \texttt{Ref} element (see section \ref{Ref}). Note that you have to specify a label to reference the section as there is
no automatic labelling!

 \texttt{Section} elements can contain text (for a description of \texttt{\%Text;} see \ref{Text}), \texttt{Heading} elements, and subsections.

 There must be exactly one direct \texttt{Heading} element in a \texttt{Section} element, containing the heading of the section.

 Note that a subsection is either a \texttt{Subsection} element or a \texttt{ManSection} element. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Subsection{\textgreater}}}}\logpage{[ 3, 3, 6 ]}
\hyperdef{L}{X803ACA187E292969}{}
{
 \index{Subsection@\texttt{Subsection}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Subsection (%Text;| Heading)*>
  <!ATTLIST Subsection Label CDATA #IMPLIED> <!-- For reference purposes -->
\end{Verbatim}
 The \texttt{Subsection} element can have a \texttt{Label} attribute, such that this subsection can be referenced later on with a \texttt{Ref} element (see section \ref{Ref}). Note that you have to specify a label to reference the subsection as there
is no automatic labelling!

 \texttt{Subsection} elements can contain text (for a description of \texttt{\%Text;} see \ref{Text}), and \texttt{Heading} elements.

 There must be exactly one \texttt{Heading} element in a \texttt{Subsection} element, containing the heading of the subsection.

 Another type of subsection is a \texttt{ManSection}, explained now: }

 }


\section{\textcolor{Chapter }{ManSection{\textendash}a special kind of subsection}}\label{sec:mansect}
\logpage{[ 3, 4, 0 ]}
\hyperdef{L}{X877B8B7C7EDD09E9}{}
{
  \texttt{ManSection}s are intended to describe a function, operation, method, variable, or some
other technical instance. It is analogous to a manpage in the UNIX
environment.
\subsection{\textcolor{Chapter }{\texttt{{\textless}ManSection{\textgreater}}}}\logpage{[ 3, 4, 1 ]}
\hyperdef{L}{X8375D9CC8672A1D5}{}
{
 \index{ManSection@\texttt{ManSection}} \index{Description@\texttt{Description}} \index{Returns@\texttt{Returns}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT ManSection ( Heading?,
                        ((Func, Returns?) | (Oper, Returns?) |
                         (Meth, Returns?) | (Filt, Returns?) |
                         (Prop, Returns?) | (Attr, Returns?) |
                         (Constr, Returns?) |
                         Var | Fam | InfoClass)+, Description )>
  <!ATTLIST ManSection Label CDATA #IMPLIED> <!-- For reference purposes -->

  <!ELEMENT Returns (%Text;)*>
  <!ELEMENT Description (%Text;)*>
\end{Verbatim}
 The \texttt{ManSection} element can have a \texttt{Label} attribute, such that this subsection can be referenced later on with a \texttt{Ref} element (see section \ref{Ref}). But this is probably rarely necessary because the elements \texttt{Func} and so on (explained below) generate automatically labels for cross
referencing.

 The content of a \texttt{ManSection} element is one or more elements describing certain items in \textsf{GAP}, each of them optionally followed by a \texttt{Returns} element, followed by a \texttt{Description} element, which contains \texttt{\%Text;} (see \ref{Text}) describing it. (Remember to include examples in the description as often as
possible, see{\nobreakspace}\ref{Log}). The classes of items \textsf{GAPDoc} knows of are: functions (\texttt{Func}), operations (\texttt{Oper}), constructors (\texttt{Constr}), methods (\texttt{Meth}), filters (\texttt{Filt}), properties (\texttt{Prop}), attributes (\texttt{Attr}), variables (\texttt{Var}), families (\texttt{Fam}), and info classes (\texttt{InfoClass}). One \texttt{ManSection} should only describe several of such items when these are very closely
related.

 Each element for an item corresponding to a \textsf{GAP} function can be followed by a \texttt{Returns} element. In output versions of the document the string ``Returns: '' will be put in front of the content text. The text in the \texttt{Returns} element should usually be a short hint about the type of object returned by
the function. This is intended to give a good mnemonic for the use of a
function (together with a good choice of names for the formal arguments).

 \texttt{ManSection}s are also sectioning elements which count as subsections. Usually there
should be no \texttt{Heading}-element in a \texttt{ManSection}, in that case a heading is generated automatically from the first \texttt{Func}-like element. Sometimes this default behaviour does not look appropriate, for
example when there are several \texttt{Func}-like elements. For such cases an optional \texttt{Heading} is allowed. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Func{\textgreater}}}}\label{Func}
\logpage{[ 3, 4, 2 ]}
\hyperdef{L}{X7C41A7B5845205C4}{}
{
 \index{Func@\texttt{Func}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Func EMPTY>
  <!ATTLIST Func Name  CDATA #REQUIRED
                 Label CDATA #IMPLIED
                 Arg   CDATA #REQUIRED
                 Comm  CDATA #IMPLIED>
\end{Verbatim}
 This element is used within a \texttt{ManSection} element to specify the usage of a function. The \texttt{Name} attribute is required and its value is the name of the function. The value of
the \texttt{Arg} attribute (also required) contains the full list of arguments including
optional parts, which are denoted by square brackets. The argument names can
be separated by whitespace, commas or the square brackets for the optional
arguments, like \texttt{"grp[,{\nobreakspace}elm]"} or \texttt{"xx[y[z]{\nobreakspace}]"}. If \textsf{GAP} options are used, this can be followed by a colon \texttt{:} and one or more assignments, like \texttt{"n[,{\nobreakspace}r]: tries := 100"}.

 The name of the function is also used as label for cross referencing. When the
name of the function appears in the text of the document it should \emph{always} be written with the \texttt{Ref} element, see{\nobreakspace}\ref{Ref}. This allows to use a unique typesetting style for function names and
automatic cross referencing.

 If the optional \texttt{Label} attribute is given, it is appended (with a colon \texttt{:} in between) to the name of the function for cross referencing purposes. The
text of the label can also appear in the document text. So, it should be a
kind of short explanation.
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  <Func Arg="x[, y]" Name="LibFunc" Label="for my objects"/>
\end{Verbatim}
 The optional \texttt{Comm} attribute should be a short description of the function, usually at most one
line long (this is currently nowhere used).

 This element automatically produces an index entry with the name of the
function and, if present, the text of the \texttt{Label} attribute as subentry (see also{\nobreakspace}\ref{TheIndex} and{\nobreakspace}\ref{Index}). }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Oper{\textgreater}}}}\logpage{[ 3, 4, 3 ]}
\hyperdef{L}{X7A15825E818A81CD}{}
{
 \index{Oper@\texttt{Oper}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Oper EMPTY>
  <!ATTLIST Oper Name  CDATA #REQUIRED
                 Label CDATA #IMPLIED
                 Arg   CDATA #REQUIRED
                 Comm  CDATA #IMPLIED>
\end{Verbatim}
 This element is used within a \texttt{ManSection} element to specify the usage of an operation. The attributes are used exactly
in the same way as in the \texttt{Func} element (see \ref{Func}).

 Note that multiple descriptions of the same operation may occur in a document
because there may be several declarations in \textsf{GAP}. Furthermore there may be several \texttt{ManSection}s for methods of this operation (see{\nobreakspace}\ref{Meth}) which also use the same name. For reference purposes these must be
distinguished by different \texttt{Label} attributes. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Constr{\textgreater}}}}\logpage{[ 3, 4, 4 ]}
\hyperdef{L}{X7FBFD7A3786C7CAB}{}
{
 \index{Constr@\texttt{Constr}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Constr EMPTY>
  <!ATTLIST Constr Name  CDATA #REQUIRED
                   Label CDATA #IMPLIED
                   Arg   CDATA #REQUIRED
                   Comm  CDATA #IMPLIED>
\end{Verbatim}
 This element is used within a \texttt{ManSection} element to specify the usage of a constructor. The attributes are used exactly
in the same way as in the \texttt{Func} element (see \ref{Func}).

 Note that multiple descriptions of the same constructor may occur in a
document because there may be several declarations in \textsf{GAP}. Furthermore there may be several \texttt{ManSection}s for methods of this constructor (see{\nobreakspace}\ref{Meth}) which also use the same name. For reference purposes these must be
distinguished by different \texttt{Label} attributes. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Meth{\textgreater}}}}\label{Meth}
\logpage{[ 3, 4, 5 ]}
\hyperdef{L}{X81196E2B7F286A01}{}
{
 \index{Meth@\texttt{Meth}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Meth EMPTY>
  <!ATTLIST Meth Name  CDATA #REQUIRED
                 Label CDATA #IMPLIED
                 Arg   CDATA #REQUIRED
                 Comm  CDATA #IMPLIED>
\end{Verbatim}
 This element is used within a \texttt{ManSection} element to specify the usage of a method. The attributes are used exactly in
the same way as in the \texttt{Func} element (see \ref{Func}).

 Frequently, an operation is implemented by several different methods.
Therefore it seems to be interesting to document them independently. This is
possible by using the same method name in different \texttt{ManSection}s. It is however required that these subsections and those describing the
corresponding operation are distinguished by different \texttt{Label} attributes. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Filt{\textgreater}}}}\logpage{[ 3, 4, 6 ]}
\hyperdef{L}{X7D8D2C38828D5854}{}
{
 \index{Filt@\texttt{Filt}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Filt EMPTY>
  <!ATTLIST Filt Name  CDATA #REQUIRED
                 Label CDATA #IMPLIED
                 Arg   CDATA #IMPLIED
                 Comm  CDATA #IMPLIED
                 Type  CDATA #IMPLIED>
\end{Verbatim}
 This element is used within a \texttt{ManSection} element to specify the usage of a filter. The first four attributes are used
in the same way as in the \texttt{Func} element (see \ref{Func}), except that the \texttt{Arg} attribute is optional.

 The \texttt{Type} attribute can be any string, but it is thought to be something like ``\texttt{Category}'' or ``\texttt{Representation}''. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Prop{\textgreater}}}}\logpage{[ 3, 4, 7 ]}
\hyperdef{L}{X7D6400A67C30B752}{}
{
 \index{Prop@\texttt{Prop}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Prop EMPTY>
  <!ATTLIST Prop Name  CDATA #REQUIRED
                 Label CDATA #IMPLIED
                 Arg   CDATA #REQUIRED
                 Comm  CDATA #IMPLIED>
\end{Verbatim}
 This element is used within a \texttt{ManSection} element to specify the usage of a property. The attributes are used exactly in
the same way as in the \texttt{Func} element (see \ref{Func}).

 }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Attr{\textgreater}}}}\logpage{[ 3, 4, 8 ]}
\hyperdef{L}{X78CEEC5986987A97}{}
{
 \index{Attr@\texttt{Attr}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Attr EMPTY>
  <!ATTLIST Attr Name  CDATA #REQUIRED
                 Label CDATA #IMPLIED
                 Arg   CDATA #REQUIRED
                 Comm  CDATA #IMPLIED>
\end{Verbatim}
 This element is used within a \texttt{ManSection} element to specify the usage of an attribute (in \textsf{GAP}). The attributes are used exactly in the same way as in the \texttt{Func} element (see \ref{Func}).

 }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Var{\textgreater}}}}\logpage{[ 3, 4, 9 ]}
\hyperdef{L}{X7C3AACBE7BC6AABF}{}
{
 \index{Var@\texttt{Var}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Var  EMPTY>
  <!ATTLIST Var  Name  CDATA #REQUIRED
                 Label CDATA #IMPLIED
                 Comm  CDATA #IMPLIED>
\end{Verbatim}
 This element is used within a \texttt{ManSection} element to document a global variable. The attributes are used exactly in the
same way as in the \texttt{Func} element (see \ref{Func}) except that there is no \texttt{Arg} attribute.

 }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Fam{\textgreater}}}}\logpage{[ 3, 4, 10 ]}
\hyperdef{L}{X85EE992E7FED2FE6}{}
{
 \index{Fam@\texttt{Fam}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Fam  EMPTY>
  <!ATTLIST Fam  Name  CDATA #REQUIRED
                 Label CDATA #IMPLIED
                 Comm  CDATA #IMPLIED>
\end{Verbatim}
 This element is used within a \texttt{ManSection} element to document a family. The attributes are used exactly in the same way
as in the \texttt{Func} element (see \ref{Func}) except that there is no \texttt{Arg} attribute.

 }


\subsection{\textcolor{Chapter }{\texttt{{\textless}InfoClass{\textgreater}}}}\logpage{[ 3, 4, 11 ]}
\hyperdef{L}{X78F0D4D1811E5BAE}{}
{
 \index{InfoClass@\texttt{InfoClass}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT InfoClass EMPTY>
  <!ATTLIST InfoClass Name  CDATA #REQUIRED
                      Label CDATA #IMPLIED
                      Comm  CDATA #IMPLIED>
\end{Verbatim}
 This element is used within a \texttt{ManSection} element to document an info class. The attributes are used exactly in the same
way as in the \texttt{Func} element (see \ref{Func}) except that there is no \texttt{Arg} attribute.

 }

 }


\section{\textcolor{Chapter }{Cross Referencing and Citations}}\logpage{[ 3, 5, 0 ]}
\hyperdef{L}{X78595FB585569617}{}
{
 Cross referencing in the \textsf{GAPDoc} system is somewhat different to the usual {\LaTeX} cross referencing in so far, that a reference knows ``which type of object'' it is referencing. For example a ``reference to a function'' is distinguished from a ``reference to a chapter''. The idea of this is, that the markup must contain this information such that
the converters can produce better output. The HTML converter can for example
typeset a function reference just as the name of the function with a link to
the description of the function, or a chapter reference as a number with a
link in the other case.

 Referencing is done with the \texttt{Ref} element:
\subsection{\textcolor{Chapter }{\texttt{{\textless}Ref{\textgreater}}}}\label{Ref}
\logpage{[ 3, 5, 1 ]}
\hyperdef{L}{X8656F2338007406E}{}
{
 \index{Ref@\texttt{Ref}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Ref EMPTY>
  <!ATTLIST Ref Func      CDATA #IMPLIED
                Oper      CDATA #IMPLIED
                Constr    CDATA #IMPLIED
                Meth      CDATA #IMPLIED
                Filt      CDATA #IMPLIED
                Prop      CDATA #IMPLIED
                Attr      CDATA #IMPLIED
                Var       CDATA #IMPLIED
                Fam       CDATA #IMPLIED
                InfoClass CDATA #IMPLIED
                Chap      CDATA #IMPLIED
                Sect      CDATA #IMPLIED
                Subsect   CDATA #IMPLIED
                Appendix  CDATA #IMPLIED
                Text      CDATA #IMPLIED

                Label     CDATA #IMPLIED
                BookName  CDATA #IMPLIED
                Style (Text | Number) #IMPLIED>  <!-- normally automatic -->
\end{Verbatim}
 The \texttt{Ref} element is defined to be \texttt{EMPTY}. If one of the attributes \texttt{Func}, \texttt{Oper}, \texttt{Constr}, \texttt{Meth}, \texttt{Prop}, \texttt{Attr}, \texttt{Var}, \texttt{Fam}, \texttt{InfoClass}, \texttt{Chap}, \texttt{Sect}, \texttt{Subsect}, \texttt{Appendix} is given then there must be exactly one of these, making the reference one to
the corresponding object. The \texttt{Label} attribute can be specified in addition to make the reference unique, for
example if more than one method with a given name is present. (Note that there
is no way to specify in the DTD that exactly one of the first listed
attributes must be given, this is an additional rule.)

 A reference to a \texttt{Label} element defined below (see \ref{Label}) is done by giving the \texttt{Label} attribute and optionally the \texttt{Text} attribute. If the \texttt{Text} attribute is present its value is typeset in place of the \texttt{Ref} element, if linking is possible (for example in HTML). If this is not
possible, the section number is typeset. This type of reference is also used
for references to tables (see \ref{Table}).

  An external reference into another book can be specified by using the \texttt{BookName} attribute. In this case the \texttt{Label} attribute or, if this is not given, the function or section like attribute, is
used to resolve the reference. The generated reference points to the first hit
when asking ``?book name: label'' inside \textsf{GAP}.

 The optional attribute \texttt{Style} can take only the values \texttt{Text} and \texttt{Number}. It can be used with references to sectioning units and it gives a hint to
the converter programs, whether an explicit section number is generated or
text. Normally all references to sections generate numbers and references to a \textsf{GAP} object generate the name of the corresponding object with some additional link
or sectioning information, which is the behavior of \texttt{Style="Text"}. In case \texttt{Style="Number"} in all cases an explicit section number is generated. So
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  <Ref Subsect="Func" Style="Text"/> described in section
  <Ref Subsect="Func" Style="Number"/>
\end{Verbatim}
 produces: \hyperref[Func]{`\texttt{{\textless}Func{\textgreater}}'} described in section \ref{Func}. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Label{\textgreater}}}}\label{Label}
\logpage{[ 3, 5, 2 ]}
\hyperdef{L}{X7C85CA5484344DB5}{}
{
 \index{Label@\texttt{Label}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Label EMPTY>
  <!ATTLIST Label Name CDATA #REQUIRED>
\end{Verbatim}
 This element is used to define a label for referencing a certain position in
the document, if this is possible. If an exact reference is not possible (like
in a printed version of the document) a reference to the corresponding
subsection is generated. The value of the \texttt{Name} attribute must be unique under all \texttt{Label} elements. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Cite{\textgreater}}}}\label{Cite}
\logpage{[ 3, 5, 3 ]}
\hyperdef{L}{X851DE9D279D8FB04}{}
{
 \index{Cite@\texttt{Cite}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Cite EMPTY>
  <!ATTLIST Cite Key CDATA #REQUIRED
                 Where CDATA #IMPLIED>
\end{Verbatim}
 This element is for bibliography citations. It is \texttt{EMPTY} by definition. The attribute \texttt{Key} is the key for a lookup in a Bib{\TeX} database that has to be specified in the \texttt{Bibliography} element (see \ref{Bibliography}). The value of the \texttt{Where} attribute specifies the position in the document as in the corresponding {\LaTeX} syntax \texttt{\texttt{\symbol{92}}cite[Where value]\texttt{\symbol{123}}Key
value\texttt{\symbol{125}}}. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Index{\textgreater}}}}\label{Index}
\logpage{[ 3, 5, 4 ]}
\hyperdef{L}{X811042BA78843777}{}
{
 \index{Index@\texttt{Index}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Index (%InnerText;|Subkey)*>
  <!ATTLIST Index Key    CDATA #IMPLIED
                  Subkey CDATA #IMPLIED>
  <!ELEMENT Subkey (%InnerText;)*>
\end{Verbatim}
 This element generates an index entry. The content of the element is typeset
in the index. It can optionally contain a \texttt{Subkey} element. If one or both of the attributes \texttt{Key} and \texttt{Subkey} are given, then the attribute values are used for sorting the index entries.
Otherwise the content itself is used for sorting. The attributes should be
used when the content contains markup. Note that all \texttt{Func} and similar elements automatically generate index entries. If the \texttt{TheIndex} element (\ref{TheIndex}) is not present in the document all \texttt{Index} elements are ignored. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}URL{\textgreater}}}}\label{URL}
\logpage{[ 3, 5, 5 ]}
\hyperdef{L}{X81B3E46F839E1C5B}{}
{
 \index{URL@\texttt{URL}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT URL (#PCDATA|Alt|Link|LinkText)*>  <!-- Link, LinkText
       variant for case where text needs further markup -->
  <!ATTLIST URL Text CDATA #IMPLIED>   <!-- This is for output formats
                                            that have links like HTML -->
  <!ELEMENT Link     (%InnerText;)*> <!-- the URL -->
  <!ELEMENT LinkText (%InnerText;)*> <!-- text for links, can contain markup -->

\end{Verbatim}
 This element is for references into the internet. It specifies an URL and
optionally a text which can be used for a link (like in HTML or PDF versions
of the document). This can be specified in two ways: Either the URL is given
as element content and the text is given in the optional \texttt{Text} attribute (in this case the text cannot contain further markup), or the
element contains the two elements \texttt{Link} and \texttt{LinkText} which in turn contain the URL and the text, respectively. The default value
for the text is the URL itself. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Email{\textgreater}}}}\label{elEmail}
\logpage{[ 3, 5, 6 ]}
\hyperdef{L}{X8310C4F084CD9DB9}{}
{
 \index{Email@\texttt{Email}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Email (#PCDATA|Alt|Link|LinkText)*>
\end{Verbatim}
 This element type is the special case of an URL specifying an email address.
The content of the element should be the email address without any prefix like ``\texttt{mailto:}''. This address is typeset by all converters, also without any prefix. In the
case of an output document format like HTML the converter can produce a link
with a ``\texttt{mailto:}'' prefix. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Homepage{\textgreater}}}}\label{elHomepage}
\logpage{[ 3, 5, 7 ]}
\hyperdef{L}{X7D5CC4267D04D7E7}{}
{
 \index{Homepage@\texttt{Homepage}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Homepage (#PCDATA|Alt|Link|LinkText)*>
\end{Verbatim}
 This element type is the special case of an URL specifying a WWW-homepage. }

 }


\section{\textcolor{Chapter }{Structural Elements like Lists}}\logpage{[ 3, 6, 0 ]}
\hyperdef{L}{X840099DF83823686}{}
{
 The \textsf{GAPDoc} system offers some limited access to structural elements like lists,
enumerations, and tables. Although it is possible to use all {\LaTeX} constructs one always has to think about other output formats. The elements in
this section are guaranteed to produce something reasonable in all output
formats.
\subsection{\textcolor{Chapter }{\texttt{{\textless}List{\textgreater}}}}\label{List}
\logpage{[ 3, 6, 1 ]}
\hyperdef{L}{X785183F67DA402A0}{}
{
 \index{List@\texttt{List}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT List ( ((Mark,Item)|Item)+ )>
  <!ATTLIST List Only CDATA #IMPLIED
                 Not  CDATA #IMPLIED>
\end{Verbatim}
 This element produces a list. Each item in the list corresponds to an \texttt{Item} element. Every \texttt{Item} element is optionally preceded by a \texttt{Mark} element. The content of this is used as a marker for the item. Note that this
marker can be a whole word or even a sentence. It will be typeset in some
emphasized fashion and most converters will provide some indentation for the
rest of the item.

 The \texttt{Only} and \texttt{Not} attributes can be used to specify, that the list is included into the output
by only one type of converter (\texttt{Only}) or all but one type of converter (\texttt{Not}). Of course at most one of the two attributes may occur in one element. The
following values are allowed as of now: ``\texttt{LaTeX}'', ``\texttt{HTML}'', and ``\texttt{Text}''. See also the \texttt{Alt} element in \ref{Alt} for more about text alternatives for certain converters. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Mark{\textgreater}}}}\logpage{[ 3, 6, 2 ]}
\hyperdef{L}{X7B1545A9797442DC}{}
{
 \index{Mark@\texttt{Mark}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Mark ( %InnerText;)*>
\end{Verbatim}
 This element is used in the \texttt{List} element to mark items. See \ref{List} for an explanation. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Item{\textgreater}}}}\label{Item}
\logpage{[ 3, 6, 3 ]}
\hyperdef{L}{X86C204987AB4B13D}{}
{
 \index{Item@\texttt{Item}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Item ( %Text;)*>
\end{Verbatim}
 This element is used in the \texttt{List}, \texttt{Enum}, and \texttt{Table} elements to specify the items. See sections \ref{List}, \ref{Enum}, and \ref{Table} for further information. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Enum{\textgreater}}}}\label{Enum}
\logpage{[ 3, 6, 4 ]}
\hyperdef{L}{X78A52B00846562DE}{}
{
 \index{Enum@\texttt{Enum}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Enum ( Item+ )>
  <!ATTLIST Enum Only CDATA #IMPLIED
                 Not  CDATA #IMPLIED>
\end{Verbatim}
 This element is used like the \texttt{List} element (see \ref{List}) except that the items must not have marks attached to them. Instead, the
items are numbered automatically. The same comments about the \texttt{Only} and \texttt{Not} attributes as above apply. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Table{\textgreater}}}}\label{Table}
\logpage{[ 3, 6, 5 ]}
\hyperdef{L}{X7F9CAA577EB4070B}{}
{
 \index{Table@\texttt{Table}} \index{Caption@\texttt{{\textless}Caption{\textgreater}}} \index{Row@\texttt{{\textless}Row{\textgreater}}} \index{Align@\texttt{{\textless}Align{\textgreater}}} \index{HorLine@\texttt{{\textless}HorLine{\textgreater}}} \index{Item in Table@\texttt{{\textless}Item{\textgreater}} in \texttt{{\textless}Table{\textgreater}}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Table ( Caption?, (Row | HorLine)+ )>
  <!ATTLIST Table Label   CDATA #IMPLIED
                  Only    CDATA #IMPLIED
                  Not     CDATA #IMPLIED
                  Align   CDATA #REQUIRED>
                  <!-- We allow | and l,c,r, nothing else -->
  <!ELEMENT Row   ( Item+ )>
  <!ELEMENT HorLine EMPTY>
  <!ELEMENT Caption ( %InnerText;)*>
\end{Verbatim}
 A table in \textsf{GAPDoc} consists of an optional \texttt{Caption} element followed by a sequence of \texttt{Row} and \texttt{HorLine} elements. A \texttt{HorLine} element produces a horizontal line in the table. A \texttt{Row} element consists of a sequence of \texttt{Item} elements as they also occur in \texttt{List} and \texttt{Enum} elements. The \texttt{Only} and \texttt{Not} attributes have the same functionality as described in the \texttt{List} element in \ref{List}.

 The \texttt{Align} attribute is written like a {\LaTeX} tabular alignment specifier but only the letters ``\texttt{l}'', ``\texttt{r}'', ``\texttt{c}'', and ``\texttt{|}'' are allowed meaning left alignment, right alignment, centered alignment, and a
vertical line as delimiter between columns respectively.

 If the \texttt{Label} attribute is there, one can reference the table with the \texttt{Ref} element (see \ref{Ref}) using its \texttt{Label} attribute.

 Usually only simple tables should be used. If you want a complicated table in
the {\LaTeX} output you should provide alternatives for text and HTML output. Note that in
HTML-4.0 there is no possibility to interpret the ``\texttt{|}'' column separators and \texttt{HorLine} elements as intended. There are lines between all columns and rows or no lines
at all. }

 }


\section{\textcolor{Chapter }{Types of Text}}\logpage{[ 3, 7, 0 ]}
\hyperdef{L}{X7CA1E1327AFBA578}{}
{
 This section covers the markup of text. Various types of ``text'' exist. The following elements are used in the \textsf{GAPDoc} system to mark them. They mostly come in pairs, one long name which is easier
to remember and a shortcut to make the markup ``lighter''.

 Most of the following elements are thought to contain only character data and
no further markup elements. It is however necessary to allow \texttt{Alt} elements to resolve the entities described in section \ref{GDent}.
\subsection{\textcolor{Chapter }{\texttt{{\textless}Emph{\textgreater}} and \texttt{{\textless}E{\textgreater}}}}\logpage{[ 3, 7, 1 ]}
\hyperdef{L}{X7B15C428861749FD}{}
{
 \index{Emph@\texttt{Emph}} \index{E@\texttt{E}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Emph (%InnerText;)*>    <!-- Emphasize something -->
  <!ELEMENT E    (%InnerText;)*>    <!-- the same as shortcut -->
\end{Verbatim}
 This element is used to emphasize some piece of text. It may contain \texttt{\%InnerText;} (see \ref{InnerText}). }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Quoted{\textgreater}} and \texttt{{\textless}Q{\textgreater}}}}\logpage{[ 3, 7, 2 ]}
\hyperdef{L}{X80028C2483C9467E}{}
{
 \index{Quoted@\texttt{Quoted}} \index{Q@\texttt{Q}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Quoted (%InnerText;)*>   <!-- Quoted (in quotes) text -->
  <!ELEMENT Q (%InnerText;)*>        <!-- Quoted text (shortcut) -->
\end{Verbatim}
 This element is used to put some piece of text into ``{\nobreakspace}''-quotes. It may contain \texttt{\%InnerText;} (see \ref{InnerText}). }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Keyword{\textgreater}} and \texttt{{\textless}K{\textgreater}}}}\logpage{[ 3, 7, 3 ]}
\hyperdef{L}{X867BB95E7DC87014}{}
{
 \index{Keyword@\texttt{Keyword}} \index{K@\texttt{K}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Keyword (#PCDATA|Alt)*>  <!-- Keyword -->
  <!ELEMENT K (#PCDATA|Alt)*>        <!-- Keyword (shortcut) -->
\end{Verbatim}
 This element is used to mark something as a \emph{keyword}. Usually this will be a \textsf{GAP} keyword such as ``\texttt{if}'' or ``\texttt{for}''. No further markup elements are allowed within this element except for the \texttt{Alt} element, which is necessary. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Arg{\textgreater}} and \texttt{{\textless}A{\textgreater}}}}\label{Arg}
\logpage{[ 3, 7, 4 ]}
\hyperdef{L}{X86FD4CCA7F98351F}{}
{
 \index{Arg@\texttt{Arg}} \index{A@\texttt{A}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Arg (#PCDATA|Alt)*>      <!-- Argument -->
  <!ELEMENT A (#PCDATA|Alt)*>        <!-- Argument (shortcut) -->
\end{Verbatim}
 This element is used inside \texttt{Description}s in \texttt{ManSection}s to mark something as an \emph{argument} (of a function, operation, or such). It is guaranteed that the converters
typeset those exactly as in the definition of functions. No further markup
elements are allowed within this element. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Code{\textgreater}} and \texttt{{\textless}C{\textgreater}}}}\label{Code}
\logpage{[ 3, 7, 5 ]}
\hyperdef{L}{X8400998B7B3A4379}{}
{
 \index{Code@\texttt{Code}} \index{C@\texttt{C}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Code (#PCDATA|Arg|Alt)*>     <!-- GAP code -->
  <!ELEMENT C (#PCDATA|Arg|Alt)*>        <!-- GAP code (shortcut) -->
\end{Verbatim}
 This element is used to mark something as a piece of \emph{code} like for example a \textsf{GAP} expression. It is guaranteed that the converters typeset this exactly as in
the \texttt{Listing} element (compare section \ref{Listing}). The only further markup elements allowed within this element are \texttt{{\textless}Arg{\textgreater}} elements (see \ref{Arg}). }


\subsection{\textcolor{Chapter }{\texttt{{\textless}File{\textgreater}} and \texttt{{\textless}F{\textgreater}}}}\logpage{[ 3, 7, 6 ]}
\hyperdef{L}{X875AF9B4812C5249}{}
{
 \index{File@\texttt{File}} \index{F@\texttt{F}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT File (#PCDATA|Alt)*>     <!-- Filename -->
  <!ELEMENT F (#PCDATA|Alt)*>        <!-- Filename (shortcut) -->
\end{Verbatim}
 This element is used to mark something as a \emph{filename} or a \emph{pathname} in the file system. No further markup elements are allowed within this
element. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Button{\textgreater}} and \texttt{{\textless}B{\textgreater}}}}\logpage{[ 3, 7, 7 ]}
\hyperdef{L}{X7929BA7D78A977FF}{}
{
 \index{Button@\texttt{Button}} \index{B@\texttt{B}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Button (#PCDATA|Alt)*>   <!-- "Button" (also Menu, Key, ...) -->
  <!ELEMENT B (#PCDATA|Alt)*>        <!-- "Button" (shortcut) -->
\end{Verbatim}
 This element is used to mark something as a \emph{button}. It can also be used for other items in a graphical user interface like \emph{menus}, \emph{menu entries}, or \emph{keys}. No further markup elements are allowed within this element. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Package{\textgreater}}}}\logpage{[ 3, 7, 8 ]}
\hyperdef{L}{X7F4FFA877B775188}{}
{
 \index{Package@\texttt{Package}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Package (#PCDATA|Alt)*>   <!-- A package name -->
\end{Verbatim}
 This element is used to mark something as a name of a \emph{package}. This is for example used to define the entities \textsf{GAP}, \textsf{XGAP} or \textsf{GAPDoc} (see section \ref{GDent}). No further markup elements are allowed within this element. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Listing{\textgreater}}}}\label{Listing}
\logpage{[ 3, 7, 9 ]}
\hyperdef{L}{X7F531B157D656836}{}
{
 \index{Listing@\texttt{Listing}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Listing (#PCDATA)>  <!-- This is just for GAP code listings -->
  <!ATTLIST Listing Type CDATA #IMPLIED> <!-- a comment about the type of
                                              listed code, may appear in
                                              output -->
\end{Verbatim}
 This element is used to embed listings of programs into the document. Only
character data and no other elements are allowed in the content. You should \emph{not} use the character entities described in section \ref{GDent} but instead type the characters directly. Only the general XML rules from
section \ref{EnterXML} apply. Note especially the usage of \texttt{{\textless}![CDATA[} sections described there. It is guaranteed that all converters use a fixed
width font for typesetting \texttt{Listing} elements. Compare also the usage of the \texttt{Code} and \texttt{C} elements in \ref{Code}.

 The \texttt{Type} attribute contains a comment about the type of listed code. It may appear in
the output. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Log{\textgreater}} and \texttt{{\textless}Example{\textgreater}}}}\label{Log}
\logpage{[ 3, 7, 10 ]}
\hyperdef{L}{X810DEA1E83A57CFE}{}
{
 \index{Log@\texttt{Log}} \index{Example@\texttt{Example}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Example (#PCDATA)>  <!-- This is subject to the automatic
                                     example checking mechanism -->
  <!ELEMENT Log (#PCDATA)>      <!-- This not -->
\end{Verbatim}
 These two elements behave exactly like the \texttt{Listing} element (see \ref{Listing}). They are thought for protocols of \textsf{GAP} sessions. The only difference between the two is that \texttt{Example} sections are intended to be subject to an automatic manual checking mechanism
used to ensure the correctness of the \textsf{GAP} manual whereas \texttt{Log} is not touched by this (see section \ref{Sec:TestExample} for checking tools).

 To get a good layout of the examples for display in a standard terminal we
suggest to use \texttt{SizeScreen([72]);} (see \texttt{SizeScreen} (\textbf{Reference: SizeScreen})) in your \textsf{GAP} session before producing the content of \texttt{Example} elements. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Verb{\textgreater}}}}\label{Verb}
\logpage{[ 3, 7, 11 ]}
\hyperdef{L}{X7F8C4D018346B2CF}{}
{
 There is one further type of verbatim-like element.
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Verb  (#PCDATA)>
\end{Verbatim}
 The content of such an element is guaranteed to be put into an output version
exactly as it is using some fixed width font. Before the content a new line is
started. If the line after the end of the start tag consists of whitespace
only then this part of the content is skipped.

 This element is intended to be used together with the \texttt{Alt} element to specify pre-formatted ASCII alternatives for complicated \texttt{Display} formulae or \texttt{Table}s. }

 }


\section{\textcolor{Chapter }{Elements for Mathematical Formulae}}\label{MathForm}
\logpage{[ 3, 8, 0 ]}
\hyperdef{L}{X8145F6B37C04AA0A}{}
{

\subsection{\textcolor{Chapter }{\texttt{{\textless}Math{\textgreater}} and \texttt{{\textless}Display{\textgreater}}}}\label{Math}
\logpage{[ 3, 8, 1 ]}
\hyperdef{L}{X7AA02845868AA533}{}
{
 \index{Math@\texttt{Math}} \index{Display@\texttt{Display}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!-- Normal TeX math mode formula -->
  <!ELEMENT Math (#PCDATA|A|Arg|Alt)*>
  <!-- TeX displayed math mode formula -->
  <!ELEMENT Display (#PCDATA|A|Arg|Alt)*>
  <!-- Mode="M" causes <M>-style formatting -->
  <!ATTLIST Display Mode CDATA #IMPLIED>
\end{Verbatim}
 These elements are used for mathematical formulae. As described in section \ref{GDformulae} they correspond to {\LaTeX}'s math and display math mode respectively.

 The formulae are typed in as in {\LaTeX}, \emph{except} that the standard XML entities, see{\nobreakspace}\ref{XMLent} (in particular the characters \texttt{{\textless}} and \texttt{\&}), must be escaped - either by using the corresponding entities or by
enclosing the formula between ``\texttt{{\textless}![CDATA[}'' and ``\texttt{]]{\textgreater}}''. (The main reference for {\LaTeX} is \cite{La85}.)

 It is also possible to use some unicode characters for mathematical symbols
directly, provided that it can be translated by \texttt{Encode} (\ref{Encode}) into \texttt{"LaTeX"} encoding and that \texttt{SimplifiedUnicodeString} (\ref{SimplifiedUnicodeString}) with arguments \texttt{"latin1"} and \texttt{"single"} returns something sensible. Currently, we support entities \texttt{\&CC;}, \texttt{\&ZZ;}, \texttt{\&NN;}, \texttt{\&PP;}, \texttt{\&QQ;}, \texttt{\&HH;}, \texttt{\&RR;} for the corresponding black board bold letters {\ensuremath{\mathbb C}},
{\ensuremath{\mathbb Z}}, {\ensuremath{\mathbb N}}, {\ensuremath{\mathbb P}},
{\ensuremath{\mathbb Q}}, {\ensuremath{\mathbb H}} and {\ensuremath{\mathbb
R}}, respectively.

 The only element type that is allowed within the formula elements is the \texttt{Arg} or \texttt{A} element (see \ref{Arg}), which is used to typeset identifiers that are arguments to \textsf{GAP} functions or operations.

 If a \texttt{Display} element has an attribute \texttt{Mode} with value \texttt{"M"}, then the formula is formatted as in \texttt{M} elements (see{\nobreakspace}\ref{M}). Otherwise in text and HTML output the formula is shown as {\LaTeX} source code.

 For simple formulae (and you should try to make all your formulae simple!)
attempt to use the \texttt{M} element or the \texttt{Mode="M"} attribute in \texttt{Display} for which there is a well defined translation into text, which can be used for
text and HTML output versions of the document. So, if possible try to avoid
the \texttt{Math} elements and \texttt{Display} elements without attribute or provide useful text substitutes for complicated
formulae via \texttt{Alt} elements (see{\nobreakspace}\ref{Alt} and{\nobreakspace}\ref{Verb}). }


\subsection{\textcolor{Chapter }{\texttt{{\textless}M{\textgreater}}}}\label{M}
\logpage{[ 3, 8, 2 ]}
\hyperdef{L}{X7ABF42328467E966}{}
{
 \index{M@\texttt{M}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!-- Math with well defined translation to text output -->
  <!ELEMENT M (#PCDATA|A|Arg|Alt)*>
\end{Verbatim}
 The ``\texttt{M}'' element type is intended for formulae in the running text for which there is a
sensible text version. For the {\LaTeX} version of a \textsf{GAPDoc} document the \texttt{M} and \texttt{Math} elements are equivalent. The remarks in \ref{Math} about special characters and the \texttt{Arg} element apply here as well. A document which has all formulae enclosed in \texttt{M} elements can be well readable in text terminal output and printed output
versions.

 Compared to former versions of \textsf{GAPDoc} many more formulae can be put into \texttt{M} elements. Most modern terminal emulations support unicode characters and many
mathematical symbols can now be represented by such characters. But even if a
terminal can only display ASCII characters, the user will see some not too bad
representation of a formula.

 As examples, here are some {\LaTeX} macros which have a sensible ASCII translation and are guaranteed to be
translated accordingly by text (and HTML) converters (for a full list of
handled Macros see \texttt{RecNames(TEXTMTRANSLATIONS)}): \begin{center}
\begin{tabular}{|l|l|}\hline
\texttt{\symbol{92}}ast&
\texttt{*}\\
\hline
\texttt{\symbol{92}}bf&
\texttt{}\\
\hline
\texttt{\symbol{92}}bmod&
\texttt{mod}\\
\hline
\texttt{\symbol{92}}cdot&
\texttt{*}\\
\hline
\texttt{\symbol{92}}colon&
\texttt{:}\\
\hline
\texttt{\symbol{92}}equiv&
\texttt{=}\\
\hline
\texttt{\symbol{92}}geq&
\texttt{{\textgreater}=}\\
\hline
\texttt{\symbol{92}}germ&
\texttt{}\\
\hline
\texttt{\symbol{92}}hookrightarrow&
\texttt{-{\textgreater}}\\
\hline
\texttt{\symbol{92}}iff&
\texttt{{\textless}={\textgreater}}\\
\hline
\texttt{\symbol{92}}langle&
\texttt{{\textless}}\\
\hline
\texttt{\symbol{92}}ldots&
\texttt{...}\\
\hline
\texttt{\symbol{92}}left&
\texttt{{\nobreakspace}}\\
\hline
\texttt{\symbol{92}}leq&
\texttt{{\textless}=}\\
\hline
\texttt{\symbol{92}}leftarrow&
\texttt{{\textless}-}\\
\hline
\texttt{\symbol{92}}Leftarrow&
\texttt{{\textless}=}\\
\hline
\texttt{\symbol{92}}limits&
\texttt{{\nobreakspace}}\\
\hline
\texttt{\symbol{92}}longrightarrow&
\texttt{--{\textgreater}}\\
\hline
\texttt{\symbol{92}}Longrightarrow&
\texttt{=={\textgreater}}\\
\hline
\texttt{\symbol{92}}mapsto&
\texttt{-{\textgreater}}\\
\hline
\texttt{\symbol{92}}mathbb&
\texttt{{\nobreakspace}}\\
\hline
\texttt{\symbol{92}}mathop&
\texttt{{\nobreakspace}}\\
\hline
\texttt{\symbol{92}}mid&
\texttt{|}\\
\hline
\texttt{\symbol{92}}pmod&
\texttt{mod}\\
\hline
\texttt{\symbol{92}}prime&
\texttt{'}\\
\hline
\texttt{\symbol{92}}rangle&
\texttt{{\textgreater}}\\
\hline
\texttt{\symbol{92}}right&
\texttt{{\nobreakspace}}\\
\hline
\texttt{\symbol{92}}rightarrow&
\texttt{-{\textgreater}}\\
\hline
\texttt{\symbol{92}}Rightarrow&
\texttt{={\textgreater}}\\
\hline
\texttt{\symbol{92}}rm, \texttt{\symbol{92}}sf, \texttt{\symbol{92}}textrm,
\texttt{\symbol{92}}text&
\texttt{}\\
\hline
\texttt{\symbol{92}}setminus&
\texttt{\texttt{\symbol{92}}}\\
\hline
\texttt{\symbol{92}}thinspace&
\texttt{ }\\
\hline
\texttt{\symbol{92}}times&
\texttt{x}\\
\hline
\texttt{\symbol{92}}to&
\texttt{-{\textgreater}}\\
\hline
\texttt{\symbol{92}}vert&
\texttt{|}\\
\hline
\texttt{\symbol{92}}!&
\texttt{}\\
\hline
\texttt{\symbol{92}},&
\texttt{}\\
\hline
\texttt{\symbol{92}};&
\texttt{{\nobreakspace}}\\
\hline
\texttt{\symbol{92}}\texttt{\symbol{123}}&
\texttt{\texttt{\symbol{123}}}\\
\hline
\texttt{\symbol{92}}\texttt{\symbol{125}}&
\texttt{\texttt{\symbol{125}}}\\
\hline
\end{tabular}\\[2mm]
\textbf{Table: }{\LaTeX} macros with special text translation\end{center}

 In all other macros only the backslash is removed (except for some macros
describing more exotic symbols). Whitespace is normalized (to one blank) but
not removed. Note that whitespace is not added, so you may want to add a few
more spaces than you usually do in your {\LaTeX} documents.

 Braces \texttt{\texttt{\symbol{123}}\texttt{\symbol{125}}} are removed in general, however pairs of double braces are converted to one
pair of braces. This can be used to write \texttt{{\textless}M{\textgreater}x\texttt{\symbol{94}}\texttt{\symbol{123}}12\texttt{\symbol{125}}{\textless}/M{\textgreater}} for \texttt{x\texttt{\symbol{94}}12} and \texttt{{\textless}M{\textgreater}x{\textunderscore}\texttt{\symbol{123}}\texttt{\symbol{123}}i+1\texttt{\symbol{125}}\texttt{\symbol{125}}{\textless}/M{\textgreater}} for \texttt{x{\textunderscore}\texttt{\symbol{123}}i+1\texttt{\symbol{125}}}.

 }

 }


\section{\textcolor{Chapter }{Everything else}}\label{sec:misc}
\logpage{[ 3, 9, 0 ]}
\hyperdef{L}{X7A0D26B180BEDE37}{}
{

\subsection{\textcolor{Chapter }{\texttt{{\textless}Alt{\textgreater}}}}\label{Alt}
\logpage{[ 3, 9, 1 ]}
\hyperdef{L}{X850E69017945AE3E}{}
{
 \index{Alt@\texttt{Alt}} This element is used to specify alternatives for different output formats
within normal text. See also sections \ref{List}, \ref{Enum}, and \ref{Table} for alternatives in lists and tables.
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Alt (%InnerText;)*>  <!-- This is only to allow "Only" and
                                      "Not" attributes for normal text -->
  <!ATTLIST Alt Only CDATA #IMPLIED
                Not  CDATA #IMPLIED>
\end{Verbatim}
 Of course exactly one of the two attributes must occur in one element. The
attribute values must be one word or a list of words, separated by spaces or
commas. The words which are currently recognized by the converter programs
contained in \textsf{GAPDoc} are: ``\texttt{LaTeX}'', ``\texttt{HTML}'', and ``\texttt{Text}''. If the \texttt{Only} attribute is specified then only the corresponding converter will include the
content of the element into the output document. If the \texttt{Not} attribute is specified the corresponding converter will ignore the content of
the element. You can use other words to specify special alternatives for other
converters of \textsf{GAPDoc} documents.

 In the case of ``\texttt{HTML}'' there is a second word which is recognized and this can either be ``\texttt{MathJax}'' or ``\texttt{noMathJax}''. For example a pair of \texttt{Alt} elements with \texttt{{\textless}Alt Only="HTML noMathJax"{\textgreater}...} and \texttt{{\textless}Alt Not="HTML noMathJax"{\textgreater}...} could provide special content for the case of HTML output without use of \textsf{MathJax} and every other output.

 We fix a rule for handling the content of an \texttt{Alt} element with \texttt{Only} attribute. In their content code for the corresponding output format is
included directly. So, in case of HTML the content is HTML code, in case of {\LaTeX} the content is {\LaTeX} code. The converters don't apply any handling of special characters to this
content. In the case of {\LaTeX} the formatting of the code is not changed.

 Within the element only \texttt{\%InnerText;} (see \ref{InnerText}) is allowed. This is to ensure that the same set of chapters, sections, and
subsections show up in all output formats. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Par{\textgreater}} and \texttt{{\textless}P{\textgreater}}}}\label{Par}
\logpage{[ 3, 9, 2 ]}
\hyperdef{L}{X85D23A648444069F}{}
{
 \index{Par@\texttt{Par}} \index{P@\texttt{P}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Par EMPTY>    <!-- this is intentionally empty! -->
  <!ELEMENT P EMPTY>      <!-- the same as shortcut  -->
\end{Verbatim}
 This \texttt{EMPTY} element marks the boundary of paragraphs. Note that an empty line in the input
does not mark a new paragraph as opposed to the {\LaTeX} convention.

 (Remark: it would be much easier to parse a document and to understand its
sectioning and paragraph structure when there was an element whose \emph{content} is the text of a paragraph. But in practice many paragraph boundaries are
implicitly clear which would make it somewhat painful to enclose each
paragraph in extra tags. The introduction of the \texttt{P} or \texttt{Par} elements as above delegates this pain to the writer of a conversion program
for \textsf{GAPDoc} documents.) }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Br{\textgreater}}}}\label{Br}
\logpage{[ 3, 9, 3 ]}
\hyperdef{L}{X7A3EF0647B10C1EC}{}
{
 \index{Br@\texttt{Br}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Br EMPTY>     <!-- a forced line break  -->
\end{Verbatim}
 This element can be used to force a line break in the output versions of a \textsf{GAPDoc} element, it does not start a new paragraph. Please, do not use this instead of
a \texttt{Par} element, this would often lead to ugly output versions of your document. }


\subsection{\textcolor{Chapter }{\texttt{{\textless}Ignore{\textgreater}}}}\label{Ignore}
\logpage{[ 3, 9, 4 ]}
\hyperdef{L}{X7A81FB717A30B485}{}
{
 \index{Ignore@\texttt{Ignore}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Ignore (%Text;| Chapter | Section | Subsection | ManSection |
                    Heading)*>
  <!ATTLIST Ignore Remark CDATA #IMPLIED>
\end{Verbatim}
 This element can appear anywhere. Its content is ignored by the standard
converters. It can be used, for example, to include data which are not part of
the actual \textsf{GAPDoc} document, like source code, or to make not finished parts of the document
invisible.

 Of course, one can use special converter programs which extract the contents
of \texttt{Ignore} elements. Information on the type of the content can be stored in the optional
attribute \texttt{Remark}. }

 }

 }


\chapter{\textcolor{Chapter }{Distributing a Document into Several Files}}\label{Distributing}
\logpage{[ 4, 0, 0 ]}
\hyperdef{L}{X7A3355C07F57C280}{}
{
  In \textsf{GAPDoc} there are facilities to distribute a single document over several files. This
is for example interesting, if one wants to store the documentation of some
code in the same file as the code itself. Or, if one just wants to store
chapters of a document in separate files. There is a set of conventions how
this is done and some tools to collect the text for further processing.

 The technique can also be used to distribute and collect other types of
documents into respectively from several files (e.g., source code, examples).


\section{\textcolor{Chapter }{The Conventions}}\label{DistrConv}
\logpage{[ 4, 1, 0 ]}
\hyperdef{L}{X7CE078A07E8256DC}{}
{
 \index{Include@\texttt{{\textless}\#Include{\textgreater}}} \index{GAPDoc@\texttt{{\textless}\#GAPDoc{\textgreater}}}  In this description we use the string \texttt{GAPDoc} for marking pieces of a document to collect.

 Pieces of documentation that shall be incorporated into another document are
marked as follows:
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  ##  <#GAPDoc Label="MyPiece">
  ##  <E>This</E> is the piece.
  ##  The hash characters are removed.
  ##  <#/GAPDoc>
\end{Verbatim}
 This piece is then included into another file by a statement like:  \texttt{{\textless}\#Include Label="MyPiece"{\textgreater}}  Here are the exact rules, how pieces are gathered:
\begin{itemize}
\item  All lines up to a line containing the character sequence ``\texttt{{\textless}\#GAPDoc{\nobreakspace}Label="}'' (exactly one space character) are ignored. The characters on the same line
before this sequence are stored as ``prefix''. The characters after the sequence up to the next double quotes character
(which should not contain whitespace) are stored as ``label''. All other characters in the line are ignored.
\item  The following lines up to a line containing the character sequence ``\texttt{{\textless}\#/GAPDoc{\textgreater}}'' are stored under the label. These lines are processed as follows: The longest
possible substring from the beginning of the line that equals the
corresponding substring of the prefix is removed.
\end{itemize}
 Having stored a list of labels and pieces of text gathered as above this can
be used as follows.
\begin{itemize}
\item  In \textsf{GAPDoc} documentation files all statements of the form ``\texttt{{\textless}\#Include Label="Key"{\textgreater}}'' are replaced by the sequence of lines stored under the label \texttt{Key}.
\item  Additionally, every occurrence of a statement of the form ``\texttt{{\textless}\#Include SYSTEM "Filename"{\textgreater}}'' is replaced by the whole file stored under the name \texttt{Filename} in the file system.
\item  These substitutions are done recursively (although one should probably avoid
to use this extensively).
\end{itemize}
 Here is another example:
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  # # <#GAPDoc Label="AnotherPiece">  some characters
  # # This text is not indented.
  #  This text is indented by one blank.
  #Not indented.
  #<#/GAPDoc>
\end{Verbatim}
 replaces \texttt{{\textless}\#Include Label="AnotherPiece"{\textgreater}} by
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  This text is not indented.
   This text is indented by one blank.
  Not indented.
\end{Verbatim}
 Since these rules are very simple it is quite easy to write a program in
almost any programming language which does this gathering of text pieces and
the substitutions. In \textsf{GAPDoc} there is the \textsf{GAP} function \texttt{ComposedDocument} (\ref{ComposedDocument}) which does this.

 Note that the XML-tag-like markup we have used here is not a legal XML markup,
since the hash character is not allowed in element names. The mechanism
described here is a preprocessing step which composes a document. }


\section{\textcolor{Chapter }{A Tool for Collecting a Document}}\logpage{[ 4, 2, 0 ]}
\hyperdef{L}{X81E07B0F83EBDA5F}{}
{


\subsection{\textcolor{Chapter }{ComposedDocument}}
\logpage{[ 4, 2, 1 ]}\nobreak
\hyperdef{L}{X857D77557D12559D}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ComposedDocument({\mdseries\slshape tagname, path, main, source[, info]})\index{ComposedDocument@\texttt{ComposedDocument}}
\label{ComposedDocument}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ComposedXMLString({\mdseries\slshape path, main, source[, info]})\index{ComposedXMLString@\texttt{ComposedXMLString}}
\label{ComposedXMLString}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a document as string, or a list with this string and information about the
source positions



 The argument \mbox{\texttt{\mdseries\slshape tagname}} is the string used for the pseudo elements which mark the pieces of a document
to collect. (In \ref{DistrConv} we used \texttt{GAPDoc} as \mbox{\texttt{\mdseries\slshape tagname}}. The second function \texttt{ComposedXMLString}\texttt{( ... )} is an abbreviation for \texttt{ComposedDocument}\texttt{("GAPDoc", ... )}.

 The argument \mbox{\texttt{\mdseries\slshape path}} must be a path to some directory (as string or directory object), \mbox{\texttt{\mdseries\slshape main}} the name of a file and \mbox{\texttt{\mdseries\slshape source}} a list of file names. These file names are relative to \mbox{\texttt{\mdseries\slshape path}}, except they start with \texttt{"/"} to specify an absolute path or they start with \texttt{"gap://"} to specify a file relative to the \textsf{GAP} roots (see \texttt{FilenameGAP} (\ref{FilenameGAP})). The document is constructed via the mechanism described in
Section{\nobreakspace}\ref{DistrConv}.

 First the files given in \mbox{\texttt{\mdseries\slshape source}} are scanned for chunks of the document marked by \texttt{{\textless}\#\mbox{\texttt{\mdseries\slshape tagname}} Label="..."{\textgreater}} and \texttt{{\textless}/\#\mbox{\texttt{\mdseries\slshape tagname}}{\textgreater}} pairs. Then the file \mbox{\texttt{\mdseries\slshape main}} is read and all \texttt{{\textless}\#Include ... {\textgreater}}-tags are substituted recursively by other files or chunks of documentation
found in the first step, respectively.

 If the optional argument \mbox{\texttt{\mdseries\slshape info}} is given and set to \texttt{true} this function returns a list \texttt{[str, origin]}, where \texttt{str} is a string containing the composed document and \texttt{origin} is a sorted list of entries of the form \texttt{[pos, filename, line]}. Here \texttt{pos} runs through all character positions of starting lines or text pieces from
different files in \texttt{str}. The \texttt{filename} and \texttt{line} describe the origin of this part of the collected document.

 Without the fourth argument only the string \texttt{str} is returned.

 By default \texttt{ComposedDocument} runs into an error if an \texttt{{\textless}\#Include ...{\textgreater}}-tag cannot be substituted (because a file or chunk is missing). This
behaviour can be changed by setting \texttt{DOCCOMPOSEERROR := false;}. Then the missing parts are substituted by a short note about what is
missing. Of course, this feature is only useful if the resulting document is a
valid XML document (e.g., when the missing pieces are complete paragraphs or
sections).


\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@doc := ComposedDocument("GAPDoc", "/my/dir", "manual.xml", |
  !gapprompt@>| !gapinput@["../lib/func.gd", "../lib/func.gi"], true);;|
\end{Verbatim}
 }



\subsection{\textcolor{Chapter }{OriginalPositionDocument}}
\logpage{[ 4, 2, 2 ]}\nobreak
\hyperdef{L}{X86D1141E7EDCAAC8}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{OriginalPositionDocument({\mdseries\slshape srcinfo, pos})\index{OriginalPositionDocument@\texttt{OriginalPositionDocument}}
\label{OriginalPositionDocument}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
A pair \texttt{[filename, linenumber]}.



 Here \mbox{\texttt{\mdseries\slshape srcinfo}} must be a data structure as returned as second entry by \texttt{ComposedDocument} (\ref{ComposedDocument}) called with \mbox{\texttt{\mdseries\slshape info}}=\texttt{true}. It returns for a given position \mbox{\texttt{\mdseries\slshape pos}} in the composed document the file name and line number from which that text
was collected. }



\subsection{\textcolor{Chapter }{FilenameGAP}}
\logpage{[ 4, 2, 3 ]}\nobreak
\hyperdef{L}{X81E67E4678FB6843}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{FilenameGAP({\mdseries\slshape fname})\index{FilenameGAP@\texttt{FilenameGAP}}
\label{FilenameGAP}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
file name as string or fail



 This functions returns the full path of a file with name \mbox{\texttt{\mdseries\slshape fname}} relative to a \textsf{GAP} root path, or \texttt{fail} if such a file does not exist. The argument \mbox{\texttt{\mdseries\slshape fname}} can optionally start with the prefix \texttt{"gap://"} which will be removed.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@FilenameGAP("hsdkfhs.g");|
  fail
  !gapprompt@gap>| !gapinput@FilenameGAP("lib/system.g");|
  "/usr/local/gap4/lib/system.g"
  !gapprompt@gap>| !gapinput@FilenameGAP("gap://lib/system.g");|
  "/usr/local/gap4/lib/system.g"
\end{Verbatim}
 }

 }

 }


\chapter{\textcolor{Chapter }{The Converters and an XML Parser}}\label{ch:conv}
\logpage{[ 5, 0, 0 ]}
\hyperdef{L}{X845E7FDC7C082CC4}{}
{
  The \textsf{GAPDoc} package contains a set of programs which allow us to convert a \textsf{GAPDoc} book into several output versions and to make them available to \textsf{GAP}'s online help.

 Currently the following output formats are provided: text for browsing inside
a terminal running \textsf{GAP}, {\LaTeX} with \texttt{hyperref}-package for cross references via hyperlinks and HTML for reading with a
Web-browser.


\section{\textcolor{Chapter }{Producing Documentation from Source Files}}\label{MakeDoc}
\logpage{[ 5, 1, 0 ]}
\hyperdef{L}{X7D1BB5867C13FA14}{}
{
  Here we explain how to use the functions which are described in more detail in
the following sections. We assume that we have the main file \texttt{MyBook.xml} of a book \texttt{"MyBook"} in the directory \texttt{/my/book/path}. This contains \texttt{{\textless}\#Include ...{\textgreater}}-statements as explained in Chapter{\nobreakspace}\ref{Distributing}. These refer to some other files as well as pieces of text which are found in
the comments of some \textsf{GAP} source files \texttt{../lib/a.gd} and \texttt{../lib/b.gi} (relative to the path above). A Bib{\TeX} database \texttt{MyBook.bib} for the citations is also in the directory given above. We want to produce a
text-, \texttt{pdf-} and HTML-version of the document. (A {\LaTeX} version of the manual is produced, so it is also easy to compile \texttt{dvi}-, and postscript-versions.)

 All the commands shown in this Section are collected in the single function \texttt{MakeGAPDocDoc} (\ref{MakeGAPDocDoc}).

 First we construct the complete XML-document as a string with \texttt{ComposedDocument} (\ref{ComposedDocument}). This interprets recursively the \texttt{{\textless}\#Include ...{\textgreater}}-statements.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@path := Directory("/my/book/path");;|
  !gapprompt@gap>| !gapinput@main := "MyBook.xml";;|
  !gapprompt@gap>| !gapinput@files := ["../lib/a.gd", "../lib/b.gi"];;|
  !gapprompt@gap>| !gapinput@bookname := "MyBook";;|
  !gapprompt@gap>| !gapinput@doc := ComposedDocument("GAPDoc", path, main, files, true);;|
\end{Verbatim}
 Now \texttt{doc} is a list with two entries, the first is a string containing the XML-document,
the second gives information from which files and locations which part of the
document was collected. This is useful in the next step, if there are any
errors in the document.

 Next we parse the document and store its structure in a tree-like data
structure. The commands for this are \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}) and \texttt{CheckAndCleanGapDocTree} (\ref{CheckAndCleanGapDocTree}).
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@r := ParseTreeXMLString(doc[1], doc[2]);;|
  !gapprompt@gap>| !gapinput@CheckAndCleanGapDocTree(r);|
  true
\end{Verbatim}
 We start to produce a text version of the manual, which can be read in a
terminal (window). The command is \texttt{GAPDoc2Text} (\ref{GAPDoc2Text}). This produces a record with the actual text and some additional information.
The text can be written chapter-wise into files with \texttt{GAPDoc2TextPrintTextFiles} (\ref{GAPDoc2TextPrintTextFiles}). The names of these files are \texttt{chap0.txt}, \texttt{chap1.txt} and so on. The text contains some markup using ANSI escape sequences. This
markup is substituted by the \textsf{GAP} help system (user configurable) to show the text with colors and other
attributes. For the bibliography we have to tell \texttt{GAPDoc2Text} (\ref{GAPDoc2Text}) the location of the Bib{\TeX} database by specifying a \texttt{path} as second argument.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@t := GAPDoc2Text(r, path);;|
  !gapprompt@gap>| !gapinput@GAPDoc2TextPrintTextFiles(t, path);|
\end{Verbatim}
 This command constructs all parts of the document including table of contents,
bibliography and index. The functions \texttt{FormatParagraph} (\ref{FormatParagraph}) for formatting text paragraphs and \texttt{ParseBibFiles} (\ref{ParseBibFiles}) for reading Bib{\TeX} files with \textsf{GAP} may be of independent interest.

 With the text version we have also produced the information which is used for
searching with \textsf{GAP}'s online help. Also, labels are produced which can be used by links in the
HTML- and \texttt{pdf}-versions of the manual.

 Next we produce a {\LaTeX} version of the document. \texttt{GAPDoc2LaTeX} (\ref{GAPDoc2LaTeX}) returns a string containing the {\LaTeX} source. The utility function \texttt{FileString} (\ref{FileString}) writes the content of a string to a file, we choose \texttt{MyBook.tex}.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@l := GAPDoc2LaTeX(r);;|
  !gapprompt@gap>| !gapinput@FileString(Filename(path, Concatenation(bookname, ".tex")), l);|
\end{Verbatim}
 Assuming that you have a sufficiently good installation of {\TeX} available (see \texttt{GAPDoc2LaTeX} (\ref{GAPDoc2LaTeX}) for details) this can be processed with a series of commands like in the
following example.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  cd /my/book/path
  pdflatex MyBook
  bibtex MyBook
  pdflatex MyBook
  makeindex MyBook
  pdflatex MyBook
  mv MyBook.pdf manual.pdf
\end{Verbatim}
 After this we have a \texttt{pdf}-version of the document in the file \texttt{manual.pdf}. It contains hyperlink information which can be used with appropriate
browsers for convenient reading of the document on screen (e.g., \texttt{xpdf} is nice because it allows remote calls to display named locations of the
document). Of course, we could also use other commands like \texttt{latex} or \texttt{dvips} to process the {\LaTeX} source file. Furthermore we have produced a file \texttt{MyBook.pnr} which is \textsf{GAP}-readable and contains the page number information for each (sub-)section of
the document.

 We can add this page number information to the indexing information collected
by the text converter and then print a \texttt{manual.six} file which is read by \textsf{GAP} when the manual is loaded. This is done with \texttt{AddPageNumbersToSix} (\ref{AddPageNumbersToSix}) and \texttt{PrintSixFile} (\ref{PrintSixFile}).
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@AddPageNumbersToSix(r, Filename(path, "MyBook.pnr"));|
  !gapprompt@gap>| !gapinput@PrintSixFile(Filename(path, "manual.six"), r, bookname);|
\end{Verbatim}
 Finally we produce an HTML-version of the document and write it (chapter-wise)
into files \texttt{chap0.html}, \texttt{chap1.html} and so on. They can be read with any Web-browser. The commands are \texttt{GAPDoc2HTML} (\ref{GAPDoc2HTML}) and \texttt{GAPDoc2HTMLPrintHTMLFiles} (\ref{GAPDoc2HTMLPrintHTMLFiles}). We also add a link from \texttt{manual.html} to \texttt{chap0.html}. You probably want to copy stylesheet files into the same directory, see \ref{StyleSheets} for more details. The argument \texttt{path} of \texttt{GAPDoc2HTML} (\ref{GAPDoc2HTML}) specifies the directory containing the Bib{\TeX} database files.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@h := GAPDoc2HTML(r, path);;|
  !gapprompt@gap>| !gapinput@GAPDoc2HTMLPrintHTMLFiles(h, path);|
\end{Verbatim}


\subsection{\textcolor{Chapter }{MakeGAPDocDoc}}
\logpage{[ 5, 1, 1 ]}\nobreak
\hyperdef{L}{X826F530686F4D052}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{MakeGAPDocDoc({\mdseries\slshape path, main, files, bookname[, gaproot][, ...]})\index{MakeGAPDocDoc@\texttt{MakeGAPDocDoc}}
\label{MakeGAPDocDoc}
}\hfill{\scriptsize (function)}}\\


 This function collects all the commands for producing a text-, \texttt{pdf}- and HTML-version of a \textsf{GAPDoc} document as described in Section{\nobreakspace}\ref{MakeDoc}. It checks the \texttt{.log} file from the call of \texttt{pdflatex} and reports if there are errors, warnings or overfull boxes.

 \emph{Note:} If this function works for you depends on your operating system and installed
software. It will probably work on most \texttt{UNIX} systems with a standard {\LaTeX} installation. If the function doesn't work for you look at the source code and
adjust it to your system.

 Here \mbox{\texttt{\mdseries\slshape path}} must be the directory (as string or directory object) containing the main file \mbox{\texttt{\mdseries\slshape main}} of the document (given with or without the \texttt{.xml} extension. The argument \mbox{\texttt{\mdseries\slshape files}} is a list of (probably source code) files relative to \mbox{\texttt{\mdseries\slshape path}} which contain pieces of documentation which must be included in the document,
see Chapter{\nobreakspace}\ref{Distributing}. And \mbox{\texttt{\mdseries\slshape bookname}} is the name of the book used by \textsf{GAP}'s online help. The optional argument \mbox{\texttt{\mdseries\slshape gaproot}} must be a string which gives the relative path from \mbox{\texttt{\mdseries\slshape path}} to the main \textsf{GAP} root directory. If this is given, the HTML files are produced with relative
paths to external books.

 If the string \texttt{"nopdf"} is given as optional argument then \texttt{MakeGAPDocDoc} will not produce a \texttt{pdf}-version of the help book (the source \texttt{.tex}-file is generated). Consequently, the index for the help system will not
contain page numbers for the \texttt{pdf}-version. This variant of \texttt{MakeGAPDocDoc} should work independently of the operating system because no external programs
are called. It is recommended that distributed manuals contain the \texttt{pdf}-version.

 \index{MathJax@\textsf{MathJax}!in \texttt{MakeGAPDocDoc}} \texttt{MakeGAPDocDoc} can be called with additional arguments \texttt{"MathJax"}, \texttt{"Tth"} and/or \texttt{"MathML"}. If these are given additional variants of the HTML conversion are called,
see \texttt{GAPDoc2HTML} (\ref{GAPDoc2HTML}) for details.

 It is possible to use \textsf{GAPDoc} with other languages than English, see \texttt{SetGapDocLanguage} (\ref{SetGapDocLanguage}) for more details.

 }

 }


\section{\textcolor{Chapter }{Parsing XML Documents}}\label{ParseXML}
\logpage{[ 5, 2, 0 ]}
\hyperdef{L}{X7FE2AF49838D9034}{}
{
  Arbitrary well-formed XML documents can be parsed and browsed by the following
functions.

\subsection{\textcolor{Chapter }{ParseTreeXMLString}}
\logpage{[ 5, 2, 1 ]}\nobreak
\hyperdef{L}{X847EB8498151D443}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ParseTreeXMLString({\mdseries\slshape str[, srcinfo][, entitydict]})\index{ParseTreeXMLString@\texttt{ParseTreeXMLString}}
\label{ParseTreeXMLString}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ParseTreeXMLFile({\mdseries\slshape fname[, entitydict]})\index{ParseTreeXMLFile@\texttt{ParseTreeXMLFile}}
\label{ParseTreeXMLFile}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a record which is root of a tree structure



 The first function parses an XML-document stored in string \mbox{\texttt{\mdseries\slshape str}} and returns the document in form of a tree.

 The optional argument \mbox{\texttt{\mdseries\slshape srcinfo}} must have the same format as in \texttt{OriginalPositionDocument} (\ref{OriginalPositionDocument}). If it is given then error messages refer to the original source of the text
with the problem.

 With the optional argument \mbox{\texttt{\mdseries\slshape entitydict}} named entities can be given to the parser, for example entities which are
defined in the \texttt{.dtd}-file (which is not read by this parser). The standard XML-entities do not
need to be provided, and for \textsf{GAPDoc} documents the entity definitions from \texttt{gapdoc.dtd} are automatically provided. Entities in the document's \texttt{{\textless}!DOCTYPE} declaration are parsed and also need not to be provided here. The argument \mbox{\texttt{\mdseries\slshape entitydict}} must be a record where each component name is an entity name (without the
surrounding \& and ;) to which is assigned its substitution string.

 The second function is just a shortcut for \texttt{ParseTreeXMLString( StringFile(}\mbox{\texttt{\mdseries\slshape fname}}\texttt{), ... )}, see \texttt{StringFile} (\ref{StringFile}).

 After these functions return the list of named entities which were known
during the parsing can be found in the record \texttt{ENTITYDICT}.

 A node in the result tree corresponds to an XML element, or to some parsed
character data. In the first case it looks as follows:
\begin{Verbatim}[fontsize=\small,frame=single,label=Example Node]
  rec( name := "Book",
       attributes := rec( Name := "EDIM" ),
       content := [ ... list of nodes for content ...],
       start := 312,
       stop := 15610,
       next := 15611     )
\end{Verbatim}
 This means that \texttt{\mbox{\texttt{\mdseries\slshape str}}\texttt{\symbol{123}}[312..15610]\texttt{\symbol{125}}} looks like \texttt{{\textless}Book Name="EDIM"{\textgreater} ... content ...
{\textless}/Book{\textgreater}}.

 The leaves of the tree encode parsed character data as in the following
example:
\begin{Verbatim}[fontsize=\small,frame=single,label=Example Node]
  rec( name := "PCDATA",
       content := "text without markup "     )
\end{Verbatim}
 This function checks whether the XML document is \emph{well formed}, see \ref{XMLvalid} for an explanation. If an error in the XML structure is found, a break loop is
entered and the text around the position where the problem starts is shown.
With \texttt{Show();} one can browse the original input in the \texttt{Pager} (\textbf{Reference: Pager}), starting with the line where the error occurred. All entities are resolved
when they are either entities defined in the \textsf{GAPDoc} package (in particular the standard XML entities) or if their definition is
included in the \texttt{{\textless}!DOCTYPE ..{\textgreater}} tag of the document.

 Note that \texttt{ParseTreeXMLString} does not parse and interpret the corresponding document type definition (the \texttt{.dtd}-file given in the \texttt{{\textless}!DOCTYPE ..{\textgreater}} tag). Hence it also does not check the \emph{validity} of the document (i.e., it is no \emph{validating XML parser}).

 If you are using this function to parse a \textsf{GAPDoc} document you can use \texttt{CheckAndCleanGapDocTree} (\ref{CheckAndCleanGapDocTree}) for some validation and additional checking of the document structure. }



\subsection{\textcolor{Chapter }{StringXMLElement}}
\logpage{[ 5, 2, 2 ]}\nobreak
\hyperdef{L}{X835887057D0B4DA8}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{StringXMLElement({\mdseries\slshape tree})\index{StringXMLElement@\texttt{StringXMLElement}}
\label{StringXMLElement}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a list \texttt{[string, positions]}



 The argument \mbox{\texttt{\mdseries\slshape tree}} must have a format of a node in the parse tree of an XML document as returned
by \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}) (including the root node representing the full document). This function
computes a pair \texttt{[string, positions]} where \texttt{string} contains XML code which is equivalent to the code which was parsed to get \mbox{\texttt{\mdseries\slshape tree}}. And \texttt{positions} is a list of lists of four numbers \texttt{[eltb, elte, contb, conte]}. There is one such list for each XML element occuring in \texttt{string}, where \texttt{eltb} and \texttt{elte} are the begin and end position of this element in \texttt{string} and where \texttt{contb} and \texttt{conte} are begin and end position of the content of this element, or both are \texttt{0} if there is no content.

 Note that parsing XML code is an irreversible task, we can only expect to get
equivalent XML code from this function. But parsing the resulting \texttt{string} again and applying \texttt{StringXMLElement} again gives the same result. See the function \texttt{EntitySubstitution} (\ref{EntitySubstitution}) for back-substitutions of entities in the result. }



\subsection{\textcolor{Chapter }{EntitySubstitution}}
\logpage{[ 5, 2, 3 ]}\nobreak
\hyperdef{L}{X786827BF793191B3}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{EntitySubstitution({\mdseries\slshape xmlstring, entities})\index{EntitySubstitution@\texttt{EntitySubstitution}}
\label{EntitySubstitution}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a string



 The argument \mbox{\texttt{\mdseries\slshape xmlstring}} must be a string containing XML code or a pair \texttt{[string, positions]} as returned by \texttt{StringXMLElement} (\ref{StringXMLElement}). The argument \mbox{\texttt{\mdseries\slshape entities}} specifies entity names (without the surrounding \mbox{\texttt{\mdseries\slshape \&}} and \texttt{;}) and their substitution strings, either a list of pairs of strings or as a
record with the names as components and the substitutions as values.

 This function tries to substitute non-intersecting parts of \texttt{string} by the given entities. If the \texttt{positions} information is given then only parts of the document which allow a valid
substitution by an entity are considered. Otherwise a simple text substitution
without further check is done.

 Note that in general the entity resolution in XML documents is a complicated
and non-reversible task. But nevertheless this utility may be useful in not
too complicated situations. }



\subsection{\textcolor{Chapter }{DisplayXMLStructure}}
\logpage{[ 5, 2, 4 ]}\nobreak
\hyperdef{L}{X86589C5C859ACE38}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DisplayXMLStructure({\mdseries\slshape tree})\index{DisplayXMLStructure@\texttt{DisplayXMLStructure}}
\label{DisplayXMLStructure}
}\hfill{\scriptsize (function)}}\\


 This utility displays the tree structure of an XML document as it is returned
by \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}) (without the \texttt{PCDATA} leaves).

 Since this is usually quite long the result is shown using the \texttt{Pager} (\textbf{Reference: Pager}). }



\subsection{\textcolor{Chapter }{ApplyToNodesParseTree}}
\logpage{[ 5, 2, 5 ]}\nobreak
\hyperdef{L}{X7A7B223A83E38B40}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ApplyToNodesParseTree({\mdseries\slshape tree, fun})\index{ApplyToNodesParseTree@\texttt{ApplyToNodesParseTree}}
\label{ApplyToNodesParseTree}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AddRootParseTree({\mdseries\slshape tree})\index{AddRootParseTree@\texttt{AddRootParseTree}}
\label{AddRootParseTree}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RemoveRootParseTree({\mdseries\slshape tree})\index{RemoveRootParseTree@\texttt{RemoveRootParseTree}}
\label{RemoveRootParseTree}
}\hfill{\scriptsize (function)}}\\


 The function \texttt{ApplyToNodesParseTree} applies a function \mbox{\texttt{\mdseries\slshape fun}} to all nodes of the parse tree \mbox{\texttt{\mdseries\slshape tree}} of an XML document returned by \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}).

 The function \texttt{AddRootParseTree} is an application of this. It adds to all nodes a component \texttt{.root} to which the top node tree \mbox{\texttt{\mdseries\slshape tree}} is assigned. These components can be removed afterwards with \texttt{RemoveRootParseTree}. }

 Here are two more utilities which use \texttt{ApplyToNodesParseTree} (\ref{ApplyToNodesParseTree}).

\subsection{\textcolor{Chapter }{GetTextXMLTree}}
\logpage{[ 5, 2, 6 ]}\nobreak
\hyperdef{L}{X7F76D4A27C7FB946}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GetTextXMLTree({\mdseries\slshape tree})\index{GetTextXMLTree@\texttt{GetTextXMLTree}}
\label{GetTextXMLTree}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a string



 The argument \mbox{\texttt{\mdseries\slshape tree}} must be a node of a parse tree of some XML document, see \texttt{ParseTreeXMLFile} (\ref{ParseTreeXMLFile}). This function collects the content of this and all included elements
recursively into a string. }



\subsection{\textcolor{Chapter }{XMLElements}}
\logpage{[ 5, 2, 7 ]}\nobreak
\hyperdef{L}{X8466F74C80442F7D}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{XMLElements({\mdseries\slshape tree, eltnames})\index{XMLElements@\texttt{XMLElements}}
\label{XMLElements}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a list of nodes



 The argument \mbox{\texttt{\mdseries\slshape tree}} must be a node of a parse tree of some XML document, see \texttt{ParseTreeXMLFile} (\ref{ParseTreeXMLFile}). This function returns a list of all subnodes of \mbox{\texttt{\mdseries\slshape tree}} (possibly including \mbox{\texttt{\mdseries\slshape tree}}) of elements with name given in the list of strings \mbox{\texttt{\mdseries\slshape eltnames}}. Use \texttt{"PCDATA"} as name for leave nodes which contain the actual text of the document. As an
abbreviation \mbox{\texttt{\mdseries\slshape eltnames}} can also be a string which is then put in a one element list. }

 And here are utilities for processing \textsf{GAPDoc} XML documents.

\subsection{\textcolor{Chapter }{CheckAndCleanGapDocTree}}
\logpage{[ 5, 2, 8 ]}\nobreak
\hyperdef{L}{X84CFF72484B19C0D}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{CheckAndCleanGapDocTree({\mdseries\slshape tree})\index{CheckAndCleanGapDocTree@\texttt{CheckAndCleanGapDocTree}}
\label{CheckAndCleanGapDocTree}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing



 The argument \mbox{\texttt{\mdseries\slshape tree}} of this function is a parse tree from \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}) of some \textsf{GAPDoc} document. This function does an (incomplete) validity check of the document
according to the document type declaration in \texttt{gapdoc.dtd}. It also does some additional checks which cannot be described in the DTD
(like checking whether chapters and sections have a heading). For elements
with element content the whitespace between these elements is removed.

 In case of an error the break loop is entered and the position of the error in
the original XML document is printed. With \texttt{Show();} one can browse the original input in the \texttt{Pager} (\textbf{Reference: Pager}). }



\subsection{\textcolor{Chapter }{AddParagraphNumbersGapDocTree}}
\logpage{[ 5, 2, 9 ]}\nobreak
\hyperdef{L}{X84062CD67B286FF0}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AddParagraphNumbersGapDocTree({\mdseries\slshape tree})\index{AddParagraphNumbersGapDocTree@\texttt{AddParagraphNumbersGapDocTree}}
\label{AddParagraphNumbersGapDocTree}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing



 The argument \mbox{\texttt{\mdseries\slshape tree}} must be an XML tree returned by \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}) applied to a \textsf{GAPDoc} document. This function adds to each node of the tree a component \texttt{.count} which is of form \texttt{[Chapter[, Section[, Subsection, Paragraph] ] ]}. Here the first three numbers should be the same as produced by the {\LaTeX} version of the document. Text before the first chapter is counted as chapter \texttt{0} and similarly for sections and subsections. Some elements are always
considered to start a new paragraph. }



\subsection{\textcolor{Chapter }{InfoXMLParser}}
\logpage{[ 5, 2, 10 ]}\nobreak
\hyperdef{L}{X78A22C58841E5D0B}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{InfoXMLParser\index{InfoXMLParser@\texttt{InfoXMLParser}}
\label{InfoXMLParser}
}\hfill{\scriptsize (info class)}}\\


 The default level of this info class is 1. Functions like \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}) are then printing some information, in particular in case of errors. You can
suppress it by setting the level of \texttt{InfoXMLParser} to 0. With level 2 there may be some more information for debugging purposes. }

 }


\section{\textcolor{Chapter }{The Converters}}\label{Converters}
\logpage{[ 5, 3, 0 ]}
\hyperdef{L}{X8560E1A2845EC2C1}{}
{
  Here are more details about the conversion programs for \textsf{GAPDoc} XML documents.

\subsection{\textcolor{Chapter }{GAPDoc2LaTeX}}
\logpage{[ 5, 3, 1 ]}\nobreak
\hyperdef{L}{X85BE6DF178423EF5}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GAPDoc2LaTeX({\mdseries\slshape tree})\index{GAPDoc2LaTeX@\texttt{GAPDoc2LaTeX}}
\label{GAPDoc2LaTeX}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
{\LaTeX} document as string

\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SetGapDocLaTeXOptions({\mdseries\slshape [...]})\index{SetGapDocLaTeXOptions@\texttt{SetGapDocLaTeXOptions}}
\label{SetGapDocLaTeXOptions}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
Nothing



 The argument \mbox{\texttt{\mdseries\slshape tree}} for this function is a tree describing a \textsf{GAPDoc} XML document as returned by \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}) (probably also checked with \texttt{CheckAndCleanGapDocTree} (\ref{CheckAndCleanGapDocTree})). The output is a string containing a version of the document which can be
written to a file and processed with {\LaTeX} or pdf{\LaTeX} (and probably Bib{\TeX} and \texttt{makeindex}).

 The output uses the \texttt{report} document class and needs the following {\LaTeX} packages: \texttt{amssymb}, \texttt{inputenc}, \texttt{makeidx}, \texttt{color}, \texttt{fancyvrb}, \texttt{psnfss}, \texttt{pslatex}, \texttt{enumitem} and \texttt{hyperref}. These are for example provided by the \textsf{teTeX-1.0} or \textsf{texlive} distributions of {\TeX} (which in turn are used for most {\TeX} packages of current Linux distributions); see \href{http://www.tug.org/tetex/} {\texttt{http://www.tug.org/tetex/}}.

 In particular, the resulting \texttt{pdf}-output (and \texttt{dvi}-output) contains (internal and external) hyperlinks which can be very useful
for onscreen browsing of the document.

 The {\LaTeX} processing also produces a file with extension \texttt{.pnr} which is \textsf{GAP} readable and contains the page numbers for all (sub)sections of the document.
This can be used by \textsf{GAP}'s online help; see \texttt{AddPageNumbersToSix} (\ref{AddPageNumbersToSix}). Non-ASCII characters in the \textsf{GAPDoc} document are translated to {\LaTeX} input in ASCII-encoding with the help of \texttt{Encode} (\ref{Encode}) and the option \texttt{"LaTeX"}. See the documentation of \texttt{Encode} (\ref{Encode}) for how to proceed if you have a character which is not handled (yet).

 This function works by running recursively through the document tree and
calling a handler function for each \textsf{GAPDoc} XML element. Many of these handler functions (usually in \texttt{GAPDoc2LaTeXProcs.{\textless}ElementName{\textgreater}}) are not difficult to understand (the greatest complications are some
commands for index entries, labels or the output of page number information).
So it should be easy to adjust layout details to your own taste by slight
modifications of the program.

 Former versions of \textsf{GAPDoc} supported some XML processing instructions to add some extra lines to the
preamble of the {\LaTeX} document. Its use is now deprecated, use the much more flexible \texttt{SetGapDocLaTeXOptions} instead: The default layout of the resulting documents can be changed with \texttt{SetGapDocLaTeXOptions}. This changes parts of the header of the {\LaTeX} file produced by \textsf{GAPDoc}. You can see the header with some placeholders by \texttt{Page(GAPDoc2LaTeXProcs.Head);}. The placeholders are filled with components from the record \texttt{GAPDoc2LaTeXProcs.DefaultOptions}. The arguments of \texttt{SetGapDocLaTeXOptions} can be records with the same structure (or parts of it) with different values.
As abbreviations there are also three strings supported as arguments. These
are \texttt{"nocolor"} for switching all colors to black; then \texttt{"nopslatex"} to use standard {\LaTeX} fonts instead of postscript fonts; and finally \texttt{"utf8"} to choose UTF-8 as input encoding for the {\LaTeX} document. }



\subsection{\textcolor{Chapter }{GAPDoc2Text}}
\logpage{[ 5, 3, 2 ]}\nobreak
\hyperdef{L}{X86CD0B197CD58D2A}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GAPDoc2Text({\mdseries\slshape tree[, bibpath][, width]})\index{GAPDoc2Text@\texttt{GAPDoc2Text}}
\label{GAPDoc2Text}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
record containing text files as strings and other information



 The argument \mbox{\texttt{\mdseries\slshape tree}} for this function is a tree describing a \textsf{GAPDoc} XML document as returned by \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}) (probably also checked with \texttt{CheckAndCleanGapDocTree} (\ref{CheckAndCleanGapDocTree})). This function produces a text version of the document which can be used
with \textsf{GAP}'s online help (with the \texttt{"screen"} viewer, see \texttt{SetHelpViewer} (\textbf{Reference: SetHelpViewer})). It includes title page, bibliography and index. The bibliography is made
from BibXMLext or Bib{\TeX} databases, see \ref{ch:bibutil}. Their location must be given with the argument \mbox{\texttt{\mdseries\slshape bibpath}} (as string or directory object).

 The output is a record with one component for each chapter (with names \texttt{"0"}, \texttt{"1"}, ..., \texttt{"Bib"} and \texttt{"Ind"}). Each such component is again a record with the following components:
\begin{description}
\item[{\texttt{text}}] the text of the whole chapter as a string
\item[{\texttt{ssnr}}] list of subsection numbers in this chapter (like \texttt{[3, 2, 1]} for chapter{\nobreakspace}3, section{\nobreakspace}2,
subsection{\nobreakspace}1)
\item[{\texttt{linenr}}] corresponding list of line numbers where the subsections start
\item[{\texttt{len}}] number of lines of this chapter
\end{description}
 The result can be written into files with the command \texttt{GAPDoc2TextPrintTextFiles} (\ref{GAPDoc2TextPrintTextFiles}).

 As a side effect this function also produces the \texttt{manual.six} information which is used for searching in \textsf{GAP}'s online help. This is stored in \texttt{\mbox{\texttt{\mdseries\slshape tree}}.six} and can be printed into a \texttt{manual.six} file with \texttt{PrintSixFile} (\ref{PrintSixFile}) (preferably after producing a {\LaTeX} version of the document as well and adding the page number information to \texttt{\mbox{\texttt{\mdseries\slshape tree}}.six}, see \texttt{GAPDoc2LaTeX} (\ref{GAPDoc2LaTeX}) and \texttt{AddPageNumbersToSix} (\ref{AddPageNumbersToSix})).

 The text produced by this function contains some markup via ANSI escape
sequences. The sequences used here are usually ignored by terminals. But the \textsf{GAP} help system will substitute them by interpreted color and attribute sequences
(see \texttt{TextAttr} (\ref{TextAttr})) before displaying them. There is a default markup used for this but it can
also be configured by the user, see \texttt{SetGAPDocTextTheme} (\ref{SetGAPDocTextTheme}). Furthermore, the text produced is in UTF-8 encoding. The encoding is also
translated on the fly, if \texttt{GAPInfo.TermEncoding} is set to some encoding supported by \texttt{Encode} (\ref{Encode}), e.g., \texttt{"ISO-8859-1"} or \texttt{"latin1"}.

 With the optional argument \mbox{\texttt{\mdseries\slshape width}} a different length of the output text lines can be chosen. The default is 76
and all lines in the resulting text start with two spaces. This looks good on
a terminal with a standard width of 80 characters and you probably don't want
to use this argument. }



\subsection{\textcolor{Chapter }{GAPDoc2TextPrintTextFiles}}
\logpage{[ 5, 3, 3 ]}\nobreak
\hyperdef{L}{X7DFCE7357D6032A2}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GAPDoc2TextPrintTextFiles({\mdseries\slshape t[, path]})\index{GAPDoc2TextPrintTextFiles@\texttt{GAPDoc2TextPrintTextFiles}}
\label{GAPDoc2TextPrintTextFiles}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing



 The first argument must be a result returned by \texttt{GAPDoc2Text} (\ref{GAPDoc2Text}). The second argument is a path for the files to write, it can be given as
string or directory object. The text of each chapter is written into a
separate file with name \texttt{chap0.txt}, \texttt{chap1.txt}, ..., \texttt{chapBib.txt}, and \texttt{chapInd.txt}.

 If you want to make your document accessible via the \textsf{GAP} online help you must put at least these files for the text version into a
directory, together with the file \texttt{manual.six}, see \texttt{PrintSixFile} (\ref{PrintSixFile}). Then specify the path to the \texttt{manual.six} file in the packages \texttt{PackageInfo.g} file, see  (\textbf{Reference: The PackageInfo.g File}).

 Optionally you can add the \texttt{dvi}- and \texttt{pdf}-versions of the document which are produced with \texttt{GAPDoc2LaTeX} (\ref{GAPDoc2LaTeX}) to this directory. The files must have the names \texttt{manual.dvi} and \texttt{manual.pdf}, respectively. Also you can add the files of the HTML version produced with \texttt{GAPDoc2HTML} (\ref{GAPDoc2HTML}) to this directory, see \texttt{GAPDoc2HTMLPrintHTMLFiles} (\ref{GAPDoc2HTMLPrintHTMLFiles}). The handler functions in \textsf{GAP} for this help format detect automatically which of the optional formats of a
book are actually available. }



\subsection{\textcolor{Chapter }{AddPageNumbersToSix}}
\logpage{[ 5, 3, 4 ]}\nobreak
\hyperdef{L}{X7EB5E86F87A09F94}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AddPageNumbersToSix({\mdseries\slshape tree, pnrfile})\index{AddPageNumbersToSix@\texttt{AddPageNumbersToSix}}
\label{AddPageNumbersToSix}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing



 Here \mbox{\texttt{\mdseries\slshape tree}} must be the XML tree of a \textsf{GAPDoc} document, returned by \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}). Running \texttt{latex} on the result of \texttt{GAPDoc2LaTeX(\mbox{\texttt{\mdseries\slshape tree}})} produces a file \mbox{\texttt{\mdseries\slshape pnrfile}} (with extension \texttt{.pnr}). The command \texttt{GAPDoc2Text(\mbox{\texttt{\mdseries\slshape tree}})} creates a component \texttt{\mbox{\texttt{\mdseries\slshape tree}}.six} which contains all information about the document for the \textsf{GAP} online help, except the page numbers in the \texttt{.dvi, .ps, .pdf} versions of the document. This command adds the missing page number
information to \texttt{\mbox{\texttt{\mdseries\slshape tree}}.six}. }



\subsection{\textcolor{Chapter }{PrintSixFile}}
\logpage{[ 5, 3, 5 ]}\nobreak
\hyperdef{L}{X7D42CFED7885BC00}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{PrintSixFile({\mdseries\slshape tree, bookname, fname})\index{PrintSixFile@\texttt{PrintSixFile}}
\label{PrintSixFile}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing



 This function prints the \texttt{.six} file \mbox{\texttt{\mdseries\slshape fname}} for a \textsf{GAPDoc} document stored in \mbox{\texttt{\mdseries\slshape tree}} with name \mbox{\texttt{\mdseries\slshape bookname}}. Such a file contains all information about the book which is needed by the \textsf{GAP} online help. This information must first be created by calls of \texttt{GAPDoc2Text} (\ref{GAPDoc2Text}) and \texttt{AddPageNumbersToSix} (\ref{AddPageNumbersToSix}). }



\subsection{\textcolor{Chapter }{SetGAPDocTextTheme}}
\logpage{[ 5, 3, 6 ]}\nobreak
\hyperdef{L}{X7DEB37417BBD8941}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SetGAPDocTextTheme({\mdseries\slshape [optrec1[, optrec2], ...]})\index{SetGAPDocTextTheme@\texttt{SetGAPDocTextTheme}}
\label{SetGAPDocTextTheme}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing



 This utility function is for readers of the screen version of \textsf{GAP} manuals which are generated by the \textsf{GAPDoc} package. It allows to configure the color and attribute layout of the
displayed text. There is a default which can be reset by calling this function
without argument.

 As an abbreviation the arguments \mbox{\texttt{\mdseries\slshape optrec1}} and so on can be strings for the known name of a theme. Information about
valid names is shown with \texttt{SetGAPDocTextTheme("");}.

 Otherwise, \mbox{\texttt{\mdseries\slshape optrec1}} and so on must be a record. Its entries overwrite the corresponding entries in
the default and in previous arguments. To construct valid markup you can use \texttt{TextAttr} (\ref{TextAttr}). Entries must be either pairs of strings, which are put before and after the
corresponding text, or as an abbreviation it can be a single string. In the
latter case, the second string is implied; if the string contains an escape
sequence the second string is \texttt{TextAttr.reset}, otherwise the given string is used. The following components are recognized:
\begin{description}
\item[{\texttt{flush}}] \texttt{"both"} for left-right justified paragraphs, and \texttt{"left"} for ragged right ones
\item[{\texttt{Heading}}] chapter and (sub-)section headings
\item[{\texttt{Func}}] function, operation, ... names
\item[{\texttt{Arg}}] argument names in descriptions
\item[{\texttt{Example}}] example code
\item[{\texttt{Package}}] package names
\item[{\texttt{Returns}}] Returns-line in descriptions
\item[{\texttt{URL}}] URLs
\item[{\texttt{Mark}}] Marks in description lists
\item[{\texttt{K}}] \textsf{GAP} keywords
\item[{\texttt{C}}] code or text to type
\item[{\texttt{F}}] file names
\item[{\texttt{B}}] buttons
\item[{\texttt{M}}] simplified math elements
\item[{\texttt{Math}}] normal math elements
\item[{\texttt{Display}}] displayed math elements
\item[{\texttt{Emph}}] emphasized text
\item[{\texttt{Q}}] quoted text
\item[{\texttt{Ref}}] reference text
\item[{\texttt{Prompt}}] \textsf{GAP} prompt in examples
\item[{\texttt{BrkPrompt}}] \textsf{GAP} break prompt in examples
\item[{\texttt{GAPInput}}] \textsf{GAP} input in examples
\item[{\texttt{reset}}] reset to default, don't change this
\item[{\texttt{BibAuthor}}] author names in bibliography
\item[{\texttt{BibTitle}}] titles in bibliography
\item[{\texttt{BibJournal}}] journal names in bibliography
\item[{\texttt{BibVolume}}] volume number in bibliography
\item[{\texttt{BibLabel}}] labels for bibliography entries
\item[{\texttt{BibReset}}] reset for bibliography, don't change
\item[{\texttt{ListBullet}}] bullet for simple lists (2 visible characters long)
\item[{\texttt{EnumMarks}}] one visible character before and after the number in enumerated lists
\item[{\texttt{DefLineMarker}}] marker before function and variable definitions (2 visible characters long)
\item[{\texttt{FillString}}] for filling in definitions and example separator lines
\end{description}

\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@# use no colors for GAP examples and |
  !gapprompt@gap>| !gapinput@# change display of headings to bold green|
  !gapprompt@gap>| !gapinput@SetGAPDocTextTheme("noColorPrompt", |
  !gapprompt@>| !gapinput@           rec(Heading:=Concatenation(TextAttr.bold, TextAttr.2)));|
\end{Verbatim}
 }



\subsection{\textcolor{Chapter }{GAPDoc2HTML}}
\logpage{[ 5, 3, 7 ]}\nobreak
\hyperdef{L}{X84F22EEB78845CFD}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GAPDoc2HTML({\mdseries\slshape tree[, bibpath[, gaproot]][, mtrans]})\index{GAPDoc2HTML@\texttt{GAPDoc2HTML}}
\label{GAPDoc2HTML}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
record containing HTML files as strings and other information



 \index{MathJax@\textsf{MathJax}} The argument \mbox{\texttt{\mdseries\slshape tree}} for this function is a tree describing a \textsf{GAPDoc} XML document as returned by \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}) (probably also checked with \texttt{CheckAndCleanGapDocTree} (\ref{CheckAndCleanGapDocTree})). Without an \mbox{\texttt{\mdseries\slshape mtrans}} argument this function produces an HTML version of the document which can be
read with any Web-browser and also be used with \textsf{GAP}'s online help (see \texttt{SetHelpViewer} (\textbf{Reference: SetHelpViewer})). It includes title page, bibliography, and index. The bibliography is made
from Bib{\TeX} databases. Their location must be given with the argument \mbox{\texttt{\mdseries\slshape bibpath}} (as string or directory object, if not given the current directory is used).
If the third argument \mbox{\texttt{\mdseries\slshape gaproot}} is given and is a string then this string is interpreted as relative path to \textsf{GAP}'s main root directory. Reference-URLs to external HTML-books which begin with
the \textsf{GAP} root path are then rewritten to start with the given relative path. This makes
the HTML-documentation portable provided a package is installed in some
standard location below the \textsf{GAP} root.

 The output is a record with one component for each chapter (with names \texttt{"0"}, \texttt{"1"}, ..., \texttt{"Bib"}, and \texttt{"Ind"}). Each such component is again a record with the following components:
\begin{description}
\item[{\texttt{text}}] the text of an HTML file containing the whole chapter (as a string)
\item[{\texttt{ssnr}}] list of subsection numbers in this chapter (like \texttt{[3, 2, 1]} for chapter{\nobreakspace}3, section{\nobreakspace}2,
subsection{\nobreakspace}1)
\end{description}
 \emph{Standard output format without} \mbox{\texttt{\mdseries\slshape mtrans}} \emph{argument}

 The HTML code produced with this converter conforms to the W3C specification ``XHTML 1.0 strict'', see \href{http://www.w3.org/TR/xhtml1} {\texttt{http://www.w3.org/TR/xhtml1}}. First, this means that the HTML files are valid XML files. Secondly, the
extension ``strict'' says in particular that the code doesn't contain any explicit font or color
information.

 Mathematical formulae are handled as in the text converter \texttt{GAPDoc2Text} (\ref{GAPDoc2Text}). We don't want to assume that the browser can use symbol fonts. Some \textsf{GAP} users like to browse the online help with \texttt{lynx}, see \texttt{SetHelpViewer} (\textbf{Reference: SetHelpViewer}), which runs inside the same terminal windows as \textsf{GAP}.

 To view the generated files in graphical browsers, stylesheet files with
layout configuration should be copied into the directory with the generated
HTML files, see \ref{StyleSheets}.

 \label{mtransarg} \emph{Output format with} \mbox{\texttt{\mdseries\slshape mtrans}} argument

 Currently, there are three variants of this converter available which handle
mathematical formulae differently. They are accessed via the optional last \mbox{\texttt{\mdseries\slshape mtrans}} argument.

 If \mbox{\texttt{\mdseries\slshape mtrans}} is set to \texttt{"MathJax"} the formulae are essentially translated as for {\LaTeX} documents (there is no processing of \texttt{{\textless}M{\textgreater}} elements as decribed in \ref{M}). Inline formulae are delimited by \texttt{\texttt{\symbol{92}}(} and \texttt{\texttt{\symbol{92}})} and displayed formulae by \texttt{\texttt{\symbol{92}}[} and \texttt{\texttt{\symbol{92}}]}. With \textsf{MathJax} webpages can contain nicely formatted scalable and searchable formulae. The
resulting files link by default to \href{http://cdn.mathjax.org} {http://cdn.mathjax.org} to get the \textsf{MathJax} script and fonts. This means that they can only be used on computers with
internet access. An alternative URL can be set by overwriting \texttt{GAPDoc2HTMLProcs.MathJaxURL} before building the HTML version of a manual. This way a local installation of \textsf{MathJax} could be used. See \href{http://www.mathjax.org/} {http://www.mathjax.org/} for more details.

 The following possibilities for \mbox{\texttt{\mdseries\slshape mtrans}} are still supported, but since the \textsf{MathJax} approach seems much better, their use is deprecated.

 If the argument \mbox{\texttt{\mdseries\slshape mtrans}} is set to \texttt{"Tth"} it is assumed that you have installed the {\LaTeX} to HTML translation program \texttt{tth}. This is used to translate the contents of the \texttt{M}, \texttt{Math} and \texttt{Display} elements into HTML code. Note that the resulting code is not compliant with
any standard. Formally it is ``XHTML 1.0 Transitional'', it contains explicit font specifications and the characters of mathematical
symbols are included via their position in a ``Symbol'' font. Some graphical browsers can be configured to display this in a useful
manner, check \href{http://hutchinson.belmont.ma.us/tth/} {the Tth homepage} for more details.

 This function works by running recursively through the document tree and
calling a handler function for each \textsf{GAPDoc} XML element. Many of these handler functions (usually in \texttt{GAPDoc2TextProcs.{\textless}ElementName{\textgreater}}) are not difficult to understand (the greatest complications are some
commands for index entries, labels or the output of page number information).
So it should be easy to adjust certain details to your own taste by slight
modifications of the program.

 The result of this converter can be written to files with the command \texttt{GAPDoc2HTMLPrintHTMLFiles} (\ref{GAPDoc2HTMLPrintHTMLFiles}).

 There are two user preferences for reading the HTML manuals produced by \textsf{GAPDoc}. A user can choose among several style files which determine the appearance
of the manual pages with \texttt{SetUserPreference("GAPDoc", "HTMLStyle", [...]);} where the list in the third argument are arguments for \texttt{SetGAPDocHTMLStyle} (\ref{SetGAPDocHTMLStyle}). The second preference is set by \texttt{SetUserPreference("GAPDoc", "UseMathJax", ...);} where the third argument is \texttt{true} or \texttt{false} (default). If this is set to \texttt{true}, the \textsf{GAP} help system displays the \textsf{MathJax} version of the HTML manuals. }



\subsection{\textcolor{Chapter }{GAPDoc2HTMLPrintHTMLFiles}}
\logpage{[ 5, 3, 8 ]}\nobreak
\hyperdef{L}{X84A7007778073E7A}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GAPDoc2HTMLPrintHTMLFiles({\mdseries\slshape t[, path]})\index{GAPDoc2HTMLPrintHTMLFiles@\texttt{GAPDoc2HTMLPrintHTMLFiles}}
\label{GAPDoc2HTMLPrintHTMLFiles}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing



 The first argument must be a result returned by \texttt{GAPDoc2HTML} (\ref{GAPDoc2HTML}). The second argument is a path for the files to write, it can be given as
string or directory object. The text of each chapter is written into a
separate file with name \texttt{chap0.html}, \texttt{chap1.html}, ..., \texttt{chapBib.html}, and \texttt{chapInd.html}.

 The \textsf{MathJax} versions are written to files \texttt{chap0{\textunderscore}mj.html}, ..., \texttt{chapInd{\textunderscore}mj.html}.

 The experimental version which is produced with \texttt{tth} uses different names for the files, namely \texttt{chap0{\textunderscore}sym.html}, and so on for files which need symbol fonts.

 You should also add stylesheet files to the directory with the HTML files, see \ref{StyleSheets}. }


\subsection{\textcolor{Chapter }{Stylesheet files}}\label{StyleSheets}
\logpage{[ 5, 3, 9 ]}
\hyperdef{L}{X788AB14383272FDB}{}
{
  \index{CSS stylesheets} For graphical browsers the layout of the generated HTML manuals can be highly
configured by cascading stylesheet (CSS) and javascript files. Such files are
provided in the \texttt{styles} directory of the \textsf{GAPDoc} package.

 We recommend that these files are copied into each manual directory (such that
each of them is selfcontained). There is a utility function \texttt{CopyHTMLStyleFiles} (\ref{CopyHTMLStyleFiles}) which does this. Of course, these files may be changed or new styles may be
added. New styles may also be sent to the \textsf{GAPDoc} authors for possible inclusion in future versions.

 The generated HTML files refer to the file \texttt{manual.css} which conforms to the W3C specification CSS 2.0, see \href{http://www.w3.org/TR/REC-CSS2} {\texttt{http://www.w3.org/TR/REC-CSS2}}, and the javascript file \texttt{manual.js} (only in browsers which support CSS or javascript, respectively; but the HTML
files are also readable without any of them). To add a style \texttt{mystyle} one or both of \texttt{mystyle.css} and \texttt{mystyle.js} must be provided; these can overwrite default settings and add new javascript
functions. For more details see the comments in \texttt{manual.js}.

 }



\subsection{\textcolor{Chapter }{CopyHTMLStyleFiles}}
\logpage{[ 5, 3, 10 ]}\nobreak
\hyperdef{L}{X813599E982DE9B98}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{CopyHTMLStyleFiles({\mdseries\slshape dir})\index{CopyHTMLStyleFiles@\texttt{CopyHTMLStyleFiles}}
\label{CopyHTMLStyleFiles}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing



 This utility function copies the \texttt{*.css} and \texttt{*.js} files from the \texttt{styles} directory of the \textsf{GAPDoc} package into the directory \mbox{\texttt{\mdseries\slshape dir}}. }



\subsection{\textcolor{Chapter }{SetGAPDocHTMLStyle}}
\logpage{[ 5, 3, 11 ]}\nobreak
\hyperdef{L}{X85AFD98383174BB5}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SetGAPDocHTMLStyle({\mdseries\slshape [style1[, style2], ...]})\index{SetGAPDocHTMLStyle@\texttt{SetGAPDocHTMLStyle}}
\label{SetGAPDocHTMLStyle}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing



 This utility function is for readers of the HTML version of \textsf{GAP} manuals which are generated by the \textsf{GAPDoc} package. It allows to configure the display style of the manuals. This will
only have an effect if you are using a browser that supports \textsf{javascript}. There is a default which can be reset by calling this function without
argument.

 The arguments \mbox{\texttt{\mdseries\slshape style1}} and so on must be strings. You can find out about the valid strings by
following the \textsc{[Style]} link on top of any manual page. (Going back to the original page, its address
has a setting for \texttt{GAPDocStyle} which is the list of strings, separated by commas, you want to use here.)
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@# show/hide subsections in tables on contents only after click,|
  !gapprompt@gap>| !gapinput@# and don't use colors in GAP examples|
  !gapprompt@gap>| !gapinput@SetGAPDocHTMLStyle("toggless", "nocolorprompt");|
\end{Verbatim}
 }



\subsection{\textcolor{Chapter }{InfoGAPDoc}}
\logpage{[ 5, 3, 12 ]}\nobreak
\hyperdef{L}{X864A528B81C661A2}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{InfoGAPDoc\index{InfoGAPDoc@\texttt{InfoGAPDoc}}
\label{InfoGAPDoc}
}\hfill{\scriptsize (info class)}}\\


 The default level of this info class is 1. The converter functions for \textsf{GAPDoc} documents are then printing some information. You can suppress this by setting
the level of \texttt{InfoGAPDoc} to 0. With level 2 there may be some more information for debugging purposes. }



\subsection{\textcolor{Chapter }{SetGapDocLanguage}}
\logpage{[ 5, 3, 13 ]}\nobreak
\hyperdef{L}{X82AB468887ED0DBB}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SetGapDocLanguage({\mdseries\slshape [lang]})\index{SetGapDocLanguage@\texttt{SetGapDocLanguage}}
\label{SetGapDocLanguage}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing



 \index{Using \textsf{GAPDoc} with other languages} The \textsf{GAPDoc} converter programs sometimes produce text which is not explicit in the
document, e.g., headers like ``Abstract'', ``Appendix'', links to ``Next Chapter'', variable types ``function'' and so on.

 With \texttt{SetGapDocLanguage} the language for these texts can be changed. The argument \mbox{\texttt{\mdseries\slshape lang}} must be a string. Calling without argument or with a language name for which
no translations are available is the same as using the default \texttt{"english"}.

 If your language \mbox{\texttt{\mdseries\slshape lang}} is not yet available, look at the record \texttt{GAPDocTexts.english} and translate all the strings to \mbox{\texttt{\mdseries\slshape lang}}. Then assign this record to \texttt{GAPDocTexts.(\mbox{\texttt{\mdseries\slshape lang}})} and send it to the \textsf{GAPDoc} authors for inclusion in future versions of \textsf{GAPDoc}. (Currently, there are translations for \texttt{english}, \texttt{german}, \texttt{russian} and \texttt{ukrainian}.)

 \emph{Further hints:} To get strings produced by {\LaTeX} right you will probably use the \texttt{babel} package with option \mbox{\texttt{\mdseries\slshape lang}}, see \texttt{SetGapDocLaTeXOptions} (\ref{SetGapDocLaTeXOptions}). If \mbox{\texttt{\mdseries\slshape lang}} cannot be encoded in \texttt{latin1} encoding you can consider the use of \texttt{"utf8"} with \texttt{SetGapDocLaTeXOptions} (\ref{SetGapDocLaTeXOptions}). }

 }


\section{\textcolor{Chapter }{Testing Manual Examples}}\label{Sec:TestExample}
\logpage{[ 5, 4, 0 ]}
\hyperdef{L}{X800299827B88ABBE}{}
{
 \index{\texttt{ManualExamples}} \index{\texttt{TestManualExamples}}  We also provide some tools to check and adjust the examples given in \texttt{{\textless}Example{\textgreater}}-elements.

 Former versions of \textsf{GAPDoc} provided functions \texttt{ManualExamples} and \texttt{TestManualExamples}. These functions are still available, but no longer documented. Their use is
deprecated.

\subsection{\textcolor{Chapter }{ExtractExamples}}
\logpage{[ 5, 4, 1 ]}\nobreak
\hyperdef{L}{X8337B2BC79253B3F}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ExtractExamples({\mdseries\slshape path, main, files, units})\index{ExtractExamples@\texttt{ExtractExamples}}
\label{ExtractExamples}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a list of lists

\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ExtractExamplesXMLTree({\mdseries\slshape tree, units})\index{ExtractExamplesXMLTree@\texttt{ExtractExamplesXMLTree}}
\label{ExtractExamplesXMLTree}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a list of lists



 The argument \mbox{\texttt{\mdseries\slshape tree}} must be a parse tree of a \textsf{GAPDoc} document, see \texttt{ParseTreeXMLFile} (\ref{ParseTreeXMLFile}). The function \texttt{ExtractExamplesXMLTree} returns a data structure representing the \texttt{{\textless}Example{\textgreater}} elements of the document. The return value can be used with \texttt{RunExamples} (\ref{RunExamples}) to check and optionally update the examples of the document.

 Depending on the argument \mbox{\texttt{\mdseries\slshape units}} several examples are collected in one list. Recognized values for \mbox{\texttt{\mdseries\slshape units}} are \texttt{"Chapter"}, \texttt{"Section"}, \texttt{"Subsection"} or \texttt{"Single"}. The latter means that each example is in a separate list. For all other
value of \mbox{\texttt{\mdseries\slshape units}} just one list with all examples is returned.

 The arguments \mbox{\texttt{\mdseries\slshape path}}, \mbox{\texttt{\mdseries\slshape main}} and \mbox{\texttt{\mdseries\slshape files}} of \texttt{ExtractExamples} are the same as for \texttt{ComposedDocument} (\ref{ComposedDocument}). This function first contructs and parses the \textsf{GAPDoc} document and then applies \texttt{ExtractExamplesXMLTree}. }



\subsection{\textcolor{Chapter }{RunExamples}}
\logpage{[ 5, 4, 2 ]}\nobreak
\hyperdef{L}{X781D56FC7B938DCB}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RunExamples({\mdseries\slshape exmpls[, optrec]})\index{RunExamples@\texttt{RunExamples}}
\label{RunExamples}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
\texttt{true} or \texttt{false}



 The argument \mbox{\texttt{\mdseries\slshape exmpls}} must be the output of a call to \texttt{ExtractExamples} (\ref{ExtractExamples}) or \texttt{ExtractExamplesXMLTree} (\ref{ExtractExamplesXMLTree}). The optional argument \mbox{\texttt{\mdseries\slshape optrec}} must be a record, its components can change the default behaviour of this
function.

 By default this function runs the \textsf{GAP} input of all examples and compares the actual output with the output given in
the examples. If differences occur these are displayed together with
information on the location of the source code of that example. Before running
the examples in each unit (entry of \mbox{\texttt{\mdseries\slshape exmpls}}) the function \texttt{START{\textunderscore}TEST} (\textbf{Reference: START{\textunderscore}TEST}) is called and the screen width is set to 72 characters.

 This function returns \texttt{true} if no differences are found and \texttt{false} otherwise.

 If the argument \mbox{\texttt{\mdseries\slshape optrec}} is given, the following components are recognized:
\begin{description}
\item[{\texttt{showDiffs}}]  The default value is \texttt{true}, if set to something else found differences in the examples are not
displayed.
\item[{\texttt{width}}]  The value must be a positive integer which is used as screen width when
running the examples. As mentioned above, the default is 72 which is a
sensible value for the text version of the \textsf{GAPDoc} document used in a 80 character wide terminal.
\item[{\texttt{ignoreComments}}]  The default is \texttt{false}.\\
 If set to \texttt{true} comments in the input will be ignored (as in the default behaviour of the \texttt{Test} (\textbf{Reference: Test}) function).
\item[{\texttt{changeSources}}]  If this is set to \texttt{true} then the source code of all manual examples which show differences is adjusted
to the current outputs. The default is \texttt{false}.\\
 Use this feature with care. Note that sometimes differences can indicate a
bug, and in such a case it is more appropriate to fix the bug instead of
changing the example output.
\item[{\texttt{compareFunction}}]  The function used to compare the output shown in the example and the current
output. See \texttt{Test} (\textbf{Reference: Test}) for more details.
\item[{\texttt{checkWidth}}]  If this option is a positive integer \texttt{n} the function prints warnings if an example contains any line with more than \texttt{n} characters (input and output lines are considered). By default this option is
set to \texttt{false}.
\end{description}
 }

 }

 }


\chapter{\textcolor{Chapter }{String and Text Utilities}}\label{ch:util}
\logpage{[ 6, 0, 0 ]}
\hyperdef{L}{X86CEF540862EE042}{}
{

\section{\textcolor{Chapter }{Text Utilities}}\label{TextUtil}
\logpage{[ 6, 1, 0 ]}
\hyperdef{L}{X847DA07C7C46B38A}{}
{
  This section describes some utility functions for handling texts within \textsf{GAP}. They are used by the functions in the \textsf{GAPDoc} package but may be useful for other purposes as well. We start with some
variables containing useful strings and go on with functions for parsing and
reformatting text.



\subsection{\textcolor{Chapter }{WHITESPACE}}
\logpage{[ 6, 1, 1 ]}\nobreak
\hyperdef{L}{X786D477C7AB636AA}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{WHITESPACE\index{WHITESPACE@\texttt{WHITESPACE}}
\label{WHITESPACE}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{CAPITALLETTERS\index{CAPITALLETTERS@\texttt{CAPITALLETTERS}}
\label{CAPITALLETTERS}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SMALLLETTERS\index{SMALLLETTERS@\texttt{SMALLLETTERS}}
\label{SMALLLETTERS}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LETTERS\index{LETTERS@\texttt{LETTERS}}
\label{LETTERS}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DIGITS\index{DIGITS@\texttt{DIGITS}}
\label{DIGITS}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{HEXDIGITS\index{HEXDIGITS@\texttt{HEXDIGITS}}
\label{HEXDIGITS}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{BOXCHARS\index{BOXCHARS@\texttt{BOXCHARS}}
\label{BOXCHARS}
}\hfill{\scriptsize (global variable)}}\\


 These variables contain sets of characters which are useful for text
processing. They are defined as follows.


\begin{description}
\item[{\texttt{WHITESPACE}}] \texttt{" \texttt{\symbol{92}}n\texttt{\symbol{92}}t\texttt{\symbol{92}}r"}
\item[{\texttt{CAPITALLETTERS}}] \texttt{"ABCDEFGHIJKLMNOPQRSTUVWXYZ"}
\item[{\texttt{SMALLLETTERS}}] \texttt{"abcdefghijklmnopqrstuvwxyz"}
\item[{\texttt{LETTERS}}] concatenation of \texttt{CAPITALLETTERS} and \texttt{SMALLLETTERS}
\item[{\texttt{DIGITS}}] \texttt{"0123456789"}
\item[{\texttt{HEXDIGITS}}] \texttt{"0123456789ABCDEFabcdef"}
\item[{\texttt{BOXCHARS}}]  \texttt{Encode(Unicode(9472 + [ 0, 2, 12, 44, 16, 28,
   60, 36, 20, 52, 24, 1, 3, 15, 51, 19, 35, 75, 43, 23, 59, 27, 80, 81,
   84, 102, 87, 96, 108, 99, 90, 105, 93 ]), "UTF-8")}, these are in UTF-8 encoding, the \texttt{i}-th unicode character is \texttt{BOXCHARS\texttt{\symbol{123}}[3*i-2..3*i]\texttt{\symbol{125}}}.
\end{description}
 }



\subsection{\textcolor{Chapter }{TextAttr}}
\logpage{[ 6, 1, 2 ]}\nobreak
\hyperdef{L}{X785F61E77899580E}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{TextAttr\index{TextAttr@\texttt{TextAttr}}
\label{TextAttr}
}\hfill{\scriptsize (global variable)}}\\


 The record \texttt{TextAttr} contains strings which can be printed to change the terminal attribute for the
following characters. This only works with terminals which understand basic
ANSI escape sequences. Try the following example to see if this is the case
for the terminal you are using. It shows the effect of the foreground and
background color attributes and of the \texttt{.bold}, \texttt{.blink}, \texttt{.normal}, \texttt{.reverse} and \texttt{.underscore} which can partly be mixed.
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  extra := ["CSI", "reset", "delline", "home"];;
  for t in Difference(RecNames(TextAttr), extra) do
    Print(TextAttr.(t), "TextAttr.", t, TextAttr.reset,"\n");
  od;
\end{Verbatim}
 The suggested defaults for colors \texttt{0..7} are black, red, green, brown, blue, magenta, cyan, white. But this may be
different for your terminal configuration.

 The escape sequence \texttt{.delline} deletes the content of the current line and \texttt{.home} moves the cursor to the beginning of the current line.
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  for i in [1..5] do
    Print(TextAttr.home, TextAttr.delline, String(i,-6), "\c");
    Sleep(1);
  od;
\end{Verbatim}
 \index{UseColorsInTerminal} Whenever you use this in some printing routines you should make it optional.
Use these attributes only when \texttt{UserPreference("UseColorsInTerminal");} returns \texttt{true}. }



\subsection{\textcolor{Chapter }{WrapTextAttribute}}
\logpage{[ 6, 1, 3 ]}\nobreak
\hyperdef{L}{X7B8AD7517E5FD0EA}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{WrapTextAttribute({\mdseries\slshape str, attr})\index{WrapTextAttribute@\texttt{WrapTextAttribute}}
\label{WrapTextAttribute}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a string with markup



 The argument \mbox{\texttt{\mdseries\slshape str}} must be a text as \textsf{GAP} string, possibly with markup by escape sequences as in \texttt{TextAttr} (\ref{TextAttr}). This function returns a string which is wrapped by the escape sequences \mbox{\texttt{\mdseries\slshape attr}} and \texttt{TextAttr.reset}. It takes care of markup in the given string by appending \mbox{\texttt{\mdseries\slshape attr}} also after each given \texttt{TextAttr.reset} in \mbox{\texttt{\mdseries\slshape str}}.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@str := Concatenation("XXX",TextAttr.2, "BLUB", TextAttr.reset,"YYY");|
  "XXX\033[32mBLUB\033[0mYYY"
  !gapprompt@gap>| !gapinput@str2 := WrapTextAttribute(str, TextAttr.1);|
  "\033[31mXXX\033[32mBLUB\033[0m\033[31m\027YYY\033[0m"
  !gapprompt@gap>| !gapinput@str3 := WrapTextAttribute(str, TextAttr.underscore);|
  "\033[4mXXX\033[32mBLUB\033[0m\033[4m\027YYY\033[0m"
  !gapprompt@gap>| !gapinput@# use Print(str); and so on to see how it looks like.|
\end{Verbatim}
 }



\subsection{\textcolor{Chapter }{FormatParagraph}}
\logpage{[ 6, 1, 4 ]}\nobreak
\hyperdef{L}{X812058CE7C8E9022}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{FormatParagraph({\mdseries\slshape str[, len][, flush][, attr][, widthfun]})\index{FormatParagraph@\texttt{FormatParagraph}}
\label{FormatParagraph}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
the formatted paragraph as string



 This function formats a text given in the string \mbox{\texttt{\mdseries\slshape str}} as a paragraph. The optional arguments have the following meaning:
\begin{description}
\item[{\mbox{\texttt{\mdseries\slshape len}}}] the length of the lines of the formatted text, default is \texttt{78} (counted without a visible length of the strings specified in the \mbox{\texttt{\mdseries\slshape attr}} argument)
\item[{\mbox{\texttt{\mdseries\slshape flush}}}] can be \texttt{"left"}, \texttt{"right"}, \texttt{"center"} or \texttt{"both"}, telling that lines should be flushed left, flushed right, centered or
left-right justified, respectively, default is \texttt{"both"}
\item[{\mbox{\texttt{\mdseries\slshape attr}}}] is a list of two strings; the first is prepended and the second appended to
each line of the result (can for example be used for indenting, \texttt{[" ", ""]}, or some markup, \texttt{[TextAttr.bold, TextAttr.reset]}, default is \texttt{["", ""]})
\item[{\mbox{\texttt{\mdseries\slshape widthfun}}}] must be a function which returns the display width of text in \mbox{\texttt{\mdseries\slshape str}}. The default is \texttt{Length} assuming that each byte corresponds to a character of width one. If \mbox{\texttt{\mdseries\slshape str}} is given in \texttt{UTF-8} encoding one can use \texttt{WidthUTF8String} (\ref{WidthUTF8String}) here.
\end{description}
 This function tries to handle markup with the escape sequences explained in \texttt{TextAttr} (\ref{TextAttr}) correctly.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@str := "One two three four five six seven eight nine ten eleven.";;|
  !gapprompt@gap>| !gapinput@Print(FormatParagraph(str, 25, "left", ["/* ", " */"]));           |
  /* One two three four five */
  /* six seven eight nine ten */
  /* eleven. */
\end{Verbatim}
 }



\subsection{\textcolor{Chapter }{SubstitutionSublist}}
\logpage{[ 6, 1, 5 ]}\nobreak
\hyperdef{L}{X82A9121678923445}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SubstitutionSublist({\mdseries\slshape list, sublist, new[, flag]})\index{SubstitutionSublist@\texttt{SubstitutionSublist}}
\label{SubstitutionSublist}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
the changed list



 This function looks for (non-overlapping) occurrences of a sublist \mbox{\texttt{\mdseries\slshape sublist}} in a list \mbox{\texttt{\mdseries\slshape list}} (compare \texttt{PositionSublist} (\textbf{Reference: PositionSublist})) and returns a list where these are substituted with the list \mbox{\texttt{\mdseries\slshape new}}.

 The optional argument \mbox{\texttt{\mdseries\slshape flag}} can either be \texttt{"all"} (this is the default if not given) or \texttt{"one"}. In the second case only the first occurrence of \mbox{\texttt{\mdseries\slshape sublist}} is substituted.

 If \mbox{\texttt{\mdseries\slshape sublist}} does not occur in \mbox{\texttt{\mdseries\slshape list}} then \mbox{\texttt{\mdseries\slshape list}} itself is returned (and not a \texttt{ShallowCopy(list)}).
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@SubstitutionSublist("xababx", "ab", "a");|
  "xaax"
\end{Verbatim}
 }



\subsection{\textcolor{Chapter }{StripBeginEnd}}
\logpage{[ 6, 1, 6 ]}\nobreak
\hyperdef{L}{X83DE31017B557136}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{StripBeginEnd({\mdseries\slshape list, strip})\index{StripBeginEnd@\texttt{StripBeginEnd}}
\label{StripBeginEnd}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
changed string



 Here \mbox{\texttt{\mdseries\slshape list}} and \mbox{\texttt{\mdseries\slshape strip}} must be lists. This function returns the sublist of list which does not
contain the leading and trailing entries which are entries of \mbox{\texttt{\mdseries\slshape strip}}. If the result is equal to \mbox{\texttt{\mdseries\slshape list}} then \mbox{\texttt{\mdseries\slshape list}} itself is returned.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@StripBeginEnd(" ,a, b,c,   ", ", ");|
  "a, b,c"
\end{Verbatim}
 }



\subsection{\textcolor{Chapter }{StripEscapeSequences}}
\logpage{[ 6, 1, 7 ]}\nobreak
\hyperdef{L}{X7A5978CF84C3C2D3}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{StripEscapeSequences({\mdseries\slshape str})\index{StripEscapeSequences@\texttt{StripEscapeSequences}}
\label{StripEscapeSequences}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
string without escape sequences



 This function returns the string one gets from the string \mbox{\texttt{\mdseries\slshape str}} by removing all escape sequences which are explained in \texttt{TextAttr} (\ref{TextAttr}). If \mbox{\texttt{\mdseries\slshape str}} does not contain such a sequence then \mbox{\texttt{\mdseries\slshape str}} itself is returned. }



\subsection{\textcolor{Chapter }{RepeatedString}}
\logpage{[ 6, 1, 8 ]}\nobreak
\hyperdef{L}{X7D71CB837EE969D4}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RepeatedString({\mdseries\slshape c, len})\index{RepeatedString@\texttt{RepeatedString}}
\label{RepeatedString}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RepeatedUTF8String({\mdseries\slshape c, len})\index{RepeatedUTF8String@\texttt{RepeatedUTF8String}}
\label{RepeatedUTF8String}
}\hfill{\scriptsize (function)}}\\


 Here \mbox{\texttt{\mdseries\slshape c}} must be either a character or a string and \mbox{\texttt{\mdseries\slshape len}} is a non-negative number. Then \texttt{RepeatedString} returns a string of length \mbox{\texttt{\mdseries\slshape len}} consisting of copies of \mbox{\texttt{\mdseries\slshape c}}.

 In the variant \texttt{RepeatedUTF8String} the argument \mbox{\texttt{\mdseries\slshape c}} is considered as string in UTF-8 encoding, and it can also be specified as
unicode string or character, see \texttt{Unicode} (\ref{Unicode}). The result is a string in UTF-8 encoding which has visible width \mbox{\texttt{\mdseries\slshape len}} as explained in \texttt{WidthUTF8String} (\ref{WidthUTF8String}).
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@RepeatedString('=',51);|
  "==================================================="
  !gapprompt@gap>| !gapinput@RepeatedString("*=",51);|
  "*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*"
  !gapprompt@gap>| !gapinput@s := "b�h";;|
  !gapprompt@gap>| !gapinput@enc := GAPInfo.TermEncoding;;|
  !gapprompt@gap>| !gapinput@if enc <> "UTF-8" then s := Encode(Unicode(s, enc), "UTF-8"); fi;|
  !gapprompt@gap>| !gapinput@l := RepeatedUTF8String(s, 8);;|
  !gapprompt@gap>| !gapinput@u := Unicode(l, "UTF-8");;|
  !gapprompt@gap>| !gapinput@Print(Encode(u, enc), "\n");|
  b�hb�hb�
\end{Verbatim}
 }



\subsection{\textcolor{Chapter }{NumberDigits}}
\logpage{[ 6, 1, 9 ]}\nobreak
\hyperdef{L}{X7CEEA5B57D7BB38F}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{NumberDigits({\mdseries\slshape str, base})\index{NumberDigits@\texttt{NumberDigits}}
\label{NumberDigits}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
integer

\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DigitsNumber({\mdseries\slshape n, base})\index{DigitsNumber@\texttt{DigitsNumber}}
\label{DigitsNumber}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
string



 The argument \mbox{\texttt{\mdseries\slshape str}} of \texttt{NumberDigits} must be a string consisting only of an optional leading \texttt{'-'} and characters in \texttt{0123456789abcdefABCDEF}, describing an integer in base \mbox{\texttt{\mdseries\slshape base}} with $2 \leq \mbox{\texttt{\mdseries\slshape base}} \leq 16$. This function returns the corresponding integer.

 The function \texttt{DigitsNumber} does the reverse.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@NumberDigits("1A3F",16);|
  6719
  !gapprompt@gap>| !gapinput@DigitsNumber(6719, 16);|
  "1A3F"
\end{Verbatim}
 }



\subsection{\textcolor{Chapter }{LabelInt}}
\logpage{[ 6, 1, 10 ]}\nobreak
\hyperdef{L}{X79EF038284598D41}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LabelInt({\mdseries\slshape n, type, pre, post})\index{LabelInt@\texttt{LabelInt}}
\label{LabelInt}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
string



 The argument \mbox{\texttt{\mdseries\slshape n}} must be an integer in the range from 1 to 5000, while \mbox{\texttt{\mdseries\slshape pre}} and \mbox{\texttt{\mdseries\slshape post}} must be strings.

 The argument \mbox{\texttt{\mdseries\slshape type}} can be one of \texttt{"Decimal"}, \texttt{"Roman"}, \texttt{"roman"}, \texttt{"Alpha"}, \texttt{"alpha"}.

 The function returns a string that starts with \mbox{\texttt{\mdseries\slshape pre}}, followed by a decimal, respectively roman number or alphanumerical number
literal (capital, respectively small letters), followed by \mbox{\texttt{\mdseries\slshape post}}.


\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@List([1,2,3,4,5,691], i-> LabelInt(i,"Decimal","","."));|
  [ "1.", "2.", "3.", "4.", "5.", "691." ]
  !gapprompt@gap>| !gapinput@List([1,2,3,4,5,691], i-> LabelInt(i,"alpha","(",")"));|
  [ "(a)", "(b)", "(c)", "(d)", "(e)", "(zo)" ]
  !gapprompt@gap>| !gapinput@List([1,2,3,4,5,691], i-> LabelInt(i,"alpha","(",")"));|
  [ "(a)", "(b)", "(c)", "(d)", "(e)", "(zo)" ]
  !gapprompt@gap>| !gapinput@List([1,2,3,4,5,691], i-> LabelInt(i,"Alpha","",".)"));|
  [ "A.)", "B.)", "C.)", "D.)", "E.)", "ZO.)" ]
  !gapprompt@gap>| !gapinput@List([1,2,3,4,5,691], i-> LabelInt(i,"roman","","."));|
  [ "i.", "ii.", "iii.", "iv.", "v.", "dcxci." ]
  !gapprompt@gap>| !gapinput@List([1,2,3,4,5,691], i-> LabelInt(i,"Roman","",""));|
  [ "I", "II", "III", "IV", "V", "DCXCI" ]
\end{Verbatim}
 }



\subsection{\textcolor{Chapter }{PositionMatchingDelimiter}}
\logpage{[ 6, 1, 11 ]}\nobreak
\hyperdef{L}{X7AF694D9839BF65C}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{PositionMatchingDelimiter({\mdseries\slshape str, delim, pos})\index{PositionMatchingDelimiter@\texttt{PositionMatchingDelimiter}}
\label{PositionMatchingDelimiter}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
position as integer or \texttt{fail}



 Here \mbox{\texttt{\mdseries\slshape str}} must be a string and \mbox{\texttt{\mdseries\slshape delim}} a string with two different characters. This function searches the smallest
position \texttt{r} of the character \texttt{\mbox{\texttt{\mdseries\slshape delim}}[2]} in \mbox{\texttt{\mdseries\slshape str}} such that the number of occurrences of \texttt{\mbox{\texttt{\mdseries\slshape delim}}[2]} in \mbox{\texttt{\mdseries\slshape str}} between positions \texttt{\mbox{\texttt{\mdseries\slshape pos}}+1} and \texttt{r} is by one greater than the corresponding number of occurrences of \texttt{\mbox{\texttt{\mdseries\slshape delim}}[1]}.

 If such an \texttt{r} exists, it is returned. Otherwise \texttt{fail} is returned.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@PositionMatchingDelimiter("{}x{ab{c}d}", "{}", 0);|
  fail
  !gapprompt@gap>| !gapinput@PositionMatchingDelimiter("{}x{ab{c}d}", "{}", 1);|
  2
  !gapprompt@gap>| !gapinput@PositionMatchingDelimiter("{}x{ab{c}d}", "{}", 6);|
  11
\end{Verbatim}
 }



\subsection{\textcolor{Chapter }{WordsString}}
\logpage{[ 6, 1, 12 ]}\nobreak
\hyperdef{L}{X832556617F10AAA8}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{WordsString({\mdseries\slshape str})\index{WordsString@\texttt{WordsString}}
\label{WordsString}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
list of strings containing the words



 This returns the list of words of a text stored in the string \mbox{\texttt{\mdseries\slshape str}}. All non-letters are considered as word boundaries and are removed.
\begin{Verbatim}[commandchars=@|A,fontsize=\small,frame=single,label=Example]
  @gapprompt|gap>A @gapinput|WordsString("one_two \n    three!?");A
  [ "one", "two", "three" ]
\end{Verbatim}
 }



\subsection{\textcolor{Chapter }{Base64String}}
\logpage{[ 6, 1, 13 ]}\nobreak
\hyperdef{L}{X83F2821783DA9826}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Base64String({\mdseries\slshape str})\index{Base64String@\texttt{Base64String}}
\label{Base64String}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{StringBase64({\mdseries\slshape bstr})\index{StringBase64@\texttt{StringBase64}}
\label{StringBase64}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a string



 The first function translates arbitrary binary data given as a GAP string into
a \emph{base 64} encoded string. This encoded string contains only printable ASCII characters
and is used in various data transfer protocols (\texttt{MIME} encoded emails, weak password encryption, ...). We use the specification in \href{http://tools.ietf.org/html/rfc2045} {RFC 2045}.

 The second function has the reverse functionality. Here we also accept the
characters \texttt{-{\textunderscore}} instead of \texttt{+/} as last two characters. Whitespace is ignored.
\begin{Verbatim}[commandchars=@|D,fontsize=\small,frame=single,label=Example]
  @gapprompt|gap>D @gapinput|b := Base64String("This is a secret!");D
  "VGhpcyBpcyBhIHNlY3JldCEA="
  @gapprompt|gap>D @gapinput|StringBase64(b);                       D
  "This is a secret!"
\end{Verbatim}
 }

 }


\section{\textcolor{Chapter }{Unicode Strings}}\label{sec:Unicode}
\logpage{[ 6, 2, 0 ]}
\hyperdef{L}{X8489C67D80399814}{}
{
  The \textsf{GAPDoc} package provides some tools to deal with unicode characters and strings. These
can be used for recoding text strings between various encodings.
\subsection{\textcolor{Chapter }{Unicode Strings and Characters}}\logpage{[ 6, 2, 1 ]}
\hyperdef{L}{X8475671278948DDD}{}
{
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Unicode({\mdseries\slshape list[, encoding]})\index{Unicode@\texttt{Unicode}}
\label{Unicode}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{UChar({\mdseries\slshape num})\index{UChar@\texttt{UChar}}
\label{UChar}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsUnicodeString\index{IsUnicodeString@\texttt{IsUnicodeString}}
\label{IsUnicodeString}
}\hfill{\scriptsize (filter)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsUnicodeCharacter\index{IsUnicodeCharacter@\texttt{IsUnicodeCharacter}}
\label{IsUnicodeCharacter}
}\hfill{\scriptsize (filter)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IntListUnicodeString({\mdseries\slshape ustr})\index{IntListUnicodeString@\texttt{IntListUnicodeString}}
\label{IntListUnicodeString}
}\hfill{\scriptsize (function)}}\\


 Unicode characters are described by their \emph{codepoint}, an integer in the range from $0$ to $2^{21}-1$. For details about unicode, see \href{http://www.unicode.org} {\texttt{http://www.unicode.org}}.

 The function \texttt{UChar} wraps an integer \mbox{\texttt{\mdseries\slshape num}} into a \textsf{GAP} object lying in the filter \texttt{IsUnicodeCharacter}. Use \texttt{Int} to get the codepoint back. The argument \mbox{\texttt{\mdseries\slshape num}} can also be a \textsf{GAP} character which is then translated to an integer via \texttt{IntChar} (\textbf{Reference: IntChar}).

 \texttt{Unicode} produces a \textsf{GAP} object in the filter \texttt{IsUnicodeString}. This is a wrapped list of integers for the unicode characters in the string.
The function \texttt{IntListUnicodeString} gives access to this list of integers. Basic list functionality is available
for \texttt{IsUnicodeString} elements. The entries are in \texttt{IsUnicodeCharacter}. The argument \mbox{\texttt{\mdseries\slshape list}} for \texttt{Unicode} is either a list of integers or a \textsf{GAP} string. In the latter case an \mbox{\texttt{\mdseries\slshape encoding}} can be specified as string, its default is \texttt{"UTF-8"}.

 \index{URL encoding}\index{RFC 3986} Currently supported encodings can be found in \texttt{UNICODE{\textunderscore}RECODE.NormalizedEncodings} (ASCII, ISO-8859-X, UTF-8 and aliases). The encoding \texttt{"XML"} means an ASCII encoding in which non-ASCII characters are specified by XML
character entities. The encoding \texttt{"URL"} is for URL-encoded (also called percent-encoded strings, as specified in RFC
3986 (\href{http://www.ietf.org/rfc/rfc3986.txt} {see here}). The listed encodings \texttt{"LaTeX"} and aliases cannot be used with \texttt{Unicode}. See the operation \texttt{Encode} (\ref{Encode}) for mapping a unicode string to a \textsf{GAP} string.


\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@ustr := Unicode("a and \366", "latin1");|
  Unicode("a and �")
  !gapprompt@gap>| !gapinput@ustr = Unicode("a and &#246;", "XML");  |
  true
  !gapprompt@gap>| !gapinput@IntListUnicodeString(ustr);|
  [ 97, 32, 97, 110, 100, 32, 246 ]
  !gapprompt@gap>| !gapinput@ustr[7];|
  '�'
\end{Verbatim}
 }



\subsection{\textcolor{Chapter }{Encode}}
\logpage{[ 6, 2, 2 ]}\nobreak
\hyperdef{L}{X818A31567EB30A39}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Encode({\mdseries\slshape ustr[, encoding]})\index{Encode@\texttt{Encode}}
\label{Encode}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
a \textsf{GAP} string

\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SimplifiedUnicodeString({\mdseries\slshape ustr[, encoding][, "single"]})\index{SimplifiedUnicodeString@\texttt{SimplifiedUnicodeString}}
\label{SimplifiedUnicodeString}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a unicode string

\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LowercaseUnicodeString({\mdseries\slshape ustr})\index{LowercaseUnicodeString@\texttt{LowercaseUnicodeString}}
\label{LowercaseUnicodeString}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a unicode string

\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{UppercaseUnicodeString({\mdseries\slshape ustr})\index{UppercaseUnicodeString@\texttt{UppercaseUnicodeString}}
\label{UppercaseUnicodeString}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a unicode string

\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LaTeXUnicodeTable\index{LaTeXUnicodeTable@\texttt{LaTeXUnicodeTable}}
\label{LaTeXUnicodeTable}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SimplifiedUnicodeTable\index{SimplifiedUnicodeTable@\texttt{SimplifiedUnicodeTable}}
\label{SimplifiedUnicodeTable}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LowercaseUnicodeTable\index{LowercaseUnicodeTable@\texttt{LowercaseUnicodeTable}}
\label{LowercaseUnicodeTable}
}\hfill{\scriptsize (global variable)}}\\


 The operation \texttt{Encode} translates a unicode string \mbox{\texttt{\mdseries\slshape ustr}} into a \textsf{GAP} string in some specified \mbox{\texttt{\mdseries\slshape encoding}}. The default encoding is \texttt{"UTF-8"}.

 Supported encodings can be found in \texttt{UNICODE{\textunderscore}RECODE.NormalizedEncodings}. Except for some cases mentioned below characters which are not available in
the target encoding are substituted by '?' characters.

 If the \mbox{\texttt{\mdseries\slshape encoding}} is \texttt{"URL"} (see \texttt{Unicode} (\ref{Unicode})) then an optional argument \mbox{\texttt{\mdseries\slshape encreserved}} can be given, it must be a list of reserved characters which should be percent
encoded; the default is to encode only the \texttt{\%} character.

 The encoding \texttt{"LaTeX"} substitutes non-ASCII characters and {\LaTeX} special characters by {\LaTeX} code as given in an ordered list \texttt{LaTeXUnicodeTable} of pairs [codepoint, string]. If you have a unicode character for which no
substitution is contained in that list, you will get a warning and the
translation is \texttt{Unicode(nr)}. In this case find a substitution and add a corresponding [codepoint, string]
pair to \texttt{LaTeXUnicodeTable} using \texttt{AddSet} (\textbf{Reference: AddSet}). Also, please, tell the \textsf{GAPDoc} authors about your addition, such that we can extend the list \texttt{LaTeXUnicodeTable}. (Most of the initial entries were generated from lists in the {\TeX} projects enc{\TeX} and \texttt{ucs}.) There are some variants of this encoding:

 \texttt{"LaTeXleavemarkup"} does the same translations for non-ASCII characters but leaves the {\LaTeX} special characters (e.g., any {\LaTeX} commands) as they are.

 \texttt{"LaTeXUTF8"} does not give a warning about unicode characters without explicit translation,
instead it translates the character to its \texttt{UTF-8} encoding. Make sure to setup your {\LaTeX} document such that all these characters are understood.

 \texttt{"LaTeXUTF8leavemarkup"} is a combination of the last two variants.

 Note that the \texttt{"LaTeX"} encoding can only be used with \texttt{Encode} but not for the opposite translation with \texttt{Unicode} (\ref{Unicode}) (which would need far too complicated heuristics).

 The function \texttt{SimplifiedUnicodeString} can be used to substitute many non-ASCII characters by related ASCII
characters or strings (e.g., by a corresponding character without accents).
The argument \mbox{\texttt{\mdseries\slshape ustr}} and the result are unicode strings, if \mbox{\texttt{\mdseries\slshape encoding}} is \texttt{"ASCII"} then all non-ASCII characters are translated, otherwise only the non-latin1
characters. If the string \texttt{"single"} in an argument then only substitutions are considered which don't make the
result string longer. The translations are stored in a sorted list \texttt{SimplifiedUnicodeTable}. Its entries are of the form \texttt{[codepoint, trans1, trans2, ...]}. Here \texttt{trans1} and so on is either an integer for the codepoint of a substitution character
or it is a list of codepoint integers. If you are missing characters in this
list and know a sensible ASCII approximation, then add an entry (with \texttt{AddSet} (\textbf{Reference: AddSet})) and tell the \textsf{GAPDoc} authors about it. (The initial content of \texttt{SimplifiedUnicodeTable} was mainly generated from the ``\texttt{transtab}'' tables by Markus Kuhn.)

 The function \texttt{LowercaseUnicodeString} gets and returns a unicode string and translates each uppercase character to
its corresponding lowercase version. This function uses a list \texttt{LowercaseUnicodeTable} of pairs of codepoint integers. This list was generated using the file \texttt{UnicodeData.txt} from the unicode definition (field 14 in each row).

 The function \texttt{UppercaseUnicodeString} does the similar translation to uppercase characters.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@ustr := Unicode("a and &#246;", "XML");|
  Unicode("a and �")
  !gapprompt@gap>| !gapinput@SimplifiedUnicodeString(ustr, "ASCII");|
  Unicode("a and oe")
  !gapprompt@gap>| !gapinput@SimplifiedUnicodeString(ustr, "ASCII", "single");|
  Unicode("a and o")
  !gapprompt@gap>| !gapinput@ustr2 := UppercaseUnicodeString(ustr);;|
  !gapprompt@gap>| !gapinput@Print(Encode(ustr2, GAPInfo.TermEncoding), "\n");|
  A AND �
\end{Verbatim}
 }


\subsection{\textcolor{Chapter }{Lengths of UTF-8 strings}}\logpage{[ 6, 2, 3 ]}
\hyperdef{L}{X801237207E06A876}{}
{
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{WidthUTF8String({\mdseries\slshape str})\index{WidthUTF8String@\texttt{WidthUTF8String}}
\label{WidthUTF8String}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{NrCharsUTF8String({\mdseries\slshape str})\index{NrCharsUTF8String@\texttt{NrCharsUTF8String}}
\label{NrCharsUTF8String}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
an integer



 Let \mbox{\texttt{\mdseries\slshape str}} be a \textsf{GAP} string with text in UTF-8 encoding. There are three ``lengths'' of such a string which must be distinguished. The operation \texttt{Length} (\textbf{Reference: Length}) returns the number of bytes and so the memory occupied by \mbox{\texttt{\mdseries\slshape str}}. The function \texttt{NrCharsUTF8String} returns the number of unicode characters in \mbox{\texttt{\mdseries\slshape str}}, that is the length of \texttt{Unicode(\mbox{\texttt{\mdseries\slshape str}})}.

 In many applications the function \texttt{WidthUTF8String} is more interesting, it returns the number of columns needed by the string if
printed to a terminal. This takes into account that some unicode characters
are combining characters and that there are wide characters which need two
columns (e.g., for Chinese or Japanese). (To be precise: This implementation
assumes that there are no control characters in \mbox{\texttt{\mdseries\slshape str}} and uses the character width returned by the \texttt{wcwidth} function in the GNU C-library called with UTF-8 locale.)
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@# A, German umlaut u, B, zero width space, C, newline|
  !gapprompt@gap>| !gapinput@str := Encode( Unicode( "A&#xFC;B&#x200B;C\n", "XML" ) );;|
  !gapprompt@gap>| !gapinput@Print(str);|
  A�BC
  !gapprompt@gap>| !gapinput@# umlaut u needs two bytes and the zero width space three|
  !gapprompt@gap>| !gapinput@Length(str);|
  9
  !gapprompt@gap>| !gapinput@NrCharsUTF8String(str);|
  6
  !gapprompt@gap>| !gapinput@# zero width space and newline don't contribute to width|
  !gapprompt@gap>| !gapinput@WidthUTF8String(str);|
  4
\end{Verbatim}
 }



\subsection{\textcolor{Chapter }{InitialSubstringUTF8String}}
\logpage{[ 6, 2, 4 ]}\nobreak
\hyperdef{L}{X7E2974CD84977819}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{InitialSubstringUTF8String({\mdseries\slshape str, maxwidth[, suf]})\index{InitialSubstringUTF8String@\texttt{InitialSubstringUTF8String}}
\label{InitialSubstringUTF8String}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
UTF-8 encoded string



 The arguments \mbox{\texttt{\mdseries\slshape str}} and \mbox{\texttt{\mdseries\slshape suf}} each must be a \textsf{GAP} string with text in UTF-8 encoding or a unicode string. The argument \mbox{\texttt{\mdseries\slshape suf}} is optional and its default value is the empty string. If the visible width of \mbox{\texttt{\mdseries\slshape str}} is at most \mbox{\texttt{\mdseries\slshape maxwidth}} then \mbox{\texttt{\mdseries\slshape str}} is returned as UTF-8 encoded \textsf{GAP} string. Otherwise, \mbox{\texttt{\mdseries\slshape suf}} is appended to the maximal initial substring of \mbox{\texttt{\mdseries\slshape str}} such that the total visible width of the result is at most \mbox{\texttt{\mdseries\slshape maxwidth}}.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@# A, German umlaut u, B, zero width space, C, newline|
  !gapprompt@gap>| !gapinput@str := Encode( Unicode( "A&#xFC;B&#x200B;C\n", "XML" ) );;|
  !gapprompt@gap>| !gapinput@ini := InitialSubstringUTF8String(str, 3);;|
  !gapprompt@gap>| !gapinput@WidthUTF8String(ini);|
  3
  !gapprompt@gap>| !gapinput@IntListUnicodeString(Unicode(ini));|
  [ 65, 252, 66, 8203 ]
  !gapprompt@gap>| !gapinput@l := Unicode([ 23380, 22827, 23376 ] );; # three chars of width 2|
  !gapprompt@gap>| !gapinput@s := InitialSubstringUTF8String(l, 4, "*");;|
  !gapprompt@gap>| !gapinput@WidthUTF8String(s);|
  3
\end{Verbatim}
 }

 }


\section{\textcolor{Chapter }{Print Utilities}}\label{PrintUtil}
\logpage{[ 6, 3, 0 ]}
\hyperdef{L}{X860C83047DC4F1BC}{}
{
  The following printing utilities turned out to be useful for interactive work
with texts in \textsf{GAP}. But they are more general and so we document them here.

\subsection{\textcolor{Chapter }{PrintTo1}}
\logpage{[ 6, 3, 1 ]}\nobreak
\hyperdef{L}{X8603B90C7C3F0AB1}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{PrintTo1({\mdseries\slshape filename, fun})\index{PrintTo1@\texttt{PrintTo1}}
\label{PrintTo1}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AppendTo1({\mdseries\slshape filename, fun})\index{AppendTo1@\texttt{AppendTo1}}
\label{AppendTo1}
}\hfill{\scriptsize (function)}}\\


 The argument \mbox{\texttt{\mdseries\slshape fun}} must be a function without arguments. Everything which is printed by a call \mbox{\texttt{\mdseries\slshape fun()}} is printed into the file \mbox{\texttt{\mdseries\slshape filename}}. As with \texttt{PrintTo} (\textbf{Reference: PrintTo}) and \texttt{AppendTo} (\textbf{Reference: AppendTo}) this overwrites or appends to, respectively, a previous content of \mbox{\texttt{\mdseries\slshape filename}}.

 These functions can be particularly efficient when many small pieces of text
shall be written to a file, because no multiple reopening of the file is
necessary.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@f := function() local i; |
  !gapprompt@>| !gapinput@  for i in [1..100000] do Print(i, "\n"); od; end;; |
  !gapprompt@gap>| !gapinput@PrintTo1("nonsense", f); # now check the local file `nonsense'|
\end{Verbatim}
 }



\subsection{\textcolor{Chapter }{StringPrint}}
\logpage{[ 6, 3, 2 ]}\nobreak
\hyperdef{L}{X829B720C86E57E8B}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{StringPrint({\mdseries\slshape obj1[, obj2[, ...]]})\index{StringPrint@\texttt{StringPrint}}
\label{StringPrint}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{StringView({\mdseries\slshape obj})\index{StringView@\texttt{StringView}}
\label{StringView}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{StringDisplay({\mdseries\slshape obj})\index{StringDisplay@\texttt{StringDisplay}}
\label{StringDisplay}
}\hfill{\scriptsize (function)}}\\


 These functions return a string containing the output of a \texttt{Print}, \texttt{ViewObj} or \texttt{Display} call, respectively, with the same arguments.

 This should be considered as a (temporary?) hack. It would be better to have \texttt{String} (\textbf{Reference: String}) methods for all \textsf{GAP} objects and to have a generic \texttt{Print} (\textbf{Reference: Print})-function which just interprets these strings. }



\subsection{\textcolor{Chapter }{PrintFormattedString}}
\logpage{[ 6, 3, 3 ]}\nobreak
\hyperdef{L}{X812A8326844BC910}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{PrintFormattedString({\mdseries\slshape str})\index{PrintFormattedString@\texttt{PrintFormattedString}}
\label{PrintFormattedString}
}\hfill{\scriptsize (function)}}\\


 This function prints a string \mbox{\texttt{\mdseries\slshape str}}. The difference to \texttt{Print(str);} is that no additional line breaks are introduced by \textsf{GAP}'s standard printing mechanism. This can be used to print lines which are
longer than the current screen width. In particular one can print text which
contains escape sequences like those explained in \texttt{TextAttr} (\ref{TextAttr}), where lines may have more characters than \emph{visible characters}. }



\subsection{\textcolor{Chapter }{Page}}
\logpage{[ 6, 3, 4 ]}\nobreak
\hyperdef{L}{X7BB6731F7E3AAA98}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Page({\mdseries\slshape ...})\index{Page@\texttt{Page}}
\label{Page}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{PageDisplay({\mdseries\slshape obj})\index{PageDisplay@\texttt{PageDisplay}}
\label{PageDisplay}
}\hfill{\scriptsize (function)}}\\


 These functions are similar to \texttt{Print} (\textbf{Reference: Print}) and \texttt{Display} (\textbf{Reference: Display}), respectively. The difference is that the output is not sent directly to the
screen, but is piped into the current pager; see \texttt{Pager} (\textbf{Reference: Pager}).
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@Page([1..1421]+0);|
  !gapprompt@gap>| !gapinput@PageDisplay(CharacterTable("Symmetric", 14));|
\end{Verbatim}
 }



\subsection{\textcolor{Chapter }{StringFile}}
\logpage{[ 6, 3, 5 ]}\nobreak
\hyperdef{L}{X7E14D32181FBC3C3}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{StringFile({\mdseries\slshape filename})\index{StringFile@\texttt{StringFile}}
\label{StringFile}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{FileString({\mdseries\slshape filename, str[, append]})\index{FileString@\texttt{FileString}}
\label{FileString}
}\hfill{\scriptsize (function)}}\\


 The function \texttt{StringFile} returns the content of file \mbox{\texttt{\mdseries\slshape filename}} as a string. This works efficiently with arbitrary (binary or text) files. If
something went wrong, this function returns \texttt{fail}.

 Conversely the function \texttt{FileString} writes the content of a string \mbox{\texttt{\mdseries\slshape str}} into the file \mbox{\texttt{\mdseries\slshape filename}}. If the optional third argument \mbox{\texttt{\mdseries\slshape append}} is given and equals \texttt{true} then the content of \mbox{\texttt{\mdseries\slshape str}} is appended to the file. Otherwise previous content of the file is deleted.
This function returns the number of bytes written or \texttt{fail} if something went wrong.

 Both functions are quite efficient, even with large files. }

 }

 }


\chapter{\textcolor{Chapter }{Utilities for Bibliographies}}\label{ch:bibutil}
\logpage{[ 7, 0, 0 ]}
\hyperdef{L}{X7EB94CE97ABF7192}{}
{
  A standard for collecting references (in particular to mathematical texts) is Bib{\TeX} (\href{http://www.ctan.org/tex-archive/biblio/bibtex/distribs/doc/} {\texttt{http://www.ctan.org/tex-archive/biblio/bibtex/distribs/doc/}}). A disadvantage of Bib{\TeX} is that the format of the data is specified with the use by {\LaTeX} in mind. The data format is less suited for conversion to other document types
like plain text or HTML.

 In the first section we describe utilities for using data from Bib{\TeX} files in \textsf{GAP}.

 In the second section we introduce a new XML based data format BibXMLext for
bibliographies which seems better suited for other tasks than using it with {\LaTeX}.

 Another section will describe utilities to deal with BibXMLext data in \textsf{GAP}.
\section{\textcolor{Chapter }{Parsing Bib{\TeX} Files}}\label{ParseBib}
\logpage{[ 7, 1, 0 ]}
\hyperdef{L}{X7A4126EC7BD68F64}{}
{
  Here are functions for parsing, normalizing and printing reference lists in Bib{\TeX} format. The reference describing this format is{\nobreakspace}\cite[Appendix B]{La85}.

\subsection{\textcolor{Chapter }{ParseBibFiles}}
\logpage{[ 7, 1, 1 ]}\nobreak
\hyperdef{L}{X82555C307FDC1817}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ParseBibFiles({\mdseries\slshape bibfile1[, bibfile2[, ...]]})\index{ParseBibFiles@\texttt{ParseBibFiles}}
\label{ParseBibFiles}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ParseBibStrings({\mdseries\slshape str1[, str2[, ...]]})\index{ParseBibStrings@\texttt{ParseBibStrings}}
\label{ParseBibStrings}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
list \texttt{[list of bib-records, list of abbrevs, list of expansions]}



 The first function parses the files \mbox{\texttt{\mdseries\slshape bibfile1}} and so on (if a file does not exist the extension \texttt{.bib} is appended) in Bib{\TeX} format and returns a list as follows: \texttt{[entries, strings, texts]}. Here \texttt{entries} is a list of records, one record for each reference contained in \mbox{\texttt{\mdseries\slshape bibfile}}. Then \texttt{strings} is a list of abbreviations defined by \texttt{@string}-entries in \mbox{\texttt{\mdseries\slshape bibfile}} and \texttt{texts} is a list which contains in the corresponding position the full text for such
an abbreviation.

 The second function does the same, but the input is given as \textsf{GAP} strings \mbox{\texttt{\mdseries\slshape str1}} and so on.

 The records in \texttt{entries} store key-value pairs of a Bib{\TeX} reference in the form \texttt{rec(key1 = value1, ...)}. The names of the keys are converted to lower case. The type of the reference
(i.e., book, article, ...) and the citation key are stored as components \texttt{.Type} and \texttt{.Label}. The records also have a \texttt{.From} field that says that the data are read from a Bib{\TeX} source.

 As an example consider the following Bib{\TeX} file.
\begin{Verbatim}[fontsize=\small,frame=single,label=doc/test.bib]
  @string{ j  = "Important Journal" }
  @article{ AB2000, Author=  "Fritz A. First and Sec, X. Y.",
  TITLE="Short", journal = j, year = 2000 }
\end{Verbatim}

\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@bib := ParseBibFiles("doc/test.bib");|
  [ [ rec( From := rec( BibTeX := true ), Label := "AB2000",
            Type := "article", author := "Fritz A. First and Sec, X. Y."
              , journal := "Important Journal", title := "Short",
            year := "2000" ) ], [ "j" ], [ "Important Journal" ] ]
\end{Verbatim}
 }



\subsection{\textcolor{Chapter }{NormalizedNameAndKey}}
\logpage{[ 7, 1, 2 ]}\nobreak
\hyperdef{L}{X7C9F0C337A0A0FF0}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{NormalizedNameAndKey({\mdseries\slshape namestr})\index{NormalizedNameAndKey@\texttt{NormalizedNameAndKey}}
\label{NormalizedNameAndKey}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
list of strings and names as lists

\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{NormalizeNameAndKey({\mdseries\slshape r})\index{NormalizeNameAndKey@\texttt{NormalizeNameAndKey}}
\label{NormalizeNameAndKey}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing



 The argument \mbox{\texttt{\mdseries\slshape namestr}} must be a string describing an author or a list of authors as described in the Bib{\TeX} documentation in \cite[Appendix  B 1.2]{La85}. The function \texttt{NormalizedNameAndKey} returns a list of the form [ normalized name string, short key, long key,
names as lists]. The first entry is a normalized form of the input where names
are written as ``lastname, first name initials''. The second and third entry are the name parts of a short and long key for
the bibliography entry, formed from the (initials of) last names. The fourth
entry is a list of lists, one for each name, where a name is described by
three strings for the last name, the first name initials and the first name(s)
as given in the input.

 The function \texttt{NormalizeNameAndKey} gets as argument \mbox{\texttt{\mdseries\slshape r}} a record for a bibliography entry as returned by \texttt{ParseBibFiles} (\ref{ParseBibFiles}). It substitutes \texttt{.author} and \texttt{.editor} fields of \mbox{\texttt{\mdseries\slshape r}} by their normalized form, the original versions are stored in fields \texttt{.authororig} and \texttt{.editororig}.

 Furthermore a short and a long citation key is generated and stored in
components \texttt{.printedkey} (only if no \texttt{.key} is already bound) and \texttt{.keylong}.

 We continue the example from \texttt{ParseBibFiles} (\ref{ParseBibFiles}).
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@bib := ParseBibFiles("doc/test.bib");;|
  !gapprompt@gap>| !gapinput@NormalizedNameAndKey(bib[1][1].author);|
  [ "First, F. A. and Sec, X. Y.", "FS", "firstsec",
    [ [ "First", "F. A.", "Fritz A." ], [ "Sec", "X. Y.", "X. Y." ] ] ]
  !gapprompt@gap>| !gapinput@NormalizeNameAndKey(bib[1][1]);|
  !gapprompt@gap>| !gapinput@bib[1][1];|
  rec( From := rec( BibTeX := true ), Label := "AB2000",
    Type := "article", author := "First, F. A. and Sec, X. Y.",
    authororig := "Fritz A. First and Sec, X. Y.",
    journal := "Important Journal", keylong := "firstsec2000",
    printedkey := "FS00", title := "Short", year := "2000" )
\end{Verbatim}
 }



\subsection{\textcolor{Chapter }{WriteBibFile}}
\logpage{[ 7, 1, 3 ]}\nobreak
\hyperdef{L}{X7C2B2F65851EAA0B}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{WriteBibFile({\mdseries\slshape bibfile, bib})\index{WriteBibFile@\texttt{WriteBibFile}}
\label{WriteBibFile}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing



 This is the converse of \texttt{ParseBibFiles} (\ref{ParseBibFiles}). Here \mbox{\texttt{\mdseries\slshape bib}} either must have a format as list of three lists as it is returned by \texttt{ParseBibFiles} (\ref{ParseBibFiles}). Or \mbox{\texttt{\mdseries\slshape bib}} can be a record as returned by \texttt{ParseBibXMLextFiles} (\ref{ParseBibXMLextFiles}). A Bib{\TeX} file \mbox{\texttt{\mdseries\slshape bibfile}} is written and the entries are formatted in a uniform way. All given
abbreviations are used while writing this file.

 We continue the example from \texttt{NormalizeNameAndKey} (\ref{NormalizeNameAndKey}). The command
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@WriteBibFile("nicer.bib", bib);|
\end{Verbatim}
 produces a file \texttt{nicer.bib} as follows:
\begin{Verbatim}[fontsize=\small,frame=single,label=nicer.bib]
  @string{j = "Important Journal" }

  @article{ AB2000,
    author =           {First, F. A. and Sec, X. Y.},
    title =            {Short},
    journal =          j,
    year =             {2000},
    authororig =       {Fritz A. First and Sec, X. Y.},
    keylong =          {firstsec2000},
    printedkey =       {FS00}
  }
\end{Verbatim}
 }



\subsection{\textcolor{Chapter }{LabelsFromBibTeX}}
\logpage{[ 7, 1, 4 ]}\nobreak
\hyperdef{L}{X783FD118794399DF}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LabelsFromBibTeX({\mdseries\slshape path, keys, bibfiles, style})\index{LabelsFromBibTeX@\texttt{LabelsFromBibTeX}}
\label{LabelsFromBibTeX}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a list of pairs of strings \texttt{[key, label]}



 This function uses \texttt{bibtex} to determine the ordering of a list of references and a label for each entry
which is typeset in a document citing these references.

 The argument \mbox{\texttt{\mdseries\slshape path}} is a directory specified as string or directory object. The argument \mbox{\texttt{\mdseries\slshape bibfiles}} must be a list of files in Bib{\TeX} format, each specified by a path relative to the first argument, or an
absolute path (starting with \texttt{'/'}) or relative to the \textsf{GAP} roots (starting with \texttt{"gap://"}). The list \mbox{\texttt{\mdseries\slshape keys}} must contain strings which occur as keys in the given Bib{\TeX} files. Finally the string \mbox{\texttt{\mdseries\slshape style}} must be the name of a bibliography style (like \texttt{"alpha"}).

 The list returned by this function contains pairs \texttt{[key, label]} where \texttt{key} is one of the entries of \mbox{\texttt{\mdseries\slshape keys}} and \texttt{label} is a string used for citations of the bibliography entry in a document. These
pairs are ordered as the reference list produced by Bib{\TeX}.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@f := Filename(DirectoriesPackageLibrary("gapdoc","doc"), "test.bib");;|
  !gapprompt@gap>| !gapinput@LabelsFromBibTeX(".", ["AB2000"], [f], "alpha");|
  [ [ "AB2000", "FS00" ] ]
\end{Verbatim}
 }



\subsection{\textcolor{Chapter }{InfoBibTools}}
\logpage{[ 7, 1, 5 ]}\nobreak
\hyperdef{L}{X85C1D50F7E37A99A}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{InfoBibTools\index{InfoBibTools@\texttt{InfoBibTools}}
\label{InfoBibTools}
}\hfill{\scriptsize (info class)}}\\


 The default level of this info class is 1. Functions like \texttt{ParseBibFiles} (\ref{ParseBibFiles}), \texttt{StringBibAs...} are then printing some information. You can suppress it by setting the level
of \texttt{InfoBibTools} to 0. With level 2 there may be some more information for debugging purposes. }

 }


\section{\textcolor{Chapter }{The BibXMLext Format}}\label{BibXMLformat}
\logpage{[ 7, 2, 0 ]}
\hyperdef{L}{X7FB8F6BD80D859D1}{}
{
  Bibliographical data in Bib{\TeX} files have the disadvantage that the actual data are given in {\LaTeX} syntax. This makes it difficult to use the data for anything but for {\LaTeX}, say for representations of the data as plain text or HTML. For example:
mathematical formulae are in {\LaTeX} \texttt{\$} environments, non-ASCII characters can be specified in many strange ways, and
how to specify URLs for links if the output format allows them?

 Here we propose an XML data format for bibliographical data which addresses
these problems, it is called BibXMLext. In the next section we describe some
tools for generating (an approximation to) this data format from Bib{\TeX} data, and for using data given in BibXMLext format for various purposes.

 The first motivation for this development was the handling of bibliographical
data in \textsf{GAPDoc}, but the format and the tools are certainly useful for other purposes as
well.

 We started from a DTD \texttt{bibxml.dtd} which is publicly available, say from \href{http://bibtexml.sf.net/} {\texttt{http://bibtexml.sf.net/}}. This is essentially a reformulation of the definition of the Bib{\TeX} format, including several of some widely used further fields. This has already
the advantage that a generic XML parser can check the validity of the data
entries, for example for missing compulsary fields in entries. We applied the
following changes and extensions to define the DTD for BibXMLext, stored in
the file \texttt{bibxmlext.dtd} which can be found in the root directory of this \textsf{GAPDoc} package (and in Appendix \ref{bibxmlextdtd}):
\begin{description}
\item[{names}] Lists of names in the \texttt{author} and \texttt{editor} fields in Bib{\TeX} are difficult to parse. Here they must be given by a sequence of \texttt{{\textless}name{\textgreater}}-elements which each contain an optional \texttt{{\textless}first{\textgreater}}- and a \texttt{{\textless}last{\textgreater}}-element for the first and last names, respectively.
\item[{\texttt{{\textless}M{\textgreater}} and \texttt{{\textless}Math{\textgreater}}}] These elements enclose mathematical formulae, the content is {\LaTeX} code (without the \texttt{\$}). These should be handled in the same way as the elements with the same names
in \textsf{GAPDoc}, see \ref{M} and \ref{Math}. In particular, simple formulae which have a well defined plain text
representation can be given in \texttt{{\textless}M{\textgreater}}-elements.
\item[{Encoding}] Note that in XML files we can use the full range of unicode characters, see \href{http://www.unicode.org/} {\texttt{http://www.unicode.org/}}. All non-ASCII characters should be specified as unicode characters. This
makes dealing with special characters easy for plain text or HTML, only for
use with {\LaTeX} some sort of translation is necessary.
\item[{\texttt{{\textless}URL{\textgreater}}}] These elements are allowed everywhere in the text and should be represented by
links in converted formats which allow this. It is used in the same way as the
element with the same name in \textsf{GAPDoc}, see \ref{URL}.
\item[{\texttt{{\textless}Alt Only="..."{\textgreater}} and \texttt{{\textless}Alt Not="..."{\textgreater}}}] Sometimes information should be given in different ways, depending on the
output format of the data. This is possible with the \texttt{{\textless}Alt{\textgreater}}-elements with the same definition as in \textsf{GAPDoc}, see \ref{Alt}.
\item[{\texttt{{\textless}C{\textgreater}}}] This element should be used to protect text from case changes by converters
(the extra \texttt{\texttt{\symbol{123}}\texttt{\symbol{125}}} characters in Bib{\TeX} title fields).
\item[{\texttt{{\textless}string key="..." value="..."/{\textgreater}} and \texttt{{\textless}value key="..."/{\textgreater}}}] The \texttt{{\textless}string{\textgreater}}-element defines key-value pairs which can be used in any field via the \texttt{{\textless}value{\textgreater}}-element (not only for whole fields but also parts of the text).
\item[{\texttt{{\textless}other type="..."{\textgreater}}}] This is a generic element for fields which are otherwise not supported. An
arbitrary number of them is allowed for each entry, so any kind of additional
data can be added to entries.
\item[{\texttt{{\textless}Wrap Name="..."{\textgreater}}}] This generic element is allowed inside all fields. This markup will be just
ignored (but not the element content) by our standard tools. But it can be a
useful hook for introducing arbitrary further markup (and our tools can easily
be extended to handle it).
\item[{Extra entities}] The DTD defines the standard XML entities (\ref{XMLspchar} and the entities \texttt{\&nbsp;} (non-breakable space), \texttt{\&ndash;} and \texttt{\&copyright;}. Use \texttt{\&ndash;} in page ranges.
\end{description}
 For further details of the DTD we refer to the file \texttt{bibxmlext.dtd} itself which is shown in appendix \ref{bibxmlextdtd}. That file also recalls some information from the Bib{\TeX} documentation on how the standard fields of entries should be used. Which
entry types and which fields are supported (and the ordering of the fields
which is fixed by a DTD) can be either read off the DTD, or within \textsf{GAP} one can use the function \texttt{TemplateBibXML} (\ref{TemplateBibXML}) to get templates for the various entry types.

 Here is an example of a BibXMLext document:
\begin{Verbatim}[fontsize=\small,frame=single,label=doc/testbib.xml]
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE file SYSTEM "bibxmlext.dtd">
  <file>
  <string key="j" value="Important Journal"/>
  <entry id="AB2000"><article>
    <author>
      <name><first>Fritz A.</first><last>First</last></name>
      <name><first>X. Y.</first><last>Sec&#x0151;nd</last></name>
    </author>
    <title>The <Wrap Name="Package"> <C>F</C>ritz</Wrap> package for the
           formula <M>x^y - l_{{i+1}} \rightarrow \mathbb{R}</M></title>
    <journal><value key="j"/></journal>
    <year>2000</year>
    <number>13</number>
    <pages>13&ndash;25</pages>
    <note>Online data at <URL Text="Bla Bla Publisher">
                    http://www.publish.com/~ImpJ/123#data</URL></note>
    <other type="mycomment">very useful</other>
  </article></entry>
  </file>

\end{Verbatim}
 There is a standard XML header and a \texttt{DOCTYPE} declaration referring to the \texttt{bibxmlext.dtd} DTD mentioned above. Local entities could be defined in the \texttt{DOCTYPE} tag as shown in the example in \ref{GDent}. The actual content of the document is inside a \texttt{{\textless}file{\textgreater}}-element, it consists of \texttt{{\textless}string{\textgreater}}- and \texttt{{\textless}entry{\textgreater}}-elements. Several of the BibXMLext markup features are shown. We will use
this input document for some examples below. }


\section{\textcolor{Chapter }{Utilities for BibXMLext data}}\label{BibXMLtools}
\logpage{[ 7, 3, 0 ]}
\hyperdef{L}{X7AC255DE7D2531B6}{}
{

\subsection{\textcolor{Chapter }{Translating Bib{\TeX} to BibXMLext}}\label{Subsect:IntroXMLBib}
\logpage{[ 7, 3, 1 ]}
\hyperdef{L}{X7C5548E77ECA29D7}{}
{
  First we describe a tool which can translate bibliography entries from Bib{\TeX} data to BibXMLext \texttt{{\textless}entry{\textgreater}}-elements. It also does some validation of the data. In some cases it is
desirable to improve the result by hand afterwards (editing formulae, adding \texttt{{\textless}URL{\textgreater}}-elements, translating non-ASCII characters to unicode, ...).

 See \texttt{WriteBibXMLextFile} (\ref{WriteBibXMLextFile}) below for how to write the results to a BibXMLext file. }



\subsection{\textcolor{Chapter }{HeuristicTranslationsLaTeX2XML.Apply}}
\logpage{[ 7, 3, 2 ]}\nobreak
\hyperdef{L}{X7A025E0A7A1CD390}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{HeuristicTranslationsLaTeX2XML.Apply({\mdseries\slshape str})\index{HeuristicTranslationsLaTeX2XML.Apply@\texttt{Heuristic}\-\texttt{Translations}\-\texttt{La}\-\texttt{Te}\-\texttt{X2}\-\texttt{X}\-\texttt{M}\-\texttt{L.}\-\texttt{Apply}}
\label{HeuristicTranslationsLaTeX2XML.Apply}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a string

\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{HeuristicTranslationsLaTeX2XML.ApplyToFile({\mdseries\slshape fnam[, outnam]})\index{HeuristicTranslationsLaTeX2XML.ApplyToFile@\texttt{Heuristic}\-\texttt{Translations}\-\texttt{La}\-\texttt{Te}\-\texttt{X2}\-\texttt{X}\-\texttt{M}\-\texttt{L.}\-\texttt{Apply}\-\texttt{To}\-\texttt{File}}
\label{HeuristicTranslationsLaTeX2XML.ApplyToFile}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing



 These utilities translate some {\LaTeX} code into text in UTF-8 encoding. The input is given as a string \mbox{\texttt{\mdseries\slshape str}}, or a file name \mbox{\texttt{\mdseries\slshape fnam}}, respectively. The first function returns the translated string. The second
function with one argument overwrites the given file with the translated text.
Optionally, the translated file content can be written to another file, if its
name is given as second argument \mbox{\texttt{\mdseries\slshape outnam}}.

 The record \texttt{HeuristicTranslationsLaTeX2XML} mainly contains translations of {\LaTeX} macros for special characters which were found in hundreds of Bib{\TeX} entries from \href{http://www.ams.org/mathscinet/} {MathSciNet}. Just look at this record if you want to know how it works. It is easy to
extend, and if you have improvements which may be of general interest, please
send them to the \textsf{GAPDoc} author.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@s := "\\\"u\\'{e}\\`e{\\ss}";;|
  !gapprompt@gap>| !gapinput@Print(s, "\n");               |
  \"u\'{e}\`e{\ss}
  !gapprompt@gap>| !gapinput@Print(HeuristicTranslationsLaTeX2XML.Apply(s),"\n");|
  ����
\end{Verbatim}
 }



\subsection{\textcolor{Chapter }{StringBibAsXMLext}}
\logpage{[ 7, 3, 3 ]}\nobreak
\hyperdef{L}{X85F33C64787A00B7}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{StringBibAsXMLext({\mdseries\slshape bibentry[, abbrvs, vals][, encoding]})\index{StringBibAsXMLext@\texttt{StringBibAsXMLext}}
\label{StringBibAsXMLext}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a string with XML code, or \texttt{fail}



 The argument \mbox{\texttt{\mdseries\slshape bibentry}} is a record representing an entry from a Bib{\TeX} file, as returned in the first list of the result of \texttt{ParseBibFiles} (\ref{ParseBibFiles}). The optional two arguments \mbox{\texttt{\mdseries\slshape abbrvs}} and \mbox{\texttt{\mdseries\slshape vals}} can be lists of abbreviations and substitution strings, as returned as second
and third list element in the result of \texttt{ParseBibFiles} (\ref{ParseBibFiles}). The optional argument \mbox{\texttt{\mdseries\slshape encoding}} specifies the character encoding of the string components of \mbox{\texttt{\mdseries\slshape bibentry}}. If this is not given it is checked if all strings are valid UTF-8 encoded
strings, in that case it is assumed that the encoding is UTF-8, otherwise the
latin1 encoding is assumed.

 The function \texttt{StringBibAsXMLext} creates XML code of an \texttt{{\textless}entry{\textgreater}}-element in \texttt{BibXMLext} format. The result is in UTF-8 encoding and contains some heuristic
translations, like splitting name lists, finding places for \texttt{{\textless}C{\textgreater}}-elements, putting formulae in \texttt{{\textless}M{\textgreater}}-elements, substituting some characters. The result should always be checked
and maybe improved by hand. Some validity checks are applied to the given
data, for example if all non-optional fields are given. If this check fails
the function returns \texttt{fail}.

 If your Bib{\TeX} input contains {\LaTeX} markup for special characters, it can be convenient to translate this input
with \texttt{HeuristicTranslationsLaTeX2XML.Apply} (\ref{HeuristicTranslationsLaTeX2XML.Apply}) or \texttt{HeuristicTranslationsLaTeX2XML.ApplyToFile} (\ref{HeuristicTranslationsLaTeX2XML.ApplyToFile}) before parsing it as Bib{\TeX}.

 As an example we consider again the short Bib{\TeX} file \texttt{doc/test.bib} shown in the example for \texttt{ParseBibFiles} (\ref{ParseBibFiles}).
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@bib := ParseBibFiles("doc/test.bib");;|
  !gapprompt@gap>| !gapinput@str := StringBibAsXMLext(bib[1][1], bib[2], bib[3]);;|
  !gapprompt@gap>| !gapinput@Print(str, "\n");|
  <entry id="AB2000"><article>
    <author>
      <name><first>Fritz A.</first><last>First</last></name>
      <name><first>X. Y.</first><last>Sec</last></name>
    </author>
    <title>Short</title>
    <journal><value key="j"/></journal>
    <year>2000</year>
  </article></entry>
\end{Verbatim}
 }

 The following functions allow parsing of data which are already in BibXMLext
format.

\subsection{\textcolor{Chapter }{ParseBibXMLextString}}
\logpage{[ 7, 3, 4 ]}\nobreak
\hyperdef{L}{X86BD29AE7A453721}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ParseBibXMLextString({\mdseries\slshape str[, res]})\index{ParseBibXMLextString@\texttt{ParseBibXMLextString}}
\label{ParseBibXMLextString}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ParseBibXMLextFiles({\mdseries\slshape fname1[, fname2[, ...]]})\index{ParseBibXMLextFiles@\texttt{ParseBibXMLextFiles}}
\label{ParseBibXMLextFiles}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a record with fields \texttt{.entries}, \texttt{.strings} and \texttt{.entities}



 The first function gets a string \mbox{\texttt{\mdseries\slshape str}} containing a \texttt{BibXMLext} document or a part of it. It returns a record with the three mentioned fields.
Here \texttt{.entries} is a list of partial XML parse trees for the \texttt{{\textless}entry{\textgreater}}-elements in \mbox{\texttt{\mdseries\slshape str}}. The field \texttt{.strings} is a list of key-value pairs from the \texttt{{\textless}string{\textgreater}}-elements in \mbox{\texttt{\mdseries\slshape str}}. And \texttt{.strings} is a list of name-value pairs of the named entities which were used during the
parsing.

 The optional argument \mbox{\texttt{\mdseries\slshape res}} can be the result of a former call of this function, in that case the newly
parsed entries are added to this data structure.

 The second function \texttt{ParseBibXMLextFiles} uses the first on the content of all files given by filenames \mbox{\texttt{\mdseries\slshape fname1}} and so on. It collects the results in a single record.

 As an example we parse the file \texttt{testbib.xml} shown in \ref{BibXMLformat}.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@bib := ParseBibXMLextFiles("doc/testbib.xml");;|
  !gapprompt@gap>| !gapinput@RecNames(bib);|
  [ "entries", "strings", "entities" ]
  !gapprompt@gap>| !gapinput@bib.entries;|
  [ <BibXMLext entry: AB2000> ]
  !gapprompt@gap>| !gapinput@bib.strings;|
  [ [ "j", "Important Journal" ] ]
  !gapprompt@gap>| !gapinput@bib.entities[1]; |
  [ "amp", "&#38;#38;" ]
\end{Verbatim}
 }



\subsection{\textcolor{Chapter }{WriteBibXMLextFile}}
\logpage{[ 7, 3, 5 ]}\nobreak
\hyperdef{L}{X7811108C7E5B1709}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{WriteBibXMLextFile({\mdseries\slshape fname, bib})\index{WriteBibXMLextFile@\texttt{WriteBibXMLextFile}}
\label{WriteBibXMLextFile}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing



 This function writes a BibXMLext file with name \mbox{\texttt{\mdseries\slshape fname}}.

 There are three possibilities to specify the bibliography entries in the
argument \mbox{\texttt{\mdseries\slshape bib}}. It can be a list of three lists as returned by \texttt{ParseBibFiles} (\ref{ParseBibFiles}). Or it can be just the first of such three lists in which case the other two
lists are assumed to be empty. To all entries of the (first) list the function \texttt{StringBibAsXMLext} (\ref{StringBibAsXMLext}) is applied and the resulting strings are written to the result file.

 The third possibility is that \mbox{\texttt{\mdseries\slshape bib}} is a record in the format as returned by \texttt{ParseBibXMLextString} (\ref{ParseBibXMLextString}) and \texttt{ParseBibXMLextFiles} (\ref{ParseBibXMLextFiles}). In this case the entries for the BibXMLext file are produced with \texttt{StringXMLElement} (\ref{StringXMLElement}), and if \mbox{\texttt{\mdseries\slshape bib}}\texttt{.entities} is bound then it is tried to resubstitute parts of the string by the given
entities with \texttt{EntitySubstitution} (\ref{EntitySubstitution}).

 As an example we write back the result of the example shown for \texttt{ParseBibXMLextFiles} (\ref{ParseBibXMLextFiles}) to an equivalent XML file.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@bib := ParseBibXMLextFiles("doc/testbib.xml");;|
  !gapprompt@gap>| !gapinput@WriteBibXMLextFile("test.xml", bib);|
\end{Verbatim}
 }


\subsection{\textcolor{Chapter }{Bibliography Entries as Records}}\label{Subsect:RecBib}
\logpage{[ 7, 3, 6 ]}
\hyperdef{L}{X82167F1280F4310E}{}
{
  For working with BibXMLext entries we find it convenient to first translate
the parse tree of an entry, as returned by \texttt{ParseBibXMLextFiles} (\ref{ParseBibXMLextFiles}), to a record with the field names of the entry as components whose value is
the content of the field as string. These strings are generated with respect
to a result type. The records are generated by the following function which
can be customized by the user. }



\subsection{\textcolor{Chapter }{RecBibXMLEntry}}
\logpage{[ 7, 3, 7 ]}\nobreak
\hyperdef{L}{X786C33ED79F425F1}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RecBibXMLEntry({\mdseries\slshape entry[, restype][, strings][, options]})\index{RecBibXMLEntry@\texttt{RecBibXMLEntry}}
\label{RecBibXMLEntry}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a record with fields as strings



 This function generates a content string for each field of a bibliography
entry and assigns them to record components. This content may depend on the
requested result type and possibly some given options.

 The arguments are as follows: \mbox{\texttt{\mdseries\slshape entry}} is the parse tree of an \texttt{{\textless}entry{\textgreater}} element as returned by \texttt{ParseBibXMLextString} (\ref{ParseBibXMLextString}) or \texttt{ParseBibXMLextFiles} (\ref{ParseBibXMLextFiles}). The optional argument \mbox{\texttt{\mdseries\slshape restype}} describes the type of the result. This package supports currently the types \texttt{"BibTeX"}, \texttt{"Text"} and \texttt{"HTML"}. The default is \texttt{"BibTeX"}. The optional argument \mbox{\texttt{\mdseries\slshape strings}} must be a list of key-value pairs as returned in the component \texttt{.strings} in the result of \texttt{ParseBibXMLextString} (\ref{ParseBibXMLextString}). The argument \mbox{\texttt{\mdseries\slshape options}} must be a record.

 If the entry contains an \texttt{author} field then the result will also contain a component \texttt{.authorAsList} which is a list containing for each author a list with three entries of the
form \texttt{[last name, first name initials, first name]} (the third entry means the first name as given in the data). Similarly, an \texttt{editor} field is accompanied by a component \texttt{.editorAsList}.

 The following \mbox{\texttt{\mdseries\slshape options}} are currently supported.

 If \texttt{options.fullname} is bound and set to \texttt{true} then the full given first names for authors and editors will be used, the
default is to use the initials of the first names. Also, if \texttt{options.namefirstlast} is bound and set to \texttt{true} then the names are written in the form ``first-name(s) last-name'', the default is the form ``last-name, first-name(s)''.

 If \texttt{options.href} is bound and set to \texttt{false} then the \texttt{"BibTeX"} type result will not use \texttt{\texttt{\symbol{92}}href} commands. The default is to produce \texttt{\texttt{\symbol{92}}href} commands from \texttt{{\textless}URL{\textgreater}}-elements such that {\LaTeX} with the \texttt{hyperref} package can produce links for them.

 The content of an \texttt{{\textless}Alt{\textgreater}}-element with \texttt{Only}-attribute is included if \mbox{\texttt{\mdseries\slshape restype}} is given in the attribute and ignored otherwise, and vice versa in case of a \texttt{Not}-attribute. If \texttt{options.useAlt} is bound, it must be a list of strings to which \mbox{\texttt{\mdseries\slshape restype}} is added. Then an \texttt{{\textless}Alt{\textgreater}}-element with \texttt{Only}-attribute is evaluated if the intersection of \texttt{options.useAlt} and the types given in the attribute is not empty. In case of a \texttt{Not}-attribute the element is evaluated if this intersection is empty.

 If \mbox{\texttt{\mdseries\slshape restype}} is \texttt{"BibTeX"} then the string fields in the result will be recoded with \texttt{Encode} (\ref{Encode}) and target \texttt{"LaTeX"}. If \texttt{options.hasLaTeXmarkup} is bound and set to \texttt{true} (for example, because the data are originally read from Bib{\TeX} files), then the target \texttt{"LaTeXleavemarkup"} will be used.

 We use again the file shown in the example for \texttt{ParseBibXMLextFiles} (\ref{ParseBibXMLextFiles}).
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@bib := ParseBibXMLextFiles("doc/testbib.xml");;|
  !gapprompt@gap>| !gapinput@e := bib.entries[1];; strs := bib.strings;;|
  !gapprompt@gap>| !gapinput@Print(RecBibXMLEntry(e, "BibTeX", strs), "\n");|
  rec(
    From := rec(
        BibXML := true,
        options := rec(
             ),
        type := "BibTeX" ),
    Label := "AB2000",
    Type := "article",
    author := "First, F. A. and Sec{\\H o}nd, X. Y.",
    authorAsList :=
     [ [ "First", "F. A.", "Fritz A." ],
        [ "Sec\305\221nd", "X. Y.", "X. Y." ] ],
    journal := "Important Journal",
    mycomment := "very useful",
    note :=
     "Online data at \\href {http://www.publish.com/~ImpJ/123#data} {Bla\
   Bla Publisher}",
    number := "13",
    pages := "13{\\textendash}25",
    printedkey := "FS00",
    title :=
     "The  {F}ritz package for the \n         formula $x^y - l_{{i+1}} \
  \\rightarrow \\mathbb{R}$",
    year := "2000" )
  !gapprompt@gap>| !gapinput@Print(RecBibXMLEntry(e, "HTML", strs).note, "\n");|
  Online data at <a href="http://www.publish.com/~ImpJ/123#data">Bla Bla\
   Publisher</a>
\end{Verbatim}
 }



\subsection{\textcolor{Chapter }{AddHandlerBuildRecBibXMLEntry}}
\logpage{[ 7, 3, 8 ]}\nobreak
\hyperdef{L}{X8067261385905A36}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AddHandlerBuildRecBibXMLEntry({\mdseries\slshape elementname, restype, handler})\index{AddHandlerBuildRecBibXMLEntry@\texttt{AddHandlerBuildRecBibXMLEntry}}
\label{AddHandlerBuildRecBibXMLEntry}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing



 The argument \mbox{\texttt{\mdseries\slshape elementname}} must be the name of an entry field supported by the BibXMLext format, the name
of one of the special elements \texttt{"C"}, \texttt{"M"}, \texttt{"Math"}, \texttt{"URL"} or of the form \texttt{"Wrap:myname"} or any string \texttt{"mytype"} (which then corresponds to entry fields \texttt{{\textless}other type="mytype"{\textgreater}}). The string \texttt{"Finish"} has an exceptional meaning, see below.

 \mbox{\texttt{\mdseries\slshape restype}} is a string describing the result type for which the handler is installed, see \texttt{RecBibXMLEntry} (\ref{RecBibXMLEntry}).

 For both arguments, \mbox{\texttt{\mdseries\slshape elementname}} and \mbox{\texttt{\mdseries\slshape restype}}, it is also possible to give lists of the described ones for installing
several handler at once.

 The argument \mbox{\texttt{\mdseries\slshape handler}} must be a function with five arguments of the form \mbox{\texttt{\mdseries\slshape handler}}\texttt{(entry, r, restype, strings, options)}. Here \mbox{\texttt{\mdseries\slshape entry}} is a parse tree of a BibXMLext \texttt{{\textless}entry{\textgreater}}-element, \mbox{\texttt{\mdseries\slshape r}} is a node in this tree for an element \mbox{\texttt{\mdseries\slshape elementname}}, and \mbox{\texttt{\mdseries\slshape restype}}, \mbox{\texttt{\mdseries\slshape strings}} and \mbox{\texttt{\mdseries\slshape options}} are as explained in \texttt{RecBibXMLEntry} (\ref{RecBibXMLEntry}). The function should return a string representing the content of the node \mbox{\texttt{\mdseries\slshape r}}. If \mbox{\texttt{\mdseries\slshape elementname}} is of the form \texttt{"Wrap:myname"} the handler is used for elements of form \texttt{{\textless}Wrap Name="myname"{\textgreater}...{\textless}/Wrap{\textgreater}}.

 If \mbox{\texttt{\mdseries\slshape elementname}} is \texttt{"Finish"} the handler should look like above except that now \mbox{\texttt{\mdseries\slshape r}} is the record generated by \texttt{RecBibXMLEntry} (\ref{RecBibXMLEntry}) just before it is returned. Here the handler should return nothing. It can be
used to manipulate the record \mbox{\texttt{\mdseries\slshape r}}, for example for changing the encoding of the strings or for adding some more
components.

 The installed handler is called by \texttt{BuildRecBibXMLEntry(}\mbox{\texttt{\mdseries\slshape entry}}, \mbox{\texttt{\mdseries\slshape r}}, \mbox{\texttt{\mdseries\slshape restype}}, \mbox{\texttt{\mdseries\slshape strings}}, \mbox{\texttt{\mdseries\slshape options}}\texttt{)}. The string for the whole content of an element can be generated by \texttt{ContentBuildRecBibXMLEntry(}\mbox{\texttt{\mdseries\slshape entry}}, \mbox{\texttt{\mdseries\slshape r}}, \mbox{\texttt{\mdseries\slshape restype}}, \mbox{\texttt{\mdseries\slshape strings}}, \mbox{\texttt{\mdseries\slshape options}}\texttt{)}.

 We continue the example from \texttt{RecBibXMLEntry} (\ref{RecBibXMLEntry}) and install a handler for the \texttt{{\textless}Wrap Name="Package"{\textgreater}}-element such that {\LaTeX} puts its content in a sans serif font.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@AddHandlerBuildRecBibXMLEntry("Wrap:Package", "BibTeX",|
  !gapprompt@>| !gapinput@function(entry,  r, restype,  strings, options)|
  !gapprompt@>| !gapinput@  return Concatenation("\\textsf{", ContentBuildRecBibXMLEntry(|
  !gapprompt@>| !gapinput@            entry, r, restype,  strings, options), "}");|
  !gapprompt@>| !gapinput@end);|
  !gapprompt@gap>| !gapinput@|
  !gapprompt@gap>| !gapinput@Print(RecBibXMLEntry(e, "BibTeX", strs).title, "\n");|
  The \textsf{ {F}ritz} package for the
           formula $x^y - l_{{i+1}} \rightarrow \mathbb{R}$
  !gapprompt@gap>| !gapinput@Print(RecBibXMLEntry(e, "Text", strs).title, "\n");  |
  The  Fritz package for the
           formula x^y - l_{i+1} -> R
  !gapprompt@gap>| !gapinput@AddHandlerBuildRecBibXMLEntry("Wrap:Package", "BibTeX", "Ignore");|
\end{Verbatim}
 }



\subsection{\textcolor{Chapter }{StringBibXMLEntry}}
\logpage{[ 7, 3, 9 ]}\nobreak
\hyperdef{L}{X790A295680F7CD24}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{StringBibXMLEntry({\mdseries\slshape entry[, restype][, strings][, options]})\index{StringBibXMLEntry@\texttt{StringBibXMLEntry}}
\label{StringBibXMLEntry}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a string



 The arguments of this function have the same meaning as in \texttt{RecBibXMLEntry} (\ref{RecBibXMLEntry}) but the return value is a string representing the bibliography entry in a
format specified by \mbox{\texttt{\mdseries\slshape restype}} (default is \texttt{"BibTeX"}).

 Currently, the following cases for \mbox{\texttt{\mdseries\slshape restype}} are supported:
\begin{description}
\item[{\texttt{"BibTeX"}}] A string with Bib{\TeX} source code is generated.
\item[{\texttt{"Text"}}] A text representation of the text is returned. If \texttt{options.ansi} is bound it must be a record. The components must have names \texttt{Bib{\textunderscore}Label}, \texttt{Bib{\textunderscore}author}, and so on for all fieldnames. The value of each component is a pair of
strings which will enclose the content of the field in the result or the first
of these strings in which case the default for the second is \texttt{TextAttr.reset} (see \texttt{TextAttr} (\ref{TextAttr})). If you give an empty record here, some default ANSI color markup will be
used.
\item[{\texttt{"HTML"}}] An HTML representation of the bibliography entry is returned. The text from
each field is enclosed in markup (mostly \texttt{{\textless}span{\textgreater}}-elements) with the \texttt{class} attribute set to the field name. This allows a detailed layout of the code via
a style sheet file. If \texttt{options.MathJax} is bound and has the value \texttt{true} then formulae are encoded for display on pages with \textsf{MathJax} support.
\end{description}
 We use again the file shown in the example for \texttt{ParseBibXMLextFiles} (\ref{ParseBibXMLextFiles}).
\begin{Verbatim}[commandchars=!|C,fontsize=\small,frame=single,label=Example]
  !gapprompt|gap>C !gapinput|bib := ParseBibXMLextFiles("doc/testbib.xml");;C
  !gapprompt|gap>C !gapinput|e := bib.entries[1];; strs := bib.strings;;C
  !gapprompt|gap>C !gapinput|ebib := StringBibXMLEntry(e, "BibTeX", strs);;C
  !gapprompt|gap>C !gapinput|PrintFormattedString(ebib);C
  @article{ AB2000,
    author =           {First, F. A. and Sec{\H o}nd, X. Y.},
    title =            {The  {F}ritz  package  for  the formula $x^y -
                        l_{{i+1}} \rightarrow \mathbb{R}$},
    journal =          {Important Journal},
    number =           {13},
    year =             {2000},
    pages =            {13{\textendash}25},
    note =             {Online          data          at         \href
                        {http://www.publish.com/~ImpJ/123#data}   {Bla
                        Bla Publisher}},
    mycomment =        {very useful},
    printedkey =       {FS00}
  }
  !gapprompt|gap>C !gapinput|etxt := StringBibXMLEntry(e, "Text", strs);;      C
  !gapprompt|gap>C !gapinput|etxt := SimplifiedUnicodeString(Unicode(etxt), "latin1", "single");;C
  !gapprompt|gap>C !gapinput|etxt := Encode(etxt, GAPInfo.TermEncoding);;                        C
  !gapprompt|gap>C !gapinput|PrintFormattedString(etxt);C
  [FS00]  First,  F.  A.  and Second, X. Y., The Fritz package for the
  formula  x^y  -  l_{i+1}  ?  R, Important Journal, 13 (2000), 13-25,
  (Online        data        at        Bla        Bla        Publisher
  (http://www.publish.com/~ImpJ/123#data)).
  !gapprompt|gap>C !gapinput|ehtml := StringBibXMLEntry(e, "HTML", strs, rec(MathJax := true));;C
  !gapprompt|gap>C !gapinput|ehtml := Encode(Unicode(ehtml), GAPInfo.TermEncoding);;C
  !gapprompt|gap>C !gapinput|PrintFormattedString(ehtml);C
  <p class='BibEntry'>
  [<span class='BibKey'>FS00</span>]
   <b class='BibAuthor'>First, F. A. and Second, X. Y.</b>,
   <i class='BibTitle'>The  Fritz package for the
           formula \(x^y - l_{{i+1}} \rightarrow \mathbb{R}\)</i>,
   <span class='BibJournal'>Important Journal</span>
  (<span class='BibNumber'>13</span>)
   (<span class='BibYear'>2000</span>),
   <span class='BibPages'>13-25</span><br />
  (<span class='BibNote'>Online data at
  <a href="http://www.publish.com/~ImpJ/123#data">Bla Bla
  Publisher</a></span>).
  </p>

\end{Verbatim}
 }

 The following command may be useful to generate completly new bibliography
entries in BibXMLext format. It also informs about the supported entry types
and field names.

\subsection{\textcolor{Chapter }{TemplateBibXML}}
\logpage{[ 7, 3, 10 ]}\nobreak
\hyperdef{L}{X7C6FF57087016019}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{TemplateBibXML({\mdseries\slshape [type]})\index{TemplateBibXML@\texttt{TemplateBibXML}}
\label{TemplateBibXML}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
list of types or string



 Without an argument this function returns a list of the supported entry types
in BibXMLext documents.

 With an argument \mbox{\texttt{\mdseries\slshape type}} of one of the supported types the function returns a string which is a
template for a corresponding BibXMLext entry. Optional field elements have a \texttt{*} appended. If an element has the word \texttt{OR} appended, then either this element or the next must/can be given, not both. If \texttt{AND/OR} is appended then this and/or the next can/must be given. Elements which can
appear several times have a \texttt{+} appended. Places to fill are marked by an \texttt{X}.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@TemplateBibXML();|
  [ "article", "book", "booklet", "conference", "inbook",
    "incollection", "inproceedings", "manual", "mastersthesis", "misc",
    "phdthesis", "proceedings", "techreport", "unpublished" ]
  !gapprompt@gap>| !gapinput@Print(TemplateBibXML("inbook"));|
  <entry id="X"><inbook>
    <author>
      <name><first>X</first><last>X</last></name>+
    </author>OR
    <editor>
      <name><first>X</first><last>X</last></name>+
    </editor>
    <title>X</title>
    <chapter>X</chapter>AND/OR
    <pages>X</pages>
    <publisher>X</publisher>
    <year>X</year>
    <volume>X</volume>*OR
    <number>X</number>*
    <series>X</series>*
    <type>X</type>*
    <address>X</address>*
    <edition>X</edition>*
    <month>X</month>*
    <note>X</note>*
    <key>X</key>*
    <annotate>X</annotate>*
    <crossref>X</crossref>*
    <abstract>X</abstract>*
    <affiliation>X</affiliation>*
    <contents>X</contents>*
    <copyright>X</copyright>*
    <isbn>X</isbn>*OR
    <issn>X</issn>*
    <keywords>X</keywords>*
    <language>X</language>*
    <lccn>X</lccn>*
    <location>X</location>*
    <mrnumber>X</mrnumber>*
    <mrclass>X</mrclass>*
    <mrreviewer>X</mrreviewer>*
    <price>X</price>*
    <size>X</size>*
    <url>X</url>*
    <category>X</category>*
    <other type="X">X</other>*+
  </inbook></entry>
\end{Verbatim}
 }

 }


\section{\textcolor{Chapter }{Getting Bib{\TeX} entries from \textsf{MathSciNet}}}\label{MathSciNet}
\logpage{[ 7, 4, 0 ]}
\hyperdef{L}{X842336AF7B20048E}{}
{
  We provide utilities to access the \href{http://www.ams.org/mathscinet/} {\textsf{ MathSciNet}} data base from within GAP. The first condition for this to work is that one of
the programs \texttt{wget} or \texttt{curl} is installed on your system. The second is, of course, that you use these
functions from a computer which has access to \textsf{MathSciNet}.

 Please note, that the usual license for \textsf{MathSciNet} access does not allow for automated searches in the database. Therefore, only
use the \texttt{SearchMR} (\ref{SearchMR}) function for single queries, as you would do using your webbrowser.



\subsection{\textcolor{Chapter }{SearchMR}}
\logpage{[ 7, 4, 1 ]}\nobreak
\hyperdef{L}{X8009F8A17DDFF9AF}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SearchMR({\mdseries\slshape qurec})\index{SearchMR@\texttt{SearchMR}}
\label{SearchMR}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SearchMRBib({\mdseries\slshape bib})\index{SearchMRBib@\texttt{SearchMRBib}}
\label{SearchMRBib}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a list of strings, a string or \texttt{fail}



 The first function \texttt{SearchMR} provides the same functionality as the Web interface \href{http://www.ams.org/mathscinet/} {\textsf{ MathSciNet}}. The query strings must be given as a record, and the following components of
this record are recognized: \texttt{Author}, \texttt{AuthorRelated}, \texttt{Title}, \texttt{ReviewText}, \texttt{Journal}, \texttt{InstitutionCode}, \texttt{Series}, \texttt{MSCPrimSec}, \texttt{MSCPrimary}, \texttt{MRNumber}, \texttt{Anywhere}, \texttt{References} and \texttt{Year}.

 Furthermore, the component \texttt{type} can be specified. It can be one of \texttt{"bibtex"} (the default if not given), \texttt{"pdf"}, \texttt{"html"} and probably others. In the last cases the function returns a string with the
content of the web page returned by \textsf{MathSciNet}. In the first case the \textsf{MathSciNet} interface returns a web page with Bib{\TeX} entries, for convenience this function returns a list of strings, each
containing the Bib{\TeX} text for a single result entry.

 If a component \texttt{uri} is bound and set to \texttt{true} the function does not actually send a request to \textsf{MathSciNet} but returns a string with the URI that can be called for the request.

 The format of a \texttt{.Year} component can be either a four digit number, optionally preceded by one of the
characters \texttt{'{\textless}'}, \texttt{'{\textgreater}'} or \texttt{'='}, or it can be two four digit numbers separated by a \texttt{-} to specify a year range.

 The function \texttt{SearchMRBib} gets a record of a parsed Bib{\TeX} entry as input as returned by \texttt{ParseBibFiles} (\ref{ParseBibFiles}) or \texttt{ParseBibStrings} (\ref{ParseBibStrings}). It tries to generate some sensible input from this information for \texttt{SearchMR} and calls that function.


\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@ll := SearchMR(rec(Author:="Gauss", Title:="Disquisitiones"));;|
  !gapprompt@gap>| !gapinput@ll2 := List(ll, HeuristicTranslationsLaTeX2XML.Apply);;|
  !gapprompt@gap>| !gapinput@bib := ParseBibStrings(Concatenation(ll2));;|
  !gapprompt@gap>| !gapinput@bibxml := List(bib[1], StringBibAsXMLext);;|
  !gapprompt@gap>| !gapinput@bib2 := ParseBibXMLextString(Concatenation(bibxml));;|
  !gapprompt@gap>| !gapinput@for b in bib2.entries do |
  !gapprompt@>| !gapinput@         PrintFormattedString(StringBibXMLEntry(b, "Text")); od;     |
  [Gau95]   Gauss,   C.   F.,  Disquisitiones  arithmeticae,  Academia
  Colombiana   de  Ciencias  Exactas,  F�sicas  y  Naturales,  Bogot�,
  Colecci�n   Enrique   P�rez   Arbel�ez   [Enrique   P�rez   Arbel�ez
  Collection],  10  (1995), xliv+495 pages, (Translated from the Latin
  by  Hugo  Barrantes  Campos,  Michael Josephy and �ngel Ruiz Z��iga,
  With a preface by Ruiz Z��iga).

  [Gau86]  Gauss, C. F., Disquisitiones arithmeticae, Springer-Verlag,
  New  York  (1986),  xx+472  pages, (Translated and with a preface by
  Arthur  A.  Clarke,  Revised  by  William  C.  Waterhouse, Cornelius
  Greither and A. W. Grootendorst and with a preface by Waterhouse).

  [Gau66]  Gauss,  C. F., Disquisitiones arithmeticae, Yale University
  Press, New Haven, Conn.-London, Translated into English by Arthur A.
  Clarke, S. J (1966), xx+472 pages.

\end{Verbatim}
 }

 }

 }



\appendix


\chapter{\textcolor{Chapter }{The File \texttt{3k+1.xml}}}\label{app:3k+1}
\logpage{[ "A", 0, 0 ]}
\hyperdef{L}{X830C58F97F9CD901}{}
{
 Here is the complete source of the example \textsf{GAPDoc} document \texttt{3k+1.xml} discussed in Section{\nobreakspace}\ref{sec:3k+1expl}.
\begin{Verbatim}[fontsize=\small,frame=single,label=3k+1.xml]
  <?xml version="1.0" encoding="UTF-8"?>

  <!--   A complete "fake package" documentation
  -->

  <!DOCTYPE Book SYSTEM "gapdoc.dtd">

  <Book Name="3k+1">

  <TitlePage>
    <Title>The <Package>ThreeKPlusOne</Package> Package</Title>
    <Version>Version 42</Version>
    <Author>Dummy Auth�r
      <Email>3kplusone@dev.null</Email>
    </Author>

    <Copyright>&copyright; 2000 The Author. <P/>
      You can do with this package what you want.<P/> Really.
    </Copyright>
  </TitlePage>

  <TableOfContents/>

  <Body>
    <Chapter> <Heading>The <M>3k+1</M> Problem</Heading>
      <Section Label="sec:theory"> <Heading>Theory</Heading>
        Let  <M>k \in  &NN;</M> be  a  natural number.  We consider  the
        sequence <M>n(i, k), i \in &NN;,</M> with <M>n(1, k) = k</M> and
        else <M>n(i+1,  k) = n(i, k)  / 2</M> if <M>n(i,  k)</M> is even
        and <M>n(i+1, k) =  3 n(i, k) + 1</M> if  <M>n(i, k)</M> is odd.
        <P/> It  is not known  whether for  any natural number  <M>k \in
        &NN;</M> there is an <M>m \in &NN;</M> with <M>n(m, k) = 1</M>.
        <P/>
        <Package>ThreeKPlusOne</Package>  provides   the  function  <Ref
        Func="ThreeKPlusOneSequence"/>   to  explore   this  for   given
        <M>n</M>.  If  you really  want  to  know something  about  this
        problem, see <Cite Key="Wi98"/> or
        <URL>http://www.ku.de/mgf/mathematik/lehrstuhlstatistik/team/dr-guenther-wirsching/</URL>
        for more details (and forget this package).
      </Section>

      <Section> <Heading>Program</Heading>
        In this section we describe the main function of this package.
        <ManSection>
          <Func Name="ThreeKPlusOneSequence" Arg="k[, max]"/>
          <Description>
            This  function computes  for a  natural number  <A>k</A> the
            beginning of the sequence  <M>n(i, k)</M> defined in section
            <Ref Sect="sec:theory"/>.  The sequence  stops at  the first
            <M>1</M>  or at  <M>n(<A>max</A>, k)</M>,  if <A>max</A>  is
            given.
  <Example>
  gap> ThreeKPlusOneSequence(101);
  "Sorry, not yet implemented. Wait for Version 84 of the package"
  </Example>
          </Description>
        </ManSection>
      </Section>
    </Chapter>
  </Body>

  <Bibliography Databases="3k+1" />
  <TheIndex/>

  </Book>

\end{Verbatim}
 }


\chapter{\textcolor{Chapter }{The File \texttt{gapdoc.dtd}}}\label{GAPDocdtd}
\logpage{[ "B", 0, 0 ]}
\hyperdef{L}{X85366C6480D58C51}{}
{
  For easier reference we repeat here the complete content of the file \texttt{gapdoc.dtd}.
\begin{Verbatim}[fontsize=\small,frame=single,label=gapdoc.dtd]
  <?xml version="1.0" encoding="UTF-8"?>
  <!-- ==================================================================
       gapdoc.dtd - XML Document type definition for GAP documentation
       By Frank L�beck and Max Neunh�ffer
       ================================================================== -->


  <!-- Note that this definition goes "bottom-up" because entities can only
       be used after their definition in the file. -->


  <!-- ==================================================================
       Some entities:
       ================================================================== -->

  <!-- The standard XML entities: -->

  <!ENTITY lt     "&#38;#60;">
  <!ENTITY gt     "&#62;">
  <!ENTITY amp    "&#38;#38;">
  <!ENTITY apos   "&#39;">
  <!ENTITY quot   "&#34;">


  <!-- The following were introduced in GAPDoc version < 1.0, it is no longer
       necessary to take care of LaTeX special characters
       (we keep the entities with simplified definitions for compatibility) -->

  <!ENTITY tamp "&amp;">
  <!ENTITY tlt "&lt;">
  <!ENTITY tgt "&gt;">
  <!ENTITY hash "#">
  <!ENTITY dollar "$">
  <!ENTITY percent "&#37;">
  <!ENTITY tilde "~">
  <!ENTITY bslash "\\">
  <!ENTITY obrace "{">
  <!ENTITY cbrace "}">
  <!ENTITY uscore "_">
  <!ENTITY circum "^">

  <!-- ==================================================================
       Our predefined entities:
       ================================================================== -->

  <!ENTITY nbsp "&#160;">
  <!ENTITY ndash "&#x2013;">
  <!ENTITY GAP    "<Package>GAP</Package>">
  <!ENTITY GAPDoc "<Package>GAPDoc</Package>">
  <!ENTITY TeX
    "<Alt Only='LaTeX'>{\TeX}</Alt><Alt Not='LaTeX'>TeX</Alt>">
  <!ENTITY LaTeX
    "<Alt Only='LaTeX'>{\LaTeX}</Alt><Alt Not='LaTeX'>LaTeX</Alt>">
  <!ENTITY BibTeX
    "<Alt Only='LaTeX'>{Bib\TeX}</Alt><Alt Not='LaTeX'>BibTeX</Alt>">
  <!ENTITY MeatAxe "<Package>MeatAxe</Package>">
  <!ENTITY XGAP   "<Package>XGAP</Package>">
  <!ENTITY copyright "&#169;">

  <!-- and unicode math symbols -->
  <!ENTITY CC "&#x2102;" > <!-- double struck -->
  <!ENTITY ZZ "&#x2124;" >
  <!ENTITY NN "&#x2115;" >
  <!ENTITY PP "&#x2119;" >
  <!ENTITY QQ "&#x211a;" >
  <!ENTITY HH "&#x210d;" >
  <!ENTITY RR "&#x211d;" >


  <!-- ==================================================================
       The following describes the "innermost" documentation text which
       can occur at various places in the document like for example
       section headings. It does neither contain further sectioning
       elements nor environments like Enums or Lists.
       ================================================================== -->

  <!ENTITY % InnerText "#PCDATA |
                        Alt |
                        Emph | E |
                        Par | P | Br |
                        Keyword | K | Arg | A | Quoted | Q | Code | C |
                        File | F | Button | B | Package |
                        M | Math | Display |
                        Example | Listing | Log | Verb |
                        URL | Email | Homepage | Address | Cite | Label |
                        Ref | Index |
                        Ignore" >


  <!ELEMENT Alt (%InnerText;)*>     <!-- This is only to allow "Only" and
                                         "Not" attributes for normal text -->
  <!ATTLIST Alt Only CDATA #IMPLIED
                Not  CDATA #IMPLIED>

  <!-- The following elements declare a certain block of InnerText to
       have a certain property. They are non-terminal and can contain
       any InnerText recursively. -->

  <!ELEMENT Emph (%InnerText;)*>    <!-- Emphasize something -->
  <!ELEMENT E    (%InnerText;)*>    <!-- the same as shortcut -->


  <!-- The following is an empty element marking a paragraph boundary. -->

  <!ELEMENT Par EMPTY>    <!-- this is intentionally empty! -->
  <!ELEMENT P EMPTY>      <!-- the same as shortcut  -->

  <!-- And here is an element for forcing a line break, not starting
       a new paragraph. -->

  <!ELEMENT Br EMPTY>     <!-- a forced line break  -->

  <!-- The following elements mark a word or sentence to be of a certain
       kind, such that it can  be typeset differently. They are terminal
       elements that should only contain  character data. But we have to
       allow  Alt elements  for handling  special characters.  For these
       elements we introduce  a long name - which is  easy to remember -
       and a  short name - which  you may prefer because  of the shorter
       markup. -->

  <!ELEMENT Keyword (#PCDATA|Alt)*>  <!-- Keyword -->
  <!ELEMENT K (#PCDATA|Alt)*>        <!-- Keyword (shortcut) -->

  <!ELEMENT Arg (#PCDATA|Alt)*>      <!-- Argument -->
  <!ELEMENT A (#PCDATA|Alt)*>        <!-- Argument (shortcut) -->

  <!ELEMENT Code (#PCDATA|Alt|A|Arg)*> <!-- GAP code -->
  <!ELEMENT C (#PCDATA|Alt|A|Arg)*>    <!-- GAP code (shortcut) -->

  <!ELEMENT File (#PCDATA|Alt)*>     <!-- Filename -->
  <!ELEMENT F (#PCDATA|Alt)*>        <!-- Filename (shortcut) -->

  <!ELEMENT Button (#PCDATA|Alt)*>   <!-- "Button" (also Menu, Key) -->
  <!ELEMENT B (#PCDATA|Alt)*>        <!-- "Button" (shortcut) -->

  <!ELEMENT Package (#PCDATA|Alt)*>  <!-- A package name -->

  <!ELEMENT Quoted (%InnerText;)*>   <!-- Quoted (in quotes) text -->
  <!ELEMENT Q (%InnerText;)*>        <!-- Quoted text (shortcut) -->


  <!-- The following elements contain mathematical formulae. They are
       terminal elements that contain character data in TeX notation. -->

  <!-- Math with well defined translation to text output -->
  <!ELEMENT M (#PCDATA|A|Arg|Alt)*>
  <!-- Normal TeX math mode formula -->
  <!ELEMENT Math (#PCDATA|A|Arg|Alt)*>
  <!-- TeX displayed math mode formula -->
  <!ELEMENT Display (#PCDATA|A|Arg|Alt)*>
  <!-- Mode="M" causes <M>-style formatting -->
  <!ATTLIST Display Mode CDATA #IMPLIED>


  <!-- The  following  elements  contain  GAP related  text  like  code,
       session  logs or  examples. They  are all  terminal elements  and
       consist of character data which is normally typeset verbatim. The
       different  types  of  the  elements only  control  how  they  are
       treated. -->

  <!ELEMENT Example (#PCDATA)>  <!-- This is subject to the automatic
                                     example checking mechanism -->
  <!ELEMENT Log (#PCDATA)>      <!-- This not -->
  <!ELEMENT Listing (#PCDATA)>  <!-- This is just for code listings -->
  <!ATTLIST Listing Type CDATA #IMPLIED> <!-- a comment about the type of
                                              listed code, may appear in
                                              output -->

  <!-- One  further  verbatim element,  this is truely  verbatim without
       any processing and intended  for ASCII substitutes of complicated
       displayed formulae or tables. -->

  <!ELEMENT Verb  (#PCDATA)>

  <!-- The following  elements are  for cross-referencing  purposes like
       URLs, citations,  references, and  the index. All  these elements
       are  terminal and  need special  methods  to make  up the  actual
       output during document generation. -->

  <!ELEMENT URL (#PCDATA|Alt|Link|LinkText)*>  <!-- Link, LinkText
       variant for case where text needs further markup -->
  <!ATTLIST URL Text CDATA #IMPLIED>   <!-- This is for output formats
                                            that have links like HTML -->
  <!ELEMENT Link     (%InnerText;)*> <!-- the URL -->
  <!ELEMENT LinkText (%InnerText;)*> <!-- text for links, can contain markup -->
  <!-- The following two are actually URLs, but the element name determines
       the type. -->
  <!ELEMENT Email (#PCDATA|Alt|Link|LinkText)*>
  <!ELEMENT Homepage (#PCDATA|Alt|Link|LinkText)*>

  <!-- Those who still want to give postal addresses can use the following
       element. Use <Br/> for specifying typical line breaks  -->

  <!ELEMENT Address (#PCDATA|Alt|Br)*>

  <!ELEMENT Cite EMPTY>
  <!ATTLIST Cite Key CDATA #REQUIRED
                 Where CDATA #IMPLIED>

  <!ELEMENT Label EMPTY>
  <!ATTLIST Label Name CDATA #REQUIRED>

  <!ELEMENT Ref EMPTY>
  <!ATTLIST Ref Func      CDATA #IMPLIED
                Oper      CDATA #IMPLIED
                Constr    CDATA #IMPLIED
                Meth      CDATA #IMPLIED
                Filt      CDATA #IMPLIED
                Prop      CDATA #IMPLIED
                Attr      CDATA #IMPLIED
                Var       CDATA #IMPLIED
                Fam       CDATA #IMPLIED
                InfoClass CDATA #IMPLIED
                Chap      CDATA #IMPLIED
                Sect      CDATA #IMPLIED
                Subsect   CDATA #IMPLIED
                Appendix  CDATA #IMPLIED
                Text      CDATA #IMPLIED

                Label     CDATA #IMPLIED
                BookName  CDATA #IMPLIED
                Style (Text|Number) #IMPLIED>  <!-- normally automatic -->

  <!-- Note that  only one attribute  of Ref is used  normally. BookName
       and  Style  can  be  specified in  addition  to  handle  external
       references and the typesetting style of the reference. -->

  <!-- For explicit index entries (Func and so on should cause an
       automatically generated index entry). Use the attributes Key,
       Subkey for sorting (simplified, without markup). The Subkey value
       also gets printed. Use the optional Subkey element if the printed
       version needs some markup.                                        -->
  <!ELEMENT Index (%InnerText;|Subkey)*>
  <!ATTLIST Index Key    CDATA #IMPLIED
                  Subkey CDATA #IMPLIED>
  <!ELEMENT Subkey (%InnerText;)*>


  <!-- ==================================================================
       The following  describes the normal documentation  text which can
       occur  at various  places in  the document.  It does  not contain
       further sectioning elements. In addition to InnerText it can contain
       environments like enumerations, lists, and such.
       ================================================================== -->

  <!ENTITY % Text "%InnerText; | List | Enum | Table">

  <!ELEMENT Item ( %Text;)*>
  <!ELEMENT Mark ( %InnerText;)*>

  <!ELEMENT List ( ((Mark,Item)|Item)+ )>
  <!ATTLIST List Only CDATA #IMPLIED
                 Not  CDATA #IMPLIED>
  <!ELEMENT Enum ( Item+ )>
  <!ATTLIST Enum Only CDATA #IMPLIED
                 Not  CDATA #IMPLIED>

  <!ELEMENT Table ( Caption?, (Row | HorLine)+ )>
  <!ATTLIST Table Label   CDATA #IMPLIED
                  Only    CDATA #IMPLIED
                  Not     CDATA #IMPLIED
                  Align   CDATA #REQUIRED>    <!-- A TeX tabular string -->
                  <!-- We allow | and l,c,r, nothing else -->
  <!ELEMENT Row   ( Item+ )>
  <!ELEMENT HorLine EMPTY>
  <!ELEMENT Caption ( %InnerText;)*>

  <!-- ==================================================================
       We start defining some things within the overall structure:
       ================================================================== -->

  <!-- The TitlePage consists of several sub-elements: -->

  <!ELEMENT TitlePage (Title, Subtitle?, Version?, TitleComment?,
                       Author+, Date?, Address?, Abstract?, Copyright?,
                       Acknowledgements? , Colophon? )>

  <!ELEMENT Title (%Text;)*>
  <!ELEMENT Subtitle (%Text;)*>
  <!ELEMENT Version (%Text;)*>
  <!ELEMENT TitleComment (%Text;)*>
  <!ELEMENT Author (%Text;)*>    <!-- There may be more than one Author! -->
  <!ELEMENT Date (%Text;)*>
  <!ELEMENT Abstract (%Text;)*>
  <!ELEMENT Copyright (%Text;)*>
  <!ELEMENT Acknowledgements (%Text;)*>
  <!ELEMENT Colophon (%Text;)*>


  <!-- The following things just specify some information about the
       corresponding parts of the Book: -->

  <!ELEMENT TableOfContents EMPTY>
  <!ELEMENT Bibliography EMPTY>
  <!ATTLIST Bibliography Databases CDATA #REQUIRED
                         Style CDATA #IMPLIED>
  <!ELEMENT TheIndex EMPTY>

  <!-- ==================================================================
       The Ignore element can be used everywhere to include further
       information in a GAPDoc document which is not intended for the
       standard converters (e.g., source code, not yet finished stuff,
       and so on. This information can be extracted by special converter
       routines, more precise information about the content of an Ignore
       element can be given by the "Remark" attribute.
       ================================================================== -->

  <!ELEMENT Ignore (%Text;| Chapter | Section | Subsection | ManSection |
                    Heading)*>
  <!ATTLIST Ignore Remark CDATA #IMPLIED>

  <!-- ==================================================================
       Now we go on with the overall structure by defining the sectioning
       structure, which includes the Synopsis element:
       ================================================================== -->


  <!ELEMENT Subsection (%Text;| Heading)*>
  <!ATTLIST Subsection Label CDATA #IMPLIED> <!-- For reference purposes -->

  <!ELEMENT ManSection ( Heading?,
                        ((Func, Returns?) | (Oper, Returns?) |
                         (Meth, Returns?) | (Filt, Returns?) |
                         (Prop, Returns?) | (Attr, Returns?) |
                         (Constr, Returns?) |
                         Var | Fam | InfoClass)+, Description )>
  <!ATTLIST ManSection Label CDATA #IMPLIED> <!-- For reference purposes -->

  <!ELEMENT Returns (%Text;)*>
  <!ELEMENT Description (%Text;)*>


  <!-- Note that  the ManSection element  is actually a  subsection with
       respect  to labelling,  referencing, and  counting of  sectioning
       elements. -->

  <!ELEMENT Func EMPTY>
  <!ATTLIST Func Name  CDATA #REQUIRED
                 Label CDATA #IMPLIED
                 Arg   CDATA #REQUIRED
                 Comm  CDATA #IMPLIED>

  <!-- Note  that Arg  contains the  full list  of arguments,  including
       optional  parts,  which  are   denoted  by  square  brackets  [].
       Arguments   are  separated   by  whitespace,   commas  count   as
       whitespace. -->

  <!-- Note further that although Name and Label are  CDATA (and not ID)
       Label must make up a unique identifier. -->

  <!ELEMENT Oper EMPTY>
  <!ATTLIST Oper Name  CDATA #REQUIRED
                 Label CDATA #IMPLIED
                 Arg   CDATA #REQUIRED
                 Comm  CDATA #IMPLIED>

  <!ELEMENT Constr EMPTY>
  <!ATTLIST Constr Name  CDATA #REQUIRED
                   Label CDATA #IMPLIED
                   Arg   CDATA #REQUIRED
                   Comm  CDATA #IMPLIED>

  <!ELEMENT Meth EMPTY>
  <!ATTLIST Meth Name  CDATA #REQUIRED
                 Label CDATA #IMPLIED
                 Arg   CDATA #REQUIRED
                 Comm  CDATA #IMPLIED>

  <!ELEMENT Filt EMPTY>
  <!ATTLIST Filt Name  CDATA #REQUIRED
                 Label CDATA #IMPLIED
                 Arg   CDATA #IMPLIED
                 Comm  CDATA #IMPLIED
                 Type  CDATA #IMPLIED>

  <!ELEMENT Prop EMPTY>
  <!ATTLIST Prop Name  CDATA #REQUIRED
                 Label CDATA #IMPLIED
                 Arg   CDATA #REQUIRED
                 Comm  CDATA #IMPLIED>

  <!ELEMENT Attr EMPTY>
  <!ATTLIST Attr Name  CDATA #REQUIRED
                 Label CDATA #IMPLIED
                 Arg   CDATA #REQUIRED
                 Comm  CDATA #IMPLIED>

  <!ELEMENT Var  EMPTY>
  <!ATTLIST Var  Name  CDATA #REQUIRED
                 Label CDATA #IMPLIED
                 Comm  CDATA #IMPLIED>

  <!ELEMENT Fam  EMPTY>
  <!ATTLIST Fam  Name  CDATA #REQUIRED
                 Label CDATA #IMPLIED
                 Comm  CDATA #IMPLIED>

  <!ELEMENT InfoClass EMPTY>
  <!ATTLIST InfoClass Name  CDATA #REQUIRED
                      Label CDATA #IMPLIED
                      Comm  CDATA #IMPLIED>


  <!ELEMENT Heading (%InnerText;)*>

  <!ELEMENT Section (%Text;| Heading | Subsection | ManSection)*>
  <!ATTLIST Section Label CDATA #IMPLIED>    <!-- For reference purposes -->


  <!ELEMENT Chapter (%Text;| Heading | Section)*>
  <!ATTLIST Chapter Label CDATA #IMPLIED>    <!-- For reference purposes -->


  <!-- Note that  the entity %InnerText; is  documentation that contains
       neither sectioning  elements nor environments  like enumerations,
       but  only  formulae,  labels, references,  citations,  and  other
       terminal elements. -->

  <!ELEMENT Appendix (%Text;| Heading | Section)*>
  <!ATTLIST Appendix Label CDATA #IMPLIED>   <!-- For reference purposes -->

  <!-- Note that  an Appendix  is exactly  the same  as a  Chapter. They
       differ only in the numbering. -->

  <!-- ==================================================================
       At last we define the overall structure of a gapdoc Book:
       ================================================================== -->

  <!ELEMENT Body  ( %Text;| Chapter | Section )*>

  <!ELEMENT Book (TitlePage,
                  TableOfContents?,
                  Body,
                  Appendix*,
                  Bibliography?,
                  TheIndex?)>
  <!ATTLIST Book Name CDATA #REQUIRED>

  <!-- Note  that  the  entity  %Text; is  documentation  that  contains
       no  further sectioning  elements but  possibly environments  like
       enumerations,  and formulae,  labels, references,  and citations.
       -->

  <!-- ============================================================== -->


\end{Verbatim}
 }


\chapter{\textcolor{Chapter }{The File \texttt{bibxmlext.dtd}}}\label{bibxmlextdtd}
\logpage{[ "C", 0, 0 ]}
\hyperdef{L}{X7E2788757A1AA098}{}
{
  For easier reference we repeat here the complete content of the file \texttt{bibxmlext.dtd} which is explained in \ref{BibXMLformat}.
\begin{Verbatim}[fontsize=\small,frame=single,label=bibxmlext.dtd]
  <?xml version="1.0" encoding="UTF-8"?>
  <!--
    - (C) Frank L�beck (http://www.math.rwth-aachen.de/~Frank.Luebeck)
    -
    - The BibXMLext data format.
    -
    - This DTD expresses XML markup similar to the BibTeX language
    - specified for LaTeX, or actually its content model.
    -
    - It is a variation of a file bibxml.dtd developed by the project
    -   http://bibtexml.sf.net/
    -
    - For documentation on BibTeX, see
    -   http://www.ctan.org/tex-archive/biblio/bibtex/distribs/doc/
    -
    - A previous version of the code originally developed by
    - Vidar Bronken Gundersen, http://bibtexml.sf.net/
    - Reuse and repurposing is approved as long as this
    - notification appears with the code.
    -
  -->

  <!-- ..................................................................... -->
  <!-- Main structure -->

  <!-- key-value pairs as in BibTeX @string entries are put in empty elements
       (but here they can be used for parts of an entry field as well)       -->
  <!ELEMENT string EMPTY>
  <!ATTLIST string
     key        CDATA     #REQUIRED
     value      CDATA     #REQUIRED >

  <!-- entry may contain one of the bibliographic types. -->
  <!ELEMENT entry ( article | book | booklet |
                           manual | techreport |
                           mastersthesis | phdthesis |
                           inbook | incollection |
                           proceedings | inproceedings |
                           conference |
                           unpublished | misc ) >
  <!ATTLIST entry
     id         CDATA     #REQUIRED >

  <!-- file is the documents top element. -->
  <!ELEMENT file  ( string | entry )* >


  <!-- ..................................................................... -->
  <!-- Parameter entities -->

  <!-- these are additional elements often used, but not included in the
       standard BibTeX distribution, these must be added to the
       bibliography styles, otherwise these fields will be omitted by
       the formatter, we allow an arbitrary number of 'other' elements
       to specify any further information   -->

  <!ENTITY   %  n.user " abstract?, affiliation?,
                          contents?, copyright?,
                          (isbn | issn)?,
                          keywords?, language?, lccn?,
                          location?, mrnumber?, mrclass?, mrreviewer?,
                          price?, size?, url?, category?, other* ">

  <!ENTITY   %  n.common "key?, annotate?, crossref?,
                          %n.user;">

  <!-- content model used more than once -->

  <!ENTITY   %  n.InProceedings "author, title, booktitle,
                      year, editor?,
                      (volume | number)?,
                      series?, pages?, address?,
                      month?, organization?, publisher?,
                      note?, %n.common;">

  <!ENTITY   %  n.PHDThesis "author, title, school,
                      year, type?, address?, month?,
                      note?, %n.common;">

  <!-- ..................................................................... -->
  <!-- Entries in the BibTeX database -->

  <!-- [article] An article from a journal or magazine.
    -  Required fields: author, title, journal, year.
    -  Optional fields: volume, number, pages, month, note. -->
  <!ELEMENT   article    (author, title, journal,
                 year, volume?, number?, pages?,
                 month?, note?, %n.common;)
  >

  <!-- [book] A book with an explicit publisher.
    -  Required fields: author or editor, title, publisher, year.
    -  Optional fields: volume or number, series, address,
    -     edition, month, note. -->
  <!ELEMENT   book    ((author | editor), title,
                 publisher, year, (volume | number)?,
                 series?, address?, edition?, month?,
                 note?, %n.common;)
  >

  <!-- [booklet] A work that is printed and bound, but without a named
    -  publisher or sponsoring institution
    -  Required field: title.
    -  Optional fields: author, howpublished, address, month, year, note. -->
  <!ELEMENT   booklet    (author?, title,
                 howpublished?, address?, month?,
                 year?, note?, %n.common;)
  >

  <!-- [conference] The same as INPROCEEDINGS,
    -  included for Scribe compatibility. -->
  <!ELEMENT   conference      (%n.InProceedings;)
  >

  <!-- [inbook] A part of a book, which may be a chapter (or section or
    -  whatever) and/or a range of pages.
    -  Required fields: author or editor, title, chapter and/or pages,
    -     publisher, year.
    -  Optional fields: volume or number, series, type, address,
    -     edition, month, note. -->
  <!ELEMENT   inbook    ((author | editor), title,
                 ((chapter, pages?) | pages),
                 publisher, year, (volume |
                 number)?, series?, type?,
                 address?, edition?, month?,
                 note?, %n.common;)
  >

  <!--
    - > I want to express that the elements a and/or b are legal that is one
    - > of them or both must be present in the document instance (see the
    - > element content for BibTeX entry `InBook').
    - > How do I specify this in my DTD?
    -
    - Dave Peterson:
    -  in content model:   ((a , b?) | b)          if order matters
    -                      ((a , b?) | (b , a?))   otherwise
  -->

  <!-- [incollection] A part of a book having its own title.
    -  Required fields: author, title, booktitle, publisher, year.
    -  Optional fields: editor, volume or number, series, type,
    -     chapter, pages, address, edition, month, note. -->
  <!ELEMENT   incollection    (author, title,
                 booktitle, publisher, year,
                 editor?, (volume | number)?,
                 series?, type?, chapter?,
                 pages?, address?, edition?,
                 month?, note?,
                 %n.common;)
  >

  <!-- [inproceedings] An article in a conference proceedings.
    -  Required fields: author, title, booktitle, year.
    -  Optional fields: editor, volume or number, series, pages,
    -     address, month, organization, publisher, note. -->
  <!ELEMENT   inproceedings      (%n.InProceedings;)
  >

  <!-- [manual] Technical documentation
    -  Required field: title.
    -  Optional fields: author, organization, address,
    -     edition, month, year, note. -->
  <!ELEMENT   manual    (author?, title,
                 organization?, address?, edition?,
                 month?, year?, note?, %n.common;)
  >

  <!-- [mastersthesis] A Master's thesis.
    -  Required fields: author, title, school, year.
    -  Optional fields: type, address, month, note. -->
  <!ELEMENT   mastersthesis      (%n.PHDThesis;)
  >

  <!-- [misc] Use this type when nothing else fits.
    -  Required fields: none.
    -  Optional fields: author, title, howpublished, month, year, note. -->
  <!ELEMENT   misc    (author?, title?,
                 howpublished?, month?, year?, note?,
                 %n.common;)
  >

  <!-- [phdthesis] A PhD thesis.
    -  Required fields: author, title, school, year.
    -  Optional fields: type, address, month, note. -->
  <!ELEMENT   phdthesis      (%n.PHDThesis;)
  >

  <!-- [proceedings] The proceedings of a conference.
    -  Required fields: title, year.
    -  Optional fields: editor, volume or number, series,
    -     address, month, organization, publisher, note. -->
  <!ELEMENT   proceedings    (editor?, title, year,
                 (volume | number)?, series?,
                 address?, month?, organization?,
                 publisher?, note?, %n.common;)
  >

  <!-- [techreport] A report published by a school or other institution,
    -  usually numbered within a series.
    -  Required fields: author, title, institution, year.
    -  Optional fields: type, number, address, month, note. -->
  <!ELEMENT   techreport    (author, title,
                 institution, year, type?, number?,
                 address?, month?, note?, %n.common;)
  >

  <!-- [unpublished] A document having an author and title, but not
    -  formally published.
    -  Required fields: author, title, note.
    -  Optional fields: month, year. -->
  <!ELEMENT   unpublished    (author, title, note,
                 month?, year?, %n.common;)
  >

  <!-- ..................................................................... -->
  <!-- Fields from the standard bibliography styles -->

  <!--
    - Below is a description of all fields recognized by the standard
    - bibliography styles.  An entry can also contain other fields, which
    - are ignored by those styles.
    -
    - [address] Usually the address of the publisher or other type of
    - institution  For major publishing houses, van~Leunen recommends
    - omitting the information entirely.  For small publishers, on the other
    - hand, you can help the reader by giving the complete address.
    -
    - [annote] An annotation  It is not used by the standard bibliography
    - styles, but may be used by others that produce an annotated
    - bibliography.
    -
    - [author] The name(s) of the author(s), here *not* in the format
    - described in the LaTeX book. Contains elements <name> which in turn
    - contains elements <first>, <last> for the first name (or first names,
    - fully written or as initials, and including middle initials) and
    - the last name.
    -
    - [booktitle] Title of a book, part of which is being cited.  See the
    - LaTeX book for how to type titles.  For book entries, use the title
    - field instead.
    -
    - [chapter] A chapter (or section or whatever) number.
    -
    - [crossref] The database key of the entry being cross referenced.
    -
    - [edition] The edition of a book-for example, ``Second''.  This
    - should be an ordinal, and should have the first letter capitalized, as
    - shown here; the standard styles convert to lower case when necessary.
    -
    - [editor] Name(s) of editor(s), typed as indicated in the LaTeX book.
    - If there is also an author field, then the editor field gives the
    - editor of the book or collection in which the reference appears.
    -
    - [howpublished] How something strange has been published.  The first
    - word should be capitalized.
    -
    - [institution] The sponsoring institution of a technical report.
    -
    - [journal] A journal name.  Abbreviations are provided for many
    - journals; see the Local Guide.
    -
    - [key] Used for alphabetizing, cross referencing, and creating a label
    - when the ``author'' information (described in Section [ref: ] is
    - missing. This field should not be confused with the key that appears
    - in the \cite command and at the beginning of the database entry.
    -
    - [month] The month in which the work was published or, for an
    - unpublished work, in which it was written. You should use the
    - standard three-letter abbreviation, as described in Appendix B.1.3 of
    - the LaTeX book.
    -
    - [note] Any additional information that can help the reader.  The first
    - word should be capitalized.
    -
    - [number] The number of a journal, magazine, technical report, or of a
    - work in a series.  An issue of a journal or magazine is usually
    - identified by its volume and number; the organization that issues a
    - technical report usually gives it a number; and sometimes books are
    - given numbers in a named series.
    -
    - [organization] The organization that sponsors a conference or that
    - publishes a manual.
    -
    - [pages] One or more page numbers or range of numbers, such as 42-111
    - or 7,41,73-97 or 43+ (the `+' in this last example indicates pages
    - following that don't form a simple range).  To make it easier to
    - maintain Scribe-compatible databases, the standard styles convert a
    - single dash (as in 7-33) to the double dash used in TeX to denote
    - number ranges (as in 7-33). Here, we suggest to use the entity
    - &ndash; for a dash in page ranges.
    -
    - [publisher] The publisher's name.
    -
    - [school] The name of the school where a thesis was written.
    -
    - [series] The name of a series or set of books.  When citing an entire
    - book, the the title field gives its title and an optional series field
    - gives the name of a series or multi-volume set in which the book is
    - published.
    -
    - [title] The work's title. For mathematical formulae use the <M> or
    - <Math> elements explained below (and LaTeX code in the content, without
    - surrounding '$').
    -
    - [type] The type of a technical report-for example, ``Research
    - Note''.
    -
    - [volume] The volume of a journal or multivolume book.
    -
    - [year] The year of publication or, for an unpublished work, the year
    - it was written.  Generally it should consist of four numerals, such as
    - 1984, although the standard styles can handle any year whose last four
    - nonpunctuation characters are numerals, such as `(about 1984)'.
  -->

  <!-- Here is the main extension compared to the original BibXML definition
       from which is DTD is derived: We want to allow more markup in some
       elements such that we can use the bibliography for high quality
       output in other formats than LaTeX.

       - <M> and <Math>, mathematical formulae: Specify LaTeX code for "simple"
         formulae as content of <M> elements; "simple" means that they can be
         translated to a fairly readable ASCII representation as explained in
         the GAPDoc documentation on "<M>".
         More complicated formulae are given as content of <Math> elements.
         (Think about an <Alt> alternative for text or HTML representations.)

       - <URL>: use these elements to specify URLs, they can be properly
         converted to links if possible in an output format (in that case
         the Text attribute is used for the visible text).

       - <value key="..."/>:  substituted by the value-attribute specified
         in a <string key="..." value="..."/> element. Can be used anywhere,
         not only for complete fields as in BibTeX.

       - <C> protect case changes: should be used instead of {}'s which are
         used in BibTeX title fields to protect the case of letters from
         changes.

       - <Alt Only="...">, <Alt Not="...">, alternatives for different
         output formats:  Use this to specify alternatives, the GAPDoc
         utilities will do some special handling for "Text", "HTML",
         and "BibTeX" as output type.

       - <Wrap Name="...">, generic wrapper for other markup:
         Use this for any other type of markup you are interested in. The
         GAPDoc utilities will ignore the markup, but provide a hook
         to do install handler functions for them.
  -->
  <!ELEMENT   M               (#PCDATA | Alt)* > <!-- math with simple text
                                               representation, in LaTeX -->
  <!ELEMENT   Math            (#PCDATA | Alt)* > <!-- other math in LaTeX -->
  <!ELEMENT   URL             (#PCDATA | Alt | Link | LinkText)* > <!-- an URL -->
  <!ATTLIST   URL Text CDATA #IMPLIED>    <!-- text to be printed
                                               (default is content) -->
  <!ELEMENT   value             EMPTY   > <!-- placeholder for value given .. -->
  <!ATTLIST   value key CDATA #REQUIRED > <!-- .. by key, defined in a string
                                               element -->
  <!ELEMENT   C    (#PCDATA | value | Alt |
                    M | Math | Wrap | URL)* >  <!-- protect from case changes -->
  <!ELEMENT   Alt  (#PCDATA | value | C | Alt |
                    M | Math | Wrap | URL)* > <!-- specify alternatives for
                                               various types of output -->
  <!ATTLIST   Alt  Only CDATA #IMPLIED
                   Not  CDATA #IMPLIED  > <!-- specify output types in comma and
                    whitespace separated list (use exactly one of Only or Not) -->

  <!ENTITY % withMURL "(#PCDATA | value | M | Math | Wrap | URL | C | Alt )*" >

  <!ELEMENT   Wrap           %withMURL; > <!-- a generic wrapper  -->
  <!ATTLIST   Wrap Name CDATA #REQUIRED > <!-- needs a 'Name' attribute  -->

  <!ELEMENT   address         %withMURL; >
  <!-- here we don't want the complicated definition from the LaTeX book,
       use markup for first/last name(s): a <name> element for each
       author which contains <first> (optional), <last> elements:  -->
  <!ELEMENT   author          (name)* >
  <!ELEMENT   name            (first?, last) >
  <!ELEMENT   first           (#PCDATA) >
  <!ELEMENT   last            (#PCDATA) >

  <!ELEMENT   booktitle       %withMURL; >
  <!ELEMENT   chapter         %withMURL; >
  <!ELEMENT   edition         %withMURL; >
  <!-- same as for author field -->
  <!ELEMENT   editor          (name)* >
  <!ELEMENT   howpublished    %withMURL; >
  <!ELEMENT   institution     %withMURL; >
  <!ELEMENT   journal         %withMURL; >
  <!ELEMENT   month           %withMURL; >
  <!ELEMENT   note            %withMURL; >
  <!ELEMENT   number          %withMURL; >
  <!ELEMENT   organization    %withMURL; >
  <!ELEMENT   pages           %withMURL; >
  <!ELEMENT   publisher       %withMURL; >
  <!ELEMENT   school          %withMURL; >
  <!ELEMENT   series          %withMURL; >
  <!ELEMENT   title           %withMURL; >
  <!ELEMENT   type            %withMURL; >
  <!ELEMENT   volume          %withMURL; >
  <!ELEMENT   year            (#PCDATA) >

  <!-- These were not listed in the documentation for entry content, but
    -  appeared in the list of fields in the BibTeX documentation -->

  <!ELEMENT   annotate        %withMURL; >
  <!ELEMENT   crossref        %withMURL; >
  <!ELEMENT   key             (#PCDATA) >


  <!-- ..................................................................... -->
  <!-- Other popular fields
    -
    - From: http://www.ecst.csuchico.edu/~jacobsd/bib/formats/bibtex.html
    - BibTeX is extremely popular, and many people have used it to store
    - information. Here is a list of some of the more common fields:
    -
    - [affiliation]  The authors affiliation.
    - [abstract]  An abstract of the work.
    - [contents]  A Table of Contents
    - [copyright]  Copyright information.
    - [ISBN]  The International Standard Book Number.
    - [ISSN]  The International Standard Serial Number.
    -         Used to identify a journal.
    - [keywords]  Key words used for searching or possibly for annotation.
    - [language]  The language the document is in.
    - [location]  A location associated with the entry,
    -             such as the city in which a conference took place.
    - [LCCN]  The Library of Congress Call Number.
    -         I've also seen this as lib-congress.
    - [mrnumber]  The Mathematical Reviews number.
    - [mrclass]  The Mathematical Reviews class.
    - [mrreviewer]  The Mathematical Reviews reviewer.
    - [price]  The price of the document.
    - [size]  The physical dimensions of a work.
    - [URL] The WWW Universal Resource Locator that points to the item being
    -       referenced. This often is used for technical reports to point to the
    -       ftp site where the postscript source of the report is located.
    -
    - When using BibTeX with LaTeX you need
    - BibTeX style files to print these data.
  -->

  <!ELEMENT   abstract        %withMURL; >
  <!ELEMENT   affiliation     %withMURL; >
  <!ELEMENT   contents        %withMURL; >
  <!ELEMENT   copyright       %withMURL; >
  <!ELEMENT   isbn            (#PCDATA) >
  <!ELEMENT   issn            (#PCDATA) >
  <!ELEMENT   keywords        %withMURL; >
  <!ELEMENT   language        %withMURL; >
  <!ELEMENT   lccn            (#PCDATA) >
  <!ELEMENT   location        %withMURL; >
  <!ELEMENT   mrnumber        %withMURL; >
  <!ELEMENT   mrclass         %withMURL; >
  <!ELEMENT   mrreviewer      %withMURL; >
  <!ELEMENT   price           %withMURL; >
  <!ELEMENT   size            %withMURL; >
  <!ELEMENT   url             %withMURL; >


  <!-- Added by Zeger W. Hendrikse
    - [category]  Category of this bibitem
  -->
  <!ELEMENT   category      %withMURL; >

  <!-- A container element [other] for any further information, a description
     - of the type of data must be given in the attribute 'type'
  -->
  <!ELEMENT   other      %withMURL; >
  <!ATTLIST   other
      type      CDATA   #REQUIRED >


  <!-- ..................................................................... -->
  <!-- Predefined/reserved character entities -->

  <!ENTITY amp    "&#38;#38;">
  <!ENTITY lt     "&#38;#60;">
  <!ENTITY gt     "&#62;">
  <!ENTITY apos   "&#39;">
  <!ENTITY quot   "&#34;">


  <!-- Some more generally useful entities -->
  <!ENTITY nbsp "&#160;">
  <!ENTITY copyright "&#169;">
  <!ENTITY ndash "&#x2013;">


  <!-- ..................................................................... -->
  <!-- End of BibXMLext dtd -->

\end{Verbatim}
 }

\def\bibname{References\logpage{[ "Bib", 0, 0 ]}
\hyperdef{L}{X7A6F98FD85F02BFE}{}
}

\bibliographystyle{alpha}
\bibliography{gapdocbib.xml}

\addcontentsline{toc}{chapter}{References}

\def\indexname{Index\logpage{[ "Ind", 0, 0 ]}
\hyperdef{L}{X83A0356F839C696F}{}
}

\cleardoublepage
\phantomsection
\addcontentsline{toc}{chapter}{Index}


\printindex

\newpage
\immediate\write\pagenrlog{["End"], \arabic{page}];}
\immediate\closeout\pagenrlog
\end{document}