% generated by GAPDoc2LaTeX from XML source (Frank Luebeck)
\documentclass[11pt]{report}
\usepackage{a4wide}
\sloppy
\pagestyle{myheadings}
\usepackage{amssymb}
\usepackage{isolatin1}
\usepackage{makeidx}
\makeindex
\usepackage{color}
\definecolor{DarkOlive}{rgb}{0.1047,0.2412,0.0064}
\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{FuncColor}{rgb}{1.0,0.0,0.0}
%% strange name because of pdflatex bug:
\definecolor{Chapter }{rgb}{0.0,0.0,1.0}

\usepackage{fancyvrb}

\usepackage{pslatex}

\usepackage[
        a4paper=true,bookmarks=false,pdftitle={Written with GAPDoc},
        colorlinks=true,backref=page,breaklinks=true,linkcolor=RoyalBlue,
        citecolor=RoyalGreen,filecolor=RoyalRed,
        urlcolor=RoyalRed,pagecolor=RoyalBlue]{hyperref}

% 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,}}
\newcommand{\Q}{\mathbb{Q}}
\newcommand{\R}{\mathbb{R}}
\newcommand{\C}{\mathbb{C}}
\newcommand{\Z}{\mathbb{Z}}
\newcommand{\N}{\mathbb{N}}
\newcommand{\F}{\mathbb{F}}

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

\newsavebox{\backslashbox}
\sbox{\backslashbox}{\texttt{\symbol{92}}}
\newcommand{\bs}{\usebox{\backslashbox}}

\begin{document}

\logpage{[ 0, 0, 0 ]}
\begin{titlepage}
\begin{center}{\Huge \textbf{\textsf{GAPDoc}}}\\[1cm]
\markright{\scriptsize \mbox{}\hfill \textsf{GAPDoc} \hfill\mbox{}}
{( Version 0.99 ) }\\[1cm]
\mbox{}\\[3cm]
{\large \textbf{ Frank Lübeck   }}\\
{\large \textbf{ Max Neunhöffer   }}\\
\end{center}\vfill

\mbox{}\\
{\small \noindent \textbf{ Frank Lü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/\~{}Frank.Luebeck}}}\\
{\small \noindent \textbf{ Max Neunhöffer   } --- Email: \href{mailto://Max.Neunhoeffer@Math.RWTH-Aachen.De}{\texttt{Max.Neunhoeffer@Math.RWTH-Aachen.De}}\\
 --- Homepage: \href{http://www.math.rwth-aachen.de/~Max.Neunhoeffer}{\texttt{http://www.math.rwth-aachen.de/\~{}Max.Neunhoeffer}}}\\
\end{titlepage}

\newpage\setcounter{page}{2}
{\small 
\section*{Copyright}
\logpage{[ 0, 0, 1 ]}
 {\copyright} 2000 by Frank Lübeck and Max Neunhöffer 

 We adopt the copyright regulations of \textsf{GAP} as detailed in the copyright notice in the \textsf{GAP} manual. }\\[1cm]
\newpage

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

\tableofcontents
\newpage

  
\chapter{\textcolor{Chapter }{Introduction and Example}}\label{ch:intro}
\logpage{[ 1, 0, 0 ]}
{
 The main purpose of the \textsf{GAPDoc} package is to define a file format for documentation of \textsf{GAP}-programs and -packages. 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~\ref{ch:conv}. 
\section{\textcolor{Chapter }{XML}}\label{sec:XML}
\logpage{[ 1, 1, 0 ]}
{
 \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~\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~\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 ]}
{
 In this section we recall the lines from the example document in Appendix~\ref{app:3k+1} and give some explanations. 
\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml]
  <?xml version="1.0" encoding="ISO-8859-1"?> 
\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 ISO-8859-1, also
called ISO-latin1 character set. This is a nowadays widely used extension of
the ASCII character set which contains all special characters of Western
European languages (e.g., German umlauts and French accented characters). 
\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml]
  <!--   A complete "fake package" documentation   
     $Id: intro.xml,v 1.5 2001/11/16 15:20:47 gap Exp $
  -->
\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{<Book Name="3k+1">}, the ``element content'' and the ``end tag'' \texttt{</Book>} (end tags always start with \texttt{</}). 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{<TableOfContents/>} 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{{\textbackslash}begin\{document\} ... {\textbackslash}end\{document\}}. The sectioning in {\LaTeX} is not done by explicit start and end markup, but implicitly via heading
commands like \texttt{{\textbackslash}section}. Other markup is done by using braces \texttt{\{\}} 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~\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 (as in {\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, in particular certain ``special characters'' must be typed via entities, for example ``{\textless}'', ``{\textgreater}'' and ``\&'' to avoid a misinterpretation as XML markup. But also the special characters in {\LaTeX} are written with entities, since they need a different handling in a {\LaTeX} and a text output format, see~\ref{XMLspchar} and~\ref{GDspchar} for more details. It is possible to define additional entities for your
document inside the \texttt{<!DOCTYPE ...} declaration, see~\ref{GDent}. 

 Note that elements in XML must always be properly nested, as in this example.
A construct like \texttt{<a><b>...</a></b>} 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 ``{\textbackslash}chapter'' and ``{\textbackslash}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 \N</M> be a natural number. We consider the sequence
        <M>n(i,  k), i  \in  \N,</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 typed as in {\LaTeX}. 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~\ref{GDformulae} and~\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 BibTeX 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 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~\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{<Func Name="ThreeKPlusOneSequence" Arg="k[, max]"/>} and \texttt{<Ref Func="ThreeKPlusOneSequence"/>} 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 ]}
{
 
\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 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 parse and lots of tools are already available and there will be more
in the future. (Our experience was however, that only a few of them are usable
currently.) 
\end{description}
 }

 }

  
\chapter{\textcolor{Chapter }{How To Type a \textsf{GAPDoc} Document}}\label{HowEnter}
\logpage{[ 2, 0, 0 ]}
{
  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~\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~\ref{sec:3k+1expl}, and learning about more details in the reference Chapter~\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 ]}
{
  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 ]}
{
  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}[fontsize=\small,frame=single,label=Example]
  <?xml version="1.0" encoding="ISO-8859-1"?>
  <!DOCTYPE Book SYSTEM "gapdoc.dtd">
\end{Verbatim}
 See~\ref{XMLenc} for a remark on the ``encoding'' statement.

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

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

 
\subsection{\textcolor{Chapter }{Processing Instructions}}\label{XMLprocinstr}
\logpage{[ 2, 1, 3 ]}
{
  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. }

 ~

 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 ]}
{
  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 ]}
{
  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 ]}
{
  A ``start-tag'' consists of a less-than-character ``\texttt{{\textless}}'' directly followed (without whitespace) by an element name (see~\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 characters ``\texttt{{\textless}}'' and ``\texttt{\&}''.

 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 ]}
{
  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 ]}
{
  Elements which always have empty content can be written with a single tag.
This looks like a start tag (see~\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 ]}
{
  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. Important entities for \textsf{GAPDoc} are described in \ref{XMLspchar}, \ref{GDspchar} and \ref{GDent}.

 }

 
