<Chapter Label="DTD">
<Heading>The Document Type Definition</Heading>
In this chapter we first explain what a <Q>document type definition</Q> is
and then describe <F>gapdoc.dtd</F> in detail. That file together with the
current chapter define how a &GAPDoc; document has to look like. It can be
found in the main directory of the &GAPDoc; package and it is reproduced in
Appendix <Ref Appendix="GAPDocdtd" />.<P/>
We do not give many examples in this chapter which is more intended as a
formal reference for all &GAPDoc; elements. Instead, we provide a separate
help book, see <Ref BookName="GAPDoc Example" Label=""/>. This uses all
the constructs introduced in this chapter and you can easily compare the
source code and how it looks like in the different output formats.
Furthermore recall that many basic things about XML markup were already
explained by example in the introductory chapter <Ref Chap="ch:intro"
/>.
<Section><Heading>What is a DTD?</Heading>
A document type definition (DTD) is a formal declaration of how an XML
document has to be structured. It is itself structured such that programs
that handle documents can read it and treat the documents accordingly. There
are for example parsers and validity checkers that use the DTD to validate
an XML document, see <Ref Subsect="XMLvalid"/>. <P/>
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. <P/>
Note that a DTD can <E>not</E> ensure that a document which is <Q>valid</Q>
also makes sense to the converters! It only says something about the formal
structure of the document. <P/>
For the remaining part of this chapter we have divided the elements of
&GAPDoc; documents into several subsets, each of which will be discussed in
one of the next sections. <P/>
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 <F>gapdoc.dtd</F>. For precise descriptions of the
syntax of DTD's see again the official standard in:
<Listing Type="From gapdoc.dtd"><![CDATA[
<!ELEMENT Book (TitlePage,
TableOfContents?,
Body,
Appendix*,
Bibliography?,
TheIndex?)>
<!ATTLIST Book Name CDATA #REQUIRED>]]>
</Listing>
After the keyword <C>ELEMENT</C> and the name <C>Book</C> 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 <C>Book</C> element. Each name in such a list can be followed by one of the
characters <Q><C>?</C></Q>, <Q><C>*</C></Q> or <Q><C>+</C></Q>, 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
<Q><C>|</C></Q> characters, this denotes any element with one of the names
(i.e., <Q><C>|</C></Q> means <Q>or</Q>).<P/>
So, the <C>Book</C> element must contain first a <C>TitlePage</C> element,
then an optional <C>TableOfContents</C> element, then a <C>Body</C> element,
then zero or more elements of type <C>Appendix</C>, then an optional
<C>Bibliography</C> element, and finally an optional element of type
<C>TheIndex</C>.<P/>
Note that <Emph>only</Emph> these elements are allowed in the content of the
<C>Book</C> 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 <Q>element content</Q>.<P/>
The second declaration starts with the keyword <C>ATTLIST</C> and the element name <C>Book</C>. 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 (<C>Name</C>) is the name of an
attribute for a <C>Book</C> element. The second (<C>CDATA</C>) is always
the same for all of our declarations, it means that the value of
the attribute consists of <Q>character data</Q>. The third parameter
<C>#REQUIRED</C> means that this attribute must be specified with any
<C>Book</C> element. Later we will also see optional attributes which are
declared as <C>#IMPLIED</C>. </Subsection>
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
<Q>the following elements may occur in any order but each exactly once</Q>.
<P/>
Before going on with the other elements inside the <C>Book</C> element we
explain the elements for the title page.
</Subsection>
<Label Name="Text"/>
<Listing Type="From gapdoc.dtd">
<![CDATA[<!ELEMENT Title (%Text;)*>]]>
</Listing>
Here is the last construct you need to understand for reading
<F>gapdoc.dtd</F>. The expression <Q><C>%Text;</C></Q> is a
so-called <Q>parameter entity</Q>. It is something like a macro within the
DTD. It is defined as follows:
<Label Name="InnerText"/>
<Listing Type="From gapdoc.dtd">
<![CDATA[<!ENTITY % Text "%InnerText; | List | Enum | Table">]]>
</Listing>
This means, that every occurrence of <Q><C>%Text;</C></Q> in the DTD
is replaced by the expression
<Label Name="Innertext"/>
<Listing Type="From gapdoc.dtd"><![CDATA[%InnerText; | List | Enum | Table]]>
</Listing>
which is then expanded further because of the following definition:
<Listing Type="From gapdoc.dtd">
<![CDATA[<!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" >]]>
</Listing>
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</Emph> the
keyword <C>#PCDATA</C> (concatenated with the <Q>or</Q> character
<Q><C>|</C></Q>). <P/>
So, the element (<C>Title</C>) is of so-called <Q>mixed content</Q>: It can
contain <E>parsed character data</E> which does not contain further markup
(<C>#PCDATA</C>) or any of the other above mentioned elements. Mixed
content must always have the asterisk qualifier (like in <C>Title</C>) such
that any sequence of elements (of the above list) and character data can be
contained in a <C>Title</C> element. <P/>
The <C>%Text;</C> parameter entity is used in all places
in the DTD, where <Q>normal text</Q> should be allowed, including lists,
enumerations, and tables, but <E>no</E> sectioning elements. <P/>
The <C>%InnerText;</C> parameter entity is used in all places
in the DTD, where <Q>inner text</Q> should be allowed. This means, that no
structures like lists, enumerations, and tables are allowed. This is used
for example in headings. <P/>
Note that the version can only contain character data and no further markup
elements (except for <C>Alt</C>, which is necessary to resolve the entities
described in <Ref Subsect="GDent"/>). The converters will <E>not</E> put the
word <Q>Version</Q> in front of the text in this element.
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 <C>Abstract</C> element (see <Ref
Subsect="elAbstract"/>) for longer explanations.
<Listing Type="From gapdoc.dtd">
<![CDATA[<!ELEMENT Author (%Text;)*> <!-- There may be more than one Author! -->]]>
</Listing>
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
<C>Email</C>-address and/or WWW-<C>Homepage</C> element for this author,
see <Ref Subsect="elEmail" /> and <Ref Subsect="elHomepage" />.
You can also specify an individual postal address here, instead of using
the <C>Address</C> element described below, see <Ref
Subsect="elAddress" />.
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 <C>Address</C> elements inside the <C>Author</C>
elements. <P/>
Use the <C>Br</C> element (see <Ref Subsect="Br"/>) to mark the line
breaks in the usual formatting of the address on a letter.<P/>
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.
This element may occur in the <C>Book</C> element after the <C>TitlePage</C> 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
<C>EMPTY</C> one can use the abbreviation
This element may occur in the <C>Book</C> element after the last
<C>Appendix</C> element. If it is present, a bibliography section is
generated and inserted into the document. The attribute <C>Databases</C>
must be specified, the names of several data files can be specified,
separated by commas.<P/>
Two kinds of files can be specified in <C>Databases</C>: The first are
&BibTeX; files as defined in <Cite Key="La85" Where="Appendix B"/>.
Such files must have a name with extension <F>.bib</F>, and in
<C>Databases</C> the name must be given <E>without</E> this extension.
Note that such <F>.bib</F>-files should be in latin1-encoding (or
ASCII-encoding).
The second are files in BibXMLext format as defined in Section <Ref
Sect="BibXMLformat"/>. These files must have an extension <F>.xml</F>
and in <C>Databases</C> the <E>full</E> name must be specified.<P/>
We suggest to use the BibXMLext format because it allows to produce
potentially nicer bibliography entries in text and HTML documents.<P/>
A bibliography style may be specified with the <C>Style</C> attribute. The
optional <C>Style</C> attribute (for &LaTeX; output of the document) must
also be specified without the <F>.bst</F> extension (the default is
<C>alpha</C>). See also section <Ref Subsect="Cite"/> for a description of
the <C>Cite</C> element which is used to include bibliography references
into the text. <P/>
This element may occur in the <C>Book</C> element after the
<C>Bibliography</C> element. If it is present, an index is generated and
inserted into the document. There are elements in &GAPDoc; which implicitly
generate index entries (e.g., <C>Func</C> (<Ref Subsect="Func" />)) and
there is an element <C>Index</C> (<Ref Subsect="Index" />) for explicitly
adding index entries.
</Subsection>
</Section>
<Section><Heading>Sectioning Elements</Heading>
A &GAPDoc; book is divided into <E>chapters</E>, <E>sections</E>, and
<E>subsections</E>. 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. <P/>
<E>Appendices</E> are a flavor of chapters, occurring after all
regular chapters. There is a special type of subsection called
<Q><C>ManSection</C></Q>. 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 <C>ManSection</C>. <P/>
Cross referencing is done on the level of <C>Subsection</C>s, respectively
<C>ManSection</C>s. The topics in &GAP;'s online help are also pointing to
subsections. So, they should not be too long.<P/>
We start our description of the sectioning elements <Q>top-down</Q>:
The <C>Body</C> element marks the main part of the document. It must occur
after the <C>TableOfContents</C> element. There is a big difference between
<E>inside</E> and <E>outside</E> of this element: Whereas regular text is
allowed nearly everywhere in the <C>Body</C> element and its subelements,
this is not true for the <E>outside</E>. This has also implications
on the handling of whitespace. <E>Outside</E> superfluous whitespace is
usually ignored when it occurs between elements. <E>Inside</E> of the
<C>Body</C> element whitespace matters because character data is allowed
nearly everywhere. Here is the definition in the DTD:
The fact that <C>Chapter</C> and <C>Section</C> elements are allowed here
leads to the possibility to omit the chapter level entirely in the
document. For a description of <C>%Text;</C> see <Ref Label="Text"
Text="here"/>.<P/>
(Remark: The purpose of this element is to make sure that a
<Emph>valid</Emph> &GAPDoc; document has a correct overall structure, which
is only possible when the top element <C>Book</C> has element content.)
A <C>Chapter</C> element can have a <C>Label</C> attribute, such that this
chapter can be referenced later on with a <C>Ref</C> element (see section
<Ref Subsect="Ref"/>). Note that you have to specify a label to reference
the chapter as there is no automatic labelling!<P/>
<C>Chapter</C> elements can contain text (for a description of
<C>%Text;</C> see <Ref Label="Text" Text="here"/>), <C>Section</C>
elements, and <C>Heading</C> elements.<P/>
The following <Emph>additional</Emph> rule cannot be stated in the DTD
because we want a <C>Chapter</C> element to have mixed content. There must
be <Emph>exactly one</Emph> <C>Heading</C> element in the <C>Chapter</C> element, containing the heading of the chapter. Here is its definition:
This element is used for headings in <C>Chapter</C>, <C>Section</C>,
<C>Subsection</C>, and <C>Appendix</C> elements. It may only contain
<C>%InnerText;</C> (for a description see <Ref Text="here"
Label="InnerText"/>).<P/>
Each of the mentioned sectioning elements must contain exactly one direct
<C>Heading</C> element (i.e., one which is not contained in another
sectioning element).
The <C>Appendix</C> element behaves exactly like a <C>Chapter</C> element
(see <Ref Subsect="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., ...). <P/>
Again there is an optional <C>Label</C> attribute used for references.
</Subsection>
A <C>Section</C> element can have a <C>Label</C> attribute, such that this
section can be referenced later on with a <C>Ref</C> element (see section
<Ref Subsect="Ref"/>). Note that you have to specify a label to reference
the section as there is no automatic labelling!<P/>
<C>Section</C> elements can contain text (for a description of
<C>%Text;</C> see <Ref Label="Text" Text="here"/>), <C>Heading</C>
elements, and subsections. <P/>
There must be exactly one direct <C>Heading</C> element in a <C>Section</C> element, containing the heading of the section. <P/>
Note that a subsection is either a <C>Subsection</C> element or a
<C>ManSection</C> element.
The <C>Subsection</C> element can have a <C>Label</C> attribute, such that
this subsection can be referenced later on with a <C>Ref</C> element (see
section <Ref Subsect="Ref"/>). Note that you have to specify a label to
reference the subsection as there is no automatic labelling!<P/>
<C>Subsection</C> elements can contain text (for a description
of <C>%Text;</C> see <Ref Label="Text" Text="here"/>), and
<C>Heading</C> elements.<P/>
There must be exactly one <C>Heading</C> element in a <C>Subsection</C> element, containing the heading of the subsection. <P/>
Another type of subsection is a <C>ManSection</C>, explained now:
</Subsection>
</Section>
<Section Label="sec:mansect">
<Heading>ManSection–a special kind of subsection</Heading>
<C>ManSection</C>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.
The <C>ManSection</C> element can have a <C>Label</C> attribute, such that
this subsection can be referenced later on with a <C>Ref</C> element (see
section <Ref Subsect="Ref"/>). But this is probably rarely necessary because
the elements <C>Func</C> and so on (explained below) generate automatically
labels for cross referencing.<P/>
The content of a <C>ManSection</C> element is one or more elements
describing certain items in &GAP;, each of them optionally followed by a
<C>Returns</C> element, followed by a <C>Description</C> element, which
contains <C>%Text;</C> (see <Ref Label="Text" Text="here"/>) describing it.
(Remember to include examples in the description as often as possible,
see <Ref Subsect="Log" />). The classes of items &GAPDoc; knows
of are: functions (<C>Func</C>), operations (<C>Oper</C>), constructors
(<C>Constr</C>), methods (<C>Meth</C>), filters (<C>Filt</C>), properties
(<C>Prop</C>), attributes (<C>Attr</C>), variables (<C>Var</C>), families
(<C>Fam</C>), and info classes (<C>InfoClass</C>). One <C>ManSection</C>
should only describe several of such items when these are very closely
related. <P/>
Each element for an item corresponding to a &GAP; function can be followed
by a <C>Returns</C> element. In output versions of the document the string
<Q>Returns: </Q> will be put in front of the content text. The text in the
<C>Returns</C> 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).<P/>
<C>ManSection</C>s are also sectioning elements which count as subsections.
Usually there should be no <C>Heading</C>-element in a <C>ManSection</C>,
in that case a heading is generated automatically from the first
<C>Func</C>-like element. Sometimes this default behaviour does not look
appropriate, for example when there are several <C>Func</C>-like elements.
For such cases an optional <C>Heading</C> is allowed.
This element is used within a <C>ManSection</C> element to specify the usage
of a function. The <C>Name</C> attribute is required and its value is the
name of the function. The value of the <C>Arg</C> 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 <C><![CDATA["grp[, elm]"]]></C> or <C><![CDATA["xx[y[z] ]"]]></C>. If
&GAP; options are used, this can be followed by a colon <C>:</C> and one or
more assignments, like <C><![CDATA["n[, r]: tries := 100"]]></C>. <P/>
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 <E>always</E> be written with the <C>Ref</C> element, see <Ref
Subsect="Ref" />. This allows to use a unique typesetting style for function
names and automatic cross referencing.<P/>
If the optional <C>Label</C> attribute is given, it is appended (with a
colon <C>:</C> 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.
<Listing Type="Example">
<![CDATA[<Func Arg="x[, y]" Name="LibFunc" Label="for my objects"/>]]>
</Listing>
The optional <C>Comm</C> attribute should be a short description of the
function, usually at most one line long (this is currently nowhere
used).<P/>
This element automatically produces an index entry with the name of the
function and, if present, the text of the <C>Label</C> attribute as subentry
(see also <Ref Subsect="TheIndex" /> and <Ref Subsect="Index" />).
This element is used within a <C>ManSection</C> element to specify the usage
of an operation. The attributes are used exactly in the same way as in the
<C>Func</C> element (see <Ref Subsect="Func"/>). <P/>
Note that multiple descriptions of the same operation may occur in a
document because there may be several declarations in &GAP;. Furthermore
there may be several <C>ManSection</C>s for methods of this operation
(see <Ref Subsect="Meth" />) which also use the same name. For
reference purposes these must be distinguished by different <C>Label</C>
attributes.
This element is used within a <C>ManSection</C> element to specify the usage
of a constructor. The attributes are used exactly in the same way as in the
<C>Func</C> element (see <Ref Subsect="Func"/>). <P/>
Note that multiple descriptions of the same constructor may occur in a
document because there may be several declarations in &GAP;. Furthermore
there may be several <C>ManSection</C>s for methods of this constructor
(see <Ref Subsect="Meth" />) which also use the same name. For
reference purposes these must be distinguished by different <C>Label</C>
attributes.
This element is used within a <C>ManSection</C> element to specify the
usage of a method. The attributes are used exactly in the same
way as in the <C>Func</C> element (see <Ref Subsect="Func"/>). <P/>
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 <C>ManSection</C>s.
It is however required that these subsections and those describing
the corresponding operation are distinguished by different <C>Label</C>
attributes.
This element is used within a <C>ManSection</C> element to specify the
usage of a filter. The first four attributes are used in the same
way as in the <C>Func</C> element (see <Ref Subsect="Func"/>),
except that the <C>Arg</C> attribute is optional. <P/>
The <C>Type</C> attribute can be any string, but it is thought to be
something like <Q><C>Category</C></Q> or <Q><C>Representation</C></Q>.
</Subsection>
This element is used within a <C>ManSection</C> element to specify the
usage of a property. The attributes are used exactly in the same
way as in the <C>Func</C> element (see <Ref Subsect="Func"/>). <P/>
</Subsection>
This element is used within a <C>ManSection</C> element to specify the usage
of an attribute (in &GAP;). The attributes are used exactly in the same
way as in the <C>Func</C> element (see <Ref Subsect="Func"/>). <P/>
</Subsection>
<Listing Type="From gapdoc.dtd">
<![CDATA[<!ELEMENT Var EMPTY>
<!ATTLIST Var Name CDATA #REQUIRED
Label CDATA #IMPLIED
Comm CDATA #IMPLIED>]]>
</Listing>
This element is used within a <C>ManSection</C> element to document
a global variable. The attributes are used exactly in the same
way as in the <C>Func</C> element (see <Ref Subsect="Func"/>) except
that there is no <C>Arg</C> attribute. <P/>
</Subsection>
<Listing Type="From gapdoc.dtd">
<![CDATA[<!ELEMENT Fam EMPTY>
<!ATTLIST Fam Name CDATA #REQUIRED
Label CDATA #IMPLIED
Comm CDATA #IMPLIED>]]>
</Listing>
This element is used within a <C>ManSection</C> element to document
a family. The attributes are used exactly in the same
way as in the <C>Func</C> element (see <Ref Subsect="Func"/>) except
that there is no <C>Arg</C> attribute. <P/>
</Subsection>
<Listing Type="From gapdoc.dtd">
<![CDATA[<!ELEMENT InfoClass EMPTY>
<!ATTLIST InfoClass Name CDATA #REQUIRED
Label CDATA #IMPLIED
Comm CDATA #IMPLIED>]]>
</Listing>
This element is used within a <C>ManSection</C> element to document
an info class. The attributes are used exactly in the same
way as in the <C>Func</C> element (see <Ref Subsect="Func"/>) except
that there is no <C>Arg</C> attribute. <P/>
</Subsection>
</Section>
<Section><Heading>Cross Referencing and Citations</Heading>
Cross referencing in the &GAPDoc; system is somewhat different to
the usual &LaTeX; cross referencing in so far, that a reference
knows <Q>which type of object</Q> it is referencing. For example a
<Q>reference to a function</Q> is distinguished from a <Q>reference to
a chapter</Q>. 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.<P/>
The <C>Ref</C> element is defined to be <C>EMPTY</C>. If one of
the attributes <C>Func</C>, <C>Oper</C>, <C>Constr</C>, <C>Meth</C>,
<C>Prop</C>, <C>Attr</C>, <C>Var</C>, <C>Fam</C>, <C>InfoClass</C>,
<C>Chap</C>, <C>Sect</C>, <C>Subsect</C>, <C>Appendix</C> is given then
there must be exactly one of these, making the reference one to the
corresponding object. The <C>Label</C> 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.)<P/>
A reference to a <C>Label</C> element defined below (see <Ref
Subsect="Label"/>) is done by giving the <C>Label</C> attribute and
optionally the <C>Text</C> attribute. If the <C>Text</C> attribute is
present its value is typeset in place of the <C>Ref</C> 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 Subsect="Table"/>).<P/>
<!-- Optionally an external reference into another book can be specified by using the <C>BookName</C> attribute. In this case the <C>Label</C> attribute <E>must</E> be specified and refers to a search string as in the &GAP; help system. It is guaranteed that the reference points to the position in the other book, that the &GAP; help system finds as first match if one types the value of the <C>Label</C> element after a question mark.<P/>
-->
An external reference into another book can be specified by using the
<C>BookName</C> attribute. In this case the <C>Label</C> 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 <Q>?book name: label</Q> inside &GAP;.<P/>
The optional attribute <C>Style</C> can take only the values <C>Text</C> and
<C>Number</C>. 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 &GAP; object generate the name of the corresponding
object with some additional link or sectioning information, which is the
behavior of <C>Style="Text"</C>. In case <C>Style="Number"</C> in all cases
an explicit section number is generated. So
<Listing Type="Example">
<![CDATA[<Ref Subsect="Func" Style="Text"/> described in section
<Ref Subsect="Func" Style="Number"/>]]>
</Listing>
produces: <Ref Subsect="Func" Style="Text"/> described in section
<Ref Subsect="Func" Style="Number"/>.
</Subsection>
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 <C>Name</C> attribute must be
unique under all <C>Label</C> elements.
This element is for bibliography citations. It is <C>EMPTY</C> by
definition. The attribute <C>Key</C> is the key for a lookup in a &BibTeX;
database that has to be specified in the <C>Bibliography</C> element (see
<Ref Subsect="Bibliography"/>). The value of the <C>Where</C> attribute
specifies the position in the document as in the corresponding &LaTeX;
syntax <C>\cite[Where value]{Key value}</C>.
</Subsection>
<Listing Type="From gapdoc.dtd">
<![CDATA[<!ELEMENT Index (%InnerText;|Subkey)*>
<!ATTLIST Index Key CDATA #IMPLIED
Subkey CDATA #IMPLIED>
<!ELEMENT Subkey (%InnerText;)*>]]>
</Listing>
This element generates an index entry. The content of the element is typeset
in the index. It can optionally contain a <C>Subkey</C> element. If one or
both of the attributes <C>Key</C> and <C>Subkey</C> are given, then the
attribute values are used for sorting the index entries. Otherwise the
content itself is used for sorting. The attributes should be used when the
content contains markup.
Note that all <C>Func</C> and similar elements automatically generate index
entries. If the <C>TheIndex</C> element (<Ref Subsect="TheIndex" />) is not
present in the document all <C>Index</C> elements are ignored.
<Listing Type="From gapdoc.dtd">
<![CDATA[<!ELEMENTURL (#PCDATA|Alt|Link|LinkText)*> <!-- Link, LinkText
variant for case where text needs further markup -->
<!ATTLISTURL 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 -->
]]>
</Listing>
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 <C>Text</C> attribute (in this case the text
cannot contain further markup), or the element contains the two elements
<C>Link</C> and <C>LinkText</C> which in turn contain the URL and the
text, respectively. The default value for the text is the URL itself.
</Subsection>
This elementtype 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 <Q><C>mailto:</C></Q>. 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
<Q><C>mailto:</C></Q> prefix.
</Subsection>
This elementtype is the special case of an URL specifying a WWW-homepage.
</Subsection>
</Section>
<Section><Heading>Structural Elements like Lists</Heading>
The &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.
<Listing Type="From gapdoc.dtd">
<![CDATA[<!ELEMENT List ( ((Mark,Item)|Item)+ )>
<!ATTLIST List Only CDATA #IMPLIED
Not CDATA #IMPLIED>]]>
</Listing>
This element produces a list. Each item in the list corresponds to
an <C>Item</C> element. Every <C>Item</C> element is optionally preceded
by a <C>Mark</C> 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. <P/>
The <C>Only</C> and <C>Not</C> attributes can be used to specify, that
the list is included into the output by only one type of converter
(<C>Only</C>) or all but one type of converter (<C>Not</C>). Of course
at most one of the two attributes may occur in one element. The following
values are allowed as of now: <Q><C>LaTeX</C></Q>, <Q><C>HTML</C></Q>,
and <Q><C>Text</C></Q>. See also the <C>Alt</C> element in
<Ref Subsect="Alt"/> for more about text alternatives for certain
converters.
</Subsection>
This element is used in the <C>List</C>, <C>Enum</C>, and <C>Table</C>
elements to specify the items. See sections <Ref Subsect="List"/>,
<Ref Subsect="Enum"/>, and <Ref Subsect="Table"/> for further information.
<Listing Type="From gapdoc.dtd">
<![CDATA[<!ELEMENT Enum ( Item+ )>
<!ATTLIST Enum Only CDATA #IMPLIED
Not CDATA #IMPLIED>]]>
</Listing>
This element is used like the <C>List</C> element (see <Ref
Subsect="List"/>) except that the items must not have marks attached to
them. Instead, the items are numbered automatically. The same comments about
the <C>Only</C> and <C>Not</C> attributes as above apply.
A table in &GAPDoc; consists of an optional <C>Caption</C> element followed
by a sequence of <C>Row</C> and <C>HorLine</C> elements. A <C>HorLine</C> element produces a horizontal line in the table. A <C>Row</C> element
consists of a sequence of <C>Item</C> elements as they also occur in
<C>List</C> and <C>Enum</C> elements. The <C>Only</C> and <C>Not</C>
attributes have the same functionality as described in the <C>List</C> element in <Ref Subsect="List"/>. <P/>
The <C>Align</C> attribute is written like a &LaTeX; tabular alignment
specifier but only the letters <Q><C>l</C></Q>, <Q><C>r</C></Q>,
<Q><C>c</C></Q>, and <Q><C>|</C></Q> are allowed meaning left alignment,
right alignment, centered alignment, and a vertical line as delimiter
between columns respectively. <P/>
If the <C>Label</C> attribute is there, one can reference the table
with the <C>Ref</C> element (see <Ref Subsect="Ref"/>) using its
<C>Label</C> attribute.<P/>
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
<Q><C>|</C></Q> column separators and <C>HorLine</C> elements as intended.
There are lines between all columns and rows or no lines at all.
</Subsection>
</Section>
<Section><Heading>Types of Text</Heading>
This section covers the markup of text. Various types of <Q>text</Q> exist.
The following elements are used in the &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 <Q>lighter</Q>. <P/>
Most of the following elements are thought to contain only character
data and no further markup elements. It is however necessary to
allow <C>Alt</C> elements to resolve the entities described in section
<Ref Subsect="GDent"/>.
<Subsection><Heading><C><Emph></C> and <C><E></C></Heading>
<Index Key="Emph"><C>Emph</C></Index>
<Index Key="E"><C>E</C></Index>
<Listing Type="From gapdoc.dtd">
<![CDATA[<!ELEMENT Emph (%InnerText;)*> <!-- Emphasize something -->
<!ELEMENT E (%InnerText;)*> <!-- the same as shortcut -->]]>
</Listing>
This element is used to emphasize some piece of text. It may contain
<C>%InnerText;</C> (see <Ref Text="here" Label="InnerText"/>).
</Subsection>
<Subsection><Heading><C><Quoted></C> and <C><Q></C></Heading>
<Index Key="Quoted"><C>Quoted</C></Index>
<Index Key="Q"><C>Q</C></Index>
<Listing Type="From gapdoc.dtd">
<![CDATA[<!ELEMENT Quoted (%InnerText;)*> <!-- Quoted (in quotes) text -->
<!ELEMENT Q (%InnerText;)*> <!-- Quoted text (shortcut) -->]]>
</Listing>
This element is used to put some piece of text into <Q> </Q>-quotes.
It may contain <C>%InnerText;</C> (see <Ref Text="here"
Label="InnerText"/>).
</Subsection>
<Subsection><Heading><C><Keyword></C> and <C><K></C></Heading>
<Index Key="Keyword"><C>Keyword</C></Index>
<Index Key="K"><C>K</C></Index>
This element is used to mark something as a <E>keyword</E>. Usually this
will be a &GAP; keyword such as <Q><K>if</K></Q> or <Q><K>for</K></Q>.
No further markup elements are allowed within this element except for
the <C>Alt</C> element, which is necessary.
</Subsection>
<Subsection Label="Arg"><Heading><C><Arg></C> and
<C><A></C></Heading>
<Index Key="Arg"><C>Arg</C></Index>
<Index Key="A"><C>A</C></Index>
This element is used inside <C>Description</C>s in <C>ManSection</C>s to
mark something as an <E>argument</E> (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>
<Subsection Label="Code"><Heading><C><Code></C> and
<C><C></C></Heading>
<Index Key="Code"><C>Code</C></Index>
<Index Key="C"><C>C</C></Index>
<Listing Type="From gapdoc.dtd">
<![CDATA[<!ELEMENT Code (#PCDATA|Arg|Alt)*> <!-- GAP code -->
<!ELEMENT C (#PCDATA|Arg|Alt)*> <!-- GAP code (shortcut) -->]]>
</Listing>
This element is used to mark something as a piece of <E>code</E> like for
example a &GAP; expression. It is guaranteed that the converters typeset
this exactly as in the <C>Listing</C> element (compare section <Ref
Subsect="Listing"/>). The only further markup elements allowed within this element are <C><Arg></C> elements (see <Ref Subsect="Arg"/>).
</Subsection>
<Subsection><Heading><C><File></C> and <C><F></C></Heading>
<Index Key="File"><C>File</C></Index>
<Index Key="F"><C>F</C></Index>
This element is used to mark something as a <E>filename</E> or a
<E>pathname</E> in the file system. No further markup elements are allowed
within this element.
</Subsection>
<Subsection><Heading><C><Button></C> and <C><B></C></Heading>
<Index Key="Button"><C>Button</C></Index>
<Index Key="B"><C>B</C></Index>
This element is used to mark something as a <E>button</E>. It can also be
used for other items in a graphical user interface like <E>menus</E>,
<E>menu entries</E>, or <E>keys</E>. No further markup elements are allowed
within this element.
<Listing Type="From gapdoc.dtd">
<![CDATA[<!ELEMENT Package (#PCDATA|Alt)*> <!-- A package name -->]]>
</Listing>
This element is used to mark something as a name of a <E>package</E>. This
is for example used to define the entities &GAP;, &XGAP; or &GAPDoc; (see
section <Ref Subsect="GDent"/>). No further markup elements are allowed
within this element.
<Listing Type="From gapdoc.dtd">
<![CDATA[<!ELEMENT Listing (#PCDATA)> <!-- This is just for GAP code listings -->
<!ATTLIST Listing TypeCDATA #IMPLIED> <!-- a comment about the type of listed code, may appear in
output -->
</Listing>
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 <E>not</E> use the character entities described in section <Ref
Subsect="GDent"/> but instead type the characters directly. Only the general XML rules from section <Ref Sect="EnterXML"/> apply. Note especially the
usage of <C><![CDATA[</C> sections described there. It is guaranteed
that all converters use a fixed width font for typesetting <C>Listing</C>
elements. Compare also the usage of the <C>Code</C> and <C>C</C> elements in
<Ref Subsect="Code"/>. <P/>
The <C>Type</C> attribute contains a comment about the type of listed code.
It may appear in the output.
</Subsection>
<Subsection Label="Log"><Heading><C><Log></C> and
<C><Example></C></Heading>
<Index Key="Log"><C>Log</C></Index>
<Index Key="Example"><C>Example</C></Index>
<Listing Type="From gapdoc.dtd">
<![CDATA[<!ELEMENT Example (#PCDATA)> <!-- This is subject to the automatic
example checking mechanism -->
<!ELEMENT Log (#PCDATA)> <!-- This not -->]]>
</Listing>
These two elements behave exactly like the <C>Listing</C> element (see <Ref
Subsect="Listing"/>). They are thought for protocols of &GAP; sessions. The
only difference between the two is that <C>Example</C> sections are intended
to be subject to an automatic manual checking mechanism used to ensure the
correctness of the &GAP; manual whereas <C>Log</C> is not touched by this
(see section <Ref Sect="Sec:TestExample"/> for checking tools).
<P/>
To get a good layout of the examples for display in a standard terminal we
suggest to use <C>SizeScreen([72]);</C> (see <Ref Func="SizeScreen"
BookName="Reference"/>) in your &GAP; session before producing the content
of <C>Example</C> elements.
</Subsection>
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.<P/>
This element is intended to be used together with the <C>Alt</C> element to
specify pre-formatted ASCII alternatives for complicated <C>Display</C>
formulae or <C>Table</C>s.
</Subsection>
</Section>
<Section Label="MathForm"><Heading>Elements for Mathematical Formulae</Heading>
<Subsection Label="Math"><Heading><C><Math></C>
and <C><Display></C></Heading>
<Index Key="Math"><C>Math</C></Index>
<Index Key="Display"><C>Display</C></Index>
<Listing Type="From gapdoc.dtd"><![CDATA[ <!-- Normal TeX math mode formula -->
<!ELEMENT Math (#PCDATA|A|Arg|Alt)*> <!-- TeX displayed math mode formula -->
<!ELEMENTDisplay (#PCDATA|A|Arg|Alt)*> <!-- Mode="M" causes <M>-style formatting -->
<!ATTLISTDisplay Mode CDATA #IMPLIED>]]>
</Listing>
These elements are used for mathematical formulae. As described in section
<Ref Sect="GDformulae"/> they correspond to &LaTeX;'s math and display math
mode respectively.<P/>
The formulae are typed in as in &LaTeX;, <E>except</E> that the standard XMLentities, see <Ref Subsect="XMLent" /> (in particular the
characters <C><</C> and <C>&</C>), must be escaped - either by
using the corresponding entities or by enclosing the formula between
<Q><C><![CDATA[</C></Q> and <Q><C>]]></C></Q>. (The main reference
for &LaTeX; is <Cite Key="La85" />.)<P/>
It is also possible to use some unicode characters for
mathematical symbols directly, provided that it can be translated
by <Ref Func="Encode" /> into <C>"LaTeX"</C> encoding and that
<Ref Func="SimplifiedUnicodeString"/> with arguments <C>"latin1"</C>
and <C>"single"</C> returns something sensible. Currently, we
support entities <C>&CC;</C>, <C>&ZZ;</C>, <C>&NN;</C>,
<C>&PP;</C>, <C>&QQ;</C>, <C>&HH;</C>, <C>&RR;</C> for
the corresponding black board bold letters &CC;, &ZZ;, &NN;, &PP;, &QQ;,
&HH; and &RR;, respectively.
<P/>
The only elementtype that is allowed within the formula elements is the
<C>Arg</C> or <C>A</C> element (see <Ref Subsect="Arg"/>), which is used to
typeset identifiers that are arguments to &GAP; functions or operations.<P/>
If a <C>Display</C> element has an attribute <C>Mode</C> with value
<C>"M"</C>, then the formula is formatted as in <C>M</C> elements
(see <Ref Subsect="M" />). Otherwise in text and HTML output the
formula is shown as &LaTeX; source code.<P/>
For simple formulae (and you should try to make all your formulae
simple!) attempt to use the <C>M</C> element or the <C>Mode="M"</C>
attribute in <C>Display</C> 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 <C>Math</C>
elements and <C>Display</C> elements without attribute or provide useful
text substitutes for complicated formulae via <C>Alt</C> elements
(see <Ref Subsect="Alt" /> and <Ref Subsect="Verb" />).
<Listing Type="From gapdoc.dtd"><![CDATA[ <!-- Math with well defined translation to text output -->
<!ELEMENT M (#PCDATA|A|Arg|Alt)*>]]>
</Listing>
The <Q><C>M</C></Q> elementtype is intended for formulae in the running
text for which there is a sensible text version. For the &LaTeX; version of
a &GAPDoc; document the <C>M</C> and <C>Math</C> elements are equivalent.
The remarks in <Ref Subsect="Math" /> about special characters and the
<C>Arg</C> element apply here as well. A document which has all formulae
enclosed in <C>M</C> elements can be well readable in text terminal output
and printed output versions.<P/>
Compared to former versions of &GAPDoc; many more formulae can be put into
<C>M</C> elements. Most modern terminal emulations support unicode characters
and many mathematical symbols can now be represented by such characters.
But even if a terminal can only display ASCII characters, the user will see
some not too bad representation of a formula.<P/>
As examples, here are some &LaTeX; macros which have a sensible
ASCII translation and are
guaranteed to be translated accordingly by text (and HTML) converters
(for a full list of handled Macros see <C>RecNames(TEXTMTRANSLATIONS)</C>):
In all other macros only the backslash is removed (except for some macros
describing more exotic symbols). Whitespace is normalized
(to one blank) but not removed. Note that whitespace is not added, so you
may want to add a few more spaces than you usually do in your &LaTeX;
documents.<P/>
Braces <C>{}</C> are removed in general, however pairs of
double braces are converted to one pair of braces. This can be used to write
<C><M>x^{12}</M></C>
for <C>x^12</C> and
<C><M>x_{{i+1}}</M></C>
for <C>x_{i+1}</C>. <P/>
This element is used to specify alternatives for different output
formats within normal text. See also sections <Ref Subsect="List"/>, <Ref
Subsect="Enum"/>, and <Ref Subsect="Table"/> for alternatives in lists and
tables.
<Listing Type="From gapdoc.dtd">
<![CDATA[<!ELEMENT Alt (%InnerText;)*> <!-- This is only to allow "Only" and
"Not" attributes for normal text -->
<!ATTLIST Alt Only CDATA #IMPLIED
Not CDATA #IMPLIED>]]>
</Listing>
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 &GAPDoc; are: <Q><C>LaTeX</C></Q>, <Q><C>HTML</C></Q>, and
<Q><C>Text</C></Q>. If the <C>Only</C> attribute is specified then only the
corresponding converter will include the content of the element into the
output document. If the <C>Not</C> attribute is specified the corresponding
--> --------------------
--> maximum size reached
--> --------------------
¤ Dauer der Verarbeitung: 0.22 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.
