% generated by GAPDoc2LaTeX from XML source (Frank Luebeck)
\documentclass[a4paper,11pt]{report}
\usepackage{a4wide}
\sloppy
\pagestyle{myheadings}
\usepackage{amssymb}
\usepackage[latin1]{inputenc}
\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[pdftex=true,
a4paper=true,bookmarks=false,pdftitle={Written with GAPDoc},
pdfcreator={LaTeX with hyperref package / 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,}}
%% were never documented, give conflicts with some additional packages
\newcommand{\GAP}{\textsf{GAP}}
\begin{document}
\logpage{[ 0, 0, 0 ]}
\begin{titlepage}
\begin{center}{\Huge \textbf{\textsf{GAPDoc}\mbox{}}}\\[1cm]
\hypersetup{pdftitle=\textsf{GAPDoc}}
\markright{\scriptsize \mbox{}\hfill \textsf{GAPDoc} \hfill\mbox{}}
{( Version 1.2 ) \mbox{}}\\[1cm]
{June 2008\mbox{}}\\[1cm]
\mbox{}\\[2cm]
{\large \textbf{ Frank L{\"u}beck \mbox{}}}\\
{\large \textbf{ Max Neunh{\"o}ffer \mbox{}}}\\
\hypersetup{pdfauthor= Frank L{\"u}beck ; Max Neunh{\"o}ffer }
\end{center}\vfill
\mbox{}\\
{\mbox{}\\
\small \noindent \textbf{ Frank L{\"u}beck } --- Email: \href{mailto://Frank.Luebeck@Math.RWTH-Aachen.De} {\texttt{Frank.Luebeck@Math.RWTH-Aachen.De}}\\
--- Homepage: \href{http://www.math.rwth-aachen.de/~Frank.Luebeck} {\texttt{http://www.math.rwth-aachen.de/\texttt{\symbol{126}}Frank.Luebeck}}}\\
{\mbox{}\\
\small \noindent \textbf{ Max Neunh{\"o}ffer } --- Email: \href{mailto://neunhoef at mcs.st-and.ac.uk} {\texttt{neunhoef at mcs.st-and.ac.uk}}\\
--- Homepage: \href{http://www-groups.mcs.st-and.ac.uk/~neunhoef/} {\texttt{http://www-groups.mcs.st-and.ac.uk/\texttt{\symbol{126}}neunhoef/}}}\\
\end{titlepage}
\newpage\setcounter{page}{2}
{\small
\section*{Copyright}
\logpage{[ 0, 0, 1 ]}
{\copyright} 2000-2008 by Frank L{\"u}beck and Max Neunh{\"o}ffer
We adopt the copyright regulations of \textsf{GAP} as detailed in the copyright notice in the \textsf{GAP} manual. \mbox{}}\\[1cm]
\newpage
\def\contentsname{Contents\logpage{[ 0, 0, 2 ]}}
\tableofcontents
\newpage
\chapter{\textcolor{Chapter }{Introduction and Example}}\label{ch:intro}
\logpage{[ 1, 0, 0 ]}
\hyperdef{L}{X7D4EE663818DA109}{}
{
The main purpose of the \textsf{GAPDoc} package is to define a file format for documentation of \textsf{GAP}-programs and -packages (see \cite{GAP4}). The problem is that such documentation should be readable in several output
formats. For example it should be possible to read the documentation inside
the terminal in which \textsf{GAP} is running (a text mode) and there should be a printable version in high
typesetting quality (produced by some version of {\TeX}). It is also popular to view \textsf{GAP}'s online help with a Web-browser via an HTML-version of the documentation.
Nowadays one can use {\LaTeX} and standard viewer programs to produce and view on the screen \texttt{dvi}- or \texttt{pdf}-files with full support of internal and external hyperlinks. Certainly there
will be other interesting document formats and tools in this direction in the
future.
Our aim is to find a \emph{format for writing} the documentation which allows a relatively easy translation into the output
formats just mentioned and which hopefully makes it easy to translate to
future output formats as well.
To make documentation written in the \textsf{GAPDoc} format directly usable, we also provide a set of programs, called converters,
which produce text-, hyperlinked {\LaTeX}- and HTML-output versions of a \textsf{GAPDoc} document. These programs are developed by the first named author. They run
completely inside \textsf{GAP}, i.e., no external programs are needed. You only need \texttt{latex} and \texttt{pdflatex} to process the {\LaTeX} output. These programs are described in Chapter{\nobreakspace}\ref{ch:conv}.
\section{\textcolor{Chapter }{XML}}\label{sec:XML}
\logpage{[ 1, 1, 0 ]}
\hyperdef{L}{X8590236E858F7E93}{}
{
\index{XML} The definition of the \textsf{GAPDoc} format uses XML, the ``eXtendible Markup Language''. This is a standard (defined by the W3C consortium, see \href{http://www.w3c.org} {\texttt{http://www.w3c.org}}) which lays down a syntax for adding markup to a document or to some data. It
allows to define document structures via introducing markup \emph{elements} and certain relations between them. This is done in a \emph{document type definition}. The file \texttt{gapdoc.dtd} contains such a document type definition and is the central part of the \textsf{GAPDoc} package.
The easiest way for getting a good idea about this is probably to look at an
example. The Appendix{\nobreakspace}\ref{app:3k+1} contains a short but complete \textsf{GAPDoc} document for a fictitious share package. In the next section we will go
through this document, explain basic facts about XML and the \textsf{GAPDoc} document type, and give pointers to more details in later parts of this
documentation.
In the last Section{\nobreakspace}\ref{sec:faq} of this introductory chapter we try to answer some general questions about the
decisions which lead to the \textsf{GAPDoc} package. }
\section{\textcolor{Chapter }{A complete example}}\label{sec:3k+1expl}
\logpage{[ 1, 2, 0 ]}
\hyperdef{L}{X7B47AFA881BFC9DC}{}
{
In this section we recall the lines from the example document in
Appendix{\nobreakspace}\ref{app:3k+1} and give some explanations.
\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml]
<?xml version="1.0" encoding="UTF-8"?>
\end{Verbatim}
This line just tells a human reader and computer programs that the file is a
document with XML markup and that the text is encoded in the UTF-8 character
set (other common encodings are ASCII or ISO-8895-X encodings).
\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml]
<!-- A complete "fake package" documentation
$Id: intro.xml,v 1.13 2007/10/04 22:02:12 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{{\textless}Book Name="3k+1"{\textgreater}}, the ``element content'' and the ``end tag'' \texttt{{\textless}/Book{\textgreater}} (end tags always start with \texttt{{\textless}/}). This element also has an ``attribute'' \texttt{Name} whose ``value'' is \texttt{3k+1}.
If you know HTML, this will look familiar to you. But there are some important
differences: The element name \texttt{Book} and attribute name \texttt{Name} are \emph{case sensitive}. The value of an attribute must \emph{always} be enclosed in quotes. In XML \emph{every} element has a start and end tag (which can be combined for elements defined as ``empty'', see for example \texttt{{\textless}TableOfContents/{\textgreater}} below).
If you know {\LaTeX}, you are familiar with quite different types of markup, for example: The
equivalent of the \texttt{Book} element in {\LaTeX} is \texttt{\texttt{\symbol{92}}begin\texttt{\symbol{123}}document\texttt{\symbol{125}}
... \texttt{\symbol{92}}end\texttt{\symbol{123}}document\texttt{\symbol{125}}}. The sectioning in {\LaTeX} is not done by explicit start and end markup, but implicitly via heading
commands like \texttt{\texttt{\symbol{92}}section}. Other markup is done by using braces \texttt{\texttt{\symbol{123}}\texttt{\symbol{125}}} and putting some commands inside. And for mathematical formulae one can use
the \texttt{\$} for the start \emph{and} the end of the markup. In XML \emph{all} markup looks similar to that of the \texttt{Book} element.
The content of the book starts with a title page.
\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml]
<TitlePage>
<Title>The <Package>ThreeKPlusOne</Package> Package</Title>
<Version>Version 42</Version>
<Author>Dummy Authör
<Email>3kplusone@dev.null</Email>
</Author>
<Copyright>©right; 2000 The Author. <P/>
You can do with this package what you want.<P/> Really.
</Copyright>
</TitlePage>
\end{Verbatim}
The content of the \texttt{TitlePage} element consists again of elements. In Chapter{\nobreakspace}\ref{DTD} we describe which elements are allowed within a \texttt{TitlePage} and that their ordering is prescribed in this case. In the (stupid) name of
the author you see that a German umlaut is used directly (in ISO-latin1
encoding).
Contrary to {\LaTeX}- or HTML-files this markup does not say anything about the actual layout of
the title page in any output version of the document. It just adds information
about the \emph{meaning} of pieces of text.
Within the \texttt{Copyright} element there are two more things to learn about XML markup. The \texttt{{\textless}P/{\textgreater}} is a complete element. It is a combined start and end tag. This shortcut is
allowed for elements which are defined to be always ``empty'', i.e., to have no content. You may have already guessed that \texttt{{\textless}P/{\textgreater}} is used as a paragraph separator. Note that empty lines do not separate
paragraphs (contrary to {\LaTeX}).
The other construct we see here is \texttt{\©right;}. This is an example of an ``entity'' in XML and is a macro for some substitution text. Here we use an entity as a
shortcut for a complicated expression which makes it possible that the term \emph{copyright} is printed as some text like \texttt{(C)} in text terminal output and as a copyright character in other output formats.
In \textsf{GAPDoc} we predefine some entities. Certain ``special characters'' must be typed via entities, for example ``{\textless}'', ``{\textgreater}'' and ``\&'' to avoid a misinterpretation as XML markup. It is possible to define
additional entities for your document inside the \texttt{{\textless}!DOCTYPE ...{\textgreater}} declaration, see{\nobreakspace}\ref{GDent}.
Note that elements in XML must always be properly nested, as in this example.
A construct like \texttt{{\textless}a{\textgreater}{\textless}b{\textgreater}...{\textless}/a{\textgreater}{\textless}/b{\textgreater}} is \emph{not} allowed.
\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml]
<TableOfContents/>
\end{Verbatim}
This is another example of an ``empty element''. It just means that a table of contents for the whole document should be
included into any output version of the document.
After this the main text of the document follows inside certain sectioning
elements:
\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml]
<Body>
<Chapter> <Heading>The <M>3k+1</M> Problem</Heading>
<Section Label="sec:theory"> <Heading>Theory</Heading>
[...] (content omitted)
</Section>
<Section> <Heading>Program</Heading>
[...] (content omitted)
</Section>
</Chapter>
</Body>
\end{Verbatim}
These elements are used similarly to ``\texttt{\symbol{92}}chapter'' and ``\texttt{\symbol{92}}section'' in {\LaTeX}. But note that the explicit end tags are necessary here.
The sectioning commands allow to assign an optional attribute ``Label''. This can be used for referring to a section inside the document.
The text of the first section starts as follows. The whitespace in the text is
unimportant and the indenting is not necessary.
\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml]
Let <M>k \in &NN;</M> be a natural number. We consider the
sequence <M>n(i, k), i \in &NN;,</M> with <M>n(1, k) = k</M> and
else
\end{Verbatim}
Here we come to the interesting question how to type mathematical formulae in
a \textsf{GAPDoc} document. We did not find any alternative for writing formulae in {\TeX} syntax. (There is MATHML, but even simple formulae contain a lot of markup,
become quite unreadable and they are cumbersome to type. Furthermore there
seem to be no tools available which translate such formulae in a nice way into {\TeX} and text.) So, formulae are essentially typed as in {\LaTeX}. (Actually, it is also possible to type unicode characters of some
mathematical symbols directly, or via an entity like the \texttt{\&NN;} above.) There are three types of elements containing formulae: ``M'', ``Math'' and ``Display''. The first two are for in-text formulae and the third is for displayed
formulae. Here ``M'' and ``Math'' are equivalent, when translating a \textsf{GAPDoc} document into {\LaTeX}. But they are handled differently for terminal text (and HTML) output. For
the content of an ``M''-element there are defined rules for a translation into well readable terminal
text. More complicated formulae are in ``Math'' or ``Display'' elements and they are just printed as they are typed in text output. So, to
make a section well readable inside a terminal window you should try to put as
many formulae as possible into ``M''-elements. In our example text we used the notation \texttt{n(i, k)} instead of \texttt{n{\textunderscore}i(k)} because it is easier to read in text mode. See Sections{\nobreakspace}\ref{GDformulae} and{\nobreakspace}\ref{sec:misc} for more details.
A few lines further on we find two non-internal references.
\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml]
problem, see <Cite Key="Wi98"/> or
<URL>http://mathsrv.ku-eichstaett.de/MGF/homes/wirsching/</URL>
\end{Verbatim}
The first within the ``Cite''-element is the citation of a book. In \textsf{GAPDoc} we use the widely used Bib{\TeX} database format for reference lists. This does not use XML but has a well
documented structure which is easy to parse. And many people have collections
of references readily available in this format. The reference list in an
output version of the document is produced with the empty element
\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml]
<Bibliography Databases="3k+1" />
\end{Verbatim}
close to the end of our example file. The attribute ``Databases'' give the name(s) of the database (\texttt{.bib}) files which contain the references.
Putting a Web-address into an ``URL''-element allows one to create a hyperlink in output formats which allow this.
The second section of our example contains a special kind of subsection
defined in \textsf{GAPDoc}.
\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml]
<ManSection>
<Func Name="ThreeKPlusOneSequence" Arg="k[, max]"/>
<Description>
This function computes for a natural number <A>k</A> the
beginning of the sequence <M>n(i, k)</M> defined in section
<Ref Sect="sec:theory"/>. The sequence stops at the first
<M>1</M> or at <M>n(<A>max</A>, k)</M>, if <A>max</A> is
given.
<Example>
gap> ThreeKPlusOneSequence(101);
"Sorry, not yet implemented. Wait for Version 84 of the package"
</Example>
</Description>
</ManSection>
\end{Verbatim}
A ``ManSection'' contains the description of some function, operation, method, filter and so
on. The ``Func''-element describes the name of a \emph{function} (there are also similar elements ``Oper'', ``Meth'', ``Filt'' and so on) and names for its arguments, optional arguments enclosed in square
brackets. See Section{\nobreakspace}\ref{sec:mansect} for more details.
In the ``Description'' we write the argument names as ``A''-elements. A good description of a function should usually contain an example
of its use. For this there are some verbatim-like elements in \textsf{GAPDoc}, like ``Example'' above (here, clearly, whitespace matters which causes a slightly strange
indenting).
The text contains an internal reference to the first section via the
explicitly defined label \texttt{sec:theory}.
The first section also contains a ``Ref''-element which refers to the function described here. Note that there is no
explicit label for such a reference. The pair \texttt{{\textless}Func Name="ThreeKPlusOneSequence" Arg="k[, max]"/{\textgreater}} and \texttt{{\textless}Ref Func="ThreeKPlusOneSequence"/{\textgreater}} does the cross referencing (and hyperlinking if possible) implicitly via the
name of the function.
Here is one further element from our example document which we want to
explain.
\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml]
<TheIndex/>
\end{Verbatim}
This is again an empty element which just says that an output version of the
document should contain an index. Many entries for the index are generated
automatically because the ``Func'' and similar elements implicitly produce such entries. It is also possible to
include explicit additional entries in the index. }
\section{\textcolor{Chapter }{Some questions}}\label{sec:faq}
\logpage{[ 1, 3, 0 ]}
\hyperdef{L}{X79A97B867F45E5C7}{}
{
\begin{description}
\item[{Are those XML files too ugly to read and edit?}] Just have a look and decide yourself. The markup needs more characters than
most {\TeX} or {\LaTeX} markup. But the structure of the document is easier to see. If you configure
your favorite editor well, you do not need more key strokes for typing the
markup than in {\LaTeX}.
\item[{Why do we not use {\LaTeX} alone?}] {\LaTeX} is good for writing books. But {\LaTeX} files are generally difficult to parse and to process to other output formats
like text for browsing in a terminal window or HTML (or new formats which may
become popular in the future). \textsf{GAPDoc} markup is one step more abstract than {\LaTeX} insofar as it describes meaning instead of appearance of text. The inner
workings of {\LaTeX} are too complicated to learn without pain, which makes it difficult to
overcome problems that occur occasionally.
\item[{Why XML and not a newly defined markup language?}] XML is a well defined standard that is more and more widely used. Lots of
people have thought about it. Years of experience with SGML went into the
design. It is easy to explain, easy to parse and lots of tools are available,
there will be more in the future.
\end{description}
}
}
\chapter{\textcolor{Chapter }{How To Type a \textsf{GAPDoc} Document}}\label{HowEnter}
\logpage{[ 2, 0, 0 ]}
\hyperdef{L}{X7890CF967F3E2FED}{}
{
In this chapter we give a more formal description of what you need to start to
type documentation in \textsf{GAPDoc} XML format. Many details were already explained by example in
Section{\nobreakspace}\ref{sec:3k+1expl} of the introduction.
We do \emph{not} answer the question ``How to \emph{write} a \textsf{GAPDoc} document?'' in this chapter. You can (hopefully) find an answer to this question by
studying the example in the introduction, see{\nobreakspace}\ref{sec:3k+1expl}, and learning about more details in the reference Chapter{\nobreakspace}\ref{DTD}.
The definite source for all details of the official XML standard with useful
annotations is:
\href{http://www.xml.com/axml/axml.html} {\texttt{http://www.xml.com/axml/axml.html}}
Although this document must be quite technical, it is surprisingly well
readable.
\section{\textcolor{Chapter }{General XML Syntax}}\label{EnterXML}
\logpage{[ 2, 1, 0 ]}
\hyperdef{L}{X7B3A544986A1A9EA}{}
{
We will now discuss the pieces of text which can occur in a general XML
document. We start with those pieces which do not contribute to the actual
content of the document.
\subsection{\textcolor{Chapter }{Head of XML Document}}\label{XMLhead}
\logpage{[ 2, 1, 1 ]}
\hyperdef{L}{X84E8D39687638CF0}{}
{
Each XML document should have a head which states that it is an XML document
in some encoding and which XML-defined language is used. In case of a \textsf{GAPDoc} document this should always look as in the following example.
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Book SYSTEM "gapdoc.dtd">
\end{Verbatim}
See{\nobreakspace}\ref{XMLenc} for a remark on the ``encoding'' statement.
(There may be local entity definitions inside the \texttt{DOCTYPE} statement, see Subsection{\nobreakspace}\ref{GDent} below.) }
\subsection{\textcolor{Chapter }{Comments}}\label{XMLcomment}
\logpage{[ 2, 1, 2 ]}
\hyperdef{L}{X780C79EB85C32138}{}
{
A ``comment'' in XML starts with the character sequence ``\texttt{{\textless}!--}'' and ends with the sequence ``\texttt{--{\textgreater}}''. Between these sequences there must not be two adjacent dashes ``\texttt{--}''. }
\subsection{\textcolor{Chapter }{Processing Instructions}}\label{XMLprocinstr}
\logpage{[ 2, 1, 3 ]}
\hyperdef{L}{X82DBCCAD8358BB63}{}
{
A ``processing instruction'' in XML starts with the character sequence ``\texttt{{\textless}?}'' followed by a name (``\texttt{xml}'' is only allowed at the very beginning of the document to declare it being an
XML document, see \ref{XMLhead}). After that any characters may follow, except that the ending sequence ``\texttt{?{\textgreater}}'' must not occur within the processing instruction. }
{\nobreakspace}
And now we turn to those parts of the document which contribute to its actual
content.
\subsection{\textcolor{Chapter }{Names in XML and Whitespace}}\label{XMLnames}
\logpage{[ 2, 1, 4 ]}
\hyperdef{L}{X7A0FB16C7FEC0B53}{}
{
A ``name'' in XML (used for element and attribute identifiers, see below) must start with
a letter (in the encoding of the document) or with a colon ``\texttt{:}'' or underscore ``\texttt{{\textunderscore}}'' character. The following characters may also be digits, dots ``\texttt{.}'' or dashes ``\texttt{-}''.
This is a simplified description of the rules in the standard, which are
concerned with lots of unicode ranges to specify what a ``letter'' is.
Sequences only consisting of the following characters are considered as \emph{whitespace}: blanks, tabs, carriage return characters and new line characters. }
\subsection{\textcolor{Chapter }{Elements}}\label{XMLel}
\logpage{[ 2, 1, 5 ]}
\hyperdef{L}{X79B130FC7906FB4C}{}
{
The actual content of an XML document consists of ``elements''. An element has some ``content'' with a leading ``start tag'' (\ref{XMLstarttag}) and a trailing ``end tag'' (\ref{XMLendtag}). The content can contain further elements but they must be properly nested.
One can define elements whose content is always empty, those elements can also
be entered with a single combined tag (\ref{XMLcombtag}). }
\subsection{\textcolor{Chapter }{Start Tags}}\label{XMLstarttag}
\logpage{[ 2, 1, 6 ]}
\hyperdef{L}{X7DD1DCB783588BD5}{}
{
A ``start-tag'' consists of a less-than-character ``\texttt{{\textless}}'' directly followed (without whitespace) by an element name (see{\nobreakspace}\ref{XMLnames}), optional attributes, optional whitespace, and a greater-than-character ``\texttt{{\textgreater}}''.
An ``attribute'' consists of some whitespace and then its name followed by an equal sign ``\texttt{=}'' which is optionally enclosed by whitespace, and the attribute value, which is
enclosed either in single or double quotes. The attribute value may not
contain the type of quote used as a delimiter or the character ``\texttt{{\textless}}'', the character ``\texttt{\&}'' may only appear to start an entity, see{\nobreakspace}\ref{XMLent}. We describe in{\nobreakspace}\ref{AttrValRules} how to enter special characters in attribute values.
Note especially that no whitespace is allowed between the starting ``\texttt{{\textless}}'' character and the element name. The quotes around an attribute value cannot be
omitted. The names of elements and attributes are \emph{case sensitive}. }
\subsection{\textcolor{Chapter }{End Tags}}\label{XMLendtag}
\logpage{[ 2, 1, 7 ]}
\hyperdef{L}{X7E5A567E83005B62}{}
{
An ``end tag'' consists of the two characters ``\texttt{{\textless}/}'' directly followed by the element name, optional whitespace and a
greater-than-character ``\texttt{{\textgreater}}''. }
\subsection{\textcolor{Chapter }{Combined Tags for Empty Elements}}\label{XMLcombtag}
\logpage{[ 2, 1, 8 ]}
\hyperdef{L}{X843A02A88514D919}{}
{
Elements which always have empty content can be written with a single tag.
This looks like a start tag (see{\nobreakspace}\ref{XMLstarttag}) \emph{except} that the trailing greater-than-character ``\texttt{{\textgreater}}'' is substituted by the two character sequence ``\texttt{/{\textgreater}}''. }
\subsection{\textcolor{Chapter }{Entities}}\label{XMLent}
\logpage{[ 2, 1, 9 ]}
\hyperdef{L}{X78FB56C77B1F391A}{}
{
An ``entity'' in XML is a macro for some substitution text. There are two types of entities.
A ``character entity'' can be used to specify characters in the encoding of the document (can be
useful for entering non-ASCII characters which you cannot manage to type in
directly). They are entered with a sequence ``\texttt{\&\#}'', directly followed by either some decimal digits or an ``\texttt{x}'' and some hexadecimal digits, directly followed by a semicolon ``\texttt{;}''. Using such a character entity is just equivalent to typing the corresponding
character directly.
Then there are references to ``named entities''. They are entered with an ampersand character ``\texttt{\&}'' directly followed by a name which is directly followed by a semicolon ``\texttt{;}''. Such entities must be declared somewhere by giving a substitution text. This
text is included in the document and the document is parsed again afterwards.
The exact rules are a bit subtle but you probably want to use this only in
simple cases. Predefined entities for \textsf{GAPDoc} are described in \ref{XMLspchar} and \ref{GDent}.
}
\subsection{\textcolor{Chapter }{Special Characters in XML}}\label{XMLspchar}
\logpage{[ 2, 1, 10 ]}
\hyperdef{L}{X84A95A19801EDE76}{}
{
We have seen that the less-than-character ``\texttt{{\textless}}'' and the ampersand character ``\texttt{\&}'' start a tag or entity reference in XML. To get these characters into the
document text one has to use entity references, namely ``\texttt{\<}'' to get ``\texttt{{\textless}}'' and ``\texttt{\&}'' to get ``\texttt{\&}''. Furthermore ``\texttt{\>}'' must be used to get ``\texttt{{\textgreater}}'' when the string ``\texttt{]]{\textgreater}}'' appears in element content (and not as delimiter of a \texttt{CDATA} section explained below).
Another possibility is to use a \texttt{CDATA} statement explained in{\nobreakspace}\ref{XMLcdata}. }
\subsection{\textcolor{Chapter }{Rules for Attribute Values}}\label{AttrValRules}
\logpage{[ 2, 1, 11 ]}
\hyperdef{L}{X7F49E7AD785AED22}{}
{
Attribute values can contain entities which are substituted recursively. But
except for the entities \< or a character entity it is not allowed that a
{\textless} character is introduced by the substitution (there is no XML
parsing for evaluating the attribute value, just entity substitutions). }
\subsection{\textcolor{Chapter }{\texttt{CDATA}}}\label{XMLcdata}
\logpage{[ 2, 1, 12 ]}
\hyperdef{L}{X82E77E707A062908}{}
{
Pieces of text which contain many characters which can be misinterpreted as
markup can be enclosed by the character sequences ``\texttt{{\textless}![CDATA[}'' and ``\texttt{]]{\textgreater}}''. Everything between these sequences is considered as content of the document
and is not further interpreted as XML text. All the rules explained so far in
this section do \emph{not apply} to such a part of the document. The only document content which cannot be
entered directly inside a \texttt{CDATA} statement is the sequence ``\texttt{]]{\textgreater}}''. This can be entered as ``\texttt{]]\>}'' outside the \texttt{CDATA} statement.
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
A nesting of tags like <a> <b> </a> </b> is not allowed.
\end{Verbatim}
}
\subsection{\textcolor{Chapter }{Encoding of an XML Document}}\label{XMLenc}
\logpage{[ 2, 1, 13 ]}
\hyperdef{L}{X8709BD337DA09ED5}{}
{
We suggest to use the UTF-8 encoding for writing \textsf{GAPDoc} XML documents. But the tools described in Chapter \ref{ch:conv} also work with ASCII or the various ISO-8859-X encodings (ISO-8859-1 is also
called latin1 and covers most special characters for western European
languages). }
\subsection{\textcolor{Chapter }{Well Formed and Valid XML Documents}}\label{XMLvalid}
\logpage{[ 2, 1, 14 ]}
\hyperdef{L}{X8561F07A81CABDD6}{}
{
We want to mention two further important words which are often used in the
context of XML documents. A piece of text becomes a ``well formed'' XML document if all the formal rules described in this section are fulfilled.
But this says nothing about the content of the document. To give this content
a meaning one needs a declaration of the element and corresponding attribute
names as well as of named entities which are allowed. Furthermore there may be
restrictions how such elements can be nested. This \emph{definition of an XML based markup language} is done in a ``document type definition''. An XML document which contains only elements and entities declared in such a
document type definition and obeys the rules given there is called ``valid (with respect to this document type definition)''.
The main file of the \textsf{GAPDoc} package is \texttt{gapdoc.dtd}. This contains such a definition of a markup language. We are not going to
explain the formal syntax rules for document type definitions in this section.
But in Chapter{\nobreakspace}\ref{DTD} we will explain enough about it to understand the file \texttt{gapdoc.dtd} and so the markup language defined there. }
}
\section{\textcolor{Chapter }{Entering \textsf{GAPDoc} Documents}}\label{EnterGD}
\logpage{[ 2, 2, 0 ]}
\hyperdef{L}{X7BDE59B17CF1D5D2}{}
{
Here are some additional rules for writing \textsf{GAPDoc} XML documents.
\subsection{\textcolor{Chapter }{Other special characters}}\label{otherspecchar}
\logpage{[ 2, 2, 1 ]}
\hyperdef{L}{X79171E047B069F94}{}
{
As \textsf{GAPDoc} documents are used to produce {\LaTeX} and HTML documents, the question arises how to deal with characters with a
special meaning for other applications (for example ``\texttt{\&}'', ``\texttt{\#}'', ``\texttt{\$}'', ``\texttt{\%}'', ``\texttt{\texttt{\symbol{126}}}'', ``\texttt{\texttt{\symbol{92}}}'', ``\texttt{\texttt{\symbol{123}}}'', ``\texttt{\texttt{\symbol{125}}}'', ``\texttt{{\textunderscore}}'', ``\texttt{\texttt{\symbol{94}}}'', ``\texttt{{\nobreakspace}}'' (this is a non-breakable space, ``\texttt{\texttt{\symbol{126}}}'' in {\LaTeX}) have a special meaning for {\LaTeX} and ``\texttt{\&}'', ``\texttt{{\textless}}'', ``\texttt{{\textgreater}}'' have a special meaning for HTML (and XML). In \textsf{GAPDoc} you can usually just type these characters directly, it is the task of the
converter programs which translate to some output format to take care of such
special characters. The exceptions to this simple rule are:
\begin{itemize}
\item \& and {\textless} must be entered as \texttt{\&} and \texttt{\<} as explained in \ref{XMLspchar}.
\item The content of the \textsf{GAPDoc} elements \texttt{{\textless}M{\textgreater}}, \texttt{{\textless}Math{\textgreater}} and \texttt{{\textless}Display{\textgreater}} is {\LaTeX} code, see \ref{MathForm}.
\item The content of an \texttt{{\textless}Alt{\textgreater}} element with \texttt{Only} attribute contains code for the specified output type, see \ref{Alt}.
\end{itemize}
Remark: In former versions of \textsf{GAPDoc} one had to use particular entities for all the special characters mentioned
above (\texttt{\&tamp;}, \texttt{\&hash;}, \texttt{\$}, \texttt{\&percent;}, \texttt{\˜}, \texttt{\&bslash;}, \texttt{\&obrace;}, \texttt{\&cbrace;}, \texttt{\&uscore;}, \texttt{\&circum;}, \texttt{\&tlt;}, \texttt{\&tgt;}). These are no longer needed, but they are still defined for backwards
compatibility with older \textsf{GAPDoc} documents. }
\subsection{\textcolor{Chapter }{Mathematical Formulae}}\label{GDformulae}
\logpage{[ 2, 2, 2 ]}
\hyperdef{L}{X7EAE0C5A835F126F}{}
{
Mathematical formulae in \textsf{GAPDoc} are typed as in {\LaTeX}. They must be the content of one of three types of \textsf{GAPDoc} elements concerned with mathematical formulae: ``\texttt{Math}'', ``\texttt{Display}'', and ``\texttt{M}'' (see Sections{\nobreakspace}\ref{Math} and{\nobreakspace}\ref{M} for more details). The first two correspond to {\LaTeX}'s math mode and display math mode. The last one is a special form of the ``\texttt{Math}'' element type, that imposes certain restrictions on the content. On the other
hand the content of an ``\texttt{M}'' element is processed in a well defined way for text terminal or HTML output.
Note that the content of these element is {\LaTeX} code, but the special characters ``\texttt{{\textless}}'' and ``\texttt{\&}'' for XML must be entered via the entities described in{\nobreakspace}\ref{XMLspchar} or by using a \texttt{CDATA} statement, see{\nobreakspace}\ref{XMLcdata}.
}
\subsection{\textcolor{Chapter }{More Entities}}\label{GDent}
\logpage{[ 2, 2, 3 ]}
\hyperdef{L}{X7BDFF6D37FBED400}{}
{
In \textsf{GAPDoc} there are some more predefined entities: \begin{center}
\begin{tabular}{|l|l|}\hline
\texttt{\&GAP;}&
\textsf{GAP}\\
\hline
\texttt{\&GAPDoc;}&
\textsf{GAPDoc}\\
\hline
\texttt{\&TeX;}&
{\TeX}\\
\hline
\texttt{\&LaTeX;}&
{\LaTeX}\\
\hline
\texttt{\&BibTeX;}&
Bib{\TeX}\\
\hline
\texttt{\&MeatAxe;}&
\textsf{MeatAxe}\\
\hline
\texttt{\&XGAP;}&
\textsf{XGAP}\\
\hline
\texttt{\©right;}&
{\copyright}\\
\hline
\texttt{\ }&
``{\nobreakspace}''\\
\hline
\texttt{\–}&
{\textendash}\\
\hline
\end{tabular}\\[2mm]
\textbf{Table: }Predefined Entities in the \textsf{GAPDoc} system\end{center}
Here \texttt{\ } is a non-breakable space character.
Additional entities are defined for some mathematical symbols, see \ref{MathForm} for more details.
One can define further local entities right inside the head
(see{\nobreakspace}\ref{XMLhead}) of a \textsf{GAPDoc} XML document as in the following example.
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Book SYSTEM "gapdoc.dtd"
[ <!ENTITY MyEntity "some longish <E>text</E> possibly with markup">
]>
\end{Verbatim}
These additional definitions go into the \texttt{{\textless}!DOCTYPE} tag in square brackets. Such new entities are used like this: \texttt{\&MyEntity;}
}
}
}
\chapter{\textcolor{Chapter }{The Document Type Definition}}\label{DTD}
\logpage{[ 3, 0, 0 ]}
\hyperdef{L}{X7859CFF180D52D49}{}
{
In this chapter we first explain what a ``document type definition'' is and then describe \texttt{gapdoc.dtd} in detail. That file together with the current chapter define how a \textsf{GAPDoc} document has to look like. It can be found in the main directory of the \textsf{GAPDoc} package and it is reproduced in Appendix{\nobreakspace}\ref{GAPDocdtd}.
We do not give many examples in this chapter which is more intended as a
formal reference for all \textsf{GAPDoc} elements. Instead we provide 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{\nobreakspace}\ref{ch:intro}.
\section{\textcolor{Chapter }{What is a DTD?}}\logpage{[ 3, 1, 0 ]}
\hyperdef{L}{X7B76F6F786521F6B}{}
{
A document type definition (DTD) is a formal declaration of how an XML
document has to be structured. It is itself structured such that programs that
handle documents can read it and treat the documents accordingly. There are
for example parsers and validity checkers that use the DTD to validate an XML
document, see{\nobreakspace}\ref{XMLvalid}.
The main thing a DTD does is to specify which elements may occur in documents
of a certain document type, how they can be nested, and what attributes they
can or must have. So, for each element there is a rule.
Note that a DTD can \emph{not} ensure that a document which is ``valid'' also makes sense to the converters! It only says something about the formal
structure of the document.
For the remaining part of this chapter we have divided the elements of \textsf{GAPDoc} documents into several subsets, each of which will be discussed in one of the
next sections.
See the following three subsections to learn by example, how a DTD works. We
do not want to be too formal here, but just enable the reader to understand
the declarations in \texttt{gapdoc.dtd}. For precise descriptions of the syntax of DTD's see again the official
standard in:
{\nobreakspace}{\nobreakspace}\href{http://www.xml.com/axml/axml.html} {\texttt{http://www.xml.com/axml/axml.html}}
}
\section{\textcolor{Chapter }{Overall Document Structure}}\logpage{[ 3, 2, 0 ]}
\hyperdef{L}{X7DB0F9E57879CC76}{}
{
A \textsf{GAPDoc} document contains on its top level exactly one element with name \texttt{Book}. This element is declared in the DTD as follows:
\subsection{\textcolor{Chapter }{\texttt{{\textless}Book{\textgreater}}}}\logpage{[ 3, 2, 1 ]}
\hyperdef{L}{X7C7258A57B831934}{}
{
\index{Book@\texttt{Book}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Book (TitlePage,
TableOfContents?,
Body,
Appendix*,
Bibliography?,
TheIndex?)>
<!ATTLIST Book Name CDATA #REQUIRED>
\end{Verbatim}
After the keyword \texttt{ELEMENT} and the name \texttt{Book} there is a list in parentheses. This is a comma separated list of names of
elements which can occur (in the given order) in the content of a \texttt{Book} element. Each name in such a list can be followed by one of the characters ``\texttt{?}'', ``\texttt{*}'' or ``\texttt{+}'', meaning that the corresponding element can occur zero or one time, an
arbitrary number of times, or at least once, respectively. Without such an
extra character the corresponding element must occur exactly once. Instead of
one name in this list there can also be a list of elements names separated by ``\texttt{|}'' characters, this denotes any element with one of the names (i.e., ``\texttt{|}'' means ``or'').
So, the \texttt{Book} element must contain first a \texttt{TitlePage} element, then an optional \texttt{TableOfContents} element, then a \texttt{Body} element, then zero or more elements of type \texttt{Appendix}, then an optional \texttt{Bibliography} element, and finally an optional element of type \texttt{TheIndex}.
Note that \emph{only} these elements are allowed in the content of the \texttt{Book} element. No other elements or text is allowed in between. An exception of this
is that there may be whitespace between the end tag of one and the start tag
of the next element - this should be ignored when the document is processed to
some output format. An element like this is called an element with ``element content''.
The second declaration starts with the keyword \texttt{ATTLIST} and the element name \texttt{Book}. After that there is a triple of whitespace separated parameters (in general
an arbitrary number of such triples, one for each allowed attribute name). The
first (\texttt{Name}) is the name of an attribute for a \texttt{Book} element. The second (\texttt{CDATA}) is always the same for all of our declarations, it means that the value of
the attribute consists of ``character data''. The third parameter \texttt{\#REQUIRED} means that this attribute must be specified with any \texttt{Book} element. Later we will also see optional attributes which are declared as \texttt{\#IMPLIED}. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}TitlePage{\textgreater}}}}\logpage{[ 3, 2, 2 ]}
\hyperdef{L}{X842B421A7FBCDD2C}{}
{
\index{TitlePage@\texttt{TitlePage}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT TitlePage (Title, Subtitle?, Version?, TitleComment?,
Author+, Date?, Address?, Abstract?, Copyright?,
Acknowledgements? , Colophon? )>
\end{Verbatim}
Within this element information for the title page is collected. Note that
more than one author can be specified. The elements must appear in this order
because there is no sensible way to specify in a DTD something like ``the following elements may occur in any order but each exactly once''.
Before going on with the other elements inside the \texttt{Book} element we explain the elements for the title page. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Title{\textgreater}}}}\label{Title}
\logpage{[ 3, 2, 3 ]}
\hyperdef{L}{X7BCC8E6F79021294}{}
{
\index{Title@\texttt{Title}} \label{Text}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Title (%Text;)*>
\end{Verbatim}
Here is the last construct you need to understand for reading \texttt{gapdoc.dtd}. The expression ``\texttt{\%Text;}'' is a so-called ``parameter entity''. It is something like a macro within the DTD. It is defined as follows: \label{InnerText}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ENTITY % Text "%InnerText; | List | Enum | Table">
\end{Verbatim}
This means, that every occurrence of ``\texttt{\%Text;}'' in the DTD is replaced by the expression \label{Innertext}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
%InnerText; | List | Enum | Table
\end{Verbatim}
which is then expanded further because of the following definition:
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ENTITY % InnerText "#PCDATA |
Alt |
Emph | E |
Par | P | Br |
Keyword | K | Arg | A | Quoted | Q | Code | C |
File | F | Button | B | Package |
M | Math | Display |
Example | Listing | Log | Verb |
URL | Email | Homepage | Address | Cite | Label |
Ref | Index" >
\end{Verbatim}
These are the only two parameter entities we are using. They expand to lists
of element names which are explained in the sequel \emph{and} the keyword \texttt{\#PCDATA} (concatenated with the ``or'' character ``\texttt{|}'').
So, the element (\texttt{Title}) is of so-called ``mixed content'': It can contain \emph{parsed character data} which does not contain further markup (\texttt{\#PCDATA}) or any of the other above mentioned elements. Mixed content must always have
the asterisk qualifier (like in \texttt{Title}) such that any sequence of elements (of the above list) and character data
can be contained in a \texttt{Title} element.
The \texttt{\%Text;} parameter entity is used in all places in the DTD, where ``normal text'' should be allowed, including lists, enumerations, and tables, but \emph{no} sectioning elements.
The \texttt{\%InnerText;} parameter entity is used in all places in the DTD, where ``inner text'' should be allowed. This means, that no structures like lists, enumerations,
and tables are allowed. This is used for example in headings.
}
\subsection{\textcolor{Chapter }{\texttt{{\textless}Subtitle{\textgreater}}}}\logpage{[ 3, 2, 4 ]}
\hyperdef{L}{X82E82AF48217CC14}{}
{
\index{Subtitle@\texttt{Subtitle}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Subtitle (%Text;)*>
\end{Verbatim}
Contains the subtitle of the document. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Version{\textgreater}}}}\label{Version}
\logpage{[ 3, 2, 5 ]}
\hyperdef{L}{X876962807DCC52B3}{}
{
\index{Version@\texttt{Version}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Version (#PCDATA|Alt)*>
\end{Verbatim}
Note that the version can only contain character data and no further markup
elements (except for \texttt{Alt}, which is necessary to resolve the entities described in \ref{GDent}). The converters will \emph{not} put the word ``Version'' in front of the text in this element. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}TitleComment{\textgreater}}}}\logpage{[ 3, 2, 6 ]}
\hyperdef{L}{X87E7CD5B79230B90}{}
{
\index{TitleComment@\texttt{TitleComment}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT TitleComment (%Text;)*>
\end{Verbatim}
Sometimes a title and subtitle are not sufficient to give a rough idea about
the content of a package. In this case use this optional element to specify an
additional text for the front page of the book. This text should be short, use
the \texttt{Abstract} element (see{\nobreakspace}\ref{elAbstract}) for longer explanations. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Author{\textgreater}}}}\logpage{[ 3, 2, 7 ]}
\hyperdef{L}{X8731459C7E4C56DA}{}
{
\index{Author@\texttt{Author}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Author (%Text;)*> <!-- There may be more than one Author! -->
\end{Verbatim}
As noted in the comment there may be more than one element of this type. This
element should contain the name of an author and probably an \texttt{Email}-address and/or WWW-\texttt{Homepage} element for this author, see{\nobreakspace}\ref{elEmail} and{\nobreakspace}\ref{elHomepage}. You can also specify an individual postal address here, instead of using the \texttt{Address} element described below, see{\nobreakspace}\ref{elAddress}. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Date{\textgreater}}}}\logpage{[ 3, 2, 8 ]}
\hyperdef{L}{X8264A69D7DCDD773}{}
{
\index{Date@\texttt{Date}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Date (#PCDATA)>
\end{Verbatim}
Only character data is allowed in this element which gives a date for the
document. No automatic formatting is done. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Address{\textgreater}}}}\label{elAddress}
\logpage{[ 3, 2, 9 ]}
\hyperdef{L}{X7EEF65A07A094F65}{}
{
\index{Date@\texttt{Address}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Address (#PCDATA|Alt|Br)*>
\end{Verbatim}
This optional element can be used to specify a postal address of the author or
the authors. If there are several authors with different addresses then put
the \texttt{Address} elements inside the \texttt{Author} elements.
Use the \texttt{Br} element (see{\nobreakspace}\ref{Br}) to mark the line breaks in the usual formatting of the address on a letter.
Note that often it is not necessary to use this element because a postal
address is easy to find via a link to a personal web page. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Abstract{\textgreater}}}}\label{elAbstract}
\logpage{[ 3, 2, 10 ]}
\hyperdef{L}{X833110FE79628313}{}
{
\index{Abstract@\texttt{Abstract}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Abstract (%Text;)*>
\end{Verbatim}
This element contains an abstract of the whole book. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Copyright{\textgreater}}}}\logpage{[ 3, 2, 11 ]}
\hyperdef{L}{X84BBD8307E08E62F}{}
{
\index{Copyright@\texttt{Copyright}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Copyright (%Text;)*>
\end{Verbatim}
This element is used for the copyright notice. Note the \texttt{\©right;} entity as described in section \ref{GDent}. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Acknowledgements{\textgreater}}}}\logpage{[ 3, 2, 12 ]}
\hyperdef{L}{X8143972D7C17838E}{}
{
\index{Acknowledgements@\texttt{Acknowledgements}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Acknowledgements (%Text;)*>
\end{Verbatim}
This element contains the acknowledgements. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Colophon{\textgreater}}}}\logpage{[ 3, 2, 13 ]}
\hyperdef{L}{X7C09A3398059D18C}{}
{
\index{Colophon@\texttt{Colophon}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Colophon (%Text;)*>
\end{Verbatim}
The ``colophon'' page is used to say something about the history of a document. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}TableOfContents{\textgreater}}}}\logpage{[ 3, 2, 14 ]}
\hyperdef{L}{X7E97263A83DC26E9}{}
{
\index{TableOfContents@\texttt{TableOfContents}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT TableOfContents EMPTY>
\end{Verbatim}
This element may occur in the \texttt{Book} element after the \texttt{TitlePage} element. If it is present, a table of contents is generated and inserted into
the document. Note that because this element is declared to be \texttt{EMPTY} one can use the abbreviation
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
<TableOfContents/>
\end{Verbatim}
to denote this empty element. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Bibliography{\textgreater}} }}\label{Bibliography}
\logpage{[ 3, 2, 15 ]}
\hyperdef{L}{X84F3DF21786A8751}{}
{
\index{Bibliography@\texttt{Bibliography}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Bibliography EMPTY>
<!ATTLIST Bibliography Databases CDATA #REQUIRED
Style CDATA #IMPLIED>
\end{Verbatim}
This element may occur in the \texttt{Book} element after the last \texttt{Appendix} element. If it is present, a bibliography section is generated and inserted
into the document. The attribute \texttt{Databases} must be specified, the names of several data files can be specified, separated
by commas.
Two kinds of files can be specified in \texttt{Databases}: The first are Bib{\TeX} files as defined in{\nobreakspace}\cite[Appendix B]{La85}. Such files must have a name with extension \texttt{.bib}, and in \texttt{Databases} the name must be given \emph{without} this extension. The second are files in BibXMLext format as defined in
Section{\nobreakspace}\ref{BibXMLformat}. These files must have an extension \texttt{.xml} and in \texttt{Databases} the \emph{full} name must be specified.
We suggest to use the BibXMLext format because it allows to produce
potentially nicer bibliography entries in text and HTML documents.
A bibliography style may be specified with the \texttt{Style} attribute. The optional \texttt{Style} attribute (for {\LaTeX} output of the document) must also be specified without the \texttt{.bst} extension (the default is \texttt{alpha}). See also section \ref{Cite} for a description of the \texttt{Cite} element which is used to include bibliography references into the text.
}
\subsection{\textcolor{Chapter }{\texttt{{\textless}TheIndex{\textgreater}}}}\label{TheIndex}
\logpage{[ 3, 2, 16 ]}
\hyperdef{L}{X7C53615A8477F1E5}{}
{
\index{TheIndex@\texttt{TheIndex}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT TheIndex EMPTY>
\end{Verbatim}
This element may occur in the \texttt{Book} element after the \texttt{Bibliography} element. If it is present, an index is generated and inserted into the
document. There are elements in \textsf{GAPDoc} which implicitly generate index entries (e.g., \texttt{Func} (\ref{Func})) and there is an element \texttt{Index} (\ref{Index}) for explicitly adding index entries. }
}
\section{\textcolor{Chapter }{Sectioning Elements}}\logpage{[ 3, 3, 0 ]}
\hyperdef{L}{X80E2AD7481DD69D9}{}
{
A \textsf{GAPDoc} book is divided into \emph{chapters}, \emph{sections}, and \emph{subsections}. The idea is of course, that a chapter consists of sections, which in turn
consist of subsections. However for the sake of flexibility, the rules are not
too restrictive. Firstly, text is allowed everywhere in the body of the
document (and not only within sections). Secondly, the chapter level may be
omitted. The exact rules are described below.
\emph{Appendices} are a flavor of chapters, occurring after all regular chapters. There is a
special type of subsection called ``\texttt{ManSection}''. This is a subsection devoted to the description of a function, operation or
variable. It is analogous to a manpage in the UNIX environment. Usually each
function, operation, method, and so on should have its own \texttt{ManSection}.
Cross referencing is done on the level of \texttt{Subsection}s, respectively \texttt{ManSection}s. The topics in \textsf{GAP}'s online help are also pointing to subsections. So, they should not be too
long.
We start our description of the sectioning elements ``top-down'':
\subsection{\textcolor{Chapter }{\texttt{{\textless}Body{\textgreater}}}}\logpage{[ 3, 3, 1 ]}
\hyperdef{L}{X7B38415687510D0A}{}
{
\index{Body@\texttt{Body}} The \texttt{Body} element marks the main part of the document. It must occur after the \texttt{TableOfContents} element. There is a big difference between \emph{inside} and \emph{outside} of this element: Whereas regular text is allowed nearly everywhere in the \texttt{Body} element and its subelements, this is not true for the \emph{outside}. This has also implications on the handling of whitespace. \emph{Outside} superfluous whitespace is usually ignored when it occurs between elements. \emph{Inside} of the \texttt{Body} element whitespace matters because character data is allowed nearly
everywhere. Here is the definition in the DTD:
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Body ( %Text;| Chapter | Section )*>
\end{Verbatim}
The fact that \texttt{Chapter} and \texttt{Section} elements are allowed here leads to the possibility to omit the chapter level
entirely in the document. For a description of \texttt{\%Text;} see \ref{Text}.
(Remark: The purpose of this element is to make sure that a \emph{valid} \textsf{GAPDoc} document has a correct overall structure, which is only possible when the top
element \texttt{Book} has element content.) }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Chapter{\textgreater}}}}\label{Chapter}
\logpage{[ 3, 3, 2 ]}
\hyperdef{L}{X7A86B2BA7D688B6B}{}
{
\index{Chapter@\texttt{Chapter}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Chapter (%Text;| Heading | Section)*>
<!ATTLIST Chapter Label CDATA #IMPLIED> <!-- For reference purposes -->
\end{Verbatim}
A \texttt{Chapter} element can have a \texttt{Label} attribute, such that this chapter can be referenced later on with a \texttt{Ref} element (see section \ref{Ref}). Note that you have to specify a label to reference the chapter as there is
no automatic labelling!
\texttt{Chapter} elements can contain text (for a description of \texttt{\%Text;} see \ref{Text}), \texttt{Section} elements, and \texttt{Heading} elements.
The following \emph{additional} rule cannot be stated in the DTD because we want a \texttt{Chapter} element to have mixed content. There must be \emph{exactly one} \texttt{Heading} element in the \texttt{Chapter} element, containing the heading of the chapter. Here is its definition: }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Heading{\textgreater}}}}\label{Heading}
\logpage{[ 3, 3, 3 ]}
\hyperdef{L}{X79825E1C821D0B79}{}
{
\index{Heading@\texttt{Heading}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Heading (%InnerText;)*>
\end{Verbatim}
This element is used for headings in \texttt{Chapter}, \texttt{Section}, \texttt{Subsection}, and \texttt{Appendix} elements. It may only contain \texttt{\%InnerText;} (for a description see \ref{InnerText}).
Each of the mentioned sectioning elements must contain exactly one direct \texttt{Heading} element (i.e., one which is not contained in another sectioning element). }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Appendix{\textgreater}}}}\logpage{[ 3, 3, 4 ]}
\hyperdef{L}{X7C701B2779767556}{}
{
\index{Appendix@\texttt{Appendix}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Appendix (%Text;| Heading | Section)*>
<!ATTLIST Appendix Label CDATA #IMPLIED> <!-- For reference purposes -->
\end{Verbatim}
The \texttt{Appendix} element behaves exactly like a \texttt{Chapter} element (see \ref{Chapter}) except for the position within the document and the numbering. While
chapters are counted with numbers (1., 2., 3., ...) the appendices are counted
with capital letters (A., B., ...).
Again there is an optional \texttt{Label} attribute used for references. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Section{\textgreater}}}}\logpage{[ 3, 3, 5 ]}
\hyperdef{L}{X844DC2B47FB37339}{}
{
\index{Section@\texttt{Section}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Section (%Text;| Heading | Subsection | ManSection)*>
<!ATTLIST Section Label CDATA #IMPLIED> <!-- For reference purposes -->
\end{Verbatim}
A \texttt{Section} element can have a \texttt{Label} attribute, such that this section can be referenced later on with a \texttt{Ref} element (see section \ref{Ref}). Note that you have to specify a label to reference the section as there is
no automatic labelling!
\texttt{Section} elements can contain text (for a description of \texttt{\%Text;} see \ref{Text}), \texttt{Heading} elements, and subsections.
There must be exactly one direct \texttt{Heading} element in a \texttt{Section} element, containing the heading of the section.
Note that a subsection is either a \texttt{Subsection} element or a \texttt{ManSection} element. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Subsection{\textgreater}}}}\logpage{[ 3, 3, 6 ]}
\hyperdef{L}{X803ACA187E292969}{}
{
\index{Subsection@\texttt{Subsection}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Subsection (%Text;| Heading)*>
<!ATTLIST Subsection Label CDATA #IMPLIED> <!-- For reference purposes -->
\end{Verbatim}
The \texttt{Subsection} element can have a \texttt{Label} attribute, such that this subsection can be referenced later on with a \texttt{Ref} element (see section \ref{Ref}). Note that you have to specify a label to reference the subsection as there
is no automatic labelling!
\texttt{Subsection} elements can contain text (for a description of \texttt{\%Text;} see \ref{Text}), and \texttt{Heading} elements.
There must be exactly one \texttt{Heading} element in a \texttt{Subsection} element, containing the heading of the subsection.
Another type of subsection is a \texttt{ManSection}, explained now: }
}
\section{\textcolor{Chapter }{ManSection{\textendash}a special kind of subsection}}\label{sec:mansect}
\logpage{[ 3, 4, 0 ]}
\hyperdef{L}{X877B8B7C7EDD09E9}{}
{
\texttt{ManSection}s are intended to describe a function, operation, method, variable, or some
other technical instance. It is analogous to a manpage in the UNIX
environment.
\subsection{\textcolor{Chapter }{\texttt{{\textless}ManSection{\textgreater}}}}\logpage{[ 3, 4, 1 ]}
\hyperdef{L}{X8375D9CC8672A1D5}{}
{
\index{ManSection@\texttt{ManSection}} \index{Description@\texttt{Description}} \index{Returns@\texttt{Returns}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT ManSection ( Heading?,
((Func, Returns?) | (Oper, Returns?) |
(Meth, Returns?) | (Filt, Returns?) |
(Prop, Returns?) | (Attr, Returns?) |
Var | Fam | InfoClass)+, Description )>
<!ATTLIST ManSection Label CDATA #IMPLIED> <!-- For reference purposes -->
<!ELEMENT Returns (%Text;)*>
<!ELEMENT Description (%Text;)*>
\end{Verbatim}
The \texttt{ManSection} element can have a \texttt{Label} attribute, such that this subsection can be referenced later on with a \texttt{Ref} element (see section \ref{Ref}). But this is probably rarely necessary because the elements \texttt{Func} and so on (explained below) generate automatically labels for cross
referencing.
The content of a \texttt{ManSection} element is one or more elements describing certain items in \textsf{GAP}, each of them optionally followed by a \texttt{Returns} element, followed by a \texttt{Description} element, which contains \texttt{\%Text;} (see \ref{Text}) describing it. (Remember to include examples in the description as often as
possible, see{\nobreakspace}\ref{Log}). The classes of items \textsf{GAPDoc} knows of are: functions (\texttt{Func}), operations (\texttt{Oper}), methods (\texttt{Meth}), filters (\texttt{Filt}), properties (\texttt{Prop}), attributes (\texttt{Attr}), variables (\texttt{Var}), families (\texttt{Fam}), and info classes (\texttt{InfoClass}). One \texttt{ManSection} should only describe several of such items when these are very closely
related.
Each element for an item corresponding to a \textsf{GAP} function can be followed by a \texttt{Returns} element. In output versions of the document the string ``Returns: '' will be put in front of the content text. The text in the \texttt{Returns} element should usually be a short hint about the type of object returned by
the function. This is intended to give a good mnemonic for the use of a
function (together with a good choice of names for the formal arguments).
\texttt{ManSection}s are also sectioning elements which count as subsections. Usually there
should be no \texttt{Heading}-element in a \texttt{ManSection}, in that case a heading is generated automatically from the first \texttt{Func}-like element. Sometimes this default behaviour does not look appropriate, for
example when there are several \texttt{Func}-like elements. For such cases an optional \texttt{Heading} is allowed. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Func{\textgreater}}}}\label{Func}
\logpage{[ 3, 4, 2 ]}
\hyperdef{L}{X7C41A7B5845205C4}{}
{
\index{Func@\texttt{Func}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Func EMPTY>
<!ATTLIST Func Name CDATA #REQUIRED
Label CDATA #IMPLIED
Arg CDATA #REQUIRED
Comm CDATA #IMPLIED>
\end{Verbatim}
This element is used within a \texttt{ManSection} element to specify the usage of a function. The \texttt{Name} attribute is required and its value is the name of the function. The value of
the \texttt{Arg} attribute (also required) contains the full list of arguments including
optional parts, which are denoted by square brackets. The argument names can
be separated by whitespace, commas or the square brackets for the optional
arguments, like \texttt{"grp[,{\nobreakspace}elm]"} or \texttt{"xx[y[z]{\nobreakspace}]"}.
The name of the function is also used as label for cross referencing. When the
name of the function appears in the text of the document it should \emph{always} be written with the \texttt{Ref} element, see{\nobreakspace}\ref{Ref}. This allows to use a unique typesetting style for function names and
automatic cross referencing.
If the optional \texttt{Label} attribute is given, it is appended (with a colon \texttt{:} in between) to the name of the function for cross referencing purposes. The
text of the label can also appear in the document text. So, it should be a
kind of short explanation.
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
<Func Arg="x[, y]" Name="LibFunc" Label="for my objects"/>
\end{Verbatim}
The optional \texttt{Comm} attribute should be a short description of the function, usually at most one
line long (this is currently nowhere used).
This element automatically produces an index entry with the name of the
function and, if present, the text of the \texttt{Label} attribute as subentry (see also{\nobreakspace}\ref{TheIndex} and{\nobreakspace}\ref{Index}). }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Oper{\textgreater}}}}\logpage{[ 3, 4, 3 ]}
\hyperdef{L}{X7A15825E818A81CD}{}
{
\index{Oper@\texttt{Oper}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Oper EMPTY>
<!ATTLIST Oper Name CDATA #REQUIRED
Label CDATA #IMPLIED
Arg CDATA #REQUIRED
Comm CDATA #IMPLIED>
\end{Verbatim}
This element is used within a \texttt{ManSection} element to specify the usage of an operation. The attributes are used exactly
in the same way as in the \texttt{Func} element (see \ref{Func}).
Note that multiple descriptions of the same operation may occur in a document
because there may be several declarations in \textsf{GAP}. Furthermore there may be several \texttt{ManSection}s for methods of this operation (see{\nobreakspace}\ref{Meth}) which also use the same name. For reference purposes these must be
distinguished by different \texttt{Label} attributes. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Meth{\textgreater}}}}\label{Meth}
\logpage{[ 3, 4, 4 ]}
\hyperdef{L}{X81196E2B7F286A01}{}
{
\index{Meth@\texttt{Meth}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Meth EMPTY>
<!ATTLIST Meth Name CDATA #REQUIRED
Label CDATA #IMPLIED
Arg CDATA #REQUIRED
Comm CDATA #IMPLIED>
\end{Verbatim}
This element is used within a \texttt{ManSection} element to specify the usage of a method. The attributes are used exactly in
the same way as in the \texttt{Func} element (see \ref{Func}).
Frequently, an operation is implemented by several different methods.
Therefore it seems to be interesting to document them independently. This is
possible by using the same method name in different \texttt{ManSection}s. It is however required that these subsections and those describing the
corresponding operation are distinguished by different \texttt{Label} attributes. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Filt{\textgreater}}}}\logpage{[ 3, 4, 5 ]}
\hyperdef{L}{X7D8D2C38828D5854}{}
{
\index{Filt@\texttt{Filt}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Filt EMPTY>
<!ATTLIST Filt Name CDATA #REQUIRED
Label CDATA #IMPLIED
Arg CDATA #IMPLIED
Comm CDATA #IMPLIED
Type CDATA #IMPLIED>
\end{Verbatim}
This element is used within a \texttt{ManSection} element to specify the usage of a filter. The first four attributes are used
in the same way as in the \texttt{Func} element (see \ref{Func}), except that the \texttt{Arg} attribute is optional.
The \texttt{Type} attribute can be any string, but it is thought to be something like ``\texttt{Category}'' or ``\texttt{Representation}''. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Prop{\textgreater}}}}\logpage{[ 3, 4, 6 ]}
\hyperdef{L}{X7D6400A67C30B752}{}
{
\index{Prop@\texttt{Prop}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Prop EMPTY>
<!ATTLIST Prop Name CDATA #REQUIRED
Label CDATA #IMPLIED
Arg CDATA #REQUIRED
Comm CDATA #IMPLIED>
\end{Verbatim}
This element is used within a \texttt{ManSection} element to specify the usage of a property. The attributes are used exactly in
the same way as in the \texttt{Func} element (see \ref{Func}).
}
\subsection{\textcolor{Chapter }{\texttt{{\textless}Attr{\textgreater}}}}\logpage{[ 3, 4, 7 ]}
\hyperdef{L}{X78CEEC5986987A97}{}
{
\index{Attr@\texttt{Attr}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Attr EMPTY>
<!ATTLIST Attr Name CDATA #REQUIRED
Label CDATA #IMPLIED
Arg CDATA #REQUIRED
Comm CDATA #IMPLIED>
\end{Verbatim}
This element is used within a \texttt{ManSection} element to specify the usage of an attribute (in \textsf{GAP}). The attributes are used exactly in the same way as in the \texttt{Func} element (see \ref{Func}).
}
\subsection{\textcolor{Chapter }{\texttt{{\textless}Var{\textgreater}}}}\logpage{[ 3, 4, 8 ]}
\hyperdef{L}{X7C3AACBE7BC6AABF}{}
{
\index{Var@\texttt{Var}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Var EMPTY>
<!ATTLIST Var Name CDATA #REQUIRED
Label CDATA #IMPLIED
Comm CDATA #IMPLIED>
\end{Verbatim}
This element is used within a \texttt{ManSection} element to document a global variable. The attributes are used exactly in the
same way as in the \texttt{Func} element (see \ref{Func}) except that there is no \texttt{Arg} attribute.
}
\subsection{\textcolor{Chapter }{\texttt{{\textless}Fam{\textgreater}}}}\logpage{[ 3, 4, 9 ]}
\hyperdef{L}{X85EE992E7FED2FE6}{}
{
\index{Fam@\texttt{Fam}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Fam EMPTY>
<!ATTLIST Fam Name CDATA #REQUIRED
Label CDATA #IMPLIED
Comm CDATA #IMPLIED>
\end{Verbatim}
This element is used within a \texttt{ManSection} element to document a family. The attributes are used exactly in the same way
as in the \texttt{Func} element (see \ref{Func}) except that there is no \texttt{Arg} attribute.
}
\subsection{\textcolor{Chapter }{\texttt{{\textless}InfoClass{\textgreater}}}}\logpage{[ 3, 4, 10 ]}
\hyperdef{L}{X78F0D4D1811E5BAE}{}
{
\index{InfoClass@\texttt{InfoClass}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT InfoClass EMPTY>
<!ATTLIST InfoClass Name CDATA #REQUIRED
Label CDATA #IMPLIED
Comm CDATA #IMPLIED>
\end{Verbatim}
This element is used within a \texttt{ManSection} element to document an info class. The attributes are used exactly in the same
way as in the \texttt{Func} element (see \ref{Func}) except that there is no \texttt{Arg} attribute.
}
}
\section{\textcolor{Chapter }{Cross Referencing and Citations}}\logpage{[ 3, 5, 0 ]}
\hyperdef{L}{X78595FB585569617}{}
{
Cross referencing in the \textsf{GAPDoc} system is somewhat different to the usual {\LaTeX} cross referencing in so far, that a reference knows ``which type of object'' it is referencing. For example a ``reference to a function'' is distinguished from a ``reference to a chapter''. The idea of this is, that the markup must contain this information such that
the converters can produce better output. The HTML converter can for example
typeset a function reference just as the name of the function with a link to
the description of the function, or a chapter reference as a number with a
link in the other case.
Referencing is done with the \texttt{Ref} element:
\subsection{\textcolor{Chapter }{\texttt{{\textless}Ref{\textgreater}}}}\label{Ref}
\logpage{[ 3, 5, 1 ]}
\hyperdef{L}{X8656F2338007406E}{}
{
\index{Ref@\texttt{Ref}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Ref EMPTY>
<!ATTLIST Ref Func CDATA #IMPLIED
Oper CDATA #IMPLIED
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}).
An external reference into another book can be specified by using the \texttt{BookName} attribute. In this case the \texttt{Label} attribute or, if this is not given, the function or section like attribute, is
used to resolve the reference. The generated reference points to the first hit
when asking ``?book name: label'' inside \textsf{GAP}.
The optional attribute \texttt{Style} can take only the values \texttt{Text} and \texttt{Number}. It can be used with references to sectioning units and it gives a hint to
the converter programs, whether an explicit section number is generated or
text. Normally all references to sections generate numbers and references to a \textsf{GAP} object generate the name of the corresponding object with some additional link
or sectioning information, which is the behavior of \texttt{Style="Text"}. In case \texttt{Style="Number"} in all cases an explicit section number is generated. So
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
<Ref Subsect="Func" Style="Text"/> described in section
<Ref Subsect="Func" Style="Number"/>
\end{Verbatim}
produces: `\texttt{{\textless}Func{\textgreater}}' described in section \ref{Func}. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Label{\textgreater}}}}\label{Label}
\logpage{[ 3, 5, 2 ]}
\hyperdef{L}{X7C85CA5484344DB5}{}
{
\index{Label@\texttt{Label}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Label EMPTY>
<!ATTLIST Label Name CDATA #REQUIRED>
\end{Verbatim}
This element is used to define a label for referencing a certain position in
the document, if this is possible. If an exact reference is not possible (like
in a printed version of the document) a reference to the corresponding
subsection is generated. The value of the \texttt{Name} attribute must be unique under all \texttt{Label} elements. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Cite{\textgreater}}}}\label{Cite}
\logpage{[ 3, 5, 3 ]}
\hyperdef{L}{X851DE9D279D8FB04}{}
{
\index{Cite@\texttt{Cite}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Cite EMPTY>
<!ATTLIST Cite Key CDATA #REQUIRED
Where CDATA #IMPLIED>
\end{Verbatim}
This element is for bibliography citations. It is \texttt{EMPTY} by definition. The attribute \texttt{Key} is the key for a lookup in a Bib{\TeX} database that has to be specified in the \texttt{Bibliography} element (see \ref{Bibliography}). The value of the \texttt{Where} attribute specifies the position in the document as in the corresponding {\LaTeX} syntax \texttt{\texttt{\symbol{92}}cite[Where value]\texttt{\symbol{123}}Key
value\texttt{\symbol{125}}}. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Index{\textgreater}}}}\label{Index}
\logpage{[ 3, 5, 4 ]}
\hyperdef{L}{X811042BA78843777}{}
{
\index{Index@\texttt{Index}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Index (%InnerText;|Subkey)*>
<!ATTLIST Index Key CDATA #IMPLIED
Subkey CDATA #IMPLIED>
<!ELEMENT Subkey (%InnerText;)*>
\end{Verbatim}
This element generates an index entry. The 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.
A subkey can be specified in the simpler version as an attribute, but then no
further markup can be used for the subkey. Optionally, the subkey text can be
given in a \texttt{Subkey} element, in this case the attribute value is used for sorting but the typeset
text is taken from the content of \texttt{Subkey}.
Note that all \texttt{Func} and similar elements automatically generate index entries. If the \texttt{TheIndex} element (\ref{TheIndex}) is not present in the document all \texttt{Index} elements are ignored. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}URL{\textgreater}}}}\label{URL}
\logpage{[ 3, 5, 5 ]}
\hyperdef{L}{X81B3E46F839E1C5B}{}
{
\index{URL@\texttt{URL}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT URL (#PCDATA|Alt|Link|LinkText)*> <!-- Link, LinkText
variant for case where text needs further markup -->
<!ATTLIST URL Text CDATA #IMPLIED> <!-- This is for output formats
that have links like HTML -->
<!ELEMENT Link (%InnerText;)*> <!-- the URL -->
<!ELEMENT LinkText (%InnerText;)*> <!-- text for links, can contain markup -->
\end{Verbatim}
This element is for references into the internet. It specifies an URL and
optionally a text which can be used for a link (like in HTML or PDF versions
of the document). This can be specified in two ways: Either the URL is given
as element content and the text is given in the optional \texttt{Text} attribute (in this case the text cannot contain further markup), or the
element contains the two elements \texttt{Link} and \texttt{LinkText} which in turn contain the URL and the text, respectively. The default value
for the text is the URL itself. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Email{\textgreater}}}}\label{elEmail}
\logpage{[ 3, 5, 6 ]}
\hyperdef{L}{X8310C4F084CD9DB9}{}
{
\index{Email@\texttt{Email}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Email (#PCDATA|Alt|Link|LinkText)*>
\end{Verbatim}
This element type is the special case of an URL specifying an email address.
The content of the element should be the email address without any prefix like ``\texttt{mailto:}''. This address is typeset by all converters, also without any prefix. In the
case of an output document format like HTML the converter can produce a link
with a ``\texttt{mailto:}'' prefix. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Homepage{\textgreater}}}}\label{elHomepage}
\logpage{[ 3, 5, 7 ]}
\hyperdef{L}{X7D5CC4267D04D7E7}{}
{
\index{Homepage@\texttt{Homepage}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Homepage (#PCDATA|Alt|Link|LinkText)*>
\end{Verbatim}
This element type is the special case of an URL specifying a WWW-homepage. }
}
\section{\textcolor{Chapter }{Structural Elements like Lists}}\logpage{[ 3, 6, 0 ]}
\hyperdef{L}{X840099DF83823686}{}
{
The \textsf{GAPDoc} system offers some limited access to structural elements like lists,
enumerations, and tables. Although it is possible to use all {\LaTeX} constructs one always has to think about other output formats. The elements in
this section are guaranteed to produce something reasonable in all output
formats.
\subsection{\textcolor{Chapter }{\texttt{{\textless}List{\textgreater}}}}\label{List}
\logpage{[ 3, 6, 1 ]}
\hyperdef{L}{X785183F67DA402A0}{}
{
\index{List@\texttt{List}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT List ( ((Mark,Item)|(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 ]}
\hyperdef{L}{X7B1545A9797442DC}{}
{
\index{Mark@\texttt{Mark}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Mark ( %InnerText;)*>
\end{Verbatim}
This element is used in the \texttt{List} element to mark items. See \ref{List} for an explanation. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Item{\textgreater}}}}\label{Item}
\logpage{[ 3, 6, 3 ]}
\hyperdef{L}{X86C204987AB4B13D}{}
{
\index{Item@\texttt{Item}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Item ( %Text;)*>
\end{Verbatim}
This element is used in the \texttt{List}, \texttt{Enum}, and \texttt{Table} elements to specify the items. See sections \ref{List}, \ref{Enum}, and \ref{Table} for further information. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Enum{\textgreater}}}}\label{Enum}
\logpage{[ 3, 6, 4 ]}
\hyperdef{L}{X78A52B00846562DE}{}
{
\index{Enum@\texttt{Enum}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Enum ( Item+ )>
<!ATTLIST Enum Only CDATA #IMPLIED
Not CDATA #IMPLIED>
\end{Verbatim}
This element is used like the \texttt{List} element (see \ref{List}) except that the items must not have marks attached to them. Instead, the
items are numbered automatically. The same comments about the \texttt{Only} and \texttt{Not} attributes as above apply. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Table{\textgreater}}}}\label{Table}
\logpage{[ 3, 6, 5 ]}
\hyperdef{L}{X7F9CAA577EB4070B}{}
{
\index{Table@\texttt{Table}} \index{Caption@\texttt{{\textless}Caption{\textgreater}}} \index{Row@\texttt{{\textless}Row{\textgreater}}} \index{Align@\texttt{{\textless}Align{\textgreater}}} \index{HorLine@\texttt{{\textless}HorLine{\textgreater}}} \index{Item in Table@\texttt{{\textless}Item{\textgreater}} in \texttt{{\textless}Table{\textgreater}}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Table ( Caption?, (Row | HorLine)+ )>
<!ATTLIST Table Label CDATA #IMPLIED
Only CDATA #IMPLIED
Not CDATA #IMPLIED
Align CDATA #REQUIRED>
<!-- We allow | and l,c,r, nothing else -->
<!ELEMENT Row ( Item+ )>
<!ELEMENT HorLine EMPTY>
<!ELEMENT Caption ( %InnerText;)*>
\end{Verbatim}
A table in \textsf{GAPDoc} consists of an optional \texttt{Caption} element followed by a sequence of \texttt{Row} and \texttt{HorLine} elements. A \texttt{HorLine} element produces a horizontal line in the table. A \texttt{Row} element consists of a sequence of \texttt{Item} elements as they also occur in \texttt{List} and \texttt{Enum} elements. The \texttt{Only} and \texttt{Not} attributes have the same functionality as described in the \texttt{List} element in \ref{List}.
The \texttt{Align} attribute is written like a {\LaTeX} tabular alignment specifier but only the letters ``\texttt{l}'', ``\texttt{r}'', ``\texttt{c}'', and ``\texttt{|}'' are allowed meaning left alignment, right alignment, centered alignment, and a
vertical line as delimiter between columns respectively.
If the \texttt{Label} attribute is there, one can reference the table with the \texttt{Ref} element (see \ref{Ref}) using its \texttt{Label} attribute.
Usually only simple tables should be used. If you want a complicated table in
the {\LaTeX} output you should provide alternatives for text and HTML output. Note that in
HTML-4.0 there is no possibility to interpret the ``\texttt{|}'' column separators and \texttt{HorLine} elements as intended. There are lines between all columns and rows or no lines
at all. }
}
\section{\textcolor{Chapter }{Types of Text}}\logpage{[ 3, 7, 0 ]}
\hyperdef{L}{X7CA1E1327AFBA578}{}
{
This section covers the markup of text. Various types of ``text'' exist. The following elements are used in the \textsf{GAPDoc} system to mark them. They mostly come in pairs, one long name which is easier
to remember and a shortcut to make the markup ``lighter''.
Most of the following elements are thought to contain only character data and
no further markup elements. It is however necessary to allow \texttt{Alt} elements to resolve the entities described in section \ref{GDent}.
\subsection{\textcolor{Chapter }{\texttt{{\textless}Emph{\textgreater}} and \texttt{{\textless}E{\textgreater}}}}\logpage{[ 3, 7, 1 ]}
\hyperdef{L}{X7B15C428861749FD}{}
{
\index{Emph@\texttt{Emph}} \index{E@\texttt{E}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Emph (%InnerText;)*> <!-- Emphasize something -->
<!ELEMENT E (%InnerText;)*> <!-- the same as shortcut -->
\end{Verbatim}
This element is used to emphasize some piece of text. It may contain \texttt{\%InnerText;} (see \ref{InnerText}). }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Quoted{\textgreater}} and \texttt{{\textless}Q{\textgreater}}}}\logpage{[ 3, 7, 2 ]}
\hyperdef{L}{X80028C2483C9467E}{}
{
\index{Quoted@\texttt{Quoted}} \index{Q@\texttt{Q}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Quoted (%InnerText;)*> <!-- Quoted (in quotes) text -->
<!ELEMENT Q (%InnerText;)*> <!-- Quoted text (shortcut) -->
\end{Verbatim}
This element is used to put some piece of text into ``{\nobreakspace}''-quotes. It may contain \texttt{\%InnerText;} (see \ref{InnerText}). }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Keyword{\textgreater}} and \texttt{{\textless}K{\textgreater}}}}\logpage{[ 3, 7, 3 ]}
\hyperdef{L}{X867BB95E7DC87014}{}
{
\index{Keyword@\texttt{Keyword}} \index{K@\texttt{K}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Keyword (#PCDATA|Alt)*> <!-- Keyword -->
<!ELEMENT K (#PCDATA|Alt)*> <!-- Keyword (shortcut) -->
\end{Verbatim}
This element is used to mark something as a \emph{keyword}. Usually this will be a \textsf{GAP} keyword such as ``\texttt{if}'' or ``\texttt{for}''. No further markup elements are allowed within this element except for the \texttt{Alt} element, which is necessary. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Arg{\textgreater}} and \texttt{{\textless}A{\textgreater}}}}\label{Arg}
\logpage{[ 3, 7, 4 ]}
\hyperdef{L}{X86FD4CCA7F98351F}{}
{
\index{Arg@\texttt{Arg}} \index{A@\texttt{A}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Arg (#PCDATA|Alt)*> <!-- Argument -->
<!ELEMENT A (#PCDATA|Alt)*> <!-- Argument (shortcut) -->
\end{Verbatim}
This element is used inside \texttt{Description}s in \texttt{ManSection}s to mark something as an \emph{argument} (of a function, operation, or such). It is guaranteed that the converters
typeset those exactly as in the definition of functions. No further markup
elements are allowed within this element. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Code{\textgreater}} and \texttt{{\textless}C{\textgreater}}}}\label{Code}
\logpage{[ 3, 7, 5 ]}
\hyperdef{L}{X8400998B7B3A4379}{}
{
\index{Code@\texttt{Code}} \index{C@\texttt{C}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Code (#PCDATA|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 ]}
\hyperdef{L}{X875AF9B4812C5249}{}
{
\index{File@\texttt{File}} \index{F@\texttt{F}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT File (#PCDATA|Alt)*> <!-- Filename -->
<!ELEMENT F (#PCDATA|Alt)*> <!-- Filename (shortcut) -->
\end{Verbatim}
This element is used to mark something as a \emph{filename} or a \emph{pathname} in the file system. No further markup elements are allowed within this
element. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Button{\textgreater}} and \texttt{{\textless}B{\textgreater}}}}\logpage{[ 3, 7, 7 ]}
\hyperdef{L}{X7929BA7D78A977FF}{}
{
\index{Button@\texttt{Button}} \index{B@\texttt{B}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Button (#PCDATA|Alt)*> <!-- "Button" (also Menu, Key, ...) -->
<!ELEMENT B (#PCDATA|Alt)*> <!-- "Button" (shortcut) -->
\end{Verbatim}
This element is used to mark something as a \emph{button}. It can also be used for other items in a graphical user interface like \emph{menus}, \emph{menu entries}, or \emph{keys}. No further markup elements are allowed within this element. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Package{\textgreater}}}}\logpage{[ 3, 7, 8 ]}
\hyperdef{L}{X7F4FFA877B775188}{}
{
\index{Package@\texttt{Package}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Package (#PCDATA|Alt)*> <!-- A package name -->
\end{Verbatim}
This element is used to mark something as a name of a \emph{package}. This is for example used to define the entities \textsf{GAP}, \textsf{XGAP} or \textsf{GAPDoc} (see section \ref{GDent}). No further markup elements are allowed within this element. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Listing{\textgreater}}}}\label{Listing}
\logpage{[ 3, 7, 9 ]}
\hyperdef{L}{X7F531B157D656836}{}
{
\index{Listing@\texttt{Listing}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Listing (#PCDATA)> <!-- This is just for GAP code listings -->
<!ATTLIST Listing Type CDATA #IMPLIED> <!-- a comment about the type of
listed code, may appear in
output -->
\end{Verbatim}
This element is used to embed listings of programs into the document. Only
character data and no other elements are allowed in the content. You should \emph{not} use the character entities described in section \ref{GDent} but instead type the characters directly. Only the general XML rules from
section \ref{EnterXML} apply. Note especially the usage of \texttt{{\textless}![CDATA[} sections described there. It is guaranteed that all converters use a fixed
width font for typesetting \texttt{Listing} elements. Compare also the usage of the \texttt{Code} and \texttt{C} elements in \ref{Code}.
The \texttt{Type} attribute contains a comment about the type of listed code. It may appear in
the output. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Log{\textgreater}} and \texttt{{\textless}Example{\textgreater}}}}\label{Log}
\logpage{[ 3, 7, 10 ]}
\hyperdef{L}{X810DEA1E83A57CFE}{}
{
\index{Log@\texttt{Log}} \index{Example@\texttt{Example}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Example (#PCDATA)> <!-- This is subject to the automatic
example checking mechanism -->
<!ELEMENT Log (#PCDATA)> <!-- This not -->
\end{Verbatim}
These two elements behave exactly like the \texttt{Listing} element (see \ref{Listing}). They are thought for protocols of \textsf{GAP} sessions. The only difference between the two is that \texttt{Example} sections are intended to be subject to an automatic manual checking mechanism
used to ensure the correctness of the \textsf{GAP} manual whereas \texttt{Log} is not touched by this. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Verb{\textgreater}}}}\label{Verb}
\logpage{[ 3, 7, 11 ]}
\hyperdef{L}{X7F8C4D018346B2CF}{}
{
There is one further type of verbatim-like element.
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Verb (#PCDATA)>
\end{Verbatim}
The content of such an element is guaranteed to be put into an output version
exactly as it is using some fixed width font. Before the content a new line is
started. If the line after the end of the start tag consists of whitespace
only then this part of the content is skipped.
This element is intended to be used together with the \texttt{Alt} element to specify pre-formatted ASCII alternatives for complicated \texttt{Display} formulae or \texttt{Table}s. }
}
\section{\textcolor{Chapter }{Elements for Mathematical Formulae}}\label{MathForm}
\logpage{[ 3, 8, 0 ]}
\hyperdef{L}{X8145F6B37C04AA0A}{}
{
\subsection{\textcolor{Chapter }{\texttt{{\textless}Math{\textgreater}} and \texttt{{\textless}Display{\textgreater}}}}\label{Math}
\logpage{[ 3, 8, 1 ]}
\hyperdef{L}{X7AA02845868AA533}{}
{
\index{Math@\texttt{Math}} \index{Display@\texttt{Display}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!-- Normal TeX math mode formula -->
<!ELEMENT Math (#PCDATA|A|Arg|Alt)*>
<!-- TeX displayed math mode formula -->
<!ELEMENT Display (#PCDATA|A|Arg|Alt)*>
\end{Verbatim}
These elements are used for mathematical formulae. As described in section \ref{GDformulae} they correspond to {\LaTeX}'s math and display math mode respectively.
The formulae are typed in as in {\LaTeX}, \emph{except} that the standard XML entities, see{\nobreakspace}\ref{XMLent} (in particular the characters \texttt{{\textless}} and \texttt{\&}), must be escaped - either by using the corresponding entities or by
enclosing the formula between ``\texttt{{\textless}![CDATA[}'' and ``\texttt{]]{\textgreater}}''. (The main reference for {\LaTeX} is \cite{La85}.)
It is also possible to use some unicode characters for mathematical symbols
directly, provided that it can be translated by \texttt{Encode} (\ref{Encode}) into \texttt{"LaTeX"} encoding and that \texttt{SimplifiedUnicodeString} (\ref{SimplifiedUnicodeString}) with arguments \texttt{"latin1"} and \texttt{"single"} returns something sensible. Currently, we support entities \texttt{\&CC;}, \texttt{\&ZZ;}, \texttt{\&NN;}, \texttt{\&PP;}, \texttt{\&QQ;}, \texttt{\&HH;}, \texttt{\&RR;} for the corresponding black board bold letters {\ensuremath{\mathbb C}},
{\ensuremath{\mathbb Z}}, {\ensuremath{\mathbb N}},{\ensuremath{\mathbb P}},
{\ensuremath{\mathbb Q}}, {\ensuremath{\mathbb H}} and {\ensuremath{\mathbb
R}}, respectively.
The only element type that is allowed within the formula elements is the \texttt{Arg} or \texttt{A} element (see \ref{Arg}), which is used to typeset identifiers that are arguments to \textsf{GAP} functions or operations.
In text and HTML output these formulae 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{\nobreakspace}\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{\nobreakspace}\ref{Alt} and{\nobreakspace}\ref{Verb}). }
\subsection{\textcolor{Chapter }{\texttt{{\textless}M{\textgreater}}}}\label{M}
\logpage{[ 3, 8, 2 ]}
\hyperdef{L}{X7ABF42328467E966}{}
{
\index{M@\texttt{M}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!-- Math with well defined translation to text output -->
<!ELEMENT M (#PCDATA|A|Arg|Alt)*>
\end{Verbatim}
The ``\texttt{M}'' element type is intended for formulae in the running text for which there is a
sensible 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
\texttt{\symbol{92}}ast&
\texttt{*}\\
\hline
\texttt{\symbol{92}}bf&
\texttt{}\\
\hline
\texttt{\symbol{92}}bmod&
\texttt{mod}\\
\hline
\texttt{\symbol{92}}cdot&
\texttt{*}\\
\hline
\texttt{\symbol{92}}colon&
\texttt{:}\\
\hline
\texttt{\symbol{92}}equiv&
\texttt{=}\\
\hline
\texttt{\symbol{92}}geq&
\texttt{{\textgreater}=}\\
\hline
\texttt{\symbol{92}}germ&
\texttt{}\\
\hline
\texttt{\symbol{92}}hookrightarrow&
\texttt{-{\textgreater}}\\
\hline
\texttt{\symbol{92}}iff&
\texttt{{\textless}={\textgreater}}\\
\hline
\texttt{\symbol{92}}langle&
\texttt{{\textless}}\\
\hline
\texttt{\symbol{92}}ldots&
\texttt{...}\\
\hline
\texttt{\symbol{92}}left&
\texttt{{\nobreakspace}}\\
\hline
\texttt{\symbol{92}}leq&
\texttt{{\textless}=}\\
\hline
\texttt{\symbol{92}}leftarrow&
\texttt{{\textless}-}\\
\hline
\texttt{\symbol{92}}Leftarrow&
\texttt{{\textless}=}\\
\hline
\texttt{\symbol{92}}limits&
\texttt{{\nobreakspace}}\\
\hline
\texttt{\symbol{92}}longrightarrow&
\texttt{--{\textgreater}}\\
\hline
\texttt{\symbol{92}}Longrightarrow&
\texttt{=={\textgreater}}\\
\hline
\texttt{\symbol{92}}mapsto&
\texttt{-{\textgreater}}\\
\hline
\texttt{\symbol{92}}mathbb&
\texttt{{\nobreakspace}}\\
\hline
\texttt{\symbol{92}}mathop&
\texttt{{\nobreakspace}}\\
\hline
\texttt{\symbol{92}}mid&
\texttt{|}\\
\hline
\texttt{\symbol{92}}pmod&
\texttt{mod}\\
\hline
\texttt{\symbol{92}}prime&
\texttt{'}\\
\hline
\texttt{\symbol{92}}rangle&
\texttt{{\textgreater}}\\
\hline
\texttt{\symbol{92}}right&
\texttt{{\nobreakspace}}\\
\hline
\texttt{\symbol{92}}rightarrow&
\texttt{-{\textgreater}}\\
\hline
\texttt{\symbol{92}}Rightarrow&
\texttt{={\textgreater}}\\
\hline
\texttt{\symbol{92}}rm, \texttt{\symbol{92}}sf, \texttt{\symbol{92}}textrm,
\texttt{\symbol{92}}text&
\texttt{}\\
\hline
\texttt{\symbol{92}}setminus&
\texttt{\texttt{\symbol{92}}}\\
\hline
\texttt{\symbol{92}}thinspace&
\texttt{ }\\
\hline
\texttt{\symbol{92}}times&
\texttt{x}\\
\hline
\texttt{\symbol{92}}to&
\texttt{-{\textgreater}}\\
\hline
\texttt{\symbol{92}}vert&
\texttt{|}\\
\hline
\texttt{\symbol{92}}!&
\texttt{}\\
\hline
\texttt{\symbol{92}},&
\texttt{}\\
\hline
\texttt{\symbol{92}};&
\texttt{{\nobreakspace}}\\
\hline
\texttt{\symbol{92}}\texttt{\symbol{123}}&
\texttt{\texttt{\symbol{123}}}\\
\hline
\texttt{\symbol{92}}\texttt{\symbol{125}}&
\texttt{\texttt{\symbol{125}}}\\
\hline
\end{tabular}\\[2mm]
\textbf{Table: }{\LaTeX} macros with special text translation\end{center}
In all other macros only the backslash is removed. Whitespace is normalized
(to one blank) but not removed. Note that whitespace is not added, so you may
want to add a few more spaces than you usually do in your {\LaTeX} documents.
Braces \texttt{\texttt{\symbol{123}}\texttt{\symbol{125}}} are removed in general, however pairs of double braces are converted to one
pair of braces. This can be used to write \texttt{{\textless}M{\textgreater}x\texttt{\symbol{94}}\texttt{\symbol{123}}12\texttt{\symbol{125}}{\textless}/M{\textgreater}} for \texttt{x\texttt{\symbol{94}}12} and \texttt{{\textless}M{\textgreater}x{\textunderscore}\texttt{\symbol{123}}\texttt{\symbol{123}}i+1\texttt{\symbol{125}}\texttt{\symbol{125}}{\textless}/M{\textgreater}} for \texttt{x{\textunderscore}\texttt{\symbol{123}}i+1\texttt{\symbol{125}}}.
}
}
\section{\textcolor{Chapter }{Everything else}}\label{sec:misc}
\logpage{[ 3, 9, 0 ]}
\hyperdef{L}{X7A0D26B180BEDE37}{}
{
\subsection{\textcolor{Chapter }{\texttt{{\textless}Alt{\textgreater}}}}\label{Alt}
\logpage{[ 3, 9, 1 ]}
\hyperdef{L}{X850E69017945AE3E}{}
{
\index{Alt@\texttt{Alt}} This element is used to specify alternatives for different output formats
within normal text. See also sections \ref{List}, \ref{Enum}, and \ref{Table} for alternatives in lists and tables.
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Alt (%InnerText;)*> <!-- This is only to allow "Only" and
"Not" attributes for normal text -->
<!ATTLIST Alt Only CDATA #IMPLIED
Not CDATA #IMPLIED>
\end{Verbatim}
Of course exactly one of the two attributes must occur in one element. The
attribute values must be one word or a list of words, separated by spaces or
commas. The words which are currently recognized by the converter programs
contained in \textsf{GAPDoc} are: ``\texttt{LaTeX}'', ``\texttt{HTML}'', and ``\texttt{Text}''. If the \texttt{Only} attribute is specified then only the corresponding converter will include the
content of the element into the output document. If the \texttt{Not} attribute is specified the corresponding converter will ignore the content of
the element. You can use other words to specify special alternatives for other
converters of \textsf{GAPDoc} documents.
We fix a rule for handling the content of an \texttt{Alt} element with \texttt{Only} attribute. In their content code for the corresponding output format is
included directly. So, in case of HTML the content is HTML code, in case of {\LaTeX} the content is {\LaTeX} code. The converters don't apply any handling of special characters to this
content.
Within the element only \texttt{\%InnerText;} (see \ref{InnerText}) is allowed. This is to ensure that the same set of chapters, sections, and
subsections show up in all output formats. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Par{\textgreater}} and \texttt{{\textless}P{\textgreater}}}}\label{Par}
\logpage{[ 3, 9, 2 ]}
\hyperdef{L}{X85D23A648444069F}{}
{
\index{Par@\texttt{Par}} \index{P@\texttt{P}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Par EMPTY> <!-- this is intentionally empty! -->
<!ELEMENT P EMPTY> <!-- the same as shortcut -->
\end{Verbatim}
This \texttt{EMPTY} element marks the boundary of paragraphs. Note that an empty line in the input
does not mark a new paragraph as opposed to the {\LaTeX} convention.
(Remark: it would be much easier to parse a document and to understand its
sectioning and paragraph structure when there was an element whose \emph{content} is the text of a paragraph. But in practice many paragraph boundaries are
implicitly clear which would make it somewhat painful to enclose each
paragraph in extra tags. The introduction of the \texttt{P} or \texttt{Par} elements as above delegates this pain to the writer of a conversion program
for \textsf{GAPDoc} documents.) }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Br{\textgreater}}}}\label{Br}
\logpage{[ 3, 9, 3 ]}
\hyperdef{L}{X7A3EF0647B10C1EC}{}
{
\index{Br@\texttt{Br}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Br EMPTY> <!-- a forced line break -->
\end{Verbatim}
This element can be used to force a line break in the output versions of a \textsf{GAPDoc} element, it does not start a new paragraph. Please, do not use this instead of
a \texttt{Par} element, this would often lead to ugly output versions of your document. }
\subsection{\textcolor{Chapter }{\texttt{{\textless}Ignore{\textgreater}}}}\label{Ignore}
\logpage{[ 3, 9, 4 ]}
\hyperdef{L}{X7A81FB717A30B485}{}
{
\index{Ignore@\texttt{Ignore}}
\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Ignore (%Text;| Chapter | Section | Subsection | ManSection |
Heading)*>
<!ATTLIST Ignore Remark CDATA #IMPLIED>
\end{Verbatim}
This element can appear anywhere. Its content is ignored by the standard
converters. It can be used, for example, to include data which are not part of
the actual \textsf{GAPDoc} document, like source code, or to make not finished parts of the document
invisible.
Of course, one can use special converter programs which extract the contents
of \texttt{Ignore} elements. Information on the type of the content can be stored in the optional
attribute \texttt{Remark}. }
}
}
\chapter{\textcolor{Chapter }{Distributing a Document into Several Files}}\label{Distributing}
\logpage{[ 4, 0, 0 ]}
\hyperdef{L}{X7A3355C07F57C280}{}
{
In \textsf{GAPDoc} there are facilities to distribute a single document over several files. This
is for example interesting, if one wants to store the documentation of some
code in the same file as the code itself. Or, if one just wants to store
chapters of a document in separate files. There is a set of conventions how
this is done and some tools to collect the text for further processing.
The technique can also be used to distribute and collect other types of
documents into respectively from several files (e.g., source code, examples).
\section{\textcolor{Chapter }{The Conventions}}\label{DistrConv}
\logpage{[ 4, 1, 0 ]}
\hyperdef{L}{X7CE078A07E8256DC}{}
{
\index{Include@\texttt{{\textless}\#Include{\textgreater}}} \index{GAPDoc@\texttt{{\textless}\#GAPDoc{\textgreater}}} In this description we use the string \texttt{GAPDoc} for marking pieces of a document to collect.
Pieces of documentation that shall be incorporated into another document are
marked as follows:
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
## <#GAPDoc Label="MyPiece">
## <E>This</E> is the piece.
## The hash characters are removed.
## <#/GAPDoc>
\end{Verbatim}
This piece is then included into another file by a statement like: \texttt{{\textless}\#Include Label="MyPiece"{\textgreater}} Here are the exact rules, how pieces are gathered:
\begin{itemize}
\item All lines up to a line containing the character sequence ``\texttt{{\textless}\#GAPDoc{\nobreakspace}Label="}'' (exactly one space character) are ignored. The characters on the same line
before this sequence are stored as ``prefix''. The characters after the sequence up to the next double quotes character are
stored as ``label''. All other characters in the line are ignored.
\item The following lines up to a line containing the character sequence ``\texttt{{\textless}\#/GAPDoc{\textgreater}}'' are stored under the label. These lines are processed as follows: The longest
possible substring from the beginning of the line that equals the
corresponding substring of the prefix is removed.
\end{itemize}
Having stored a list of labels and pieces of text gathered as above this can
be used as follows.
\begin{itemize}
\item In \textsf{GAPDoc} documentation files all statements of the form ``\texttt{{\textless}\#Include Label="Key"{\textgreater}}'' are replaced by the sequence of lines stored under the label \texttt{Key}.
\item Additionally, every occurrence of a statement of the form ``\texttt{{\textless}\#Include SYSTEM "Filename"{\textgreater}}'' is replaced by the whole file stored under the name \texttt{Filename} in the file system.
\item These substitutions are done recursively (although one should probably avoid
to use this extensively).
\end{itemize}
Here is another example:
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
# # <#GAPDoc Label="AnotherPiece"> some characters
# # This text is not indented.
# This text is indented by one blank.
#Not indented.
#<#/GAPDoc>
\end{Verbatim}
replaces \texttt{{\textless}\#Include Label="AnotherPiece"{\textgreater}} by
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
This text is not indented.
This text is indented by one blank.
Not indented.
\end{Verbatim}
Since these rules are very simple it is quite easy to write a program in
almost any programming language which does this gathering of text pieces and
the substitutions. In \textsf{GAPDoc} there is the \textsf{GAP} function \texttt{ComposedDocument} (\ref{ComposedDocument}) which does this.
Note that the XML-tag-like markup we have used here is not a legal XML markup,
since the hash character is not allowed in element names. The mechanism
described here is a preprocessing step which composes a document. }
\section{\textcolor{Chapter }{A Tool for Collecting a Document}}\logpage{[ 4, 2, 0 ]}
\hyperdef{L}{X81E07B0F83EBDA5F}{}
{
\subsection{\textcolor{Chapter }{ComposedDocument}}
\logpage{[ 4, 2, 1 ]}\nobreak
\hyperdef{L}{X857D77557D12559D}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ComposedDocument({\slshape tagname, path, main, source[, info]})\index{ComposedDocument@\texttt{ComposedDocument}}
\label{ComposedDocument}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ComposedXMLString({\slshape path, main, source[, info]})\index{ComposedXMLString@\texttt{ComposedXMLString}}
\label{ComposedXMLString}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a document as string, or a list with this string and information about the
source positions
The argument \mbox{\texttt{\slshape tagname}} is the string used for the pseudo elements which mark the pieces of a document
to collect. (In \ref{DistrConv} we used \texttt{GAPDoc} as \mbox{\texttt{\slshape tagname}}. The second function \texttt{ComposedXMLString}\texttt{( ... )} is an abbreviation for \texttt{ComposedDocument}\texttt{("GAPDoc", ... )}.
The argument \mbox{\texttt{\slshape path}} must be a path to some directory (as string or directory object), \mbox{\texttt{\slshape main}} the name of a file in this directory and \mbox{\texttt{\slshape source}} a list of file names, all of these relative to \mbox{\texttt{\slshape path}}. The document is constructed via the mechanism described in
Section{\nobreakspace}\ref{DistrConv}.
First the files given in \mbox{\texttt{\slshape source}} are scanned for chunks of the document marked by \texttt{{\textless}\#\mbox{\texttt{\slshape tagname}} Label="..."{\textgreater}} and \texttt{{\textless}/\#\mbox{\texttt{\slshape tagname}}{\textgreater}} pairs. Then the file \mbox{\texttt{\slshape main}} is read and all \texttt{{\textless}\#Include ... {\textgreater}}-tags are substituted recursively by other files or chunks of documentation
found in the first step, respectively. If the optional argument \mbox{\texttt{\slshape info}} is given and set to \texttt{true} this function returns a list \texttt{[str, origin]}, where \texttt{str} is a string containing the composed document and \texttt{origin} is a sorted list of entries of the form \texttt{[pos, filename, line]}. Here \texttt{pos} runs through all character positions of starting lines or text pieces from
different files in \texttt{str}. The \texttt{filename} and \texttt{line} describe the origin of this part of the collected document. Without the fourth
argument only the string \texttt{str} is returned.
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
gap> doc := ComposedDocument("GAPDoc", "/my/dir", "manual.xml",
> ["../lib/func.gd", "../lib/func.gi"], true);;
\end{Verbatim}
}
\subsection{\textcolor{Chapter }{OriginalPositionDocument}}
\logpage{[ 4, 2, 2 ]}\nobreak
\hyperdef{L}{X86D1141E7EDCAAC8}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{OriginalPositionDocument({\slshape srcinfo, pos})\index{OriginalPositionDocument@\texttt{OriginalPositionDocument}}
\label{OriginalPositionDocument}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
A pair \texttt{[filename, linenumber]}.
Here \mbox{\texttt{\slshape srcinfo}} must be a data structure as returned as second entry by \texttt{ComposedDocument} (\ref{ComposedDocument}) called with \mbox{\texttt{\slshape info}}=\texttt{true}. It returns for a given position \mbox{\texttt{\slshape pos}} in the composed document the file name and line number from which that text
was collected. }
}
}
\chapter{\textcolor{Chapter }{The Converters and an XML Parser}}\label{ch:conv}
\logpage{[ 5, 0, 0 ]}
\hyperdef{L}{X845E7FDC7C082CC4}{}
{
The \textsf{GAPDoc} package contains a set of programs which allow us to convert a \textsf{GAPDoc} book into several output versions and to make them available to \textsf{GAP}'s online help.
Currently the following output formats are provided: text for browsing inside
a terminal running \textsf{GAP}, {\LaTeX} with \texttt{hyperref}-package for cross references via hyperlinks and HTML for reading with a
Web-browser.
\section{\textcolor{Chapter }{Producing Documentation from Source Files}}\label{MakeDoc}
\logpage{[ 5, 1, 0 ]}
\hyperdef{L}{X7D1BB5867C13FA14}{}
{
Here we explain how to use the functions which are described in more detail in
the following sections. We assume that we have the main file \texttt{MyBook.xml} of a book \texttt{"MyBook"} in the directory \texttt{/my/book/path}. This contains \texttt{{\textless}\#Include ...{\textgreater}}-statements as explained in Chapter{\nobreakspace}\ref{Distributing}. These refer to some other files as well as pieces of text which are found in
the comments of some \textsf{GAP} source files \texttt{../lib/a.gd} and \texttt{../lib/b.gi} (relative to the path above). A Bib{\TeX} database \texttt{MyBook.bib} for the citations is also in the directory given above. We want to produce a
text-, \texttt{pdf-} and HTML-version of the document. (A {\LaTeX} version of the manual is produced, so it is also easy to compile \texttt{dvi}-, and postscript-versions.)
All the commands shown in this Section are collected in the single function \texttt{MakeGAPDocDoc} (\ref{MakeGAPDocDoc}).
First we construct the complete XML-document as a string with \texttt{ComposedDocument} (\ref{ComposedDocument}). This interprets recursively the \texttt{{\textless}\#Include ...{\textgreater}}-statements.
\begin{Verbatim}[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> doc := ComposedDocument("GAPDoc", path, main, files, true);;
\end{Verbatim}
Now \texttt{doc} is a list with two entries, the first is a string containing the XML-document,
the second gives information from which files and locations which part of the
document was collected. This is useful in the next step, if there are any
errors in the document.
Next we parse the document and store its structure in a tree-like data
structure. The commands for this are \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}) and \texttt{CheckAndCleanGapDocTree} (\ref{CheckAndCleanGapDocTree}).
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
gap> r := ParseTreeXMLString(doc[1], doc[2]);;
gap> CheckAndCleanGapDocTree(r);
true
\end{Verbatim}
We start to produce a text version of the manual, which can be read in a
terminal (window). The command is \texttt{GAPDoc2Text} (\ref{GAPDoc2Text}). This produces a record with the actual text and some additional information.
The text can be written chapter-wise into files with \texttt{GAPDoc2TextPrintTextFiles} (\ref{GAPDoc2TextPrintTextFiles}). The names of these files are \texttt{chap0.txt}, \texttt{chap1.txt} and so on. The text contains some markup using ANSI escape sequences. This
markup is substituted by the \textsf{GAP} help system (user configurable) to show the text with colors and other
attributes. For the bibliography we have to tell \texttt{GAPDoc2Text} (\ref{GAPDoc2Text}) the location of the Bib{\TeX} database by specifying a \texttt{path} as second argument.
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
gap> t := GAPDoc2Text(r, path);;
gap> GAPDoc2TextPrintTextFiles(t, path);
\end{Verbatim}
This command constructs all parts of the document including table of contents,
bibliography and index. The functions \texttt{FormatParagraph} (\ref{FormatParagraph}) for formatting text paragraphs and \texttt{ParseBibFiles} (\ref{ParseBibFiles}) for reading Bib{\TeX} files with \textsf{GAP} may be of independent interest.
With the text version we have also produced the information which is used for
searching with \textsf{GAP}'s online help. Also, labels are produced which can be used by links in the
HTML- and \texttt{pdf}-versions of the manual.
Next we produce a {\LaTeX} version of the document. \texttt{GAPDoc2LaTeX} (\ref{GAPDoc2LaTeX}) returns a string containing the {\LaTeX} source. The utility function \texttt{FileString} (\ref{FileString}) writes the content of a string to a file, we choose \texttt{MyBook.tex}.
\begin{Verbatim}[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
pdflatex MyBook
bibtex MyBook
pdflatex MyBook
makeindex MyBook
pdflatex MyBook
mv MyBook.pdf manual.pdf
\end{Verbatim}
After this we have a \texttt{pdf}-version of the document in the file \texttt{manual.pdf}. It contains hyperlink information which can be used with appropriate
browsers for convenient reading of the document on screen (e.g., \texttt{xpdf} is nice because it allows remote calls to display named locations of the
document). Of course, we could also use other commands like \texttt{latex} or \texttt{dvips} to process the {\LaTeX} source file. Furthermore we have produced a file \texttt{MyBook.pnr} which is \textsf{GAP}-readable and contains the page number information for each (sub-)section of
the document.
We can add this page number information to the indexing information collected
by the text converter and then print a \texttt{manual.six} file which is read by \textsf{GAP} when the manual is loaded. This is done with \texttt{AddPageNumbersToSix} (\ref{AddPageNumbersToSix}) and \texttt{PrintSixFile} (\ref{PrintSixFile}).
\begin{Verbatim}[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 probably want to add a file \texttt{manual.css}, see \texttt{GAPDoc2HTMLPrintHTMLFiles} (\ref{GAPDoc2HTMLPrintHTMLFiles}) for more details. The argument \texttt{path} of \texttt{GAPDoc2HTML} (\ref{GAPDoc2HTML}) specifies the directory containing the Bib{\TeX} database files.
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
gap> h := GAPDoc2HTML(r, path);;
gap> GAPDoc2HTMLPrintHTMLFiles(h, path);
\end{Verbatim}
\subsection{\textcolor{Chapter }{MakeGAPDocDoc}}
\logpage{[ 5, 1, 1 ]}\nobreak
\hyperdef{L}{X826F530686F4D052}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{MakeGAPDocDoc({\slshape path, main, files, bookname[, gaproot]})\index{MakeGAPDocDoc@\texttt{MakeGAPDocDoc}}
\label{MakeGAPDocDoc}
}\hfill{\scriptsize (function)}}\\
This function collects all the commands for producing a text-, \texttt{pdf}- and HTML-version of a \textsf{GAPDoc} document as described in Section{\nobreakspace}\ref{MakeDoc}. It checks the \texttt{.log} file from the call of \texttt{pdflatex} and reports if there are errors, warnings or overfull boxes.
\emph{Note:} If this function works for you depends on your operating system and installed
software. It will probably work on most \texttt{UNIX} systems with a standard {\LaTeX} installation. If the function doesn't work for you look at the source code and
adjust it to your system.
Here \mbox{\texttt{\slshape path}} must be the directory (as string or directory object) containing the main file \mbox{\texttt{\slshape main}} of the document (given with or without the \texttt{.xml} extension. The argument \mbox{\texttt{\slshape files}} is a list of (probably source code) files relative to \mbox{\texttt{\slshape path}} which contain pieces of documentation which must be included in the document,
see Chapter{\nobreakspace}\ref{Distributing}. And \mbox{\texttt{\slshape bookname}} is the name of the book used by \textsf{GAP}'s online help. The optional argument \mbox{\texttt{\slshape gaproot}} must be a string which gives the relative path from \mbox{\texttt{\slshape path}} to the main \textsf{GAP} root directory. If this is given, the HTML files are produced with relative
paths to external books.
Experimental: \texttt{MakeGAPDocDoc} can be called with additional arguments \texttt{"Tth"} and/or \texttt{"MathML"}. If these are given additional variants of the HTML conversion are called,
see \texttt{GAPDoc2HTML} (\ref{GAPDoc2HTML}) for details.
It is possible to use \textsf{GAPDoc} with other languages than English, see \texttt{SetGapDocLanguage} (\ref{SetGapDocLanguage}) for more details.
}
}
\section{\textcolor{Chapter }{Parsing XML Documents}}\label{ParseXML}
\logpage{[ 5, 2, 0 ]}
\hyperdef{L}{X7FE2AF49838D9034}{}
{
Arbitrary well-formed XML documents can be parsed and browsed by the following
functions.
\subsection{\textcolor{Chapter }{ParseTreeXMLString}}
\logpage{[ 5, 2, 1 ]}\nobreak
\hyperdef{L}{X847EB8498151D443}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ParseTreeXMLString({\slshape str[, srcinfo][, entitydict]})\index{ParseTreeXMLString@\texttt{ParseTreeXMLString}}
\label{ParseTreeXMLString}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ParseTreeXMLFile({\slshape fname[, entitydict]})\index{ParseTreeXMLFile@\texttt{ParseTreeXMLFile}}
\label{ParseTreeXMLFile}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a record which is root of a tree structure
The first function parses an XML-document stored in string \mbox{\texttt{\slshape str}} and returns the document in form of a tree.
The optional argument \mbox{\texttt{\slshape srcinfo}} must have the same format as in \texttt{OriginalPositionDocument} (\ref{OriginalPositionDocument}). If it is given then error messages refer to the original source of the text
with the problem.
With the optional argument \mbox{\texttt{\slshape entitydict}} named entities can be given to the parser, for example entities which are
defined in the \texttt{.dtd}-file (which is not read by this parser). The standard XML-entities do not
need to be provided, and for \textsf{GAPDoc} documents the entity definitions from \texttt{gapdoc.dtd} are automatically provided. Entities in the document's \texttt{{\textless}!DOCTYPE} declaration are parsed and also need not to be provided here. The argument \mbox{\texttt{\slshape entitydict}} must be a record where each component name is an entity name (without the
surrounding \& and ;) to which is assigned its substitution string.
The second function is just a shortcut for \texttt{ParseTreeXMLString( StringFile(}\mbox{\texttt{\slshape fname}}\texttt{), ... )}, see \texttt{StringFile} (\ref{StringFile}).
After these functions return the list of named entities which were known
during the parsing can be found in the record \texttt{ENTITYDICT}.
A node in the result tree corresponds to an XML element, or to some parsed
character data. In the first case it looks as follows:
\begin{Verbatim}[fontsize=\small,frame=single,label=Example Node]
rec( name := "Book",
attributes := rec( Name := "EDIM" ),
content := [ ... list of nodes for content ...],
start := 312,
stop := 15610,
next := 15611 )
\end{Verbatim}
This means that \texttt{\mbox{\texttt{\slshape str}}\texttt{\symbol{123}}[312..15610]\texttt{\symbol{125}}} looks like \texttt{{\textless}Book Name="EDIM"{\textgreater} ... content ...
{\textless}/Book{\textgreater}}.
The leaves of the tree encode parsed character data as in the following
example:
\begin{Verbatim}[fontsize=\small,frame=single,label=Example Node]
rec( name := "PCDATA",
content := "text without markup " )
\end{Verbatim}
This function checks whether the XML document is \emph{well formed}, see \ref{XMLvalid} for an explanation. If an error in the XML structure is found, a break loop is
entered and the text around the position where the problem starts is shown.
With \texttt{Show();} one can browse the original input in the \texttt{Pager} (\textbf{Reference: Pager}), starting with the line where the error occurred. All entities are resolved
when they are either entities defined in the \textsf{GAPDoc} package (in particular the standard XML entities) or if their definition is
included in the \texttt{{\textless}!DOCTYPE ..{\textgreater}} tag of the document.
Note that \texttt{ParseTreeXMLString} does not parse and interpret the corresponding document type definition (the \texttt{.dtd}-file given in the \texttt{{\textless}!DOCTYPE ..{\textgreater}} tag). Hence it also does not check the \emph{validity} of the document (i.e., it is no \emph{validating XML parser}).
If you are using this function to parse a \textsf{GAPDoc} document you can use \texttt{CheckAndCleanGapDocTree} (\ref{CheckAndCleanGapDocTree}) for some validation and additional checking of the document structure. }
\subsection{\textcolor{Chapter }{StringXMLElement}}
\logpage{[ 5, 2, 2 ]}\nobreak
\hyperdef{L}{X835887057D0B4DA8}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StringXMLElement({\slshape tree})\index{StringXMLElement@\texttt{StringXMLElement}}
\label{StringXMLElement}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a list \texttt{[string, positions]}
The argument \mbox{\texttt{\slshape tree}} must have a format of a node in the parse tree of an XML document as returned
by \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}) (including the root node representing the full document). This function
computes a pair \texttt{[string, positions]} where \texttt{string} contains XML code which is equivalent to the code which was parsed to get \mbox{\texttt{\slshape tree}}. And \texttt{positions} is a list of lists of four numbers \texttt{[eltb, elte, contb, conte]}. There is one such list for each XML element occuring in \texttt{string}, where \texttt{eltb} and \texttt{elte} are the begin and end position of this element in \texttt{string} and where \texttt{contb} and \texttt{conte} are begin and end position of the content of this element, or both are \texttt{0} if there is no content.
Note that parsing XML code is an irreversible task, we can only expect to get
equivalent XML code from this function. But parsing the resulting \texttt{string} again and applying \texttt{StringXMLElement} again gives the same result. See the function \texttt{EntitySubstitution} (\ref{EntitySubstitution}) for back-substitutions of entities in the result. }
\subsection{\textcolor{Chapter }{EntitySubstitution}}
\logpage{[ 5, 2, 3 ]}\nobreak
\hyperdef{L}{X786827BF793191B3}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{EntitySubstitution({\slshape xmlstring, entities})\index{EntitySubstitution@\texttt{EntitySubstitution}}
\label{EntitySubstitution}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a string
The argument \mbox{\texttt{\slshape xmlstring}} must be a string containing XML code or a pair \texttt{[string, positions]} as returned by \texttt{StringXMLElement} (\ref{StringXMLElement}). The argument \mbox{\texttt{\slshape entities}} specifies entity names (without the surrounding \mbox{\texttt{\slshape \&}} and \texttt{;}) and their substitution strings, either a list of pairs of strings or as a
record with the names as components and the substitutions as values.
This function tries to substitute non-intersecting parts of \texttt{string} by the given entities. If the \texttt{positions} information is given then only parts of the document which allow a valid
substitution by an entity are considered. Otherwise a simple text substitution
without further check is done.
Note that in general the entity resolution in XML documents is a complicated
and non-reversible task. But nevertheless this utility may be useful in not
too complicated situations. }
\subsection{\textcolor{Chapter }{DisplayXMLStructure}}
\logpage{[ 5, 2, 4 ]}\nobreak
\hyperdef{L}{X86589C5C859ACE38}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DisplayXMLStructure({\slshape tree})\index{DisplayXMLStructure@\texttt{DisplayXMLStructure}}
\label{DisplayXMLStructure}
}\hfill{\scriptsize (function)}}\\
This utility displays the tree structure of an XML document as it is returned
by \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}) (without the \texttt{PCDATA} leaves).
Since this is usually quite long the result is shown using the \texttt{Pager} (\textbf{Reference: Pager}). }
\subsection{\textcolor{Chapter }{ApplyToNodesParseTree}}
\logpage{[ 5, 2, 5 ]}\nobreak
\hyperdef{L}{X7A7B223A83E38B40}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ApplyToNodesParseTree({\slshape tree, fun})\index{ApplyToNodesParseTree@\texttt{ApplyToNodesParseTree}}
\label{ApplyToNodesParseTree}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AddRootParseTree({\slshape tree})\index{AddRootParseTree@\texttt{AddRootParseTree}}
\label{AddRootParseTree}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RemoveRootParseTree({\slshape tree})\index{RemoveRootParseTree@\texttt{RemoveRootParseTree}}
\label{RemoveRootParseTree}
}\hfill{\scriptsize (function)}}\\
The function \texttt{ApplyToNodesParseTree} applies a function \mbox{\texttt{\slshape fun}} to all nodes of the parse tree \mbox{\texttt{\slshape tree}} of an XML document returned by \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}).
The function \texttt{AddRootParseTree} is an application of this. It adds to all nodes a component \texttt{.root} to which the top node tree \mbox{\texttt{\slshape tree}} is assigned. These components can be removed afterwards with \texttt{RemoveRootParseTree}. }
Here are two more utilities which use \texttt{ApplyToNodesParseTree} (\ref{ApplyToNodesParseTree}).
\subsection{\textcolor{Chapter }{GetTextXMLTree}}
\logpage{[ 5, 2, 6 ]}\nobreak
\hyperdef{L}{X7F76D4A27C7FB946}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GetTextXMLTree({\slshape tree})\index{GetTextXMLTree@\texttt{GetTextXMLTree}}
\label{GetTextXMLTree}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a string
The argument \mbox{\texttt{\slshape tree}} must be a node of a parse tree of some XML document, see \texttt{ParseTreeXMLFile} (\ref{ParseTreeXMLFile}). This function collects the content of this and all included elements
recursively into a string. }
\subsection{\textcolor{Chapter }{XMLElements}}
\logpage{[ 5, 2, 7 ]}\nobreak
\hyperdef{L}{X8466F74C80442F7D}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{XMLElements({\slshape tree, eltnames})\index{XMLElements@\texttt{XMLElements}}
\label{XMLElements}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a list of nodes
The argument \mbox{\texttt{\slshape tree}} must be a node of a parse tree of some XML document, see \texttt{ParseTreeXMLFile} (\ref{ParseTreeXMLFile}). This function returns a list of all subnodes of \mbox{\texttt{\slshape tree}} (possibly including \mbox{\texttt{\slshape tree}}) of elements with name given in the list of strings \mbox{\texttt{\slshape eltnames}}. Use \texttt{"PCDATA"} as name for leave nodes which contain the actual text of the document. As an
abbreviation \mbox{\texttt{\slshape eltnames}} can also be a string which is then put in a one element list. }
And here are utilities for processing \textsf{GAPDoc} XML documents.
\subsection{\textcolor{Chapter }{CheckAndCleanGapDocTree}}
\logpage{[ 5, 2, 8 ]}\nobreak
\hyperdef{L}{X84CFF72484B19C0D}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CheckAndCleanGapDocTree({\slshape tree})\index{CheckAndCleanGapDocTree@\texttt{CheckAndCleanGapDocTree}}
\label{CheckAndCleanGapDocTree}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing
The argument \mbox{\texttt{\slshape tree}} of this function is a parse tree from \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}) of some \textsf{GAPDoc} document. This function does an (incomplete) validity check of the document
according to the document type declaration in \texttt{gapdoc.dtd}. It also does some additional checks which cannot be described in the DTD
(like checking whether chapters and sections have a heading). For elements
with element content the whitespace between these elements is removed.
In case of an error the break loop is entered and the position of the error in
the original XML document is printed. With \texttt{Show();} one can browse the original input in the \texttt{Pager} (\textbf{Reference: Pager}). }
\subsection{\textcolor{Chapter }{AddParagraphNumbersGapDocTree}}
\logpage{[ 5, 2, 9 ]}\nobreak
\hyperdef{L}{X84062CD67B286FF0}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AddParagraphNumbersGapDocTree({\slshape tree})\index{AddParagraphNumbersGapDocTree@\texttt{AddParagraphNumbersGapDocTree}}
\label{AddParagraphNumbersGapDocTree}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing
The argument \mbox{\texttt{\slshape tree}} must be an XML tree returned by \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}) applied to a \textsf{GAPDoc} document. This function adds to each node of the tree a component \texttt{.count} which is of form \texttt{[Chapter[, Section[, Subsection, Paragraph] ] ]}. Here the first three numbers should be the same as produced by the {\LaTeX} version of the document. Text before the first chapter is counted as chapter \texttt{0} and similarly for sections and subsections. Some elements are always
considered to start a new paragraph. }
\subsection{\textcolor{Chapter }{InfoXMLParser}}
\logpage{[ 5, 2, 10 ]}\nobreak
\hyperdef{L}{X78A22C58841E5D0B}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{InfoXMLParser\index{InfoXMLParser@\texttt{InfoXMLParser}}
\label{InfoXMLParser}
}\hfill{\scriptsize (info class)}}\\
The default level of this info class is 1. Functions like \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}) are then printing some information, in particular in case of errors. You can
suppress it by setting the level of \texttt{InfoXMLParser} to 0. With level 2 there may be some more information for debugging purposes. }
}
\section{\textcolor{Chapter }{The Converters}}\label{Converters}
\logpage{[ 5, 3, 0 ]}
\hyperdef{L}{X8560E1A2845EC2C1}{}
{
Here are more details about the conversion programs for \textsf{GAPDoc} XML documents.
\subsection{\textcolor{Chapter }{GAPDoc2LaTeX}}
\logpage{[ 5, 3, 1 ]}\nobreak
\hyperdef{L}{X85BE6DF178423EF5}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GAPDoc2LaTeX({\slshape tree})\index{GAPDoc2LaTeX@\texttt{GAPDoc2LaTeX}}
\label{GAPDoc2LaTeX}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
{\LaTeX} document as string
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SetGapDocLaTeXOptions({\slshape [...]})\index{SetGapDocLaTeXOptions@\texttt{SetGapDocLaTeXOptions}}
\label{SetGapDocLaTeXOptions}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
Nothing
The argument \mbox{\texttt{\slshape tree}} for this function is a tree describing a \textsf{GAPDoc} XML document as returned by \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}) (probably also checked with \texttt{CheckAndCleanGapDocTree} (\ref{CheckAndCleanGapDocTree})). The output is a string containing a version of the document which can be
written to a file and processed with {\LaTeX} or pdf{\LaTeX} (and probably Bib{\TeX} and \texttt{makeindex}).
The output uses the \texttt{report} document class and needs the following {\LaTeX} packages: \texttt{a4wide}, \texttt{amssymb}, \texttt{inputenc}, \texttt{makeidx}, \texttt{color}, \texttt{fancyvrb}, \texttt{pslatex} and \texttt{hyperref}. These are for example provided by the \textsf{teTeX-1.0} or \textsf{texlive} distributions of {\TeX} (which in turn are used for most {\TeX} packages of current Linux distributions); see \href{http://www.tug.org/tetex/} {\texttt{http://www.tug.org/tetex/}}.
In particular, the resulting \texttt{pdf}-output (and \texttt{dvi}-output) contains (internal and external) hyperlinks which can be very useful
for 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 of 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}
Non-ASCII characters in the \textsf{GAPDoc} document are translated to {\LaTeX} input in ASCII-encoding with the help of \texttt{Encode} (\ref{Encode}) and the option \texttt{"LaTeX"}. See the documentation of \texttt{Encode} (\ref{Encode}) for how to proceed if you have a character which is not handled (yet).
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. Many of these handler functions (usually in \texttt{GAPDoc2LaTeXProcs.{\textless}ElementName{\textgreater}}) are not difficult to understand (the greatest complications are some
commands for index entries, labels or the output of page number information).
So it should be easy to adjust layout details to your own taste by slight
modifications of the program.
A few settings can be adjusted by the function \texttt{SetGapDocLaTeXOptions}. It takes strings as arguments. If the arguments contain one of the strings \texttt{"pdf"}, \texttt{"dvi"} or \texttt{"ps"} then {\LaTeX}s \texttt{hyperref} package is configured for optimized output of the given format (default is \texttt{"pdf"}). If \texttt{"color"} or \texttt{"nocolor"} is in the argument list then colors are used or not used, respectively. The
default is to use colors but \texttt{"nocolor"} can be useful for a printable version of a manual (but who wants to print such
manuals?). If "utf8" is an argument then the package \texttt{inputenc} is used with \texttt{UTF-8} encoding, instead of the default \texttt{latin1}. If \texttt{"nopslatex"} is an argument then the package \texttt{pslatex} is not used, otherwise it is.
}
\subsection{\textcolor{Chapter }{GAPDoc2Text}}
\logpage{[ 5, 3, 2 ]}\nobreak
\hyperdef{L}{X86CD0B197CD58D2A}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GAPDoc2Text({\slshape tree[, bibpath][, width]})\index{GAPDoc2Text@\texttt{GAPDoc2Text}}
\label{GAPDoc2Text}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
record containing text files as strings and other information
The argument \mbox{\texttt{\slshape tree}} for this function is a tree describing a \textsf{GAPDoc} XML document as returned by \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}) (probably also checked with \texttt{CheckAndCleanGapDocTree} (\ref{CheckAndCleanGapDocTree})). This function produces a text version of the document which can be used
with \textsf{GAP}'s online help (with the \texttt{"screen"} viewer, see \texttt{SetHelpViewer} (\textbf{Reference: SetHelpViewer})). It includes title page, bibliography and index. The bibliography is made
from BibXMLext or Bib{\TeX} databases, see \ref{ch:bibutil}. Their location must be given with the argument \mbox{\texttt{\slshape bibpath}} (as string or directory object).
The output is a record with one component for each chapter (with names \texttt{"0"}, \texttt{"1"}, ..., \texttt{"Bib"} and \texttt{"Ind"}). Each such component is again a record with the following components:
\begin{description}
\item[{\texttt{text}}] the text of the whole chapter as a string
\item[{\texttt{ssnr}}] list of subsection numbers in this chapter (like \texttt{[3, 2, 1]} for chapter{\nobreakspace}3, section{\nobreakspace}2,
subsection{\nobreakspace}1)
\item[{\texttt{linenr}}] corresponding list of line numbers where the subsections start
\item[{\texttt{len}}] number of lines of this chapter
\end{description}
The result can be written into files with the command \texttt{GAPDoc2TextPrintTextFiles} (\ref{GAPDoc2TextPrintTextFiles}).
As a side effect this function also produces the \texttt{manual.six} information which is used for searching in \textsf{GAP}'s online help. This is stored in \texttt{\mbox{\texttt{\slshape tree}}.six} and can be printed into a \texttt{manual.six} file with \texttt{PrintSixFile} (\ref{PrintSixFile}) (preferably after producing a {\LaTeX} version of the document as well and adding the page number information to \texttt{\mbox{\texttt{\slshape tree}}.six}, see \texttt{GAPDoc2LaTeX} (\ref{GAPDoc2LaTeX}) and \texttt{AddPageNumbersToSix} (\ref{AddPageNumbersToSix})).
The text produced by this function contains some markup via ANSI escape
sequences. The sequences used here are usually ignored by terminals. But the \textsf{GAP} help system will substitute them by interpreted color and attribute sequences
(see \texttt{TextAttr} (\ref{TextAttr})) before displaying them. There is a default markup used for this but it can
also be configured by the user, see \texttt{SetGAPDocTextTheme} (\ref{SetGAPDocTextTheme}). Furthermore, the text produced is in UTF-8 encoding. The encoding is also
translated on the fly, if \texttt{GAPInfo.TermEncoding} is set to some encoding supported by \texttt{Encode} (\ref{Encode}), e.g., \texttt{"ISO-8859-1"} or \texttt{"latin1"}.
With the optional argument \mbox{\texttt{\slshape width}} a different length of the output text lines can be chosen. The default is 76
and all lines in the resulting text start with two spaces. This looks good on
a terminal with a standard width of 80 characters and you probably don't want
to use this argument. }
\subsection{\textcolor{Chapter }{GAPDoc2TextPrintTextFiles}}
\logpage{[ 5, 3, 3 ]}\nobreak
\hyperdef{L}{X7DFCE7357D6032A2}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GAPDoc2TextPrintTextFiles({\slshape t[, path]})\index{GAPDoc2TextPrintTextFiles@\texttt{GAPDoc2TextPrintTextFiles}}
\label{GAPDoc2TextPrintTextFiles}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing
The first argument must be a result returned by \texttt{GAPDoc2Text} (\ref{GAPDoc2Text}). The second argument is a path for the files to write, it can be given as
string or directory object. The text of each chapter is written into a
separate file with name \texttt{chap0.txt}, \texttt{chap1.txt}, ..., \texttt{chapBib.txt}, and \texttt{chapInd.txt}.
If you want to make your document accessible via the \textsf{GAP} online help you must put at least these files for the text version into a
directory, together with the file \texttt{manual.six}, see \texttt{PrintSixFile} (\ref{PrintSixFile}). Then specify the path to the \texttt{manual.six} file in the packages \texttt{PackageInfo.g} file, see (\textbf{Extending: The PackageInfo.g File}).
Optionally you can add the \texttt{dvi}- and \texttt{pdf}-versions of the document which are produced with \texttt{GAPDoc2LaTeX} (\ref{GAPDoc2LaTeX}) to this directory. The files must have the names \texttt{manual.dvi} and \texttt{manual.pdf}, respectively. Also you can add the files of the HTML version produced with \texttt{GAPDoc2HTML} (\ref{GAPDoc2HTML}) to this directory, see \texttt{GAPDoc2HTMLPrintHTMLFiles} (\ref{GAPDoc2HTMLPrintHTMLFiles}). The handler functions in \textsf{GAP} for this help format detect automatically which of the optional formats of a
book are actually available. }
\subsection{\textcolor{Chapter }{AddPageNumbersToSix}}
\logpage{[ 5, 3, 4 ]}\nobreak
\hyperdef{L}{X7EB5E86F87A09F94}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AddPageNumbersToSix({\slshape tree, pnrfile})\index{AddPageNumbersToSix@\texttt{AddPageNumbersToSix}}
\label{AddPageNumbersToSix}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing
Here \mbox{\texttt{\slshape tree}} must be the XML tree of a \textsf{GAPDoc} document, returned by \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}). Running \texttt{latex} on the result of \texttt{GAPDoc2LaTeX} (\ref{GAPDoc2LaTeX})\texttt{(\mbox{\texttt{\slshape tree}})} produces a file \mbox{\texttt{\slshape pnrfile}} (with extension \texttt{.pnr}). The command \texttt{GAPDoc2Text} (\ref{GAPDoc2Text})\texttt{(\mbox{\texttt{\slshape tree}})} creates a component \texttt{\mbox{\texttt{\slshape tree}}.six} which contains all information about the document for the \textsf{GAP} online help, except the page numbers in the \texttt{.dvi, .ps, .pdf} versions of the document. This command adds the missing page number
information to \texttt{\mbox{\texttt{\slshape tree}}.six}. }
\subsection{\textcolor{Chapter }{PrintSixFile}}
\logpage{[ 5, 3, 5 ]}\nobreak
\hyperdef{L}{X7D42CFED7885BC00}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PrintSixFile({\slshape tree, bookname, fname})\index{PrintSixFile@\texttt{PrintSixFile}}
\label{PrintSixFile}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing
This function prints the \texttt{.six} file \mbox{\texttt{\slshape fname}} for a \textsf{GAPDoc} document stored in \mbox{\texttt{\slshape tree}} with name \mbox{\texttt{\slshape bookname}}. Such a file contains all information about the book which is needed by the \textsf{GAP} online help. This information must first be created by calls of \texttt{GAPDoc2Text} (\ref{GAPDoc2Text}) and \texttt{AddPageNumbersToSix} (\ref{AddPageNumbersToSix}). }
\subsection{\textcolor{Chapter }{SetGAPDocTextTheme}}
\logpage{[ 5, 3, 6 ]}\nobreak
\hyperdef{L}{X7DEB37417BBD8941}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SetGAPDocTextTheme({\slshape [optrec]})\index{SetGAPDocTextTheme@\texttt{SetGAPDocTextTheme}}
\label{SetGAPDocTextTheme}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing
With this function can readers of the screen version of \textsf{GAP} manuals which are generated by the \textsf{GAPDoc} package configure the color and attribute layout of the displayed text. There
is a default which can be reset by calling this function without argument.
As an abbreviation the argument \mbox{\texttt{\slshape optrec}} can be a string for the known name of a theme. Currently, there is only \texttt{"none"} which displays just the plain text without any markup.
Otherwise, \mbox{\texttt{\slshape optrec}} must be a record. Its entries overwrite the corresponding entries in the
default. To construct valid markup you can use \texttt{TextAttr} (\ref{TextAttr}). The following components are recognized:
\begin{description}
\item[{\texttt{reset}}] reset to default, don't change this
\item[{\texttt{Heading}}] chapter and (sub-)section headings
\item[{\texttt{Func}}] function, operation, ... names
\item[{\texttt{Arg}}] argument names in descriptions
\item[{\texttt{Example}}] example code
\item[{\texttt{Package}}] package names
\item[{\texttt{Returns}}] Returns-line in descriptions
\item[{\texttt{URL}}] URLs
\item[{\texttt{Mark}}] Marks in description lists
\item[{\texttt{K}}] \textsf{GAP} keywords
\item[{\texttt{C}}] code or text to type
\item[{\texttt{F}}] file names
\item[{\texttt{B}}] buttons
\item[{\texttt{Emph}}] emphasized text
\item[{\texttt{Ref}}] reference text
\item[{\texttt{BibReset}}] reset for bibliography, don't change
\item[{\texttt{BibAuthor}}] author names in bibliography
\item[{\texttt{BibTitle}}] titles in bibliography
\item[{\texttt{BibJournal}}] journal names in bibliography
\item[{\texttt{BibVolume}}] volume number in bibliography
\item[{\texttt{BibLabel}}] labels for bibliography entries
\end{description}
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
gap> # change display of headings to bold green
gap> SetGAPDocTextTheme(rec(
> Heading:=Concatenation(TextAttr.bold, TextAttr.2)));
\end{Verbatim}
}
\subsection{\textcolor{Chapter }{GAPDoc2HTML}}
\logpage{[ 5, 3, 7 ]}\nobreak
\hyperdef{L}{X84F22EEB78845CFD}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GAPDoc2HTML({\slshape tree[, bibpath[, gaproot]][, mtrans]})\index{GAPDoc2HTML@\texttt{GAPDoc2HTML}}
\label{GAPDoc2HTML}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
record containing HTML files as strings and other information
The argument \mbox{\texttt{\slshape tree}} for this function is a tree describing a \textsf{GAPDoc} XML document as returned by \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}) (probably also checked with \texttt{CheckAndCleanGapDocTree} (\ref{CheckAndCleanGapDocTree})). Without an \mbox{\texttt{\slshape mtrans}} argument this function produces an HTML version of the document which can be
read with any Web-browser and also be used with \textsf{GAP}'s online help (see \texttt{SetHelpViewer} (\textbf{Reference: SetHelpViewer})). It includes title page, bibliography, and index. The bibliography is made
from Bib{\TeX} databases. Their location must be given with the argument \mbox{\texttt{\slshape bibpath}} (as string or directory object, if not given the current directory is used).
If the third argument \mbox{\texttt{\slshape gaproot}} is given and is a string then this string is interpreted as relative path to \textsf{GAP}'s main root directory. Reference-URLs to external HTML-books which begin with
the \textsf{GAP} root path are then rewritten to start with the given relative path. This makes
the HTML-documentation portable provided a package is installed in some
standard location below the \textsf{GAP} root.
The output is a record with one component for each chapter (with names \texttt{"0"}, \texttt{"1"}, ..., \texttt{"Bib"}, and \texttt{"Ind"}). Each such component is again a record with the following components:
\begin{description}
\item[{\texttt{text}}] the text of an HTML file containing the whole chapter (as a string)
\item[{\texttt{ssnr}}] list of subsection numbers in this chapter (like \texttt{[3, 2, 1]} for chapter{\nobreakspace}3, section{\nobreakspace}2,
subsection{\nobreakspace}1)
\end{description}
\emph{Standard output format without} \mbox{\texttt{\slshape mtrans}} \emph{argument}
The HTML code produced with this converter conforms to the W3C specification ``XHTML 1.0 strict'', see \href{http://www.w3.org/TR/xhtml1} {\texttt{http://www.w3.org/TR/xhtml1}}. First, this means that the HTML files are valid XML files. Secondly, the
extension ``strict'' says in particular that the code doesn't contain any explicit font or color
information.
Mathematical formulae are handled as in the text converter \texttt{GAPDoc2Text} (\ref{GAPDoc2Text}). We don't want to assume that the browser can use symbol fonts. Some \textsf{GAP} users like to browse the online help with \texttt{lynx}, see \texttt{SetHelpViewer} (\textbf{Reference: SetHelpViewer}), which runs inside the same terminal windows as \textsf{GAP}.
\emph{Using a stylesheet file}
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}.
\label{mtransarg} \emph{Output format with} \mbox{\texttt{\slshape mtrans}} argument
Currently, there are two experimental variants of this converter available
which handle mathematical formulae differently. They are accessed via the
optional last \mbox{\texttt{\slshape mtrans}} argument.
If this argument is set to \texttt{"Tth"} it is assumed that you have installed the {\LaTeX} to HTML translation program \texttt{tth}. This is used to translate the contents of the \texttt{M}, \texttt{Math} and \texttt{Display} elements into HTML code. Note that the resulting code is not compliant with
any standard. Formally it is ``XHTML 1.0 Transitional'', it contains explicit font specifications and the characters of mathematical
symbols are included via their position in a ``Symbol'' font. Some graphical browsers can be configured to display this in a useful
manner, check \href{http://hutchinson.belmont.ma.us/tth/} {the Tth homepage} for more details.
If the \mbox{\texttt{\slshape mtrans}} argument is set to \texttt{"MathML"} it is assumed that you have installed the translation program \texttt{ttm}, see also \href{http://hutchinson.belmont.ma.us/tth/} {the Tth homepage}). This is used to translate the contents of the \texttt{M}, \texttt{Math} and \texttt{Display} elements to MathML 2.0 markup. The resulting files should conform to the
"XHTML 1.1 plus MathML 2.0" standard, see \href{http://www.w3.org/TR/MathML2/} {the W3C information} for more details. It is expected that the next generation of graphical
browsers will be able to render such files (try for example \texttt{Mozilla}, at least 0.9.9). You must copy the \texttt{.xsl} and \texttt{.css} files from \textsf{GAPDoc}s \texttt{mathml} directory to the directory containing the output files. The translation with \texttt{ttm} is still experimental. The output of this converter variant is garbage for
browsers which don't support MathML.
This function works by running recursively through the document tree and
calling a handler function for each \textsf{GAPDoc} XML element. Many of these handler functions (usually in \texttt{GAPDoc2TextProcs.{\textless}ElementName{\textgreater}}) are not difficult to understand (the greatest complications are some
commands for index entries, labels or the output of page number information).
So it should be easy to adjust certain details to your own taste by slight
modifications of the program.
The result of this converter can be written to files with the command \texttt{GAPDoc2HTMLPrintHTMLFiles} (\ref{GAPDoc2HTMLPrintHTMLFiles}).
}
\subsection{\textcolor{Chapter }{GAPDoc2HTMLPrintHTMLFiles}}
\logpage{[ 5, 3, 8 ]}\nobreak
\hyperdef{L}{X84A7007778073E7A}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GAPDoc2HTMLPrintHTMLFiles({\slshape t[, path]})\index{GAPDoc2HTMLPrintHTMLFiles@\texttt{GAPDoc2HTMLPrintHTMLFiles}}
\label{GAPDoc2HTMLPrintHTMLFiles}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing
The first argument must be a result returned by \texttt{GAPDoc2HTML} (\ref{GAPDoc2HTML}). The second argument is a path for the files to write, it can be given as
string or directory object. The text of each chapter is written into a
separate file with name \texttt{chap0.html}, \texttt{chap1.html}, ..., \texttt{chapBib.html}, and \texttt{chapInd.html}.
The experimental versions which are produced with \texttt{tth} or \texttt{ttm} use different names for the files, namely \texttt{chap0{\textunderscore}sym.html}, and so on for files which need symbol fonts and \texttt{chap0{\textunderscore}mml.xml} for files with MathML translations.
You may also want to place a style sheet file \texttt{manual.css} into the same directory as the HTML files. You can copy for example the file \texttt{gapdoc.css} in the root directory of the \textsf{GAPDoc} package (\texttt{Filename( Directory( PackageInfo( "gapdoc" )[1].InstallationPath),
"gapdoc.css");}). }
\subsection{\textcolor{Chapter }{InfoGAPDoc}}
\logpage{[ 5, 3, 9 ]}\nobreak
\hyperdef{L}{X864A528B81C661A2}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{InfoGAPDoc\index{InfoGAPDoc@\texttt{InfoGAPDoc}}
\label{InfoGAPDoc}
}\hfill{\scriptsize (info class)}}\\
The default level of this info class is 1. The converter functions for \textsf{GAPDoc} documents are then printing some information. You can suppress this by setting
the level of \texttt{InfoGAPDoc} to 0. With level 2 there may be some more information for debugging purposes. }
\subsection{\textcolor{Chapter }{SetGapDocLanguage}}
\logpage{[ 5, 3, 10 ]}\nobreak
\hyperdef{L}{X82AB468887ED0DBB}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SetGapDocLanguage({\slshape [lang]})\index{SetGapDocLanguage@\texttt{SetGapDocLanguage}}
\label{SetGapDocLanguage}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing
\index{Using \textsf{GAPDoc} with other languages} The \textsf{GAPDoc} converter programs sometimes produce text which is not explicit in the
document, e.g., headers like ``Abstract'', ``Appendix'', links to ``Next Chapter'', variable types ``function'' and so on.
With \texttt{SetGapDocLanguage} the language for these texts can be changed. The argument \mbox{\texttt{\slshape lang}} must be a string. Calling without argument or with a language name for which
no translations are available is the same as using the default \texttt{"english"}.
If your language \mbox{\texttt{\slshape lang}} is not yet available, look at the record \texttt{GAPDocTexts.english} and translate all the strings to \mbox{\texttt{\slshape lang}}. Then assign this record to \texttt{GAPDocTexts.(\mbox{\texttt{\slshape lang}})} and send it to the \textsf{GAPDoc} authors for inclusion in future versions of \textsf{GAPDoc}. (Currently, there are translations for \texttt{english}, \texttt{german}, \texttt{russian} and \texttt{ukrainian}.)
\emph{Further hints:} To get strings produced by {\LaTeX} right you will probably use the \texttt{babel} package with option \mbox{\texttt{\slshape lang}}, see the information on \texttt{ExtraPreamble} in \texttt{GAPDoc2LaTeX} (\ref{GAPDoc2LaTeX}). If \mbox{\texttt{\slshape lang}} cannot be encoded in \texttt{latin1} encoding you can consider the use of \texttt{"utf8"} with \texttt{SetGapDocLaTeXOptions} (\ref{SetGapDocLaTeXOptions}). }
}
\section{\textcolor{Chapter }{Testing Manual Examples}}\label{Sec:TestExample}
\logpage{[ 5, 4, 0 ]}
\hyperdef{L}{X800299827B88ABBE}{}
{
We also provide some tools to check the examples given in \texttt{{\textless}Example{\textgreater}}-elements.
\subsection{\textcolor{Chapter }{ManualExamples}}
\logpage{[ 5, 4, 1 ]}\nobreak
\hyperdef{L}{X7AD38E77784572A1}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ManualExamples({\slshape path, main, files, units})\index{ManualExamples@\texttt{ManualExamples}}
\label{ManualExamples}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a list of strings
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ManualExamplesXMLTree({\slshape tree, units})\index{ManualExamplesXMLTree@\texttt{ManualExamplesXMLTree}}
\label{ManualExamplesXMLTree}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a list of strings
The argument \mbox{\texttt{\slshape tree}} must be a parse tree of a \textsf{GAPDoc} document, see \texttt{ParseTreeXMLFile} (\ref{ParseTreeXMLFile}). The function \texttt{ManualExamplesXMLTree} returns a list of strings containing the content of \texttt{{\textless}Example{\textgreater}} elements. For each example there is a comment line showing the paragraph
number and (if available) the original location of this example with file and
line number. Depending on the argument \mbox{\texttt{\slshape units}} several examples are colleected in one string. Recognized values for \mbox{\texttt{\slshape units}} are \texttt{"Chapter"}, \texttt{"Section"}, \texttt{"Subsection"} or \texttt{"Single"}. The latter means that each example is in a separate string. For all other
value of \mbox{\texttt{\slshape units}} just one string with all examples is returned.
The arguments \mbox{\texttt{\slshape path}}, \mbox{\texttt{\slshape main}} and \mbox{\texttt{\slshape files}} of \texttt{ManualExamples} are the same as for \texttt{ComposedDocument} (\ref{ComposedDocument}). This function first contructs and parses the \textsf{GAPDoc} document and then applies \texttt{ManualExamplesXMLTree}. }
\subsection{\textcolor{Chapter }{ReadTestExamplesString}}
\logpage{[ 5, 4, 2 ]}\nobreak
\hyperdef{L}{X7F2555E07C499554}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ReadTestExamplesString({\slshape str})\index{ReadTestExamplesString@\texttt{ReadTestExamplesString}}
\label{ReadTestExamplesString}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
\texttt{true} or \texttt{false}
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{TestExamplesString({\slshape str[, print]})\index{TestExamplesString@\texttt{TestExamplesString}}
\label{TestExamplesString}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
\texttt{true} or a list of records
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{TestManualExamples({\slshape [tree, ][path, main, files]})\index{TestManualExamples@\texttt{TestManualExamples}}
\label{TestManualExamples}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
\texttt{true} or a list of records
The argument \mbox{\texttt{\slshape str}} must be a string containing lines for the test mode of \textsf{GAP}. The function \texttt{ReadTestExamplesString} just runs \texttt{ReadTest} (\textbf{Reference: ReadTest}) on this code.
The function \texttt{TestExamplesString} returns \texttt{true} if \texttt{ReadTest} (\textbf{Reference: ReadTest}) does not find differences. In the other case it returns a list of records,
where each record describes one difference. The records have fields \texttt{.line} with the line number of the relevant input line of \mbox{\texttt{\slshape str}}, \texttt{.input} with the input line and \texttt{.diff} with the differences as displayed by \texttt{ReadTest} (\textbf{Reference: ReadTest}). If the optional argument \mbox{\texttt{\slshape print}} is given and set to \texttt{true} then the differences are also printed before the function returns.
The arguments of the function \texttt{TestManualExamples} is either a parse tree of a \textsf{GAPDoc} document or the information to build and parse such a document. The function
extracts all examples in \texttt{"Single"} units and applies \texttt{TestExamplesString} to them.
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
gap> TestExamplesString("gap> 1+1;\n2\n");
true
gap> TestExamplesString("gap> 1+1;\n2\ngap> 2+3;\n4\n");
[ rec( line := 3, input := "gap> 2+3;", diff := "+ 5\n- 4\n" ) ]
gap> TestExamplesString("gap> 1+1;\n2\ngap> 2+3;\n4\n", true);
----------- bad example --------
line: 3
input: gap> 2+3;
differences:
+ 5
- 4
[ rec( line := 3, input := "gap> 2+3;", diff := "+ 5\n- 4\n" ) ]
\end{Verbatim}
}
}
}
\chapter{\textcolor{Chapter }{String and Text Utilities}}\label{ch:util}
\logpage{[ 6, 0, 0 ]}
\hyperdef{L}{X86CEF540862EE042}{}
{
\section{\textcolor{Chapter }{Text Utilities}}\label{TextUtil}
\logpage{[ 6, 1, 0 ]}
\hyperdef{L}{X847DA07C7C46B38A}{}
{
This section describes some utility functions for handling texts within \textsf{GAP}. They are used by the functions in the \textsf{GAPDoc} package but may be useful for other purposes as well. We start with some
variables containing useful strings and go on with functions for parsing and
reformatting text.
\subsection{\textcolor{Chapter }{WHITESPACE}}
\logpage{[ 6, 1, 1 ]}\nobreak
\hyperdef{L}{X786D477C7AB636AA}{}
{\noindent\textcolor{FuncColor}{$\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[{\texttt{WHITESPACE}}] \texttt{" \texttt{\symbol{92}}n\texttt{\symbol{92}}t\texttt{\symbol{92}}r"}
\item[{\texttt{CAPITALLETTERS}}] \texttt{"ABCDEFGHIJKLMNOPQRSTUVWXYZ"}
\item[{\texttt{SMALLLETTERS}}] \texttt{"abcdefghijklmnopqrstuvwxyz"}
\item[{\texttt{LETTERS}}] concatenation of \texttt{CAPITALLETTERS} and \texttt{SMALLLETTERS}
\item[{\texttt{DIGITS}}] \texttt{"0123456789"}
\item[{\texttt{HEXDIGITS}}] \texttt{"0123456789ABCDEFabcdef"}
\end{description}
}
\subsection{\textcolor{Chapter }{TextAttr}}
\logpage{[ 6, 1, 2 ]}\nobreak
\hyperdef{L}{X785F61E77899580E}{}
{\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 }{WrapTextAttribute}}
\logpage{[ 6, 1, 3 ]}\nobreak
\hyperdef{L}{X7B8AD7517E5FD0EA}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{WrapTextAttribute({\slshape str, attr})\index{WrapTextAttribute@\texttt{WrapTextAttribute}}
\label{WrapTextAttribute}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a string with markup
The argument \mbox{\texttt{\slshape str}} must be a text as \textsf{GAP} string, possibly with markup by escape sequences as in \texttt{TextAttr} (\ref{TextAttr}). This function returns a string which is wrapped by the escape sequences \mbox{\texttt{\slshape attr}} and \texttt{TextAttr.reset}. It takes care of markup in the given string by appending \mbox{\texttt{\slshape attr}} also after each given \texttt{TextAttr.reset} in \mbox{\texttt{\slshape str}}.
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
gap> str := Concatenation("XXX",TextAttr.2, "BLUB", TextAttr.reset,"YYY");
"XXX\033[32mBLUB\033[0mYYY"
gap> str2 := WrapTextAttribute(str, TextAttr.1);
"\033[31mXXX\033[32mBLUB\033[0m\033[31mYYY\033[0m"
gap> str3 := WrapTextAttribute(str, TextAttr.underscore);
"\033[4mXXX\033[32mBLUB\033[0m\033[4mYYY\033[0m"
gap> # use Print(str); and so on to see how it looks like.
\end{Verbatim}
}
\subsection{\textcolor{Chapter }{FormatParagraph}}
\logpage{[ 6, 1, 4 ]}\nobreak
\hyperdef{L}{X812058CE7C8E9022}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FormatParagraph({\slshape str[, len][, flush][, attr][, widthfun], ]]})\index{FormatParagraph@\texttt{FormatParagraph}}
\label{FormatParagraph}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
the formatted paragraph as string
This function formats a text given in the string \mbox{\texttt{\slshape str}} as a paragraph. The optional arguments have the following meaning:
\begin{description}
\item[{\mbox{\texttt{\slshape len}}}] the length of the lines of the resulting text (default is \texttt{78})
\item[{\mbox{\texttt{\slshape flush}}}] can be \texttt{"left"}, \texttt{"right"}, \texttt{"center"} or \texttt{"both"}, telling that lines should be flushed left, flushed right, centered or
left-right justified, respectively (default is \texttt{"both"})
\item[{\mbox{\texttt{\slshape attr}}}] is a list of two strings; the first is prepended and the second appended to
each line of the result (can for example be used for indenting, \texttt{[" ", ""]}, or some markup, \texttt{[TextAttr.bold, TextAttr.reset]}, default is \texttt{["", ""]})
\item[{\mbox{\texttt{\slshape widthfun}}}] must be a function which returns the display width of text in \mbox{\texttt{\slshape str}}. The default is \texttt{Length} assuming that each byte corresponds to a character of width one. If \mbox{\texttt{\slshape str}} is given in \texttt{UTF-8} encoding one can use \texttt{WidthUTF8String} (\ref{WidthUTF8String}) here.
\end{description}
This function tries to handle markup with the escape sequences explained in \texttt{TextAttr} (\ref{TextAttr}) correctly.
\begin{Verbatim}[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{[ 6, 1, 5 ]}\nobreak
\hyperdef{L}{X82A9121678923445}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SubstitutionSublist({\slshape list, sublist, new[, flag]})\index{SubstitutionSublist@\texttt{SubstitutionSublist}}
\label{SubstitutionSublist}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
the changed list
This function looks for (non-overlapping) occurrences of a sublist \mbox{\texttt{\slshape sublist}} in a list \mbox{\texttt{\slshape list}} (compare \texttt{PositionSublist} (\textbf{Reference: PositionSublist})) and returns a list where these are substituted with the list \mbox{\texttt{\slshape new}}.
The optional argument \mbox{\texttt{\slshape flag}} can either be \texttt{"all"} (this is the default if not given) or \texttt{"one"}. In the second case only the first occurrence of \mbox{\texttt{\slshape sublist}} is substituted.
If \mbox{\texttt{\slshape sublist}} does not occur in \mbox{\texttt{\slshape list}} then \mbox{\texttt{\slshape 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{[ 6, 1, 6 ]}\nobreak
\hyperdef{L}{X83DE31017B557136}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StripBeginEnd({\slshape list, strip})\index{StripBeginEnd@\texttt{StripBeginEnd}}
\label{StripBeginEnd}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
changed string
Here \mbox{\texttt{\slshape list}} and \mbox{\texttt{\slshape strip}} must be lists. This function returns the sublist of list which does not
contain the leading and trailing entries which are entries of \mbox{\texttt{\slshape strip}}. If the result is equal to \mbox{\texttt{\slshape list}} then \mbox{\texttt{\slshape 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{[ 6, 1, 7 ]}\nobreak
\hyperdef{L}{X7A5978CF84C3C2D3}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StripEscapeSequences({\slshape str})\index{StripEscapeSequences@\texttt{StripEscapeSequences}}
\label{StripEscapeSequences}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
string without escape sequences
This function returns the string one gets from the string \mbox{\texttt{\slshape str}} by removing all escape sequences which are explained in \texttt{TextAttr} (\ref{TextAttr}). If \mbox{\texttt{\slshape str}} does not contain such a sequence then \mbox{\texttt{\slshape str}} itself is returned. }
\subsection{\textcolor{Chapter }{RepeatedString}}
\logpage{[ 6, 1, 8 ]}\nobreak
\hyperdef{L}{X7D71CB837EE969D4}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RepeatedString({\slshape c, len})\index{RepeatedString@\texttt{RepeatedString}}
\label{RepeatedString}
}\hfill{\scriptsize (function)}}\\
Here \mbox{\texttt{\slshape c}} must be either a character or a string and \mbox{\texttt{\slshape len}} is a non-negative number. Then \texttt{RepeatedString} returns a string of length \mbox{\texttt{\slshape len}} consisting of copies of \mbox{\texttt{\slshape c}}.
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
gap> RepeatedString('=',51);
"==================================================="
gap> RepeatedString("*=",51);
"*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*"
\end{Verbatim}
}
\subsection{\textcolor{Chapter }{NumberDigits}}
\logpage{[ 6, 1, 9 ]}\nobreak
\hyperdef{L}{X7CEEA5B57D7BB38F}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{NumberDigits({\slshape str, base})\index{NumberDigits@\texttt{NumberDigits}}
\label{NumberDigits}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
integer
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DigitsNumber({\slshape n, base})\index{DigitsNumber@\texttt{DigitsNumber}}
\label{DigitsNumber}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
string
The argument \mbox{\texttt{\slshape str}} of \texttt{NumberDigits} must be a string consisting only of an optional leading \texttt{'-'} and characters in \texttt{0123456789abcdefABCDEF}, describing an integer in base \mbox{\texttt{\slshape base}} with $2 \leq \mbox{\texttt{\slshape 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{[ 6, 1, 10 ]}\nobreak
\hyperdef{L}{X7AF694D9839BF65C}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PositionMatchingDelimiter({\slshape str, delim, pos})\index{PositionMatchingDelimiter@\texttt{PositionMatchingDelimiter}}
\label{PositionMatchingDelimiter}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
position as integer or \texttt{fail}
Here \mbox{\texttt{\slshape str}} must be a string and \mbox{\texttt{\slshape delim}} a string with two different characters. This function searches the smallest
position \texttt{r} of the character \texttt{\mbox{\texttt{\slshape delim}}[2]} in \mbox{\texttt{\slshape str}} such that the number of occurrences of \texttt{\mbox{\texttt{\slshape delim}}[2]} in \mbox{\texttt{\slshape str}} between positions \texttt{\mbox{\texttt{\slshape pos}}+1} and \texttt{r} is by one greater than the corresponding number of occurrences of \texttt{\mbox{\texttt{\slshape 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{[ 6, 1, 11 ]}\nobreak
\hyperdef{L}{X832556617F10AAA8}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{WordsString({\slshape str})\index{WordsString@\texttt{WordsString}}
\label{WordsString}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
list of strings containing the words
This returns the list of words of a text stored in the string \mbox{\texttt{\slshape 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}
}
\subsection{\textcolor{Chapter }{Base64String}}
\logpage{[ 6, 1, 12 ]}\nobreak
\hyperdef{L}{X83F2821783DA9826}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Base64String({\slshape str})\index{Base64String@\texttt{Base64String}}
\label{Base64String}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StringBase64({\slshape bstr})\index{StringBase64@\texttt{StringBase64}}
\label{StringBase64}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a string
The first function translates arbitrary binary data given as a GAP string into
a \emph{base 64} encoded string. This encoded string contains only printable ASCII characters
and is used in various data transfer protocols (\texttt{MIME} encoded emails, weak password encryption, ...). We use the specification in \href{http://tools.ietf.org/html/rfc2045} {RFCÂ 2045}.
The second function has the reverse functionality. Here we also accept the
characters \texttt{-{\textunderscore}} instead of \texttt{+/} as last two characters. Whitespace is ignored.
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
gap> b := Base64String("This is a secret!");
"VGhpcyBpcyBhIHNlY3JldCEA="
gap> StringBase64(b);
"This is a secret!"
\end{Verbatim}
}
}
\section{\textcolor{Chapter }{Unicode Strings}}\label{sec:Unicode}
\logpage{[ 6, 2, 0 ]}
\hyperdef{L}{X8489C67D80399814}{}
{
The \textsf{GAPDoc} package provides some tools to deal with unicode characters and strings. These
can be used for recoding text strings between various encodings.
\subsection{\textcolor{Chapter }{Unicode Strings and Characters}}\logpage{[ 6, 2, 1 ]}
\hyperdef{L}{X8475671278948DDD}{}
{
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Unicode({\slshape list[, encoding]})\index{Unicode@\texttt{Unicode}}
\label{Unicode}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{UChar({\slshape num})\index{UChar@\texttt{UChar}}
\label{UChar}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsUnicodeString\index{IsUnicodeString@\texttt{IsUnicodeString}}
\label{IsUnicodeString}
}\hfill{\scriptsize (filter)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsUnicodeCharacter\index{IsUnicodeCharacter@\texttt{IsUnicodeCharacter}}
\label{IsUnicodeCharacter}
}\hfill{\scriptsize (filter)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IntListUnicodeString({\slshape ustr})\index{IntListUnicodeString@\texttt{IntListUnicodeString}}
\label{IntListUnicodeString}
}\hfill{\scriptsize (function)}}\\
Unicode characters are described by their \emph{codepoint}, an integer in the range from $0$ to $2^{21}-1$. For details about unicode, see \href{http://www.unicode.org} {\texttt{http://www.unicode.org}}.
The function \texttt{UChar} wraps an integer \mbox{\texttt{\slshape num}} into a \textsf{GAP} object lying in the filter \texttt{IsUnicodeCharacter}. Use \texttt{Int} to get the codepoint back. The argument \mbox{\texttt{\slshape num}} can also be a \textsf{GAP} character which is then translated to an integer via \texttt{INT{\textunderscore}CHAR} (\textbf{Reference: INT{\textunderscore}CHAR}).
\texttt{Unicode} produces a \textsf{GAP} object in the filter \texttt{IsUnicodeString}. This is a wrapped list of integers for the unicode characters in the string.
The function \texttt{IntListUnicodeString} gives access to this list of integers. Basic list functionality is available
for \texttt{IsUnicodeString} elements. The entries are in \texttt{IsUnicodeCharacter}. The argument \mbox{\texttt{\slshape list}} for \texttt{Unicode} is either a list of integers or a \textsf{GAP} string. In the latter case an \mbox{\texttt{\slshape encoding}} can be specified as string, its default is \texttt{"UTF-8"}.
\index{URL encoding}\index{RFC 3986} Currently supported encodings can be found in \texttt{UNICODE{\textunderscore}RECODE.NormalizedEncodings} (ASCII, ISO-8859-X, UTF-8 and aliases). The encoding \texttt{"XML"} means an ASCII encoding in which non-ASCII characters are specified by XML
character entities. The encoding \texttt{"URL"} is for URL-encoded (also called percent-encoded strings, as specified in RFC
3986 (\href{http://www.ietf.org/rfc/rfc3986.txt} {see here}). The listed encodings \texttt{"LaTeX"} and aliases cannot be used with \texttt{Unicode}. See the operation \texttt{Encode} (\ref{Encode}) for mapping a unicode string to a \textsf{GAP} string.
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
gap> ustr := Unicode("a and \366", "latin1");
Unicode("a and ö")
gap> ustr = Unicode("a and ö", "XML");
true
gap> IntListUnicodeString(ustr);
[ 97, 32, 97, 110, 100, 32, 246 ]
gap> ustr[7];
'ö'
\end{Verbatim}
}
\subsection{\textcolor{Chapter }{Encode}}
\logpage{[ 6, 2, 2 ]}\nobreak
\hyperdef{L}{X818A31567EB30A39}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Encode({\slshape ustr[, encoding]})\index{Encode@\texttt{Encode}}
\label{Encode}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
a \textsf{GAP} string
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SimplifiedUnicodeString({\slshape ustr[, encoding][, "single"]})\index{SimplifiedUnicodeString@\texttt{SimplifiedUnicodeString}}
\label{SimplifiedUnicodeString}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a unicode string
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{LowercaseUnicodeString({\slshape ustr})\index{LowercaseUnicodeString@\texttt{LowercaseUnicodeString}}
\label{LowercaseUnicodeString}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a unicode string
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{UppercaseUnicodeString({\slshape ustr})\index{UppercaseUnicodeString@\texttt{UppercaseUnicodeString}}
\label{UppercaseUnicodeString}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a unicode string
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{LaTeXUnicodeTable\index{LaTeXUnicodeTable@\texttt{LaTeXUnicodeTable}}
\label{LaTeXUnicodeTable}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SimplifiedUnicodeTable\index{SimplifiedUnicodeTable@\texttt{SimplifiedUnicodeTable}}
\label{SimplifiedUnicodeTable}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{LowercaseUnicodeTable\index{LowercaseUnicodeTable@\texttt{LowercaseUnicodeTable}}
\label{LowercaseUnicodeTable}
}\hfill{\scriptsize (global variable)}}\\
The operation \texttt{Encode} translates a unicode string \mbox{\texttt{\slshape ustr}} into a \textsf{GAP} string in some specified \mbox{\texttt{\slshape encoding}}. The default encoding is \texttt{"UTF-8"}.
Supported encodings can be found in \texttt{UNICODE{\textunderscore}RECODE.NormalizedEncodings}. Except for some cases mentioned below characters which are not available in
the target encoding are substituted by '?' characters.
If the \mbox{\texttt{\slshape encoding}} is \texttt{"URL"} (see \texttt{Unicode} (\ref{Unicode})) then an optional argument \mbox{\texttt{\slshape encreserved}} can be given, it must be a list of reserved characters which should be percent
encoded; the default is to encode only the \texttt{\%} character.
The encoding \texttt{"LaTeX"} substitutes non-ASCII characters and {\LaTeX} special characters by {\LaTeX} code as given in an ordered list \texttt{LaTeXUnicodeTable} of pairs [codepoint, string]. If you have a unicode character for which no
substitution is contained in that list, you will get a warning and the
translation is \texttt{Unicode(nr)}. In this case find a substitution and add a corresponding [codepoint, string]
pair to \texttt{LaTeXUnicodeTable} using \texttt{AddSet} (\textbf{Reference: AddSet}). Also, please, tell the \textsf{GAPDoc} authors about your addition, such that we can extend the list \texttt{LaTeXUnicodeTable}. (Most of the initial entries were generated from lists in the {\TeX} projects enc{\TeX} and \texttt{ucs}.) There are some variants of this encoding:
\texttt{"LaTeXleavemarkup"} does the same translations for non-ASCII characters but leaves the {\LaTeX} special characters (e.g., any {\LaTeX} commands) as they are.
\texttt{"LaTeXUTF8"} does not give a warning about unicode characters without explicit translation,
instead it translates the character to its \texttt{UTF-8} encoding. Make sure to setup your {\LaTeX} document such that all these characters are understood.
\texttt{"LaTeXUTF8leavemarkup"} is a combination of the last two variants.
Note that the \texttt{"LaTeX"} encoding can only be used with \texttt{Encode} but not for the opposite translation with \texttt{Unicode} (\ref{Unicode}) (which would need far too complicated heuristics).
The function \texttt{SimplifiedUnicodeString} can be used to substitute many non-ASCII characters by related ASCII
characters or strings (e.g., by a corresponding character without accents).
The argument \mbox{\texttt{\slshape ustr}} and the result are unicode strings, if \mbox{\texttt{\slshape encoding}} is \texttt{"ASCII"} then all non-ASCII characters are translated, otherwise only the non-latin1
characters. If the string \texttt{"single"} in an argument then only substitutions are considered which don't make the
result string longer. The translations are stored in a sorted list \texttt{SimplifiedUnicodeTable}. Its entries are of the form \texttt{[codepoint, trans1, trans2, ...]}. Here \texttt{trans1} and so on is either an integer for the codepoint of a substitution character
or it is a list of codepoint integers. If you are missing characters in this
list and know a sensible ASCII approximation, then add an entry (with \texttt{AddSet} (\textbf{Reference: AddSet})) and tell the \textsf{GAPDoc} authors about it. (The initial content of \texttt{SimplifiedUnicodeTable} was mainly generated from the ``\texttt{transtab}'' tables by Markus Kuhn.)
The function \texttt{LowercaseUnicodeString} gets and returns a unicode string and translates each uppercase character to
its corresponding lowercase version. This function uses a list \texttt{LowercaseUnicodeTable} of pairs of codepoint integers. This list was generated using the file \texttt{UnicodeData.txt} from the unicode definition (field 14 in each row).
The function \texttt{UppercaseUnicodeString} does the similar translation to uppercase characters.
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
gap> ustr := Unicode("a and ö", "XML");
Unicode("a and ö")
gap> SimplifiedUnicodeString(ustr, "ASCII");
Unicode("a and oe")
gap> SimplifiedUnicodeString(ustr, "ASCII", "single");
Unicode("a and o")
gap> ustr2 := UppercaseUnicodeString(ustr);;
gap> Print(Encode(ustr2, GAPInfo.TermEncoding), "\n");
A AND Ö
\end{Verbatim}
}
\subsection{\textcolor{Chapter }{Lengths of UTF-8 strings}}\logpage{[ 6, 2, 3 ]}
\hyperdef{L}{X801237207E06A876}{}
{
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{WidthUTF8String({\slshape str})\index{WidthUTF8String@\texttt{WidthUTF8String}}
\label{WidthUTF8String}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{NrCharsUTF8String({\slshape str})\index{NrCharsUTF8String@\texttt{NrCharsUTF8String}}
\label{NrCharsUTF8String}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
an integer
Let \mbox{\texttt{\slshape str}} be a \textsf{GAP} string with text in UTF-8 encoding. There are three ``lengths'' of such a string which must be distinguished. The operation \texttt{Length} (\textbf{Reference: Length}) returns the number of bytes and so the memory occupied by \mbox{\texttt{\slshape str}}. The function \texttt{NrCharsUTF8String} returns the number of unicode characters in \mbox{\texttt{\slshape str}}, that is the length of \texttt{Unicode(\mbox{\texttt{\slshape str}})}.
In many applications the function \texttt{WidthUTF8String} is more interesting, it returns the number of columns needed by the string if
printed to a terminal. This takes into account that some unicode characters
are combining characters and that there are wide characters which need two
columns (e.g., for Chinese or Japanese). (To be precise: This implementation
assumes that there are no control characters in \mbox{\texttt{\slshape str}} and uses the character width returned by the \texttt{wcwidth} function in the GNU C-library called with UTF-8 locale.)
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
gap> # A, German umlaut u, B, zero width space, C, newline
gap> str := Encode( Unicode( "AüB​C\n", "XML" ) );;
gap> Print(str);
AüBC
gap> # umlaut u needs two bytes and the zero width space three
gap> Length(str);
9
gap> NrCharsUTF8String(str);
6
gap> # zero width space and newline don't contribute to width
gap> WidthUTF8String(str);
4
\end{Verbatim}
}
}
\section{\textcolor{Chapter }{Print Utilities}}\label{PrintUtil}
\logpage{[ 6, 3, 0 ]}
\hyperdef{L}{X860C83047DC4F1BC}{}
{
The following printing utilities turned out to be useful for interactive work
with texts in \textsf{GAP}. But they are more general and so we document them here.
\subsection{\textcolor{Chapter }{PrintTo1}}
\logpage{[ 6, 3, 1 ]}\nobreak
\hyperdef{L}{X8603B90C7C3F0AB1}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PrintTo1({\slshape filename, fun})\index{PrintTo1@\texttt{PrintTo1}}
\label{PrintTo1}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AppendTo1({\slshape filename, fun})\index{AppendTo1@\texttt{AppendTo1}}
\label{AppendTo1}
}\hfill{\scriptsize (function)}}\\
The argument \mbox{\texttt{\slshape fun}} must be a function without arguments. Everything which is printed by a call \mbox{\texttt{\slshape fun()}} is printed into the file \mbox{\texttt{\slshape filename}}. As with \texttt{PrintTo} (\textbf{Reference: PrintTo}) and \texttt{AppendTo} (\textbf{Reference: AppendTo}) this overwrites or appends to, respectively, a previous content of \mbox{\texttt{\slshape filename}}.
These functions can be particularly efficient when many small pieces of text
shall be written to a file, because no multiple reopening of the file is
necessary.
\begin{Verbatim}[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{[ 6, 3, 2 ]}\nobreak
\hyperdef{L}{X829B720C86E57E8B}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StringPrint({\slshape obj1[, obj2[, ...]]})\index{StringPrint@\texttt{StringPrint}}
\label{StringPrint}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StringView({\slshape 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{[ 6, 3, 3 ]}\nobreak
\hyperdef{L}{X812A8326844BC910}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PrintFormattedString({\slshape str})\index{PrintFormattedString@\texttt{PrintFormattedString}}
\label{PrintFormattedString}
}\hfill{\scriptsize (function)}}\\
This function prints a string \mbox{\texttt{\slshape str}}. The difference to \texttt{Print(str);} is that no additional line breaks are introduced by \textsf{GAP}'s standard printing mechanism. This can be used to print lines which are
longer than the current screen width. In particular one can print text which
contains escape sequences like those explained in \texttt{TextAttr} (\ref{TextAttr}), where lines may have more characters than \emph{visible characters}. }
\subsection{\textcolor{Chapter }{Page}}
\logpage{[ 6, 3, 4 ]}\nobreak
\hyperdef{L}{X7BB6731F7E3AAA98}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Page({\slshape ...})\index{Page@\texttt{Page}}
\label{Page}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PageDisplay({\slshape obj})\index{PageDisplay@\texttt{PageDisplay}}
\label{PageDisplay}
}\hfill{\scriptsize (function)}}\\
These functions are similar to \texttt{Print} (\textbf{Reference: Print}) and \texttt{Display} (\textbf{Reference: Display}), respectively. The difference is that the output is not sent directly to the
screen, but is piped into the current pager; see \texttt{PAGER} (\textbf{Reference: Pager}).
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
gap> Page([1..1421]+0);
gap> PageDisplay(CharacterTable("Symmetric", 14));
\end{Verbatim}
}
\subsection{\textcolor{Chapter }{StringFile}}
\logpage{[ 6, 3, 5 ]}\nobreak
\hyperdef{L}{X7E14D32181FBC3C3}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StringFile({\slshape filename})\index{StringFile@\texttt{StringFile}}
\label{StringFile}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FileString({\slshape filename, str[, append]})\index{FileString@\texttt{FileString}}
\label{FileString}
}\hfill{\scriptsize (function)}}\\
The function \texttt{StringFile} returns the content of file \mbox{\texttt{\slshape filename}} as a string. This works efficiently with arbitrary (binary or text) files. If
something went wrong, this function returns \texttt{fail}.
Conversely the function \texttt{FileString} writes the content of a string \mbox{\texttt{\slshape str}} into the file \mbox{\texttt{\slshape filename}}. If the optional third argument \mbox{\texttt{\slshape append}} is given and equals \texttt{true} then the content of \mbox{\texttt{\slshape str}} is appended to the file. Otherwise previous content of the file is deleted.
This function returns the number of bytes written or \texttt{fail} if something went wrong.
Both functions are quite efficient, even with large files. }
}
}
\chapter{\textcolor{Chapter }{Utilities for Bibliographies}}\label{ch:bibutil}
\logpage{[ 7, 0, 0 ]}
\hyperdef{L}{X7EB94CE97ABF7192}{}
{
A standard for collecting references (in particular to mathematical texts) is Bib{\TeX} (\href{http://www.ctan.org/tex-archive/biblio/bibtex/distribs/doc/} {\texttt{http://www.ctan.org/tex-archive/biblio/bibtex/distribs/doc/}}). A disadvantage of Bib{\TeX} is that the format of the data is specified with the use by {\LaTeX} in mind. The data format is less suited for conversion to other document types
like plain text or HTML.
In the first section we describe utilities for using data from Bib{\TeX} files in \textsf{GAP}.
In the second section we introduce a new XML based data format BibXMLext for
bibliographies which seems better suited for other tasks than using it with {\LaTeX}.
Another section will describe utilities to deal with BibXMLext data in \textsf{GAP}.
\section{\textcolor{Chapter }{Parsing Bib{\TeX} Files}}\label{ParseBib}
\logpage{[ 7, 1, 0 ]}
\hyperdef{L}{X7A4126EC7BD68F64}{}
{
Here are functions for parsing, normalizing and printing reference lists in Bib{\TeX} format. The reference describing this format is{\nobreakspace}\cite[Appendix B]{La85}.
\subsection{\textcolor{Chapter }{ParseBibFiles}}
\logpage{[ 7, 1, 1 ]}\nobreak
\hyperdef{L}{X82555C307FDC1817}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ParseBibFiles({\slshape bibfile1[, bibfile2[, ...]]})\index{ParseBibFiles@\texttt{ParseBibFiles}}
\label{ParseBibFiles}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ParseBibStrings({\slshape str1[, str2[, ...]]})\index{ParseBibStrings@\texttt{ParseBibStrings}}
\label{ParseBibStrings}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
list \texttt{[list of bib-records, list of abbrevs, list of expansions]}
The first function parses the files \mbox{\texttt{\slshape bibfile1}} and so on (if a file does not exist the extension \texttt{.bib} is appended) in Bib{\TeX} format and returns a list as follows: \texttt{[entries, strings, texts]}. Here \texttt{entries} is a list of records, one record for each reference contained in \mbox{\texttt{\slshape bibfile}}. Then \texttt{strings} is a list of abbreviations defined by \texttt{@string}-entries in \mbox{\texttt{\slshape bibfile}} and \texttt{texts} is a list which contains in the corresponding position the full text for such
an abbreviation.
The second function does the same, but the input is given as \textsf{GAP} strings \mbox{\texttt{\slshape str1}} and so on.
The records in \texttt{entries} store key-value pairs of a Bib{\TeX} reference in the form \texttt{rec(key1 = value1, ...)}. The names of the keys are converted to lower case. The type of the reference
(i.e., book, article, ...) and the citation key are stored as components \texttt{.Type} and \texttt{.Label}. The records also have a \texttt{.From} field that says that the data are read from a Bib{\TeX} source.
As an example consider the following Bib{\TeX} file.
\begin{Verbatim}[fontsize=\small,frame=single,label=doc/test.bib]
@string{ j = "Important Journal" }
@article{ AB2000, Author= "Fritz A. First and Sec, X. Y.",
TITLE="Short", journal = j, year = 2000 }
\end{Verbatim}
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
gap> bib := ParseBibFiles("doc/test.bib");
[ [ rec( From := rec( BibTeX := true ), 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 }{NormalizedNameAndKey}}
\logpage{[ 7, 1, 2 ]}\nobreak
\hyperdef{L}{X7C9F0C337A0A0FF0}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{NormalizedNameAndKey({\slshape namestr})\index{NormalizedNameAndKey@\texttt{NormalizedNameAndKey}}
\label{NormalizedNameAndKey}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
list of strings and names as lists
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{NormalizeNameAndKey({\slshape r})\index{NormalizeNameAndKey@\texttt{NormalizeNameAndKey}}
\label{NormalizeNameAndKey}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing
The argument \mbox{\texttt{\slshape namestr}} must be a string describing an author or a list of authors as described in the Bib{\TeX} documentation in \cite[Appendix B 1.2]{La85}. The function \texttt{NormalizedNameAndKey} returns a list of the form [ normalized name string, short key, long key,
names as lists]. The first entry is a normalized form of the input where names
are written as ``lastname, first name initials''. The second and third entry are the name parts of a short and long key for
the bibliography entry, formed from the (initials of) last names. The fourth
entry is a list of lists, one for each name, where a name is described by
three strings for the last name, the first name initials and the first name(s)
as given in the input.
Note that the determination of the initials is limited to names where the
first letter is described by a single character (and does not contain some
markup, say for accents).
The function \texttt{NormalizeNameAndKey} gets as argument \mbox{\texttt{\slshape r}} a record for a bibliography entry as returned by \texttt{ParseBibFiles} (\ref{ParseBibFiles}). It substitutes \texttt{.author} and \texttt{.editor} fields of \mbox{\texttt{\slshape r}} by their normalized form, the original versions are stored in fields \texttt{.authororig} and \texttt{.editororig}.
Furthermore a short and a long citation key is generated and stored in
components \texttt{.printedkey} (only if no \texttt{.key} is already bound) and \texttt{.keylong}.
We continue the example from \texttt{ParseBibFiles} (\ref{ParseBibFiles}).
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
gap> bib := ParseBibFiles("doc/test.bib");;
gap> NormalizedNameAndKey(bib[1][1].author);
[ "First, F. A. and Sec, X. Y.", "FS", "firstsec",
[ [ "First", "F. A.", "Fritz A." ], [ "Sec", "X. Y.", "X. Y." ] ] ]
gap> NormalizeNameAndKey(bib[1][1]);
gap> bib[1][1];
rec( From := rec( BibTeX := true ), 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.", printedkey := "FS00",
keylong := "firstsec2000" )
\end{Verbatim}
}
\subsection{\textcolor{Chapter }{WriteBibFile}}
\logpage{[ 7, 1, 3 ]}\nobreak
\hyperdef{L}{X7C2B2F65851EAA0B}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{WriteBibFile({\slshape bibfile, bib})\index{WriteBibFile@\texttt{WriteBibFile}}
\label{WriteBibFile}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing
This is the converse of \texttt{ParseBibFiles} (\ref{ParseBibFiles}). Here \mbox{\texttt{\slshape bib}} either must have a format as list of three lists as it is returned by \texttt{ParseBibFiles} (\ref{ParseBibFiles}). Or \mbox{\texttt{\slshape bib}} can be a record as returned by \texttt{ParseBibXMLextFiles} (\ref{ParseBibXMLextFiles}). A Bib{\TeX} file \mbox{\texttt{\slshape bibfile}} is written and the entries are formatted in a uniform way. All given
abbreviations are used while writing this file.
We continue the example from \texttt{NormalizeNameAndKey} (\ref{NormalizeNameAndKey}). The command
\begin{Verbatim}[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},
authororig = {Fritz A. First and Sec, X. Y.},
keylong = {firstsec2000},
printedkey = {FS00}
}
\end{Verbatim}
}
\subsection{\textcolor{Chapter }{InfoBibTools}}
\logpage{[ 7, 1, 4 ]}\nobreak
\hyperdef{L}{X85C1D50F7E37A99A}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{InfoBibTools\index{InfoBibTools@\texttt{InfoBibTools}}
\label{InfoBibTools}
}\hfill{\scriptsize (info class)}}\\
The default level of this info class is 1. Functions like \texttt{ParseBibFiles} (\ref{ParseBibFiles}), \texttt{StringBibAs...} are then printing some information. You can suppress it by setting the level
of \texttt{InfoBibTools} to 0. With level 2 there may be some more information for debugging purposes. }
}
\section{\textcolor{Chapter }{The BibXMLext Format}}\label{BibXMLformat}
\logpage{[ 7, 2, 0 ]}
\hyperdef{L}{X7FB8F6BD80D859D1}{}
{
Bibliographical data in Bib{\TeX} files have the disadvantage that the actual data are given in {\LaTeX} syntax. This makes it difficult to use the data for anything but for {\LaTeX}, say for representations of the data as plain text or HTML. For example:
mathematical formulae are in {\LaTeX} \texttt{\$} environments, non-ASCII characters can be specified in many strange ways, and
how to specify URLs for links if the output format allows them?
Here we propose an XML data format for bibliographical data which addresses
these problems, it is called BibXMLext. In the next section we describe some
tools for generating (an approximation to) this data format from Bib{\TeX} data, and for using data given in BibXMLext format for various purposes.
The first motivation for this development was the handling of bibliographical
data in \textsf{GAPDoc}, but the format and the tools are certainly useful for other purposes as
well.
We started from a DTD \texttt{bibxml.dtd} which is publicly available, say from \href{http://bibtexml.sf.net/} {\texttt{http://bibtexml.sf.net/}}. This is essentially a reformulation of the definition of the Bib{\TeX} format, including several of some widely used further fields. This has already
the advantage that a generic XML parser can check the validity of the data
entries, for example for missing compulsary fields in entries. We applied the
following changes and extensions to define the DTD for BibXMLext, stored in
the file \texttt{bibxmlext.dtd} which can be found in the root directory of this \textsf{GAPDoc} package (and in Appendix \ref{bibxmlextdtd}):
\begin{description}
\item[{names}] Lists of names in the \texttt{author} and \texttt{editor} fields in Bib{\TeX} are difficult to parse. Here they must be given by a sequence of \texttt{{\textless}name{\textgreater}}-elements which each contain an optional \texttt{{\textless}first{\textgreater}}- and a \texttt{{\textless}last{\textgreater}}-element for the first and last names, respectively.
\item[{\texttt{{\textless}M{\textgreater}} and \texttt{{\textless}Math{\textgreater}}}] These elements enclose mathematical formulae, the content is {\LaTeX} code (without the \texttt{\$}). These should be handled in the same way as the elements with the same names
in \textsf{GAPDoc}, see \ref{M} and \ref{Math}. In particular, simple formulae which have a well defined plain text
representation can be given in \texttt{{\textless}M{\textgreater}}-elements.
\item[{Encoding}] Note that in XML files we can use the full range of unicode characters, see \href{http://www.unicode.org/} {\texttt{http://www.unicode.org/}}. All non-ASCII characters should be specified as unicode characters. This
makes dealing with special characters easy for plain text or HTML, only for
use with {\LaTeX} some sort of translation is necessary.
\item[{\texttt{{\textless}URL{\textgreater}}}] These elements are allowed everywhere in the text and should be represented by
links in converted formats which allow this. It is used in the same way as the
element with the same name in \textsf{GAPDoc}, see \ref{URL}.
\item[{\texttt{{\textless}Alt Only="..."{\textgreater}} and \texttt{{\textless}Alt Not="..."{\textgreater}}}] Sometimes information should be given in different ways, depending on the
output format of the data. This is possible with the \texttt{{\textless}Alt{\textgreater}}-elements with the same definition as in \textsf{GAPDoc}, see \ref{Alt}.
\item[{\texttt{{\textless}C{\textgreater}}}] This element should be used to protect text from case changes by converters
(the extra \texttt{\texttt{\symbol{123}}\texttt{\symbol{125}}} characters in Bib{\TeX} title fields).
\item[{\texttt{{\textless}string key="..." value="..."/{\textgreater}} and \texttt{{\textless}value key="..."/{\textgreater}}}] The \texttt{{\textless}string{\textgreater}}-element defines key-value pairs which can be used in any field via the \texttt{{\textless}value{\textgreater}}-element (not only for whole fields but also parts of the text).
\item[{\texttt{{\textless}other type="..."{\textgreater}}}] This is a generic element for fields which are otherwise not supported. An
arbitrary number of them is allowed for each entry, so any kind of additional
data can be added to entries.
\item[{\texttt{{\textless}Wrap Name="..."{\textgreater}}}] This generic element is allowed inside all fields. This markup will be just
ignored (but not the element content) by our standard tools. But it can be a
useful hook for introducing arbitrary further markup (and our tools can easily
be extended to handle it).
\item[{Extra entities}] The DTD defines the standard XML entities (\ref{XMLspchar} and the entities \texttt{\ } (non-breakable space), \texttt{\–} and \texttt{\©right;}. Use \texttt{\–} in page ranges.
\end{description}
For further details of the DTD we refer to the file \texttt{bibxmlext.dtd} itself which is shown in appendix \ref{bibxmlextdtd}. That file also recalls some information from the Bib{\TeX} documentation on how the standard fields of entries should be used. Which
entry types and which fields are supported (and the ordering of the fields
which is fixed by a DTD) can be either read off the DTD, or within \textsf{GAP} one can use the function \texttt{TemplateBibXML} (\ref{TemplateBibXML}) to get templates for the various entry types.
Here is an example of a BibXMLext document:
\begin{Verbatim}[fontsize=\small,frame=single,label=doc/testbib.xml]
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE file SYSTEM "bibxmlext.dtd">
<file>
<string key="j" value="Important Journal"/>
<entry id="AB2000"><article>
<author>
<name><first>Fritz A.</first><last>First</last></name>
<name><first>X. Y.</first><last>Secőnd</last></name>
</author>
<title>The <Wrap Name="Package"> <C>F</C>ritz</Wrap> package for the
formula <M>x^y - l_{{i+1}} \rightarrow \mathbb{R}</M></title>
<journal><value key="j"/></journal>
<year>2000</year>
<number>13</number>
<pages>13–25</pages>
<note>Online data at <URL Text="Bla Bla Publisher">
http://www.publish.com/~ImpJ/123#data</URL></note>
<other type="mycomment">very useful</other>
</article></entry>
</file>
\end{Verbatim}
There is a standard XML header and a \texttt{DOCTYPE} declaration refering to the \texttt{bibxmlext.dtd} DTD mentioned above. Local entities could be defined in the \texttt{DOCTYPE} tag as shown in the example in \ref{GDent}. The actual content of the document is inside a \texttt{{\textless}file{\textgreater}}-element, it consists of \texttt{{\textless}string{\textgreater}}- and \texttt{{\textless}entry{\textgreater}}-elements. Several of the BibXMLext markup features are shown. We will use
this input document for some examples below. }
\section{\textcolor{Chapter }{Utilities for BibXMLext data}}\label{BibXMLtools}
\logpage{[ 7, 3, 0 ]}
\hyperdef{L}{X7AC255DE7D2531B6}{}
{
\subsection{\textcolor{Chapter }{Translating Bib{\TeX} to BibXMLext}}\label{Subsect:IntroXMLBib}
\logpage{[ 7, 3, 1 ]}
\hyperdef{L}{X7C5548E77ECA29D7}{}
{
First we describe a tool which can translate bibliography entries from Bib{\TeX} data to BibXMLext \texttt{{\textless}entry{\textgreater}}-elements. It also does some validation of the data. In some cases it is
desirable to improve the result by hand afterwards (editing formulae, adding \texttt{{\textless}URL{\textgreater}}-elements, translating non-ASCII characters to unicode, ...).
See \texttt{WriteBibXMLextFile} (\ref{WriteBibXMLextFile}) below for how to write the results to a BibXMLext file. }
\subsection{\textcolor{Chapter }{HeuristicTranslationsLaTeX2XML.Apply}}
\logpage{[ 7, 3, 2 ]}\nobreak
\hyperdef{L}{X7A025E0A7A1CD390}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{HeuristicTranslationsLaTeX2XML.Apply({\slshape str})\index{HeuristicTranslationsLaTeX2XML.Apply@\texttt{HeuristicTranslationsLaTeX2XML.Apply}}
\label{HeuristicTranslationsLaTeX2XML.Apply}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a string
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{HeuristicTranslationsLaTeX2XML.ApplyFile({\slshape fnam[, outnam]})\index{HeuristicTranslationsLaTeX2XML.ApplyFile@\texttt{HeuristicTranslationsLaTeX2XML.ApplyFile}}
\label{HeuristicTranslationsLaTeX2XML.ApplyFile}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing
These utilities translate some {\LaTeX} code into text in UTF-8 encoding. The input is given as a string \mbox{\texttt{\slshape str}}, or a file name \mbox{\texttt{\slshape fnam}}, respectively. The first function returns the translated string. The second
function with one argument overwrites the given file with the translated text.
Optionally, the translated file content can be written to another file, if its
name is given as second argument \mbox{\texttt{\slshape outnam}}.
The record \texttt{HeuristicTranslationsLaTeX2XML} mainly contains translations of {\LaTeX} macros for special characters which were found in hundreds of Bib{\TeX} entries from \href{http://www.ams.org/mathscinet/} {MathSciNet}. Just look at this record if you want to know how it works. It is easy to
extend, and if you have improvements which may be of general interest, please
send them to the \textsf{GAPDoc} author.
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
gap> s := "\\\"u\\'{e}\\`e{\\ss}";;
gap> Print(s, "\n");
\"u\'{e}\`e{\ss}
gap> Print(HeuristicTranslationsLaTeX2XML.Apply(s),"\n");
üéèß
\end{Verbatim}
}
\subsection{\textcolor{Chapter }{StringBibAsXMLext}}
\logpage{[ 7, 3, 3 ]}\nobreak
\hyperdef{L}{X85F33C64787A00B7}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StringBibAsXMLext({\slshape bibentry[, abbrvs, vals][, encoding]})\index{StringBibAsXMLext@\texttt{StringBibAsXMLext}}
\label{StringBibAsXMLext}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a string with XML code, or \texttt{fail}
The argument \mbox{\texttt{\slshape bibentry}} is a record representing an entry from a Bib{\TeX} file, as returned in the first list of the result of \texttt{ParseBibFiles} (\ref{ParseBibFiles}). The optional two arguments \mbox{\texttt{\slshape abbrvs}} and \mbox{\texttt{\slshape vals}} can be lists of abbreviations and substitution strings, as returned as second
and third list element in the result of \texttt{ParseBibFiles} (\ref{ParseBibFiles}). The optional argument \mbox{\texttt{\slshape encoding}} specifies the character encoding of the string components of \mbox{\texttt{\slshape bibentry}}. If this is not given it is checked if all strings are valid UTF-8 encoded
strings, in that case it is assumed that the encoding is UTF-8, otherwise the
latin1 encoding is assumed.
The function \texttt{StringBibAsXMLext} creates XML code of an \texttt{{\textless}entry{\textgreater}}-element in \texttt{BibXMLext} format. The result is in UTF-8 encoding and contains some heuristic
translations, like splitting name lists, finding places for \texttt{{\textless}C{\textgreater}}-elements, putting formulae in \texttt{{\textless}M{\textgreater}}-elements, substituting some characters. The result should always be checked
and maybe improved by hand. Some validity checks are applied to the given
data, for example if all non-optional fields are given. If this check fails
the function returns \texttt{fail}.
If your Bib{\TeX} input contains {\LaTeX} markup for special characters, it can be convenient to translate this input
with \texttt{HeuristicTranslationsLaTeX2XML.Apply} (\ref{HeuristicTranslationsLaTeX2XML.Apply}) or \texttt{HeuristicTranslationsLaTeX2XML.ApplyFile} (\ref{HeuristicTranslationsLaTeX2XML.ApplyFile}) before parsing it as Bib{\TeX}.
As an example we consider again the short Bib{\TeX} file \texttt{doc/test.bib} shown in the example for \texttt{ParseBibFiles} (\ref{ParseBibFiles}).
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
gap> bib := ParseBibFiles("doc/test.bib");;
gap> str := StringBibAsXMLext(bib[1][1], bib[2], bib[3]);;
gap> Print(str, "\n");
<entry id="AB2000"><article>
<author>
<name><first>Fritz A.</first><last>First</last></name>
<name><first>X. Y.</first><last>Sec</last></name>
</author>
<title>Short</title>
<journal><value key="j"/></journal>
<year>2000</year>
</article></entry>
\end{Verbatim}
}
The following functions allow parsing of data which are already in BibXMLext
format.
\subsection{\textcolor{Chapter }{ParseBibXMLextString}}
\logpage{[ 7, 3, 4 ]}\nobreak
\hyperdef{L}{X86BD29AE7A453721}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ParseBibXMLextString({\slshape str})\index{ParseBibXMLextString@\texttt{ParseBibXMLextString}}
\label{ParseBibXMLextString}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ParseBibXMLextFiles({\slshape fname1[, fname2[, ...]]})\index{ParseBibXMLextFiles@\texttt{ParseBibXMLextFiles}}
\label{ParseBibXMLextFiles}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a record with fields \texttt{.entries}, \texttt{.strings} and \texttt{.entities}
The first function gets a string \mbox{\texttt{\slshape str}} containing a \texttt{BibXMLext} document or a part of it. It returns a record with the three mentioned fields.
Here \texttt{.entries} is a list of partial XML parse trees for the \texttt{{\textless}entry{\textgreater}}-elements in \mbox{\texttt{\slshape str}}. The field \texttt{.strings} is a list of key-value pairs from the \texttt{{\textless}string{\textgreater}}-elements in \mbox{\texttt{\slshape str}}. And \texttt{.strings} is a list of name-value pairs of the named entities which were used during the
parsing.
The second function \texttt{ParseBibXMLextFiles} uses the first on the content of all files given by filenames \mbox{\texttt{\slshape fname1}} and so on. It collects the results in a single record.
As an example we parse the file \texttt{testbib.xml} shown in \ref{BibXMLformat}.
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
gap> bib := ParseBibXMLextFiles("doc/testbib.xml");;
gap> RecFields(bib);
[ "entries", "strings", "entities" ]
gap> bib.entries;
[ <BibXMLext entry: AB2000> ]
gap> bib.strings;
[ [ "j", "Important Journal" ] ]
gap> bib.entities[1];
[ "amp", "&#38;" ]
\end{Verbatim}
}
\subsection{\textcolor{Chapter }{WriteBibXMLextFile}}
\logpage{[ 7, 3, 5 ]}\nobreak
\hyperdef{L}{X7811108C7E5B1709}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{WriteBibXMLextFile({\slshape fname, bib})\index{WriteBibXMLextFile@\texttt{WriteBibXMLextFile}}
\label{WriteBibXMLextFile}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing
This function writes a BibXMLext file with name \mbox{\texttt{\slshape fname}}.
There are three possibilities to specify the bibliography entries in the
argument \mbox{\texttt{\slshape bib}}. It can be a list of three lists as returned by \texttt{ParseBibFiles} (\ref{ParseBibFiles}). Or it can be just the first of such three lists in which case the other two
lists are assumed to be empty. To all entries of the (first) list the function \texttt{StringBibAsXMLext} (\ref{StringBibAsXMLext}) is applied and the resulting strings are written to the result file.
The third possibility is that \mbox{\texttt{\slshape bib}} is a record in the format as returned by \texttt{ParseBibXMLextString} (\ref{ParseBibXMLextString}) and \texttt{ParseBibXMLextFiles} (\ref{ParseBibXMLextFiles}). In this case the entries for the BibXMLext file are produced with \texttt{StringXMLElement} (\ref{StringXMLElement}), and if \mbox{\texttt{\slshape bib}}\texttt{.entities} is bound then it is tried to resubstitute parts of the string by the given
entities with \texttt{EntitySubstitution} (\ref{EntitySubstitution}).
As an example we write back the result of the example shown for \texttt{ParseBibXMLextFiles} (\ref{ParseBibXMLextFiles}) to an equivalent XML file.
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
gap> bib := ParseBibXMLextFiles("doc/testbib.xml");;
gap> WriteBibXMLextFile("test.xml", bib);
\end{Verbatim}
}
\subsection{\textcolor{Chapter }{Bibliography Entries as Records}}\label{Subsect:RecBib}
\logpage{[ 7, 3, 6 ]}
\hyperdef{L}{X82167F1280F4310E}{}
{
For working with BibXMLext entries we find it convenient to first translate
the parse tree of an entry, as returned by \texttt{ParseBibXMLextFiles} (\ref{ParseBibXMLextFiles}), to a record with the field names of the entry as components whose value is
the content of the field as string. These strings are generated with respect
to a result type. The records are generated by the following function which
can be customized by the user. }
\subsection{\textcolor{Chapter }{RecBibXMLEntry}}
\logpage{[ 7, 3, 7 ]}\nobreak
\hyperdef{L}{X786C33ED79F425F1}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RecBibXMLEntry({\slshape entry[, restype][, strings][, options]})\index{RecBibXMLEntry@\texttt{RecBibXMLEntry}}
\label{RecBibXMLEntry}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a record with fields as strings
This function generates a content string for each field of a bibliography
entry and assigns them to record components. This content may depend on the
requested result type and possibly some given options.
The arguments are as follows: \mbox{\texttt{\slshape entry}} is the parse tree of an \texttt{{\textless}entry{\textgreater}} element as returned by \texttt{ParseBibXMLextString} (\ref{ParseBibXMLextString}) or \texttt{ParseBibXMLextFiles} (\ref{ParseBibXMLextFiles}). The optional argument \mbox{\texttt{\slshape restype}} describes the type of the result. This package supports currently the types \texttt{"BibTeX"}, \texttt{"Text"} and \texttt{"HTML"}. The default is \texttt{"BibTeX"}. The optional argument \mbox{\texttt{\slshape strings}} must be a list of key-value pairs as returned in the component \texttt{.strings} in the result of \texttt{ParseBibXMLextString} (\ref{ParseBibXMLextString}). The argument \mbox{\texttt{\slshape options}} must be a record.
If the entry contains an \texttt{author} field then the result will also contain a component \texttt{.authorAsList} which is a list containing for each author a list with three entries of the
form \texttt{[last name, first name initials, first name]} (the third entry means the first name as given in the data). Similarly, an \texttt{editor} field is accompanied by a component \texttt{.editorAsList}.
The following \mbox{\texttt{\slshape options}} are currently supported.
If \texttt{options.fullname} is bound and set to \texttt{true} then the full given first names for authors and editors will be used, the
default is to use the initials of the first names. Also, if \texttt{options.namefirstlast} is bound and set to \texttt{true} then the names are written in the form ``first-name(s) last-name'', the default is the form ``last-name, first-name(s)''.
If \texttt{options.href} is bound and set to \texttt{false} then the \texttt{"BibTeX"} type result will not use \texttt{\texttt{\symbol{92}}href} commands. The default is to produce \texttt{\texttt{\symbol{92}}href} commands from \texttt{{\textless}URL{\textgreater}}-elements such that {\LaTeX} with the \texttt{hyperref} package can produce links for them.
The content of an \texttt{{\textless}Alt{\textgreater}}-element with \texttt{Only}-attribute is included if \mbox{\texttt{\slshape restype}} is given in the attribute and ignored otherwise, and vice versa in case of a \texttt{Not}-attribute. If \texttt{options.useAlt} is bound, it must be a list of strings to which \mbox{\texttt{\slshape restype}} is added. Then an \texttt{{\textless}Alt{\textgreater}}-element with \texttt{Only}-attribute is evaluated if the intersection of \texttt{options.useAlt} and the types given in the attribute is not empty. In case of a \texttt{Not}-attribute the element is evaluated if this intersection is empty.
If \mbox{\texttt{\slshape restype}} is \texttt{"BibTeX"} then the string fields in the result will be recoded with \texttt{Encode} (\ref{Encode}) and target \texttt{"LaTeX"}. If \texttt{options.hasLaTeXmarkup} is bound and set to \texttt{true} (for example, because the data are originally read from Bib{\TeX} files), then the target \texttt{"LaTeXleavemarkup"} will be used.
We use again the file shown in the example for \texttt{ParseBibXMLextFiles} (\ref{ParseBibXMLextFiles}).
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
gap> bib := ParseBibXMLextFiles("doc/testbib.xml");;
gap> e := bib.entries[1];; strs := bib.strings;;
gap> Print(RecBibXMLEntry(e, "BibTeX", strs), "\n");
rec(
From := rec(
BibXML := true,
type := "BibTeX",
options := rec(
) ),
Label := "AB2000",
Type := "article",
authorAsList :=
[ [ "First", "F. A.", "Fritz A." ], [ "Sec\305\221nd", "X. Y.",
"X. Y." ] ],
author := "First, F. A. and Sec{\\H o}nd, X. Y.",
title :=
"The \\textsf{ {F}ritz} package for the \n formula $x^y - l\
_{{i+1}} \\rightarrow \\mathbb{R}$",
journal := "Important Journal",
year := "2000",
number := "13",
pages := "13{\\textendash}25",
note :=
"Online data at \\href {http://www.publish.com/~ImpJ/123#data} {Bla\
Bla Publisher}",
mycomment := "very useful",
printedkey := "FS00" )
gap> Print(RecBibXMLEntry(e, "HTML", strs).note, "\n");
Online data at <a href="http://www.publish.com/~ImpJ/123#data">Bla Bla\
Publisher</a>
\end{Verbatim}
}
\subsection{\textcolor{Chapter }{AddHandlerBuildRecBibXMLEntry}}
\logpage{[ 7, 3, 8 ]}\nobreak
\hyperdef{L}{X8067261385905A36}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AddHandlerBuildRecBibXMLEntry({\slshape elementname, restype, handler})\index{AddHandlerBuildRecBibXMLEntry@\texttt{AddHandlerBuildRecBibXMLEntry}}
\label{AddHandlerBuildRecBibXMLEntry}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
nothing
The argument \mbox{\texttt{\slshape elementname}} must be the name of an entry field supported by the BibXMLext format, the name
of one of the special elements \texttt{"C"}, \texttt{"M"}, \texttt{"Math"}, \texttt{"URL"} or of the form \texttt{"Wrap:myname"} or any string \texttt{"mytype"} (which then corresponds to entry fields \texttt{{\textless}other type="mytype"{\textgreater}}). The string \texttt{"Finish"} has an exceptional meaning, see below.
\mbox{\texttt{\slshape restype}} is a string describing the result type for which the handler is installed, see \texttt{RecBibXMLEntry} (\ref{RecBibXMLEntry}).
For both arguments, \mbox{\texttt{\slshape elementname}} and \mbox{\texttt{\slshape restype}}, it is also possible to give lists of the described ones for installing
several handler at once.
The argument \mbox{\texttt{\slshape handler}} must be a function with five arguments of the form \mbox{\texttt{\slshape handler}}\texttt{(entry, r, restype, strings, options)}. Here \mbox{\texttt{\slshape entry}} is a parse tree of a BibXMLext \texttt{{\textless}entry{\textgreater}}-element, \mbox{\texttt{\slshape r}} is a node in this tree for an element \mbox{\texttt{\slshape elementname}}, and \mbox{\texttt{\slshape restype}}, \mbox{\texttt{\slshape strings}} and \mbox{\texttt{\slshape options}} are as explained in \texttt{RecBibXMLEntry} (\ref{RecBibXMLEntry}). The function should return a string representing the content of the node \mbox{\texttt{\slshape r}}. If \mbox{\texttt{\slshape elementname}} is of the form \texttt{"Wrap:myname"} the handler is used for elements of form \texttt{{\textless}Wrap Name="myname"{\textgreater}...{\textless}/Wrap{\textgreater}}.
If \mbox{\texttt{\slshape elementname}} is \texttt{"Finish"} the handler should look like above except that now \mbox{\texttt{\slshape r}} is the record generated by \texttt{RecBibXMLEntry} (\ref{RecBibXMLEntry}) just before it is returned. Here the handler should return nothing. It can be
used to manipulate the record \mbox{\texttt{\slshape r}}, for example for changing the encoding of the strings or for adding some more
components.
The installed handler is called by \texttt{BuildRecBibXMLEntry(}\mbox{\texttt{\slshape entry}}, \mbox{\texttt{\slshape r}}, \mbox{\texttt{\slshape restype}}, \mbox{\texttt{\slshape strings}}, \mbox{\texttt{\slshape options}}\texttt{)}. The string for the whole content of an element can be generated by \texttt{ContentBuildRecBibXMLEntry(}\mbox{\texttt{\slshape entry}}, \mbox{\texttt{\slshape r}}, \mbox{\texttt{\slshape restype}}, \mbox{\texttt{\slshape strings}}, \mbox{\texttt{\slshape options}}\texttt{)}.
We continue the example from \texttt{RecBibXMLEntry} (\ref{RecBibXMLEntry}) and install a handler for the \texttt{{\textless}Wrap Name="Package"{\textgreater}}-element such that {\LaTeX} puts its content in a sans serif font.
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
gap> AddHandlerBuildRecBibXMLEntry("Wrap:Package", "BibTeX",
> function(entry, r, restype, strings, options)
> return Concatenation("\\textsf{", ContentBuildRecBibXMLEntry(
> entry, r, restype, strings, options), "}");
> end);
gap>
gap> Print(RecBibXMLEntry(e, "BibTeX", strs).title, "\n");
The \textsf{ {F}ritz} package for the
formula $x^y - l_{{i+1}} \rightarrow \mathbb{R}$
gap> Print(RecBibXMLEntry(e, "Text", strs).title, "\n");
The Fritz package for the
formula x^y - l_{i+1} -> R
\end{Verbatim}
}
\subsection{\textcolor{Chapter }{StringBibXMLEntry}}
\logpage{[ 7, 3, 9 ]}\nobreak
\hyperdef{L}{X790A295680F7CD24}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StringBibXMLEntry({\slshape entry[, restype][, strings][, options]})\index{StringBibXMLEntry@\texttt{StringBibXMLEntry}}
\label{StringBibXMLEntry}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a string
The arguments of this function have the same meaning as in \texttt{RecBibXMLEntry} (\ref{RecBibXMLEntry}) but the return value is a string representing the bibliography entry in a
format specified by \mbox{\texttt{\slshape restype}} (default is \texttt{"BibTeX"}).
Currently, the following cases for \mbox{\texttt{\slshape restype}} are supported:
\begin{description}
\item[{\texttt{"BibTeX"}}] A string with Bib{\TeX} source code is generated.
\item[{\texttt{"Text"}}] A text representation of the text is returned. If \texttt{options.ansi} is bound it must be a record. The components must have names \texttt{Bib{\textunderscore}Label}, \texttt{Bib{\textunderscore}author}, and so on for all fieldnames. The value of each component is a pair of
strings which will enclose the content of the field in the result or the first
of these strings in which case the default for the second is \texttt{TextAttr.reset} (see \texttt{TextAttr} (\ref{TextAttr})). If you give an empty record here, some default ANSI color markup will be
used.
\item[{\texttt{"HTML"}}] An HTML representation of the bibliography entry is returned. The text from
each field is enclosed in markup (mostly \texttt{{\textless}span{\textgreater}}-elements) with the \texttt{class} attribute set to the field name. This allows a detailed layout of the code via
a style sheet file.
\end{description}
We use again the file shown in the example for \texttt{ParseBibXMLextFiles} (\ref{ParseBibXMLextFiles}).
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
gap> bib := ParseBibXMLextFiles("doc/testbib.xml");;
gap> e := bib.entries[1];; strs := bib.strings;;
gap> ebib := StringBibXMLEntry(e, "BibTeX", strs);;
gap> PrintFormattedString(ebib);
@article{ AB2000,
author = {First, F. A. and Sec{\H o}nd, X. Y.},
title = {The \textsf{ {F}ritz} package for the formula $x^y -
l_{{i+1}} \rightarrow \mathbb{R}$},
journal = {Important Journal},
number = {13},
year = {2000},
pages = {13{\textendash}25},
note = {Online data at \href
{http://www.publish.com/~ImpJ/123#data} {Bla Bla
Publisher}},
mycomment = {very useful},
printedkey = {FS00}
}
gap> etxt := StringBibXMLEntry(e, "Text", strs);;
gap> etxt := SimplifiedUnicodeString(Unicode(etxt), "latin1", "single");;
gap> etxt := Encode(etxt, GAPInfo.TermEncoding);;
gap> PrintFormattedString(etxt);
[FS00] First, F. A. and Second, X. Y., The Fritz package for the formula
x^y - l_{i+1} -> R, Important Journal, 13 (2000), 13-25, (Online data at
Bla Bla Publisher (http://www.publish.com/~ImpJ/123#data)).
\end{Verbatim}
}
The following command may be useful to generate completly new bibliography
entries in BibXMLext format. It also informs about the supported entry types
and field names.
\subsection{\textcolor{Chapter }{TemplateBibXML}}
\logpage{[ 7, 3, 10 ]}\nobreak
\hyperdef{L}{X7C6FF57087016019}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{TemplateBibXML({\slshape [type]})\index{TemplateBibXML@\texttt{TemplateBibXML}}
\label{TemplateBibXML}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
list of types or string
Without an argument this function returns a list of the supported entry types
in BibXMLext documents.
With an argument \mbox{\texttt{\slshape type}} of one of the supported types the function returns a string which is a
template for a corresponding BibXMLext entry. Optional field elements have a \texttt{*} appended. If an element has the word \texttt{OR} appended, then either this element or the next must/can be given, not both. If \texttt{AND/OR} is appended then this and/or the next can/must be given. Elements which can
appear several times have a \texttt{+} appended. Places to fill are marked by an \texttt{X}.
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
gap> TemplateBibXML();
[ "article", "book", "booklet", "manual", "techreport",
"mastersthesis", "phdthesis", "inbook", "incollection",
"proceedings", "inproceedings", "conference", "unpublished", "misc"
]
gap> Print(TemplateBibXML("inbook"));
<entry id="X"><inbook>
<author>
<name><first>X</first><last>X</last></name>+
</author>OR
<editor>
<name><first>X</first><last>X</last></name>+
</editor>
<title>X</title>
<chapter>X</chapter>AND/OR
<pages>X</pages>
<publisher>X</publisher>
<year>X</year>
<volume>X</volume>*OR
<number>X</number>*
<series>X</series>*
<type>X</type>*
<address>X</address>*
<edition>X</edition>*
<month>X</month>*
<note>X</note>*
<key>X</key>*
<annotate>X</annotate>*
<crossref>X</crossref>*
<abstract>X</abstract>*
<affiliation>X</affiliation>*
<contents>X</contents>*
<copyright>X</copyright>*
<isbn>X</isbn>*OR
<issn>X</issn>*
<keywords>X</keywords>*
<language>X</language>*
<lccn>X</lccn>*
<location>X</location>*
<mrnumber>X</mrnumber>*
<mrclass>X</mrclass>*
<mrreviewer>X</mrreviewer>*
<price>X</price>*
<size>X</size>*
<url>X</url>*
<category>X</category>*
<other type="X">X</other>*+
</inbook></entry>
\end{Verbatim}
}
}
\section{\textcolor{Chapter }{Getting Bib{\TeX} entries from \textsf{MathSciNet}}}\label{MathSciNet}
\logpage{[ 7, 4, 0 ]}
\hyperdef{L}{X842336AF7B20048E}{}
{
We provide utilities to access the \href{http://www.ams.org/mathscinet/} {\textsf{ MathSciNet}} data base from within GAP. One condition for this to work is that the \textsf{IO}-package \cite{IO} is available. The other is, of course, that you use these functions from a
computer which has access to \textsf{MathSciNet}.
\subsection{\textcolor{Chapter }{SearchMR}}
\logpage{[ 7, 4, 1 ]}\nobreak
\hyperdef{L}{X8009F8A17DDFF9AF}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SearchMR({\slshape qurec})\index{SearchMR@\texttt{SearchMR}}
\label{SearchMR}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SearchMRBib({\slshape bib})\index{SearchMRBib@\texttt{SearchMRBib}}
\label{SearchMRBib}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a list of strings, a string or \texttt{fail}
The first function \texttt{SearchMR} provides the same functionality as the Web interface \href{http://www.ams.org/mathscinet/} {\textsf{ MathSciNet}}. The query strings must be given as a record, and the following components of
this record are recognized: \texttt{Author}, \texttt{AuthorRelated}, \texttt{Title}, \texttt{ReviewText}, \texttt{Journal}, \texttt{InstitutionCode}, \texttt{Series}, \texttt{MSCPrimSec}, \texttt{MSCPrimary}, \texttt{MRNumber}, \texttt{Anywhere}, \texttt{References} and \texttt{Year}.
Furthermore, the component \texttt{type} can be specified. It can be one of \texttt{"bibtex"} (the default if not given), \texttt{"pdf"}, \texttt{"html"} and probably others. In the last cases the function returns a string with the
correspondig PDF-file or web page from \textsf{MathSciNet}. In the first case the \textsf{MathSciNet} interface returns a web page with Bib{\TeX} entries, for convenience this function returns a list of strings, each
containing the Bib{\TeX} text for a single result entry.
The format of a \texttt{.Year} component can be either a four digit number, optionally preceded by one of the
characters \texttt{'{\textless}'}, \texttt{'{\textgreater}'} or \texttt{'='}, or it can be two four digit numbers separated by a \texttt{-} to specify a year range.
The function \texttt{SearchMRBib} gets a record of a parsed Bib{\TeX} entry as input as returned by \texttt{ParseBibFiles} (\ref{ParseBibFiles}) or \texttt{ParseBibStrings} (\ref{ParseBibStrings}). It tries to generate some sensible input from this information for \texttt{SearchMR} and calls that function.
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
gap> ll := SearchMR(rec(Author:="Gauss", Title:="Disquisitiones"));;
gap> ll2 := List(ll, HeuristicTranslationsLaTeX2XML.Apply);;
gap> bib := ParseBibStrings(Concatenation(ll2));;
gap> bibxml := List(bib[1], StringBibAsXMLext);;
gap> bib2 := ParseBibXMLextString(Concatenation(bibxml));;
gap> for b in bib2.entries do
gap> PrintFormattedString(StringBibXMLEntry(b, "Text")); od;
[Gau95] Gauss, C. F., Disquisitiones arithmeticae, Academia Colombiana
de Ciencias Exactas Físicas y Naturales, Colección Enrique Pérez
Arbeláez [Enrique Pérez Arbeláez Collection], 10, Bogotá (1995),
xliv+495 pages, (Translated from the Latin by Hugo Barrantes Campos,
Michael Josephy and Ángel Ruiz Zúñiga, With a preface by Ruiz Zúñiga).
[Gau86] Gauss, C. F., Disquisitiones arithmeticae, Springer-Verlag, New
York (1986), xx+472 pages, (Translated and with a preface by Arthur A.
Clarke, Revised by William C. Waterhouse, Cornelius Greither and A. W.
Grootendorst and with a preface by Waterhouse).
[Gau66] Gauss, C. F., Disquisitiones arithmeticae, Yale University
Press, Translated into English by Arthur A. Clarke, S. J, New Haven,
Conn. (1966), xx+472 pages.
\end{Verbatim}
}
}
}
\appendix
\chapter{\textcolor{Chapter }{The File \texttt{3k+1.xml}}}\label{app:3k+1}
\logpage{[ "A", 0, 0 ]}
\hyperdef{L}{X830C58F97F9CD901}{}
{
Here is the complete source of the example \textsf{GAPDoc} document \texttt{3k+1.xml} discussed in Section{\nobreakspace}\ref{sec:3k+1expl}.
\begin{Verbatim}[fontsize=\small,frame=single,label=3k+1.xml]
<?xml version="1.0" encoding="UTF-8"?>
<!-- A complete "fake package" documentation
$Id: 3k+1.xml,v 1.4 2007/10/04 22:02:12 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>©right; 2000 The Author. <P/>
You can do with this package what you want.<P/> Really.
</Copyright>
</TitlePage>
<TableOfContents/>
<Body>
<Chapter> <Heading>The <M>3k+1</M> Problem</Heading>
<Section Label="sec:theory"> <Heading>Theory</Heading>
Let <M>k \in &NN;</M> be a natural number. We consider the
sequence <M>n(i, k), i \in &NN;,</M> with <M>n(1, k) = k</M> and
else <M>n(i+1, k) = n(i, k) / 2</M> if <M>n(i, k)</M> is even
and <M>n(i+1, k) = 3 n(i, k) + 1</M> if <M>n(i, k)</M> is odd.
<P/> It is not known whether for any natural number <M>k \in
&NN;</M> there is an <M>m \in &NN;</M> with <M>n(m, k) = 1</M>.
<P/>
<Package>ThreeKPlusOne</Package> provides the function <Ref
Func="ThreeKPlusOneSequence"/> to explore this for given
<M>n</M>. If you really want to know something about this
problem, see <Cite Key="Wi98"/> or
<URL>http://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 ]}
\hyperdef{L}{X85366C6480D58C51}{}
{
For easier reference we repeat here the complete content of the file \texttt{gapdoc.dtd}.
\begin{Verbatim}[fontsize=\small,frame=single,label=gapdoc.dtd]
<?xml version="1.0" encoding="UTF-8"?>
<!-- ==================================================================
gapdoc.dtd - XML Document type definition for GAP documentation
By Frank Lübeck and Max Neunhöffer
================================================================== -->
<!-- $Id: gapdoc.dtd,v 1.17 2008/04/30 15:29:10 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 "&#60;">
<!ENTITY gt ">">
<!ENTITY amp "&#38;">
<!ENTITY apos "'">
<!ENTITY quot """>
<!-- The following were introduced in GAPDoc version < 1.0, it is no longer
necessary to take care of LaTeX special characters
(we keep the entities with simplified definitions for compatibility) -->
<!ENTITY tamp "&">
<!ENTITY tlt "<">
<!ENTITY tgt ">">
<!ENTITY hash "#">
<!ENTITY dollar "$">
<!ENTITY percent "%">
<!ENTITY tilde "~">
<!ENTITY bslash "\\">
<!ENTITY obrace "{">
<!ENTITY cbrace "}">
<!ENTITY uscore "_">
<!ENTITY circum "^">
<!-- ==================================================================
Our predefined entities:
================================================================== -->
<!ENTITY nbsp " ">
<!ENTITY ndash "–">
<!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 "©">
<!-- and unicode math symbols -->
<!ENTITY CC "ℂ" > <!-- double struck -->
<!ENTITY ZZ "ℤ" >
<!ENTITY NN "ℕ" >
<!ENTITY PP "ℙ" >
<!ENTITY QQ "ℚ" >
<!ENTITY HH "ℍ" >
<!ENTITY RR "ℝ" >
<!-- ==================================================================
The following describes the "innermost" documentation text which
can occur at various places in the document like for example
section headings. It does neither contain further sectioning
elements nor environments like Enums or Lists.
================================================================== -->
<!ENTITY % InnerText "#PCDATA |
Alt |
Emph | E |
Par | P | Br |
Keyword | K | Arg | A | Quoted | Q | Code | C |
File | F | Button | B | Package |
M | Math | Display |
Example | Listing | Log | Verb |
URL | Email | Homepage | Address | Cite | Label |
Ref | Index |
Ignore" >
<!ELEMENT Alt (%InnerText;)*> <!-- This is only to allow "Only" and
"Not" attributes for normal text -->
<!ATTLIST Alt Only CDATA #IMPLIED
Not CDATA #IMPLIED>
<!-- The following elements declare a certain block of InnerText to
have a certain property. They are non-terminal and can contain
any InnerText recursively. -->
<!ELEMENT Emph (%InnerText;)*> <!-- Emphasize something -->
<!ELEMENT E (%InnerText;)*> <!-- the same as shortcut -->
<!-- The following is an empty element marking a paragraph boundary. -->
<!ELEMENT Par EMPTY> <!-- this is intentionally empty! -->
<!ELEMENT P EMPTY> <!-- the same as shortcut -->
<!-- And here is an element for forcing a line break, not starting
a new paragraph. -->
<!ELEMENT Br EMPTY> <!-- a forced line break -->
<!-- The following elements mark a word or sentence to be of a certain
kind, such that it can be typeset differently. They are terminal
elements that should only contain character data. But we have to
allow Alt elements for handling special characters. For these
elements we introduce a long name - which is easy to remember -
and a short name - which you may prefer because of the shorter
markup. -->
<!ELEMENT Keyword (#PCDATA|Alt)*> <!-- Keyword -->
<!ELEMENT K (#PCDATA|Alt)*> <!-- Keyword (shortcut) -->
<!ELEMENT Arg (#PCDATA|Alt)*> <!-- Argument -->
<!ELEMENT A (#PCDATA|Alt)*> <!-- Argument (shortcut) -->
<!ELEMENT Code (#PCDATA|Alt|A|Arg)*> <!-- GAP code -->
<!ELEMENT C (#PCDATA|Alt|A|Arg)*> <!-- GAP code (shortcut) -->
<!ELEMENT File (#PCDATA|Alt)*> <!-- Filename -->
<!ELEMENT F (#PCDATA|Alt)*> <!-- Filename (shortcut) -->
<!ELEMENT Button (#PCDATA|Alt)*> <!-- "Button" (also Menu, Key) -->
<!ELEMENT B (#PCDATA|Alt)*> <!-- "Button" (shortcut) -->
<!ELEMENT Package (#PCDATA|Alt)*> <!-- A package name -->
<!ELEMENT Quoted (%InnerText;)*> <!-- Quoted (in quotes) text -->
<!ELEMENT Q (%InnerText;)*> <!-- Quoted text (shortcut) -->
<!-- The following elements contain mathematical formulae. They are
terminal elements that contain character data in TeX notation. -->
<!-- Math with well defined translation to text output -->
<!ELEMENT M (#PCDATA|A|Arg|Alt)*>
<!-- Normal TeX math mode formula -->
<!ELEMENT Math (#PCDATA|A|Arg|Alt)*>
<!-- TeX displayed math mode formula -->
<!ELEMENT Display (#PCDATA|A|Arg|Alt)*>
<!-- The following elements contain GAP related text like code,
session logs or examples. They are all terminal elements and
consist of character data which is normally typeset verbatim. The
different types of the elements only control how they are
treated. -->
<!ELEMENT Example (#PCDATA)> <!-- This is subject to the automatic
example checking mechanism -->
<!ELEMENT Log (#PCDATA)> <!-- This not -->
<!ELEMENT Listing (#PCDATA)> <!-- This is just for code listings -->
<!ATTLIST Listing Type CDATA #IMPLIED> <!-- a comment about the type of
listed code, may appear in
output -->
<!-- One further verbatim element, this is truely verbatim without
any processing and intended for ASCII substitutes of complicated
displayed formulae or tables. -->
<!ELEMENT Verb (#PCDATA)>
<!-- The following elements are for cross-referencing purposes like
URLs, citations, references, and the index. All these elements
are terminal and need special methods to make up the actual
output during document generation. -->
<!ELEMENT URL (#PCDATA|Alt|Link|LinkText)*> <!-- Link, LinkText
variant for case where text needs further markup -->
<!ATTLIST URL Text CDATA #IMPLIED> <!-- This is for output formats
that have links like HTML -->
<!ELEMENT Link (%InnerText;)*> <!-- the URL -->
<!ELEMENT LinkText (%InnerText;)*> <!-- text for links, can contain markup -->
<!-- The following two are actually URLs, but the element name determines
the type. -->
<!ELEMENT Email (#PCDATA|Alt|Link|LinkText)*>
<!ELEMENT Homepage (#PCDATA|Alt|Link|LinkText)*>
<!-- Those who still want to give postal addresses can use the following
element. Use <Br/> for specifying typical line breaks -->
<!ELEMENT Address (#PCDATA|Alt|Br)*>
<!ELEMENT Cite EMPTY>
<!ATTLIST Cite Key CDATA #REQUIRED
Where CDATA #IMPLIED>
<!ELEMENT Label EMPTY>
<!ATTLIST Label Name CDATA #REQUIRED>
<!ELEMENT Ref EMPTY>
<!ATTLIST Ref Func CDATA #IMPLIED
Oper CDATA #IMPLIED
Meth CDATA #IMPLIED
Filt CDATA #IMPLIED
Prop CDATA #IMPLIED
Attr CDATA #IMPLIED
Var CDATA #IMPLIED
Fam CDATA #IMPLIED
InfoClass CDATA #IMPLIED
Chap CDATA #IMPLIED
Sect CDATA #IMPLIED
Subsect CDATA #IMPLIED
Appendix CDATA #IMPLIED
Text CDATA #IMPLIED
Label CDATA #IMPLIED
BookName CDATA #IMPLIED
Style (Text|Number) #IMPLIED> <!-- normally automatic -->
<!-- Note that only one attribute of Ref is used normally. BookName
and Style can be specified in addition to handle external
references and the typesetting style of the reference. -->
<!-- For explicit index entries (Func and so on should cause an
automatically generated index entry). Use the attributes Key,
Subkey for sorting (simplified, without markup). The Subkey value
also gets printed. Use the optional Subkey element if the printed
version needs some markup. -->
<!ELEMENT Index (%InnerText;|Subkey)*>
<!ATTLIST Index Key CDATA #IMPLIED
Subkey CDATA #IMPLIED>
<!ELEMENT Subkey (%InnerText;)*>
<!-- ==================================================================
The following describes the normal documentation text which can
occur at various places in the document. It does not contain
further sectioning elements. In addition to InnerText it can contain
environments like enumerations, lists, and such.
================================================================== -->
<!ENTITY % Text "%InnerText; | List | Enum | Table">
<!ELEMENT Item ( %Text;)*>
<!ELEMENT Mark ( %InnerText;)*>
<!ELEMENT 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?, TitleComment?,
Author+, Date?, Address?, Abstract?, Copyright?,
Acknowledgements? , Colophon? )>
<!ELEMENT Title (%Text;)*>
<!ELEMENT Subtitle (%Text;)*>
<!ELEMENT Version (%Text;)*>
<!ELEMENT TitleComment (%Text;)*>
<!ELEMENT Author (%Text;)*> <!-- There may be more than one Author! -->
<!ELEMENT Date (%Text;)*>
<!ELEMENT Abstract (%Text;)*>
<!ELEMENT Copyright (%Text;)*>
<!ELEMENT Acknowledgements (%Text;)*>
<!ELEMENT Colophon (%Text;)*>
<!-- The following things just specify some information about the
corresponding parts of the Book: -->
<!ELEMENT TableOfContents EMPTY>
<!ELEMENT Bibliography EMPTY>
<!ATTLIST Bibliography Databases CDATA #REQUIRED
Style CDATA #IMPLIED>
<!ELEMENT TheIndex EMPTY>
<!-- ==================================================================
The Ignore element can be used everywhere to include further
information in a GAPDoc document which is not intended for the
standard converters (e.g., source code, not yet finished stuff,
and so on. This information can be extracted by special converter
routines, more precise information about the content of an Ignore
element can be given by the "Remark" attribute.
================================================================== -->
<!ELEMENT Ignore (%Text;| Chapter | Section | Subsection | ManSection |
Heading)*>
<!ATTLIST Ignore Remark CDATA #IMPLIED>
<!-- ==================================================================
Now we go on with the overall structure by defining the sectioning
structure, which includes the Synopsis element:
================================================================== -->
<!ELEMENT Subsection (%Text;| Heading)*>
<!ATTLIST Subsection Label CDATA #IMPLIED> <!-- For reference purposes -->
<!ELEMENT ManSection ( Heading?,
((Func, Returns?) | (Oper, Returns?) |
(Meth, Returns?) | (Filt, Returns?) |
(Prop, Returns?) | (Attr, Returns?) |
Var | Fam | InfoClass)+, Description )>
<!ATTLIST ManSection Label CDATA #IMPLIED> <!-- For reference purposes -->
<!ELEMENT Returns (%Text;)*>
<!ELEMENT Description (%Text;)*>
<!-- Note that the ManSection element is actually a subsection with
respect to labelling, referencing, and counting of sectioning
elements. -->
<!ELEMENT Func EMPTY>
<!ATTLIST Func Name CDATA #REQUIRED
Label CDATA #IMPLIED
Arg CDATA #REQUIRED
Comm CDATA #IMPLIED>
<!-- Note that Arg contains the full list of arguments, including
optional parts, which are denoted by square brackets [].
Arguments are separated by whitespace, commas count as
whitespace. -->
<!-- Note further that although Name and Label are CDATA (and not ID)
Label must make up a unique identifier. -->
<!ELEMENT Oper EMPTY>
<!ATTLIST Oper Name CDATA #REQUIRED
Label CDATA #IMPLIED
Arg CDATA #REQUIRED
Comm CDATA #IMPLIED>
<!ELEMENT Meth EMPTY>
<!ATTLIST Meth Name CDATA #REQUIRED
Label CDATA #IMPLIED
Arg CDATA #REQUIRED
Comm CDATA #IMPLIED>
<!ELEMENT Filt EMPTY>
<!ATTLIST Filt Name CDATA #REQUIRED
Label CDATA #IMPLIED
Arg CDATA #IMPLIED
Comm CDATA #IMPLIED
Type CDATA #IMPLIED>
<!ELEMENT Prop EMPTY>
<!ATTLIST Prop Name CDATA #REQUIRED
Label CDATA #IMPLIED
Arg CDATA #REQUIRED
Comm CDATA #IMPLIED>
<!ELEMENT Attr EMPTY>
<!ATTLIST Attr Name CDATA #REQUIRED
Label CDATA #IMPLIED
Arg CDATA #REQUIRED
Comm CDATA #IMPLIED>
<!ELEMENT Var EMPTY>
<!ATTLIST Var Name CDATA #REQUIRED
Label CDATA #IMPLIED
Comm CDATA #IMPLIED>
<!ELEMENT Fam EMPTY>
<!ATTLIST Fam Name CDATA #REQUIRED
Label CDATA #IMPLIED
Comm CDATA #IMPLIED>
<!ELEMENT InfoClass EMPTY>
<!ATTLIST InfoClass Name CDATA #REQUIRED
Label CDATA #IMPLIED
Comm CDATA #IMPLIED>
<!ELEMENT Heading (%InnerText;)*>
<!ELEMENT Section (%Text;| Heading | Subsection | ManSection)*>
<!ATTLIST Section Label CDATA #IMPLIED> <!-- For reference purposes -->
<!ELEMENT Chapter (%Text;| Heading | Section)*>
<!ATTLIST Chapter Label CDATA #IMPLIED> <!-- For reference purposes -->
<!-- Note that the entity %InnerText; is documentation that contains
neither sectioning elements nor environments like enumerations,
but only formulae, labels, references, citations, and other
terminal elements. -->
<!ELEMENT Appendix (%Text;| Heading | Section)*>
<!ATTLIST Appendix Label CDATA #IMPLIED> <!-- For reference purposes -->
<!-- Note that an Appendix is exactly the same as a Chapter. They
differ only in the numbering. -->
<!-- ==================================================================
At last we define the overall structure of a gapdoc Book:
================================================================== -->
<!ELEMENT Body ( %Text;| Chapter | Section )*>
<!ELEMENT Book (TitlePage,
TableOfContents?,
Body,
Appendix*,
Bibliography?,
TheIndex?)>
<!ATTLIST Book Name CDATA #REQUIRED>
<!-- Note that the entity %Text; is documentation that contains
no further sectioning elements but possibly environments like
enumerations, and formulae, labels, references, and citations.
-->
<!-- ============================================================== -->
\end{Verbatim}
}
\chapter{\textcolor{Chapter }{The File \texttt{bibxmlext.dtd}}}\label{bibxmlextdtd}
\logpage{[ "C", 0, 0 ]}
\hyperdef{L}{X7E2788757A1AA098}{}
{
For easier reference we repeat here the complete content of the file \texttt{bibxmlext.dtd} which is explained in \ref{BibXMLformat}.
\begin{Verbatim}[fontsize=\small,frame=single,label=bibxmlext.dtd]
<?xml version="1.0" encoding="UTF-8"?>
<!--
- (C) Frank Lübeck (http://www.math.rwth-aachen.de/~Frank.Luebeck)
-
- The BibXMLext data format.
-
- This DTD expresses XML markup similar to the BibTeX language
- specified for LaTeX, or actually its content model.
-
- It is a variation of a file bibxml.dtd developed by the project
- http://bibtexml.sf.net/
-
- For documentation on BibTeX, see
- http://www.ctan.org/tex-archive/biblio/bibtex/distribs/doc/
-
- A previous version of the code originally developed by
- Vidar Bronken Gundersen, http://bibtexml.sf.net/
- Reuse and repurposing is approved as long as this
- notification appears with the code.
-
-->
<!-- ..................................................................... -->
<!-- Main structure -->
<!-- key-value pairs as in BibTeX @string entries are put in empty elements
(but here they can be used for parts of an entry field as well) -->
<!ELEMENT string EMPTY>
<!ATTLIST string
key CDATA #REQUIRED
value CDATA #REQUIRED >
<!-- entry may contain one of the bibliographic types. -->
<!ELEMENT entry ( article | book | booklet |
manual | techreport |
mastersthesis | phdthesis |
inbook | incollection |
proceedings | inproceedings |
conference |
unpublished | misc ) >
<!ATTLIST entry
id CDATA #REQUIRED >
<!-- file is the documents top element. -->
<!ELEMENT file ( string | entry )* >
<!-- ..................................................................... -->
<!-- Parameter entities -->
<!-- these are additional elements often used, but not included in the
standard BibTeX distribution, these must be added to the
bibliography styles, otherwise these fields will be omitted by
the formatter, we allow an arbitrary number of 'other' elements
to specify any further information -->
<!ENTITY % n.user " abstract?, affiliation?,
contents?, copyright?,
(isbn | issn)?,
keywords?, language?, lccn?,
location?, mrnumber?, mrclass?, mrreviewer?,
price?, size?, url?, category?, other* ">
<!ENTITY % n.common "key?, annotate?, crossref?,
%n.user;">
<!-- content model used more than once -->
<!ENTITY % n.InProceedings "author, title, booktitle,
year, editor?,
(volume | number)?,
series?, pages?, address?,
month?, organization?, publisher?,
note?, %n.common;">
<!ENTITY % n.PHDThesis "author, title, school,
year, type?, address?, month?,
note?, %n.common;">
<!-- ..................................................................... -->
<!-- Entries in the BibTeX database -->
<!-- [article] An article from a journal or magazine.
- Required fields: author, title, journal, year.
- Optional fields: volume, number, pages, month, note. -->
<!ELEMENT article (author, title, journal,
year, volume?, number?, pages?,
month?, note?, %n.common;)
>
<!-- [book] A book with an explicit publisher.
- Required fields: author or editor, title, publisher, year.
- Optional fields: volume or number, series, address,
- edition, month, note. -->
<!ELEMENT book ((author | editor), title,
publisher, year, (volume | number)?,
series?, address?, edition?, month?,
note?, %n.common;)
>
<!-- [booklet] A work that is printed and bound, but without a named
- publisher or sponsoring institution
- Required field: title.
- Optional fields: author, howpublished, address, month, year, note. -->
<!ELEMENT booklet (author?, title,
howpublished?, address?, month?,
year?, note?, %n.common;)
>
<!-- [conference] The same as INPROCEEDINGS,
- included for Scribe compatibility. -->
<!ELEMENT conference (%n.InProceedings;)
>
<!-- [inbook] A part of a book, which may be a chapter (or section or
- whatever) and/or a range of pages.
- Required fields: author or editor, title, chapter and/or pages,
- publisher, year.
- Optional fields: volume or number, series, type, address,
- edition, month, note. -->
<!ELEMENT inbook ((author | editor), title,
((chapter, pages?) | pages),
publisher, year, (volume |
number)?, series?, type?,
address?, edition?, month?,
note?, %n.common;)
>
<!--
- > I want to express that the elements a and/or b are legal that is one
- > of them or both must be present in the document instance (see the
- > element content for BibTeX entry `InBook').
- > How do I specify this in my DTD?
-
- Dave Peterson:
- in content model: ((a , b?) | b) if order matters
- ((a , b?) | (b , a?)) otherwise
-->
<!-- [incollection] A part of a book having its own title.
- Required fields: author, title, booktitle, publisher, year.
- Optional fields: editor, volume or number, series, type,
- chapter, pages, address, edition, month, note. -->
<!ELEMENT incollection (author, title,
booktitle, publisher, year,
editor?, (volume | number)?,
series?, type?, chapter?,
pages?, address?, edition?,
month?, note?,
%n.common;)
>
<!-- [inproceedings] An article in a conference proceedings.
- Required fields: author, title, booktitle, year.
- Optional fields: editor, volume or number, series, pages,
- address, month, organization, publisher, note. -->
<!ELEMENT inproceedings (%n.InProceedings;)
>
<!-- [manual] Technical documentation
- Required field: title.
- Optional fields: author, organization, address,
- edition, month, year, note. -->
<!ELEMENT manual (author?, title,
organization?, address?, edition?,
month?, year?, note?, %n.common;)
>
<!-- [mastersthesis] A Master's thesis.
- Required fields: author, title, school, year.
- Optional fields: type, address, month, note. -->
<!ELEMENT mastersthesis (%n.PHDThesis;)
>
<!-- [misc] Use this type when nothing else fits.
- Required fields: none.
- Optional fields: author, title, howpublished, month, year, note. -->
<!ELEMENT misc (author?, title?,
howpublished?, month?, year?, note?,
%n.common;)
>
<!-- [phdthesis] A PhD thesis.
- Required fields: author, title, school, year.
- Optional fields: type, address, month, note. -->
<!ELEMENT phdthesis (%n.PHDThesis;)
>
<!-- [proceedings] The proceedings of a conference.
- Required fields: title, year.
- Optional fields: editor, volume or number, series,
- address, month, organization, publisher, note. -->
<!ELEMENT proceedings (editor?, title, year,
(volume | number)?, series?,
address?, month?, organization?,
publisher?, note?, %n.common;)
>
<!-- [techreport] A report published by a school or other institution,
- usually numbered within a series.
- Required fields: author, title, institution, year.
- Optional fields: type, number, address, month, note. -->
<!ELEMENT techreport (author, title,
institution, year, type?, number?,
address?, month?, note?, %n.common;)
>
<!-- [unpublished] A document having an author and title, but not
- formally published.
- Required fields: author, title, note.
- Optional fields: month, year. -->
<!ELEMENT unpublished (author, title, note,
month?, year?, %n.common;)
>
<!-- ..................................................................... -->
<!-- Fields from the standard bibliography styles -->
<!--
- Below is a description of all fields recognized by the standard
- bibliography styles. An entry can also contain other fields, which
- are ignored by those styles.
-
- [address] Usually the address of the publisher or other type of
- institution For major publishing houses, van~Leunen recommends
- omitting the information entirely. For small publishers, on the other
- hand, you can help the reader by giving the complete address.
-
- [annote] An annotation It is not used by the standard bibliography
- styles, but may be used by others that produce an annotated
- bibliography.
-
- [author] The name(s) of the author(s), here *not* in the format
- described in the LaTeX book. Contains elements <name> which in turn
- contains elements <first>, <last> for the first name (or first names,
- fully written or as initials, and including middle initials) and
- the last name.
-
- [booktitle] Title of a book, part of which is being cited. See the
- LaTeX book for how to type titles. For book entries, use the title
- field instead.
-
- [chapter] A chapter (or section or whatever) number.
-
- [crossref] The database key of the entry being cross referenced.
-
- [edition] The edition of a book-for example, ``Second''. This
- should be an ordinal, and should have the first letter capitalized, as
- shown here; the standard styles convert to lower case when necessary.
-
- [editor] Name(s) of editor(s), typed as indicated in the LaTeX book.
- If there is also an author field, then the editor field gives the
- editor of the book or collection in which the reference appears.
-
- [howpublished] How something strange has been published. The first
- word should be capitalized.
-
- [institution] The sponsoring institution of a technical report.
-
- [journal] A journal name. Abbreviations are provided for many
- journals; see the Local Guide.
-
- [key] Used for alphabetizing, cross referencing, and creating a label
- when the ``author'' information (described in Section [ref: ] is
- missing. This field should not be confused with the key that appears
- in the \cite command and at the beginning of the database entry.
-
- [month] The month in which the work was published or, for an
- unpublished work, in which it was written. You should use the
- standard three-letter abbreviation, as described in Appendix B.1.3 of
- the LaTeX book.
-
- [note] Any additional information that can help the reader. The first
- word should be capitalized.
-
- [number] The number of a journal, magazine, technical report, or of a
- work in a series. An issue of a journal or magazine is usually
- identified by its volume and number; the organization that issues a
- technical report usually gives it a number; and sometimes books are
- given numbers in a named series.
-
- [organization] The organization that sponsors a conference or that
- publishes a manual.
-
- [pages] One or more page numbers or range of numbers, such as 42-111
- or 7,41,73-97 or 43+ (the `+' in this last example indicates pages
- following that don't form a simple range). To make it easier to
- maintain Scribe-compatible databases, the standard styles convert a
- single dash (as in 7-33) to the double dash used in TeX to denote
- number ranges (as in 7-33). Here, we suggest to use the entity
- – for a dash in page ranges.
-
- [publisher] The publisher's name.
-
- [school] The name of the school where a thesis was written.
-
- [series] The name of a series or set of books. When citing an entire
- book, the the title field gives its title and an optional series field
- gives the name of a series or multi-volume set in which the book is
- published.
-
- [title] The work's title. For mathematical formulae use the <M> or
- <Math> elements explained below (and LaTeX code in the content, without
- surrounding '$').
-
- [type] The type of a technical report-for example, ``Research
- Note''.
-
- [volume] The volume of a journal or multivolume book.
-
- [year] The year of publication or, for an unpublished work, the year
- it was written. Generally it should consist of four numerals, such as
- 1984, although the standard styles can handle any year whose last four
- nonpunctuation characters are numerals, such as `(about 1984)'.
-->
<!-- Here is the main extension compared to the original BibXML definition
from which is DTD is derived: We want to allow more markup in some
elements such that we can use the bibliography for high quality
output in other formats than LaTeX.
- <M> and <Math>, mathematical formulae: Specify LaTeX code for "simple"
formulae as content of <M> elements; "simple" means that they can be
translated to a fairly readable ASCII representation as explained in
the GAPDoc documentation on "<M>".
More complicated formulae are given as content of <Math> elements.
(Think about an <Alt> alternative for text or HTML representations.)
- <URL>: use these elements to specify URLs, they can be properly
converted to links if possible in an output format (in that case
the Text attribute is used for the visible text).
- <value key="..."/>: substituted by the value-attribute specified
in a <string key="..." value="..."/> element. Can be used anywhere,
not only for complete fields as in BibTeX.
- <C> protect case changes: should be used instead of {}'s which are
used in BibTeX title fields to protect the case of letters from
changes.
- <Alt Only="...">, <Alt Not="...">, alternatives for different
output formats: Use this to specify alternatives, the GAPDoc
utilities will do some special handling for "Text", "HTML",
and "BibTeX" as output type.
- <Wrap Name="...">, generic wrapper for other markup:
Use this for any other type of markup you are interested in. The
GAPDoc utilities will ignore the markup, but provide a hook
to do install handler functions for them.
-->
<!ELEMENT M (#PCDATA | Alt)* > <!-- math with simple text
representation, in LaTeX -->
<!ELEMENT Math (#PCDATA | Alt)* > <!-- other math in LaTeX -->
<!ELEMENT URL (#PCDATA | Alt | Link | LinkText)* > <!-- an URL -->
<!ATTLIST URL Text CDATA #IMPLIED> <!-- text to be printed
(default is content) -->
<!ELEMENT value EMPTY > <!-- placeholder for value given .. -->
<!ATTLIST value key CDATA #REQUIRED > <!-- .. by key, defined in a string
element -->
<!ELEMENT C (#PCDATA | value | Alt |
M | Math | Wrap | URL)* > <!-- protect from case changes -->
<!ELEMENT Alt (#PCDATA | value | C | Alt |
M | Math | Wrap | URL)* > <!-- specify alternatives for
various types of output -->
<!ATTLIST Alt Only CDATA #IMPLIED
Not CDATA #IMPLIED > <!-- specify output types in comma and
whitespace separated list (use exactly one of Only or Not) -->
<!ENTITY % withMURL "(#PCDATA | value | M | Math | Wrap | URL | C | Alt )*" >
<!ELEMENT Wrap %withMURL; > <!-- a generic wrapper -->
<!ATTLIST Wrap Name CDATA #REQUIRED > <!-- needs a 'Name' attribute -->
<!ELEMENT address %withMURL; >
<!-- here we don't want the complicated definition from the LaTeX book,
use markup for first/last name(s): a <name> element for each
author which contains <first> (optional), <last> elements: -->
<!ELEMENT author (name)* >
<!ELEMENT name (first?, last) >
<!ELEMENT first (#PCDATA) >
<!ELEMENT last (#PCDATA) >
<!ELEMENT booktitle %withMURL; >
<!ELEMENT chapter %withMURL; >
<!ELEMENT edition %withMURL; >
<!-- same as for author field -->
<!ELEMENT editor (name)* >
<!ELEMENT howpublished %withMURL; >
<!ELEMENT institution %withMURL; >
<!ELEMENT journal %withMURL; >
<!ELEMENT month %withMURL; >
<!ELEMENT note %withMURL; >
<!ELEMENT number %withMURL; >
<!ELEMENT organization %withMURL; >
<!ELEMENT pages %withMURL; >
<!ELEMENT publisher %withMURL; >
<!ELEMENT school %withMURL; >
<!ELEMENT series %withMURL; >
<!ELEMENT title %withMURL; >
<!ELEMENT type %withMURL; >
<!ELEMENT volume %withMURL; >
<!ELEMENT year (#PCDATA) >
<!-- These were not listed in the documentation for entry content, but
- appeared in the list of fields in the BibTeX documentation -->
<!ELEMENT annotate %withMURL; >
<!ELEMENT crossref %withMURL; >
<!ELEMENT key (#PCDATA) >
<!-- ..................................................................... -->
<!-- Other popular fields
-
- From: http://www.ecst.csuchico.edu/~jacobsd/bib/formats/bibtex.html
- BibTeX is extremely popular, and many people have used it to store
- information. Here is a list of some of the more common fields:
-
- [affiliation] The authors affiliation.
- [abstract] An abstract of the work.
- [contents] A Table of Contents
- [copyright] Copyright information.
- [ISBN] The International Standard Book Number.
- [ISSN] The International Standard Serial Number.
- Used to identify a journal.
- [keywords] Key words used for searching or possibly for annotation.
- [language] The language the document is in.
- [location] A location associated with the entry,
- such as the city in which a conference took place.
- [LCCN] The Library of Congress Call Number.
- I've also seen this as lib-congress.
- [mrnumber] The Mathematical Reviews number.
- [mrclass] The Mathematical Reviews class.
- [mrreviewer] The Mathematical Reviews reviewer.
- [price] The price of the document.
- [size] The physical dimensions of a work.
- [URL] The WWW Universal Resource Locator that points to the item being
- referenced. This often is used for technical reports to point to the
- ftp site where the postscript source of the report is located.
-
- When using BibTeX with LaTeX you need
- BibTeX style files to print these data.
-->
<!ELEMENT abstract %withMURL; >
<!ELEMENT affiliation %withMURL; >
<!ELEMENT contents %withMURL; >
<!ELEMENT copyright %withMURL; >
<!ELEMENT isbn (#PCDATA) >
<!ELEMENT issn (#PCDATA) >
<!ELEMENT keywords %withMURL; >
<!ELEMENT language %withMURL; >
<!ELEMENT lccn (#PCDATA) >
<!ELEMENT location %withMURL; >
<!ELEMENT mrnumber %withMURL; >
<!ELEMENT mrclass %withMURL; >
<!ELEMENT mrreviewer %withMURL; >
<!ELEMENT price %withMURL; >
<!ELEMENT size %withMURL; >
<!ELEMENT url %withMURL; >
<!-- Added by Zeger W. Hendrikse
- [category] Category of this bibitem
-->
<!ELEMENT category %withMURL; >
<!-- A container element [other] for any further information, a description
- of the type of data must be given in the attribute 'type'
-->
<!ELEMENT other %withMURL; >
<!ATTLIST other
type CDATA #REQUIRED >
<!-- ..................................................................... -->
<!-- Predefined/reserved character entities -->
<!ENTITY amp "&#38;">
<!ENTITY lt "&#60;">
<!ENTITY gt ">">
<!ENTITY apos "'">
<!ENTITY quot """>
<!-- Some more generally useful entities -->
<!ENTITY nbsp " ">
<!ENTITY copyright "©">
<!ENTITY ndash "–">
<!-- ..................................................................... -->
<!-- End of BibXMLext dtd -->
\end{Verbatim}
}
\def\bibname{References\logpage{[ "Bib", 0, 0 ]}
\hyperdef{L}{X7A6F98FD85F02BFE}{}
}
\bibliographystyle{alpha}
\bibliography{gapdocbib.xml}
\def\indexname{Index\logpage{[ "Ind", 0, 0 ]}
\hyperdef{L}{X83A0356F839C696F}{}
}
\printindex
\newpage
\immediate\write\pagenrlog{["End"], \arabic{page}];}
\immediate\closeout\pagenrlog
\end{document}
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
91213ddcfbe7f54821d42c2d9e091326
>
files
>
77
