%% for a long time these were red and blue by default, %% now black, but keep variables to overwrite \definecolor{FuncColor}{rgb}{0.0,0.0,0.0} %% strange name because of pdflatex bug: \definecolor{Chapter }{rgb}{0.0,0.0,0.0} \definecolor{DarkOlive}{rgb}{0.1047,0.2412,0.0064}
% write page numbers to a .pnr log file for online help \newwrite\pagenrlog \immediate\openout\pagenrlog =\jobname.pnr \immediate\write\pagenrlog{PAGENRS := [} \newcommand{\logpage}[1]{\protect\write\pagenrlog{#1, \thepage,}} %% were never documented, give conflicts with some additional packages
\newcommand{\GAP}{\textsf{GAP}}
%% nicer description environments, allows long labels \usepackage{enumitem} \setdescription{style=nextline}
\newpage\setcounter{page}{2}
{\small \section*{Copyright} \logpage{[ 0, 0, 1 ]} \index{License} {\copyright} 2000\texttt{\symbol{45}}2024 by Frank L{\"u}beck and Max
Neunh{\"o}ffer
\textsf{GAPDoc} is free software; you can redistribute it and/or modify it under the terms of
the \href{https://www.fsf.org/licenses/gpl.html} {GNU General Public License} as published by the Free Software Foundation; either version 2 of the License,
or (at your option) any later version. \mbox{}}\\[1cm] \newpage
\def\contentsname{Contents\logpage{[ 0, 0, 2 ]}}
\tableofcontents \newpage
\chapter{\textcolor{Chapter }{Introduction and Example}}\label{ch:intro} \logpage{[ 1, 0, 0 ]} \hyperdef{L}{X7D4EE663818DA109}{}
{
The main purpose of the \textsf{GAPDoc} package is to define a file format for documentation of \textsf{GAP}\texttt{\symbol{45}}programs and \texttt{\symbol{45}}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\texttt{\symbol{45}}browser via an
HTML\texttt{\symbol{45}}version of the documentation. Nowadays one can use {\LaTeX} and standard viewer programs to produce and view on the screen \texttt{dvi}\texttt{\symbol{45}} or \texttt{pdf}\texttt{\symbol{45}}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\texttt{\symbol{45}}, hyperlinked {\LaTeX}\texttt{\symbol{45}} and HTML\texttt{\symbol{45}}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{https://www.w3c.org}{\texttt{https://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}[commandchars=!@|,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\texttt{\symbol{45}}8 character set (other common encodings are ASCII or
ISO\texttt{\symbol{45}}8895\texttt{\symbol{45}}X encodings). \begin{Verbatim}[commandchars=@|B,fontsize=\small,frame=single,label=from 3k+1.xml]
<!-- A complete "fake package" documentation
--> \end{Verbatim}
Everything in a XML file between ``\texttt{{\textless}!\texttt{\symbol{45}}\texttt{\symbol{45}}}'' and ``\texttt{\texttt{\symbol{45}}\texttt{\symbol{45}}{\textgreater}}'' is a comment and not part of the document content. \begin{Verbatim}[commandchars=@|A,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}[commandchars=!@|,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}[commandchars=!|B,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>
Contrary to {\LaTeX}\texttt{\symbol{45}} or HTML\texttt{\symbol{45}}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}).
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}[commandchars=!@|,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}[commandchars=!@|,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}[commandchars=!@|,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\texttt{\symbol{45}}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''\texttt{\symbol{45}}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''\texttt{\symbol{45}}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\texttt{\symbol{45}}internal references. \begin{Verbatim}[commandchars=!@|,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''\texttt{\symbol{45}}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}[commandchars=!@|,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\texttt{\symbol{45}}address into an ``URL''\texttt{\symbol{45}}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}[commandchars=!@|,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>
!gapprompt@gap>| !gapinput@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''\texttt{\symbol{45}}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''\texttt{\symbol{45}}elements. A good description of a function should usually
contain an example of its use. For this there are some
verbatim\texttt{\symbol{45}}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''\texttt{\symbol{45}}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}[commandchars=!@|,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. }
\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:
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\texttt{\symbol{45}}defined language is used. In
case of a \textsf{GAPDoc} document this should always look as in the following example. \begin{Verbatim}[commandchars=@|A,fontsize=\small,frame=single,label=Example]
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Book SYSTEM "gapdoc.dtd"> \end{Verbatim}
See{\nobreakspace}\ref{XMLenc} for a remark on the ``encoding'' statement.
(There may be local entity definitions inside the \texttt{DOCTYPE} statement, see Subsection{\nobreakspace}\ref{GDent} below.) }
\subsection{\textcolor{Chapter }{Comments}}\label{XMLcomment} \logpage{[ 2, 1, 2 ]} \hyperdef{L}{X780C79EB85C32138}{}
{
A ``comment'' in XML starts with the character sequence ``\texttt{{\textless}!\texttt{\symbol{45}}\texttt{\symbol{45}}}'' and ends with the sequence ``\texttt{\texttt{\symbol{45}}\texttt{\symbol{45}}{\textgreater}}''. Between these sequences there must not be two adjacent dashes ``\texttt{\texttt{\symbol{45}}\texttt{\symbol{45}}}''. }
\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{\texttt{\symbol{45}}}''.
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\texttt{\symbol{45}}tag'' consists of a less\texttt{\symbol{45}}than\texttt{\symbol{45}}character ``\texttt{{\textless}}'' directly followed (without whitespace) by an element name (see{\nobreakspace}\ref{XMLnames}), optional attributes, optional whitespace, and a
greater\texttt{\symbol{45}}than\texttt{\symbol{45}}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\texttt{\symbol{45}}than\texttt{\symbol{45}}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\texttt{\symbol{45}}than\texttt{\symbol{45}}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\texttt{\symbol{45}}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\texttt{\symbol{45}}than\texttt{\symbol{45}}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}[commandchars=!@|,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\texttt{\symbol{45}}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\texttt{\symbol{45}}8859\texttt{\symbol{45}}X encodings
(ISO\texttt{\symbol{45}}8859\texttt{\symbol{45}}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\texttt{\symbol{45}}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.
The ``\texttt{Display}'' element also has an attribute such that its content is processed as in ``\texttt{M}'' elements.
Note that the content of these element is {\LaTeX} code, but the special characters ``\texttt{{\textless}}'' and ``\texttt{\&}'' for XML must be entered via the entities described in{\nobreakspace}\ref{XMLspchar} or by using a \texttt{CDATA} statement, see{\nobreakspace}\ref{XMLcdata}.
Here \texttt{\ } is a non\texttt{\symbol{45}}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}[commandchars=@|A,fontsize=\small,frame=single,label=Example]
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Book SYSTEM "gapdoc.dtd"
[ <!ENTITY MyEntity "some longish text possibly with markup">
]> \end{Verbatim}
These additional definitions go into the \texttt{{\textless}!DOCTYPE} tag in square brackets. Such new entities are used like this: \texttt{\&MyEntity;}
}
}
}
\chapter{\textcolor{Chapter }{The Document Type Definition}}\label{DTD} \logpage{[ 3, 0, 0 ]} \hyperdef{L}{X7859CFF180D52D49}{}
{
In this chapter we first explain what a ``document type definition'' is and then describe \texttt{gapdoc.dtd} in detail. That file together with the current chapter define how a \textsf{GAPDoc} document has to look like. It can be found in the main directory of the \textsf{GAPDoc} package and it is reproduced in Appendix{\nobreakspace}\ref{GAPDocdtd}.
We do not give many examples in this chapter which is more intended as a
formal reference for all \textsf{GAPDoc} elements. Instead, we provide a separate help book, see{\nobreakspace} \textbf{GAPDoc Example: Various types of text}. 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:
\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}[commandchars=@|F,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 \texttt{\symbol{45}} 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}[commandchars=@|B,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}[commandchars=@|A,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\texttt{\symbol{45}}called ``parameter entity''. It is something like a macro within the DTD. It is defined as follows: \label{InnerText} \begin{Verbatim}[commandchars=@AB,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}[commandchars=!@A,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}[commandchars=@GJ,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\texttt{\symbol{45}}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}[commandchars=@|A,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}[commandchars=@BF,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}[commandchars=@|A,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}[commandchars=@|B,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}\texttt{\symbol{45}}address and/or WWW\texttt{\symbol{45}}\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}[commandchars=@|B,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}[commandchars=@FG,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}[commandchars=@|B,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}Acknowledgements{\textgreater}}}}\logpage{[ 3, 2, 12 ]} \hyperdef{L}{X8143972D7C17838E}{}
{ \index{Acknowledgements@\texttt{Acknowledgements}} \begin{Verbatim}[commandchars=@|B,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}[commandchars=@|A,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}[commandchars=@|A,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}[commandchars=!@|,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}[commandchars=@|F,fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT Bibliography EMPTY>
<!ATTLIST Bibliography Databases CDATA #REQUIRED
Style CDATA #IMPLIED> \end{Verbatim}
This element may occur in the \texttt{Book} element after the last \texttt{Appendix} element. If it is present, a bibliography section is generated and inserted
into the document. The attribute \texttt{Databases} must be specified, the names of several data files can be specified, separated
by commas.
Two kinds of files can be specified in \texttt{Databases}: The first are Bib{\TeX} files as defined in{\nobreakspace}\cite[Appendix B]{La85}. Such files must have a name with extension \texttt{.bib}, and in \texttt{Databases} the name must be given \emph{without} this extension. Note that such \texttt{.bib}\texttt{\symbol{45}}files should be in latin1\texttt{\symbol{45}}encoding (or
ASCII\texttt{\symbol{45}}encoding). The second are files in BibXMLext format
as defined in Section{\nobreakspace}\ref{BibXMLformat}. These files must have an extension \texttt{.xml} and in \texttt{Databases} the \emph{full} name must be specified.
We suggest to use the BibXMLext format because it allows to produce
potentially nicer bibliography entries in text and HTML documents.
A bibliography style may be specified with the \texttt{Style} attribute. The optional \texttt{Style} attribute (for {\LaTeX} output of the document) must also be specified without the \texttt{.bst} extension (the default is \texttt{alpha}). See also section \ref{Cite} for a description of the \texttt{Cite} element which is used to include bibliography references into the text.
}
\subsection{\textcolor{Chapter }{\texttt{{\textless}TheIndex{\textgreater}}}}\label{TheIndex} \logpage{[ 3, 2, 16 ]} \hyperdef{L}{X7C53615A8477F1E5}{}
{ \index{TheIndex@\texttt{TheIndex}} \begin{Verbatim}[commandchars=@|A,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\texttt{\symbol{45}}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}[commandchars=@AD,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}[commandchars=@BG,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}[commandchars=@|A,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}[commandchars=@BG,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}[commandchars=@BG,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}[commandchars=@BG,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}[commandchars=@BG,fontsize=\small,frame=single,label=From gapdoc.dtd]
<!ELEMENT ManSection ( Heading?,
((Func, Returns?) | (Oper, Returns?) |
(Meth, Returns?) | (Filt, Returns?) |
(Prop, Returns?) | (Attr, Returns?) |
(Constr, Returns?) |
Var | Fam | InfoClass)+, Description )>
<!ATTLIST ManSection Label CDATA #IMPLIED> <!-- For reference purposes -->
<!ELEMENT Returns (%Text;)*>
<!ELEMENT Description (%Text;)*> \end{Verbatim}
The \texttt{ManSection} element can have a \texttt{Label} attribute, such that this subsection can be referenced later on with a \texttt{Ref} element (see section \ref{Ref}). But this is probably rarely necessary because the elements \texttt{Func} and so on (explained below) generate automatically labels for cross
referencing.
The content of a \texttt{ManSection} element is one or more elements describing certain items in \textsf{GAP}, each of them optionally followed by a \texttt{Returns} element, followed by a \texttt{Description} element, which contains \texttt{\%Text;} (see \ref{Text}) describing it. (Remember to include examples in the description as often as
--> --------------------
--> maximum size reached
--> --------------------
¤ Dauer der Verarbeitung: 0.29 Sekunden
(vorverarbeitet)
¤
Die Informationen auf dieser Webseite wurden
nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit,
noch Qualität der bereit gestellten Informationen zugesichert.
Bemerkung:
Die farbliche Syntaxdarstellung ist noch experimentell.