\subsection{\textcolor{Chapter }{Special Characters in XML}}\label{XMLspchar}
\logpage{[ 2, 1, 10 ]}
{
  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;}'' should sometimes be used to get ``\texttt{{\textgreater}}''.

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

 
\subsection{\textcolor{Chapter }{\texttt{CDATA}}}\label{XMLcdata}
\logpage{[ 2, 1, 11 ]}
{
  Pieces of text which contain many characters which can be misinterpreted as
markup can be enclosed by the character sequences ``\texttt{<![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, 12 ]}
{
  We suggest to use the ISO-8859-1 or ISO-latin1 encoding for writing \textsf{GAPDoc} XML documents. This character set contains the ASCII characters and all
special characters from Western European languages like German umlauts or
French accented characters. Text in this character set can be used directly
with {\LaTeX} and many current default terminal fonts support this character set. }

 
\subsection{\textcolor{Chapter }{Well Formed and Valid XML Documents}}\label{XMLvalid}
\logpage{[ 2, 1, 13 ]}
{
  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~\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 ]}
{
  Here are some additional rules for writing \textsf{GAPDoc} XML documents. 
\subsection{\textcolor{Chapter }{More Special Characters}}\label{GDspchar}
\logpage{[ 2, 2, 1 ]}
{
  Since one purpose of \textsf{GAPDoc} documents is to produce a high quality {\LaTeX} output version we have to pay attention to characters with a special meaning
in {\LaTeX} or in XML. These are the following characters:

 ``\texttt{\&}'', ``\texttt{{\textless}}'', ``\texttt{{\textgreater}}'', ``\texttt{\#}'', ``\texttt{\$}'', ``\texttt{\%}'', ``\texttt{{\textasciitilde}}'', ``\texttt{{\textbackslash}}'', ``\texttt{\{}'', ``\texttt{\}}'', ``\texttt{{\textunderscore}}'', ``\texttt{{\textasciicircum}}'' and ``\texttt{~}'' (the last one is a non-breakable space, similar to {\LaTeX}'s ``\texttt{{\textasciitilde}}'' character). 

 The right way to access these symbols is by using ``entities'', see~\ref{XMLent}. The following table shows what to type to get these characters in the output
text of the document.

 \mbox{}\label{charsInCDATA}\begin{center}
\begin{tabular}{|l|l|}\hline
\texttt{\&}&
\texttt{\&tamp;}\\
\hline
\texttt{{\textless}}&
\texttt{\&tlt;}\\
\hline
\texttt{{\textgreater}}&
\texttt{\&tgt;}\\
\hline
\texttt{\#}&
\texttt{\&hash;}\\
\hline
\texttt{\$}&
\texttt{\&dollar;}\\
\hline
\texttt{\%}&
\texttt{\&percent;}\\
\hline
\texttt{{\textasciitilde}}&
\texttt{\&tilde;}\\
\hline
\texttt{{\textbackslash}}&
\texttt{\&bslash;}\\
\hline
\texttt{\{}&
\texttt{\&obrace;}\\
\hline
\texttt{\}}&
\texttt{\&cbrace;}\\
\hline
\texttt{{\textunderscore}}&
\texttt{\&uscore;}\\
\hline
\texttt{{\textasciicircum}}&
\texttt{\&circum;}\\
\hline
\texttt{~}&
\texttt{\&nbsp;}\\
\hline
\end{tabular}\\[2mm]
\textbf{Table: }What to type for special characters in character data\end{center}



 Note that the first three have an extra ``t'' at the beginning in comparison with the standard entities of XML described in~\ref{XMLspchar}. The difference is necessary because for example ``\texttt{\&tamp;}'' produces ``\texttt{{\textbackslash}\&}'' for {\LaTeX} to actually get an ampersand character in the printed version. Use ``\texttt{\&amp;}'' if you want to pass an ampersand character without a backslash in front
directly to {\LaTeX}.

 Inside attribute values you should \emph{not} use these entities. Instead use the corresponding characters directly. The
reason is that attribute values are often used as labels in {\LaTeX} and it is easier to process this properly with the direct input of the
characters.

 Also, these entities are \emph{not} used inside mathematical formulae, see ~\ref{GDformulae} below. }

 
\subsection{\textcolor{Chapter }{Mathematical Formulae}}\label{GDformulae}
\logpage{[ 2, 2, 2 ]}
{
  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~\ref{Math} and~\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 remarks about special characters in~\ref{GDspchar} do not apply to the content of these elements. But the special characters ``\texttt{{\textless}}'' and ``\texttt{\&}'' for XML must be entered via the entities described in~\ref{XMLspchar} or by using a \texttt{CDATA} statement, see~\ref{XMLcdata}.

 }

 
\subsection{\textcolor{Chapter }{More Entities}}\label{GDent}
\logpage{[ 2, 2, 3 ]}
{
  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;}&
BibTeX\\
\hline
\texttt{\&MeatAxe;}&
\textsf{MeatAxe}\\
\hline
\texttt{\&XGAP;}&
\textsf{XGAP}\\
\hline
\texttt{\&copyright;}&
{\copyright}\\
\hline
\end{tabular}\\[2mm]
\textbf{Table: }Predefined Entities in the \textsf{GAPDoc} system\end{center}

 One can define further local entities right inside the head (see~\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="ISO-8859-1"?>
  
  <!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 ]}
{
  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~\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 an extra document with book name \texttt{GAPDocExample} (also accessible from the \textsf{GAP} online help). 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~\ref{ch:intro}. 
\section{\textcolor{Chapter }{What is a DTD?}}\logpage{[ 3, 1, 0 ]}
{
 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~\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: 

 ~~\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 ]}
{
 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 ]}
{
 \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 ]}
{
 \index{TitlePage@\texttt{TitlePage}} 
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT TitlePage (Title, Subtitle?, Version?, Author+, Date?, 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 ]}
{
 \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 | 
                        Keyword | K | Arg | A | Quoted | Q | Code | C | 
                        File | F | Button | B | Package |
                        M | Math | Display | 
                        Example | Listing | Log | Verb |
                        URL | Email | Homepage | 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 ]}
{
 \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 ]}
{
 \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}Author{\textgreater}}}}\logpage{[ 3, 2, 6 ]}
{
 \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
elements should contain the name of an author and probably an \texttt{Email}-address and/or WWW-\texttt{Homepage} element for this author, see~\ref{elEmail} and~\ref{elHomepage}. }

 
\subsection{\textcolor{Chapter }{\texttt{{\textless}Date{\textgreater}}}}\logpage{[ 3, 2, 7 ]}
{
 \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}Abstract{\textgreater}}}}\logpage{[ 3, 2, 8 ]}
{
 \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, 9 ]}
{
 \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, 10 ]}
{
 \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, 11 ]}
{
 \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, 12 ]}
{
 \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=From gapdoc.dtd]
  <TableOfContents/>
\end{Verbatim}
 to denote this empty element. }

 
\subsection{\textcolor{Chapter }{\texttt{{\textless}Bibliography{\textgreater}} }}\label{Bibliography}
\logpage{[ 3, 2, 13 ]}
{
 \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 and refers to BibTeX databases. The databases must be separated by commas and must \emph{not} have a \texttt{.bib} extension. 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. 

 The reference for the format of BibTeX database files is~\cite[Appendix B]{La85}. }

 
\subsection{\textcolor{Chapter }{\texttt{{\textless}TheIndex{\textgreater}}}}\label{TheIndex}
\logpage{[ 3, 2, 14 ]}
{
 \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 ]}
{
 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 ]}
{
 \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 ]}
{
 \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 ]}
{
 \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 ]}
{
 \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 ]}
{
 \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 ]}
{
 \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}}\label{sec:mansect}
\logpage{[ 3, 4, 0 ]}
{
  \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 ]}
{
 \index{ManSection@\texttt{ManSection}} \index{Description@\texttt{Description}} \index{Returns@\texttt{Returns}} 
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT ManSection (((Func, Returns?) | (Oper, Returns?) | 
                         (Meth, Returns?) | (Filt, Returns?) | 
                         (Prop, Returns?) | (Attr, 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~\ref{Log}). The classes of items \textsf{GAPDoc} knows of are: functions (\texttt{Func}), operations (\texttt{Oper}), 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. A possible heading
is generated automatically from the first element. }

 
\subsection{\textcolor{Chapter }{\texttt{{\textless}Func{\textgreater}}}}\label{Func}
\logpage{[ 3, 4, 2 ]}
{
 \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 arguments are
separated by whitespace or commas.

 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~\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 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~\ref{TheIndex} and~\ref{Index}). }

 
\subsection{\textcolor{Chapter }{\texttt{{\textless}Oper{\textgreater}}}}\logpage{[ 3, 4, 3 ]}
{
 \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~\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, 4 ]}
{
 \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}). 

 Due to the fact that it often happens that many methods are installed for the
same operation 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, 5 ]}
{
 \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, 6 ]}
{
 \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, 7 ]}
{
 \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, 8 ]}
{
 \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, 9 ]}
{
 \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, 10 ]}
{
 \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 ]}
{
 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 ]}
{
 \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
                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{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}).

 Optionally an external reference into another book can be specified by using
the \texttt{BookName} attribute. In this case the \texttt{Label} attribute \emph{must} be specified and refers to a search string as in the \textsf{GAP} help system. It is guaranteed that the reference points to the position in the
other book, that the \textsf{GAP} help system finds as first match if one types the value of the \texttt{Label} element after a question mark.

 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 controls, 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: `\texttt{{\textless}Func{\textgreater}}' described in section \ref{Func}. }

 
\subsection{\textcolor{Chapter }{\texttt{{\textless}Label{\textgreater}}}}\label{Label}
\logpage{[ 3, 5, 2 ]}
{
 \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 ]}
{
 \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 BibTeX 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{{\textbackslash}cite[...]\{...\}}. }

 
\subsection{\textcolor{Chapter }{\texttt{{\textless}Index{\textgreater}}}}\label{Index}
\logpage{[ 3, 5, 4 ]}
{
 \index{Index@\texttt{Index}} 
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Index (%InnerText;)*>
  <!ATTLIST Index Key    CDATA #IMPLIED
                  Subkey CDATA #IMPLIED>
\end{Verbatim}
 This element generates an index entry. The text within the element is typeset
in the index entry, which is sorted under the value, that is specified in the \texttt{Key} and \texttt{Subkey} attributes. If they are not specified, the typeset text itself is used as the
key. 

 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}}}}\logpage{[ 3, 5, 5 ]}
{
 \index{URL@\texttt{URL}} 
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT URL (#PCDATA)>    <!-- Can we define this better? -->
  <!ATTLIST URL Text CDATA #IMPLIED>   <!-- This is for output formats
                                            that have links like HTML -->
\end{Verbatim}
 This element is for references into the internet. The text within the element
should be a valid URL. It is typeset in the document. For the case of an
output document format that supports links the value of the attribute \texttt{Text} is typeset as visible text for the link. }

 
\subsection{\textcolor{Chapter }{\texttt{{\textless}Email{\textgreater}}}}\label{elEmail}
\logpage{[ 3, 5, 6 ]}
{
 \index{Email@\texttt{Email}} 
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Email (#PCDATA)>
\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 ]}
{
 \index{Homepage@\texttt{Homepage}} 
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Homepage (#PCDATA)>
\end{Verbatim}
 This element type is the special case of an URL specifying a WWW-homepage. The
content of the element should be the valid URL specifying a world wide web
page. In comparison with the \texttt{URL} element the address is visible in all output formats. }

 }

 
\section{\textcolor{Chapter }{Structural Elements like Lists}}\logpage{[ 3, 6, 0 ]}
{
 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 ]}
{
 \index{List@\texttt{List}} 
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT List ( ((Mark,Item)|(BigMark,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 ]}
{
 \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 ]}
{
 \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 ]}
{
 \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 identically to the \texttt{List} element (see \ref{List}) except that the items may 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 ]}
{
 \index{Table@\texttt{Table}} \index{Caption@\texttt{Caption}} \index{Row@\texttt{Row}} \index{Align@\texttt{Align}} \index{HorLine@\texttt{HorLine}} \index{Item@\texttt{Item}} 
\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 ]}
{
 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 ]}
{
 \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 ]}
{
 \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 ``~''-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 ]}
{
 \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 ]}
{
 \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 ]}
{
 \index{Code@\texttt{Code}} \index{C@\texttt{C}} 
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
  <!ELEMENT Code (#PCDATA|Alt)*>     <!-- GAP code -->
  <!ELEMENT C (#PCDATA|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}. No further markup elements are allowed within this element. }

 
\subsection{\textcolor{Chapter }{\texttt{{\textless}File{\textgreater}} and \texttt{{\textless}F{\textgreater}}}}\logpage{[ 3, 7, 6 ]}
{
 \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 ]}
{
 \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 ]}
{
 \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 ]}
{
 \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 characters 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 ]}
{
 \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. }

 
\subsection{\textcolor{Chapter }{{\textless}Verb{\textgreater}}}\label{Verb}
\logpage{[ 3, 7, 11 ]}
{
 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 ]}
{
 
\subsection{\textcolor{Chapter }{\texttt{{\textless}Math{\textgreater}} and \texttt{{\textless}Display{\textgreater}}}}\label{Math}
\logpage{[ 3, 8, 1 ]}
{
 \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)*>
\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~\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}.)

 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.

 In text and HTML output these formula are shown as {\LaTeX} source code. For simple formulae (and you should try to make all your formulae
simple!) there is the element \texttt{M} (see~\ref{M}) 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} and \texttt{Display} elements or provide useful text substitutes for complicated formulae via \texttt{Alt} elements (see~\ref{Alt} and~\ref{Verb}). }

 
\subsection{\textcolor{Chapter }{\texttt{{\textless}M{\textgreater}}}}\label{M}
\logpage{[ 3, 8, 2 ]}
{
 \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 ASCII 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.

 The following {\LaTeX} macros have a sensible ASCII translation and are guaranteed to be translated
accordingly by text (and HTML) converters: \begin{center}
\begin{tabular}{|l|l|}\hline
{\textbackslash}ldots&
\texttt{...}\\
\hline
{\textbackslash}mid&
\texttt{|}\\
\hline
{\textbackslash}left&
\texttt{~}\\
\hline
{\textbackslash}right&
\texttt{~}\\
\hline
{\textbackslash}mathbb&
\texttt{~}\\
\hline
{\textbackslash}mathop&
\texttt{~}\\
\hline
{\textbackslash}limits&
\texttt{~}\\
\hline
{\textbackslash}cdot&
\texttt{*}\\
\hline
{\textbackslash}ast&
\texttt{*}\\
\hline
{\textbackslash}geq&
\texttt{{\textgreater}=}\\
\hline
{\textbackslash}leq&
\texttt{{\textless}=}\\
\hline
{\textbackslash}pmod&
\texttt{mod}\\
\hline
{\textbackslash}equiv&
\texttt{=}\\
\hline
{\textbackslash}rightarrow&
\texttt{-{\textgreater}}\\
\hline
{\textbackslash}hookrightarrow&
\texttt{-{\textgreater}}\\
\hline
{\textbackslash}to&
\texttt{-{\textgreater}}\\
\hline
{\textbackslash}longrightarrow&
\texttt{--{\textgreater}}\\
\hline
{\textbackslash}Rightarrow&
\texttt{={\textgreater}}\\
\hline
{\textbackslash}Longrightarrow&
\texttt{=={\textgreater}}\\
\hline
{\textbackslash}Leftarrow&
\texttt{{\textless}=}\\
\hline
{\textbackslash}iff&
\texttt{{\textless}={\textgreater}}\\
\hline
{\textbackslash}mapsto&
\texttt{-{\textgreater}}\\
\hline
{\textbackslash}leftarrow&
\texttt{{\textless}-}\\
\hline
{\textbackslash}langle&
\texttt{{\textless}}\\
\hline
{\textbackslash}rangle&
\texttt{{\textgreater}}\\
\hline
{\textbackslash}setminus&
\texttt{{\textbackslash}}\\
\hline
\end{tabular}\\[2mm]
\textbf{Table: }{\LaTeX} macros with special text translation\end{center}

 In all other macros only the backslash is removed. 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{\{\}} 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{\textasciicircum}\{12\}{\textless}/M{\textgreater}} for \texttt{x{\textasciicircum}12} and \texttt{{\textless}M{\textgreater}x{\textunderscore}\{\{i+1\}\}{\textless}/M{\textgreater}} for \texttt{x{\textunderscore}\{i+1\}}. 

 }

 }

 
\section{\textcolor{Chapter }{Everything else}}\label{sec:misc}
\logpage{[ 3, 9, 0 ]}
{
  
\subsection{\textcolor{Chapter }{\texttt{{\textless}Alt{\textgreater}}}}\label{Alt}
\logpage{[ 3, 9, 1 ]}
{
 \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
following values are allowed as of now: ``\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. 

 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 ]}
{
 \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>      <!-- this is intentionally empty! -->
\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.) }

 }

 }

  
\chapter{\textcolor{Chapter }{Distributing a Document into Several Files}}\label{Distributing}
\logpage{[ 4, 0, 0 ]}
{
  In \textsf{GAPDoc} there are facilities to distribute a document into 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. Basically, there is only a set of conventions how
this is done and some tools to collect the text for further processing. 

 
\section{\textcolor{Chapter }{The Conventions}}\label{DistrConv}
\logpage{[ 4, 1, 0 ]}
{
  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 Label="}'' 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 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{ComposedXMLString} (\ref{ComposedXMLString}) 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 an XML document. }

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

\subsection{\textcolor{Chapter }{ComposedXMLString}}
\logpage{[ 4, 2, 1 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ComposedXMLString( path, main, source )\index{ComposedXMLString@\texttt{ComposedXMLString}}
\label{ComposedXMLString}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
XML document as string



 This function returns a string containing a \textsf{GAPDoc} XML document constructed from several source files.

 Here \mbox{\texttt{path}} must be a path to some directory (as string or directory object), \mbox{\texttt{main}} the name of a file in this directory and \mbox{\texttt{source}} a list of file names, all of these relative to \mbox{\texttt{path}}. The document is constructed via the mechanism described in Section~\ref{DistrConv}.

 First the files given in \mbox{\texttt{source}} are scanned for chunks of \textsf{GAPDoc}-documentation marked by \texttt{{\textless}\#GAPDoc Label="...">} and \texttt{{\textless}/\#GAPDoc>} pairs. Then the file \mbox{\texttt{main}} is read and all \texttt{{\textless}\#Include ... >}-tags are substituted recursively by other files or chunks of documentation
found in the first step, respectively. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> doc := ComposedXMLString("/my/dir", "manual.xml", 
  > ["../lib/func.gd", "../lib/func.gi"]);;
\end{Verbatim}
 }

 }

 }

  
\chapter{\textcolor{Chapter }{The Converters}}\label{ch:conv}
\logpage{[ 5, 0, 0 ]}
{
  The \textsf{GAPDoc} package contains a set of programs which allow 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 ]}
{
  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~\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 BibTeX database \texttt{MyBook.bib} for the citations is also in the directory given above. We want to produce a
text-, \texttt{dvi}-, \texttt{pdf-}, postscript- and HTML-version of the document.

 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{ComposedXMLString} (\ref{ComposedXMLString}). This interprets recursively the \texttt{{\textless}\#Include ...{\textgreater}}-statements. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> path := Directory("/my/book/path");;
  gap> main := "MyBook.xml";;
  gap> files := ["../lib/a.gd", "../lib/b.gi"];;
  gap> bookname := "MyBook";;
  gap> str := ComposedXMLString(path, main, files);;
\end{Verbatim}
 Then 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}[fontsize=\small,frame=single,label=Example]
  gap> r := ParseTreeXMLString(str);;
  gap> CheckAndCleanGapDocTree(r);
  true
\end{Verbatim}
 We first 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}[fontsize=\small,frame=single,label=Example]
  gap> l := GAPDoc2LaTeX(r);;
  gap> 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}[fontsize=\small,frame=single,label=Example]
  cd /my/book/path
  latex MyBook
  bibtex MyBook
  makeindex MyBook
  latex MyBook
  latex MyBook
  mv MyBook.dvi manual.dvi
  dvips -o manual.ps manual.dvi
  rm MyBook.aux
  pdflatex MyBook
  pdflatex MyBook
  mv MyBook.pdf manual.pdf
\end{Verbatim}
 After this we have a \texttt{dvi}-, \texttt{pdf}- and postscript version of the document in the files \texttt{manual.dvi}, \texttt{manual.pdf} and \texttt{manual.ps}. The first two versions contain hyperlink information which can be used with
appropriate browsers for convenient reading of the document on screen (e.g.,
current versions of \texttt{xdvi}, respectively \texttt{xpdf} or \texttt{acroread}.

 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 will use this later.

 Next we produce a text version 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 color markup using ANSI escape sequences.
One can use this with a terminal which interprets these sequences
appropriately after setting the \textsf{GAP} variable \texttt{ANSI{\textunderscore}COLORS} to \texttt{true}. For the bibliography we have to tell \texttt{GAPDoc2Text} (\ref{GAPDoc2Text}) the location of the BibTeX database by specifying a \texttt{path} as second argument. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  t := GAPDoc2Text(r, path);;
  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 BibTeX 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. We can add the page number information from the {\LaTeX} version of the document and then print a \texttt{manual.six} file which is read by \textsf{GAP} when the document is loaded. This is done with \texttt{AddPageNumbersToSix} (\ref{AddPageNumbersToSix}) and \texttt{PrintSixFile} (\ref{PrintSixFile}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> AddPageNumbersToSix(r, Filename(path, "MyBook.pnr"));
  gap> 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 may also add a file \texttt{manual.css}, see \texttt{GAPDoc2HTMLPrintHTMLFiles} (\ref{GAPDoc2HTMLPrintHTMLFiles}) for more details. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> h := GAPDoc2HTML(r);;
  gap> GAPDoc2HTMLPrintHTMLFiles(h, path);
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{MakeGAPDocDoc}}
\logpage{[ 5, 1, 1 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{MakeGAPDocDoc( path, main, files, bookname[, gaproot] )\index{MakeGAPDocDoc@\texttt{MakeGAPDocDoc}}
\label{MakeGAPDocDoc}
}\hfill{\scriptsize (function)}}\\


 This function collects all the commands for producing a \texttt{dvi}-, \texttt{pdf}-, postscript-, text- and HTML-version of a \textsf{GAPDoc} document as described in Section~\ref{MakeDoc}.

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

 }

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

\subsection{\textcolor{Chapter }{ParseTreeXMLString}}
\logpage{[ 5, 2, 1 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ParseTreeXMLString( str )\index{ParseTreeXMLString@\texttt{ParseTreeXMLString}}
\label{ParseTreeXMLString}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a record which is root of a tree structure



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

 A node in this tree looks corresponds either to an XML element, or 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{str}}{[312..15610]}} looks like \texttt{{\textless}Book Name="EDIM"> ... content ... {\textless}/Book>}.

 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{<!DOCTYPE ..>} 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{<!DOCTYPE ..>} 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 }{DisplayXMLStructure}}
\logpage{[ 5, 2, 2 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DisplayXMLStructure( 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, 3 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ApplyToNodesParseTree( tree, fun )\index{ApplyToNodesParseTree@\texttt{ApplyToNodesParseTree}}
\label{ApplyToNodesParseTree}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AddRootParseTree( tree )\index{AddRootParseTree@\texttt{AddRootParseTree}}
\label{AddRootParseTree}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RemoveRootParseTree( tree )\index{RemoveRootParseTree@\texttt{RemoveRootParseTree}}
\label{RemoveRootParseTree}
}\hfill{\scriptsize (function)}}\\


 The function \texttt{ApplyToNodesParseTree} applies a function \mbox{\texttt{fun}} to all nodes of the parse tree \mbox{\texttt{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} which is assigned to the top node \mbox{\texttt{tree}}. These components can be removed afterwards with \texttt{RemoveRootParseTree}. }

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

\subsection{\textcolor{Chapter }{CheckAndCleanGapDocTree}}
\logpage{[ 5, 2, 4 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CheckAndCleanGapDocTree( tree )\index{CheckAndCleanGapDocTree@\texttt{CheckAndCleanGapDocTree}}
\label{CheckAndCleanGapDocTree}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing



 The argument \mbox{\texttt{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, 5 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AddParagraphNumbersGapDocTree( tree )\index{AddParagraphNumbersGapDocTree@\texttt{AddParagraphNumbersGapDocTree}}
\label{AddParagraphNumbersGapDocTree}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing



 The argument \mbox{\texttt{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. }

 }

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

\subsection{\textcolor{Chapter }{GAPDoc2LaTeX}}
\logpage{[ 5, 3, 1 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GAPDoc2LaTeX( tree )\index{GAPDoc2LaTeX@\texttt{GAPDoc2LaTeX}}
\label{GAPDoc2LaTeX}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
{\LaTeX} document as string



 The argument \mbox{\texttt{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 BibTeX and \texttt{makeindex}). 

 The output uses the \texttt{report} document class and needs the following {\LaTeX} packages: \texttt{a4wide}, \texttt{amssymb}, \texttt{isolatin1}, \texttt{makeidx}, \texttt{color}, \texttt{fancyvrb}, \texttt{pslatex} and \texttt{hyperref}. These are for example provided by the \textsf{teTeX-1.0} distribution of {\TeX} (which in turn is 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{dvi}- or \texttt{pdf}-output contains (internal and external) hyperlinks which can be very useful
for online 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}). There is support for two types or XML processing instructions which allow to
change the options used for the document class or to add some extra lines to
the preamble of the {\LaTeX} document. They can be specified as in the following examples: 
\begin{Verbatim}[fontsize=\small,frame=single,label=in top level of XML document]
  <?LaTeX Options="12pt"?>
  <?LaTeX ExtraPreamble="\usepackage{blabla}
  \newcommand{\bla}{blabla}
  "?>
\end{Verbatim}
 A hint for large documents: In many {\TeX} installations one can easily reach some memory limitations with documents
which contain many (cross-)references. In \textsf{teTeX} you can look for a file \texttt{texmf.cnf} which allows to enlarge certain memory sizes.

 This function works by running recursively through the document tree and
calling a handler function for each \textsf{GAPDoc} XML element. These handler functions are all quite easy 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. }

 

\subsection{\textcolor{Chapter }{GAPDoc2Text}}
\logpage{[ 5, 3, 2 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GAPDoc2Text( 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{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 BibTeX databases. Their location must be given with the argument \mbox{\texttt{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 also a record with 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~3, section~2, subsection~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{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{tree}}.six}, see \texttt{GAPDoc2LaTeX} (\ref{GAPDoc2LaTeX}) and \texttt{AddPageNumbersToSix} (\ref{AddPageNumbersToSix})).

 The text produced by this function contains color markup via ANSI escape
sequences, see \texttt{TextAttr} (\ref{TextAttr}). To view the colored text you need a terminal which interprets these escape
sequences correctly and you have to set the variable \texttt{ANSI{\textunderscore}COLORS} to \texttt{true} (a good place for doing this is your \texttt{.gaprc} file).

 With the optional argument \mbox{\texttt{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 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GAPDoc2TextPrintTextFiles( 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 and use the name of this directory as an argument for one of the
commands \texttt{DeclarePackageDocumentation} (\textbf{Reference: DeclarePackageDocumentation}) or \texttt{DeclarePackageAutoDocumentation} (\textbf{Reference: DeclarePackageAutoDocumentation}). Furthermore you need to put the file \texttt{manual.six} into this directory, see \texttt{PrintSixFile} (\ref{PrintSixFile}). 

 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 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AddPageNumbersToSix( tree, pnrfile )\index{AddPageNumbersToSix@\texttt{AddPageNumbersToSix}}
\label{AddPageNumbersToSix}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing



 Here \mbox{\texttt{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} (\ref{GAPDoc2LaTeX})\texttt{(\mbox{\texttt{tree}})} produces a file \mbox{\texttt{pnrfile}} (with extension \texttt{.pnr}). The command \texttt{GAPDoc2Text} (\ref{GAPDoc2Text})\texttt{(\mbox{\texttt{tree}})} creates a component \texttt{\mbox{\texttt{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{tree}}.six}. }

 

\subsection{\textcolor{Chapter }{PrintSixFile}}
\logpage{[ 5, 3, 5 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PrintSixFile( 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{fname}} for a \textsf{GAPDoc} document stored in \mbox{\texttt{tree}} with name \mbox{\texttt{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 }{GAPDoc2HTML}}
\logpage{[ 5, 3, 6 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GAPDoc2HTML( tree[, bibpath[, gaproot]] )\index{GAPDoc2HTML@\texttt{GAPDoc2HTML}}
\label{GAPDoc2HTML}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
record containing HTML files as strings and other information



 The argument \mbox{\texttt{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 an HTML version of the document which can be read
with any Web-browser and also 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 BibTeX databases. Their location must be given with the argument \mbox{\texttt{bibpath}} (as string or directory object). If the third argument \mbox{\texttt{gaproot}} is given and is a string then this string is interpreted as relative path to \textsf{GAP}'s 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 also a record with components The HTML code produced
with this converter conforms to the W3C specification HTML 4.01 strict, see \href{http://www.w3.org/TR/html401}{\texttt{http://www.w3.org/TR/html401}}. This means in particular that the code doesn't contain any explicit font or
color information. The layout information for a browser should be specified in
a cascading style sheet (CSS) file. The \textsf{GAPDoc} package contains an example of such a style sheet, see the file \texttt{gapdoc.css} in the root directory of the package. This file 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}}. You may just copy that file as \texttt{manual.css} into the directory which contains the HTML version of your documentation. But,
of course, you are free to adjust it for your package, e.g., change colors or
other layout details, add a background image, ... Each of the HTML files
produced by the converters contains a link to this local style sheet file
called \texttt{manual.css}. 
\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~3, section~2, subsection~1) 
\end{description}
 The result can be written into files with the command \texttt{GAPDoc2HTMLPrintHTMLFiles} (\ref{GAPDoc2HTMLPrintHTMLFiles}).

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

 

\subsection{\textcolor{Chapter }{GAPDoc2HTMLPrintHTMLFiles}}
\logpage{[ 5, 3, 7 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GAPDoc2HTMLPrintHTMLFiles( 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}.

 You can make these files accessible via the \textsf{GAP} online help by putting them into a directory and using this as an argument for
one of the commands \texttt{DeclarePackageDocumentation} (\textbf{Reference: DeclarePackageDocumentation}) or \texttt{DeclarePackageAutoDocumentation} (\textbf{Reference: DeclarePackageAutoDocumentation}). To tell \textsf{GAP} that the HTML version is accessible you have to add a file \texttt{manual.html} which is a link to or a copy of \texttt{chap0.html}. You may also want to put a file \texttt{manual.css} into that directory, see \texttt{GAPDoc2HTML} (\ref{GAPDoc2HTML}). }

 }

 
\section{\textcolor{Chapter }{Parsing BibTeX Files}}\label{ParseBib}
\logpage{[ 5, 4, 0 ]}
{
  Here are functions for parsing, normalizing and printing reference lists in BibTeX format. The reference describing this format is~\cite[Appendix B]{La85}. 

\subsection{\textcolor{Chapter }{ParseBibFiles}}
\logpage{[ 5, 4, 1 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ParseBibFiles( bibfile )\index{ParseBibFiles@\texttt{ParseBibFiles}}
\label{ParseBibFiles}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
list \texttt{[list of bib-records, list of abbrevs, list of expansions]}



 This function parses a file \mbox{\texttt{bibfile}} (if this file does not exist the extension \texttt{.bib} is appended) in BibTeX 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{bibfile}}. Then \texttt{strings} is a list of abbreviations defined by \texttt{@string}-entries in \mbox{\texttt{bibfile}} and \texttt{texts} is a list which contains in the corresponding position the full text for such
an abbreviation. 

 The records in entries store key-value pairs of a BibTeX 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}.

 As an example consider the following BibTeX file. 
\begin{Verbatim}[fontsize=\small,frame=single,label=my.bib]
  @string{ j  = "Important Journal" }
  @article{ AX2000, Author=  "Fritz A. First and Sec, X. Y.", 
  TITLE="Short", journal = j, year = 2000 }
\end{Verbatim}
 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> bib := ParseBibFiles("my.bib");
  [ [ rec( Type := "article", Label := "AB2000", 
            author := "Fritz A. First and Sec, X. Y.", title := "Short", 
            journal := "Important Journal", year := "2000" ) ], 
    [ "j" ], 
    [ "Important Journal" ] ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{NormalizeNameAndKey}}
\logpage{[ 5, 4, 2 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{NormalizeNameAndKey( r )\index{NormalizeNameAndKey@\texttt{NormalizeNameAndKey}}
\label{NormalizeNameAndKey}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing



 This function normalizes in a record describing a BibTeX reference (see \texttt{ParseBibFiles} (\ref{ParseBibFiles})) the \texttt{author} and editor fields using the description in \cite[Appendix  B 1.2]{La85}. The original entries are stored in \texttt{.authororig} and \texttt{.editororig}.

 Furthermore a short and a long citation key is generated.

 We continue the example from \texttt{ParseBibFiles} (\ref{ParseBibFiles}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> bib[1][1];
  rec( Type := "article", Label := "AB2000", 
    author := "First, F. A. and Sec, X. Y. ", title := "Short", 
    journal := "Important Journal", year := "2000", 
    authororig := "Fritz A. First and Sec, X. Y.", key := "FS00", 
    keylong := "firstsec2000" )
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{WriteBibFile}}
\logpage{[ 5, 4, 3 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{WriteBibFile( 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{bib}} must have a format as it is returned by \texttt{ParseBibFiles} (\ref{ParseBibFiles}). A BibTeX file \mbox{\texttt{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}[fontsize=\small,frame=single,label=Example]
  gap> 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},
    key =              {FS00},
    authororig =       {Fritz A. First and Sec, X. Y.},
    keylong =          {firstsec2000}
  }
\end{Verbatim}
 }

 }

 
\section{\textcolor{Chapter }{Text Utilities}}\label{TextUtil}
\logpage{[ 5, 5, 0 ]}
{
  This section describes some utility functions for handling texts within \textsf{GAP}. They are used by other 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{[ 5, 5, 1 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{WHITESPACE\index{WHITESPACE@\texttt{WHITESPACE}}
\label{WHITESPACE}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CAPITALLETTERS\index{CAPITALLETTERS@\texttt{CAPITALLETTERS}}
\label{CAPITALLETTERS}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SMALLLETTERS\index{SMALLLETTERS@\texttt{SMALLLETTERS}}
\label{SMALLLETTERS}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{LETTERS\index{LETTERS@\texttt{LETTERS}}
\label{LETTERS}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DIGITS\index{DIGITS@\texttt{DIGITS}}
\label{DIGITS}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{HEXDIGITS\index{HEXDIGITS@\texttt{HEXDIGITS}}
\label{HEXDIGITS}
}\hfill{\scriptsize (global variable)}}\\


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

 
\begin{description}
\item[{WHITESPACE}] \texttt{" {\textbackslash}n{\textbackslash}t{\textbackslash}r"}
\item[{CAPITALLETTERS}] \texttt{"ABCDEFGHIJKLMNOPQRSTUVWXYZ"}
\item[{SMALLLETTERS}] \texttt{"abcdefghijklmnopqrstuvwxyz"}
\item[{LETTERS}] concatenation of CAPITALLETTERS and SMALLLETTERS
\item[{DIGITS}] \texttt{"0123456789"}
\item[{HEXDIGITS}] \texttt{"0123456789ABCDEFabcdef"}
\end{description}
 }

 

\subsection{\textcolor{Chapter }{TextAttr}}
\logpage{[ 5, 5, 2 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \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{ANSI{\textunderscore}COLORS} Whenever you use this in some printing routines you should make it optional.
Use these attributes only, when the variable \texttt{ANSI{\textunderscore}COLORS} has the value \texttt{true}. }

 

\subsection{\textcolor{Chapter }{FormatParagraph}}
\logpage{[ 5, 5, 3 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FormatParagraph( str[, len[, flush[, attr]]] )\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{str}} as a paragraph. The optional arguments have the following meaning: 
\begin{description}
\item[{\mbox{\texttt{len}}}] the length of the lines of the resulting text (default is \texttt{78})
\item[{\mbox{\texttt{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{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{["", ""]})
\end{description}
 This function tries to handle markup with the escape sequences explained in \texttt{TextAttr} (\ref{TextAttr}) correctly. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> str := "One two three four five six seven eight nine ten eleven.";;
  gap> Print(FormatParagraph(str, 25, "left", ["/* ", " */"]));           
  /* One two three four five */
  /* six seven eight nine ten */
  /* eleven. */
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{SubstitutionSublist}}
\logpage{[ 5, 5, 4 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SubstitutionSublist( 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{sublist}} in a list \mbox{\texttt{list}} (compare \texttt{PositionSublist} (\textbf{Reference: PositionSublist})) and returns a list where these are substituted with the list \mbox{\texttt{new}}.

 The optional argument \mbox{\texttt{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{sublist}} is substituted. 

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

  

\subsection{\textcolor{Chapter }{StripBeginEnd}}
\logpage{[ 5, 5, 5 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StripBeginEnd( list, strip )\index{StripBeginEnd@\texttt{StripBeginEnd}}
\label{StripBeginEnd}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
changed string



 Here \mbox{\texttt{list}} and \mbox{\texttt{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{strip}}. If the result is equal to \mbox{\texttt{list}} then \mbox{\texttt{list}} itself is returned. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> StripBeginEnd(" ,a, b,c,   ", ", ");
  "a, b,c"
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{StripEscapeSequences}}
\logpage{[ 5, 5, 6 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StripEscapeSequences( 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{str}} by removing all escape sequences which are explained in \texttt{TextAttr} (\ref{TextAttr}). If \mbox{\texttt{str}} does not contain such a sequence then \mbox{\texttt{str}} itself is returned. }

 

\subsection{\textcolor{Chapter }{RepeatedString}}
\logpage{[ 5, 5, 7 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RepeatedString( c, len )\index{RepeatedString@\texttt{RepeatedString}}
\label{RepeatedString}
}\hfill{\scriptsize (function)}}\\


 Here \mbox{\texttt{c}} must be either a character or a string and \mbox{\texttt{len}} is a non-negative number. Then \texttt{RepeatedString} returns a string of length \mbox{\texttt{len}} consisting of copies of \mbox{\texttt{c}}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> RepeatedString('=',51);
  "==================================================="
  gap> RepeatedString("*=",51);
  "*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*"
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{NumberDigits}}
\logpage{[ 5, 5, 8 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{NumberDigits( str, base )\index{NumberDigits@\texttt{NumberDigits}}
\label{NumberDigits}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
integer

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



 The argument \mbox{\texttt{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{base}} with $2 \leq \mbox{\texttt{base}} \leq 16$. This function returns the corresponding integer.

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

 

\subsection{\textcolor{Chapter }{PositionMatchingDelimiter}}
\logpage{[ 5, 5, 9 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PositionMatchingDelimiter( str, delim, pos )\index{PositionMatchingDelimiter@\texttt{PositionMatchingDelimiter}}
\label{PositionMatchingDelimiter}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
position as integer or \texttt{fail}



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

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

 

\subsection{\textcolor{Chapter }{WordsString}}
\logpage{[ 5, 5, 10 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{WordsString( 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{str}}. All non-letters are considered as word boundaries and are removed. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> WordsString("one_two \n    three!?");
  [ "one", "two", "three" ]
\end{Verbatim}
 }

 }

 
\section{\textcolor{Chapter }{Print Utilities}}\label{PrintUtil}
\logpage{[ 5, 6, 0 ]}
{
  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{[ 5, 6, 1 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PrintTo1( filename, fun )\index{PrintTo1@\texttt{PrintTo1}}
\label{PrintTo1}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AppendTo1( filename, fun )\index{AppendTo1@\texttt{AppendTo1}}
\label{AppendTo1}
}\hfill{\scriptsize (function)}}\\


 The argument \mbox{\texttt{fun}} must be a function without arguments. Everything which is printed by a call \mbox{\texttt{fun()}} is printed into the file \mbox{\texttt{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{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}[fontsize=\small,frame=single,label=Example]
  gap> f := function() local i; 
  >   for i in [1..100000] do Print(i, "\n"); od; end; 
  gap> PrintTo1("nonsense", f); # now check the local file `nonsense'
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{StringPrint}}
\logpage{[ 5, 6, 2 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StringPrint( obj1[, obj2[, ...]] )\index{StringPrint@\texttt{StringPrint}}
\label{StringPrint}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StringView( obj )\index{StringView@\texttt{StringView}}
\label{StringView}
}\hfill{\scriptsize (function)}}\\


 These functions return a string containing the output of a \texttt{Print} or \texttt{ViewObj} call 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{[ 5, 6, 3 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PrintFormattedString( str )\index{PrintFormattedString@\texttt{PrintFormattedString}}
\label{PrintFormattedString}
}\hfill{\scriptsize (function)}}\\


 This function prints a string \mbox{\texttt{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{[ 5, 6, 4 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Page( ... )\index{Page@\texttt{Page}}
\label{Page}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PageDisplay( 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}[fontsize=\small,frame=single,label=Example]
  gap> Page([1..1421]+0);
  gap> PageDisplay(CharacterTable("Symmetric", 14));
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{StringFile}}
\logpage{[ 5, 6, 5 ]}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StringFile( filename )\index{StringFile@\texttt{StringFile}}
\label{StringFile}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FileString( filename, str[, append] )\index{FileString@\texttt{FileString}}
\label{FileString}
}\hfill{\scriptsize (function)}}\\


 The function \texttt{StringFile} returns the content of file \mbox{\texttt{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{str}} into the file \mbox{\texttt{filename}}. If the optional third argument \mbox{\texttt{append}} is given and equals \texttt{true} then the content of \mbox{\texttt{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. }

 }

 }

 

\appendix


\chapter{\textcolor{Chapter }{The file \texttt{3k+1.xml}}}\label{app:3k+1}
\logpage{[ "A", 0, 0 ]}
{
 Here is the complete source of the example \textsf{GAPDoc} document \texttt{3k+1.xml} discussed in Section~\ref{sec:3k+1expl}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=3k+1.xml]
  <?xml version="1.0" encoding="ISO-8859-1"?>
  
  <!--   A complete "fake package" documentation   
     $Id: app3k1.xml,v 1.1.1.1 2001/01/05 13:37:49 gap Exp $
  -->
  
  <!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 \N</M> be a natural number. We consider the sequence
        <M>n(i,  k), i  \in  \N,</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 \N</M> 
        there is an <M>m \in \N</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://mathsrv.ku-eichstaett.de/MGF/homes/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 ]}
{
  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="ISO-8859-1"?>
  <!-- ==================================================================
       gapdoc.dtd - XML Document type definition for GAP documentation
       By Frank Lübeck and Max Neunhöffer
       ================================================================== -->
  
  <!-- $Id: gapdoc.dtd,v 1.5 2002/05/02 20:39:58 gap Exp $ -->
  
  <!-- 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 are necessary because these characters have special
       meanings in either XML or LaTeX: -->
       
  <!ENTITY tamp 
    "<Alt Only='LaTeX'>\&amp;</Alt><Alt Not='LaTeX'><Alt Only='HTML'>&amp;amp;</Alt><Alt Not='HTML'>&amp;</Alt></Alt>">
  <!ENTITY tlt 
    "<Alt Only='LaTeX'>{\textless}</Alt><Alt Not='LaTeX'><Alt Only='HTML'>&amp;lt;</Alt><Alt Not='HTML'>&lt;</Alt></Alt>">
  <!ENTITY tgt 
    "<Alt Only='LaTeX'>{\textgreater}</Alt><Alt Not='LaTeX'><Alt Only='HTML'>&amp;gt;</Alt><Alt Not='HTML'>&gt;</Alt></Alt>">
  <!ENTITY hash "<Alt Only='LaTeX'>\#</Alt><Alt Not='LaTeX'>#</Alt>">
  <!ENTITY dollar "<Alt Only='LaTeX'>\$</Alt><Alt Not='LaTeX'>$</Alt>">
  <!ENTITY percent 
    "<Alt Only='LaTeX'>\&#37;</Alt><Alt Not='LaTeX'>&#37;</Alt>">
  <!ENTITY tilde 
    "<Alt Only='LaTeX'>{\textasciitilde}</Alt><Alt Not='LaTeX'>~</Alt>">
  <!ENTITY bslash 
    "<Alt Only='LaTeX'>{\textbackslash}</Alt><Alt Not='LaTeX'>\</Alt>">
  <!ENTITY obrace "<Alt Only='LaTeX'>\{</Alt><Alt Not='LaTeX'>{</Alt>">
  <!ENTITY cbrace "<Alt Only='LaTeX'>\}</Alt><Alt Not='LaTeX'>}</Alt>">
  <!ENTITY uscore 
    "<Alt Only='LaTeX'>{\textunderscore}</Alt><Alt Not='LaTeX'>_</Alt>">
  <!ENTITY circum 
    "<Alt Only='LaTeX'>{\textasciicircum}</Alt><Alt Not='LaTeX'>^</Alt>">
  <!ENTITY nbsp "<Alt Only='LaTeX'>~</Alt><Alt Not='LaTeX'>&#160;</Alt>">
  
  <!-- ==================================================================
       Our predefined entities:
       ================================================================== -->
  
  <!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 
    "<Alt Only='LaTeX'>{\copyright}</Alt><Alt Not='LaTeX'>(C)</Alt>">
  
  
  <!-- ==================================================================
       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 | 
                        Keyword | K | Arg | A | Quoted | Q | Code | C | 
                        File | F | Button | B | Package |
                        M | Math | Display | 
                        Example | Listing | Log | Verb |
                        URL | Email | Homepage | Cite | Label | 
                        Ref | Index" >
  
  
  <!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>      <!-- this is intentionally empty! -->
  
  
  <!-- 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)*>   <!-- GAP code -->
  <!ELEMENT C (#PCDATA|Alt|A)*>      <!-- 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)*>
  
  
  <!-- 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)*>    <!-- Can we define this better? -->
  <!ATTLIST URL Text CDATA #IMPLIED>   <!-- This is for output formats
                                            that have links like HTML -->
  
  <!-- The following two are actually URLs, but the element name determines
       the type. -->
       
  <!ELEMENT Email (#PCDATA|Alt)*>
  <!ELEMENT Homepage (#PCDATA|Alt)*>
  
  <!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
                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. -->
  
  <!ELEMENT Index (%InnerText;)*>
  <!ATTLIST Index Key    CDATA #IMPLIED
                  Subkey CDATA #IMPLIED>
  
  
  <!-- ==================================================================
       The following  describes the normal documentation  text which can
       occur  at various  places in  the document.  It does  not contain
       further sectioning elements. As  opposed to the InnerText element
       it can contain environments like enumerations, lists, and such.
       ================================================================== -->
  
  <!ENTITY % Text "%InnerText; | List | Enum | Table">
  
  <!ELEMENT Item ( %Text;)*>
  <!ELEMENT Mark ( %InnerText;)*>
  <!ELEMENT BigMark ( %InnerText;)*>
  
  <!ELEMENT List ( ((Mark,Item)|(BigMark,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?, Author+, Date?, Abstract?,
                       Copyright? , Acknowledgements? , Colophon? )>
  
  <!ELEMENT Title (%Text;)*>
  <!ELEMENT Subtitle (%Text;)*>
  <!ELEMENT Version (%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>
  
  
  <!-- ==================================================================
       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 (((Func, Returns?) | (Oper, Returns?) | 
                         (Meth, Returns?) | (Filt, Returns?) | 
                         (Prop, Returns?) | (Attr, 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  even if 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 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}
 }

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

\bibliographystyle{plain}
\bibliography{gapdoc}

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


\printindex

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