Quellcodebibliothek Statistik Leitseite products/Sources/formale Sprachen/GAP/pkg/gapdoc/doc/   (Algebra von RWTH Aachen Version 4.15.1©)  Datei vom 21.1.2024 mit Größe 97 kB image not shown  

Quelle  chap3.html   Sprache: HTML

 
 products/Sources/formale Sprachen/GAP/pkg/gapdoc/doc/chap3.html


<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
         "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>GAP (GAPDoc) - Chapter 3: The Document Type Definition</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
<meta name="generator" content="GAPDoc2HTML" />
<link rel="stylesheet" type="text/css" href="manual.css" />
<script src="manual.js" type="text/javascript"></script>
<script type="text/javascript">overwriteStyle();</script>
</head>
<body class="chap3"  onload="jscontent()">


<div class="chlinktop"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a>  <a href="chap1.html">1</a>  <a href="chap2.html">2</a>  <a href="chap3.html">3</a>  <a href="chap4.html">4</a>  <a href="chap5.html">5</a>  <a href="chap6.html">6</a>  <a href="chap7.html">7</a>  <a href="chapA.html">A</a>  <a href="chapB.html">B</a>  <a href="chapC.html">C</a>  <a href="chapBib.html">Bib</a>  <a href="chapInd.html">Ind</a>  </div>

<div class="chlinkprevnexttop"> <a href="chap0.html">[Top of Book]</a>   <a href="chap0.html#contents">[Contents]</a>    <a href="chap2.html">[Previous Chapter]</a>    <a href="chap4.html">[Next Chapter]</a>   </div>

<p id="mathjaxlink" class="pcenter"><a href="chap3_mj.html">[MathJax on]</a></p>
<p><a id="X7859CFF180D52D49" name="X7859CFF180D52D49"></a></p>
<div class="ChapSects"><a href="chap3.html#X7859CFF180D52D49">3 <span class="Heading">The Document Type Definition</span></a>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap3.html#X7B76F6F786521F6B">3.1 <span class="Heading">What is a DTD?</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap3.html#X7DB0F9E57879CC76">3.2 <span class="Heading">Overall Document Structure</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7C7258A57B831934">3.2-1 <span class="Heading"><code class="code"><Book></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X842B421A7FBCDD2C">3.2-2 <span class="Heading"><code class="code"><TitlePage></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7BCC8E6F79021294">3.2-3 <span class="Heading"><code class="code"><Title></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X82E82AF48217CC14">3.2-4 <span class="Heading"><code class="code"><Subtitle></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X876962807DCC52B3">3.2-5 <span class="Heading"><code class="code"><Version></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X87E7CD5B79230B90">3.2-6 <span class="Heading"><code class="code"><TitleComment></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X8731459C7E4C56DA">3.2-7 <span class="Heading"><code class="code"><Author></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X8264A69D7DCDD773">3.2-8 <span class="Heading"><code class="code"><Date></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7EEF65A07A094F65">3.2-9 <span class="Heading"><code class="code"><Address></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X833110FE79628313">3.2-10 <span class="Heading"><code class="code"><Abstract></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X84BBD8307E08E62F">3.2-11 <span class="Heading"><code class="code"><Copyright></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X8143972D7C17838E">3.2-12 <span class="Heading"><code class="code"><Acknowledgements></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7C09A3398059D18C">3.2-13 <span class="Heading"><code class="code"><Colophon></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7E97263A83DC26E9">3.2-14 <span class="Heading"><code class="code"><TableOfContents></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X84F3DF21786A8751">3.2-15 <span class="Heading"><code class="code"><Bibliography></code>
</span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7C53615A8477F1E5">3.2-16 <span class="Heading"><code class="code"><TheIndex></code></span></a>
</span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap3.html#X80E2AD7481DD69D9">3.3 <span class="Heading">Sectioning Elements</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7B38415687510D0A">3.3-1 <span class="Heading"><code class="code"><Body></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7A86B2BA7D688B6B">3.3-2 <span class="Heading"><code class="code"><Chapter></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X79825E1C821D0B79">3.3-3 <span class="Heading"><code class="code"><Heading></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7C701B2779767556">3.3-4 <span class="Heading"><code class="code"><Appendix></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X844DC2B47FB37339">3.3-5 <span class="Heading"><code class="code"><Section></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X803ACA187E292969">3.3-6 <span class="Heading"><code class="code"><Subsection></code></span></a>
</span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap3.html#X877B8B7C7EDD09E9">3.4 <span class="Heading">ManSection–a special kind of subsection</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X8375D9CC8672A1D5">3.4-1 <span class="Heading"><code class="code"><ManSection></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7C41A7B5845205C4">3.4-2 <span class="Heading"><code class="code"><Func></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7A15825E818A81CD">3.4-3 <span class="Heading"><code class="code"><Oper></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7FBFD7A3786C7CAB">3.4-4 <span class="Heading"><code class="code"><Constr></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X81196E2B7F286A01">3.4-5 <span class="Heading"><code class="code"><Meth></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7D8D2C38828D5854">3.4-6 <span class="Heading"><code class="code"><Filt></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7D6400A67C30B752">3.4-7 <span class="Heading"><code class="code"><Prop></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X78CEEC5986987A97">3.4-8 <span class="Heading"><code class="code"><Attr></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7C3AACBE7BC6AABF">3.4-9 <span class="Heading"><code class="code"><Var></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X85EE992E7FED2FE6">3.4-10 <span class="Heading"><code class="code"><Fam></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X78F0D4D1811E5BAE">3.4-11 <span class="Heading"><code class="code"><InfoClass></code></span></a>
</span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap3.html#X78595FB585569617">3.5 <span class="Heading">Cross Referencing and Citations</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X8656F2338007406E">3.5-1 <span class="Heading"><code class="code"><Ref></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7C85CA5484344DB5">3.5-2 <span class="Heading"><code class="code"><Label></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X851DE9D279D8FB04">3.5-3 <span class="Heading"><code class="code"><Cite></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X811042BA78843777">3.5-4 <span class="Heading"><code class="code"><Index></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X81B3E46F839E1C5B">3.5-5 <span class="Heading"><code class="code"><URL></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X8310C4F084CD9DB9">3.5-6 <span class="Heading"><code class="code"><Email></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7D5CC4267D04D7E7">3.5-7 <span class="Heading"><code class="code"><Homepage></code></span></a>
</span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap3.html#X840099DF83823686">3.6 <span class="Heading">Structural Elements like Lists</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X785183F67DA402A0">3.6-1 <span class="Heading"><code class="code"><List></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7B1545A9797442DC">3.6-2 <span class="Heading"><code class="code"><Mark></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X86C204987AB4B13D">3.6-3 <span class="Heading"><code class="code"><Item></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X78A52B00846562DE">3.6-4 <span class="Heading"><code class="code"><Enum></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7F9CAA577EB4070B">3.6-5 <span class="Heading"><code class="code"><Table></code></span></a>
</span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap3.html#X7CA1E1327AFBA578">3.7 <span class="Heading">Types of Text</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7B15C428861749FD">3.7-1 <span class="Heading"><code class="code"><Emph></code> and <code class="code"><E></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X80028C2483C9467E">3.7-2 <span class="Heading"><code class="code"><Quoted></code> and <code class="code"><Q></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X867BB95E7DC87014">3.7-3 <span class="Heading"><code class="code"><Keyword></code> and <code class="code"><K></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X86FD4CCA7F98351F">3.7-4 <span class="Heading"><code class="code"><Arg></code> and 
                                 <code class="code"><A></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X8400998B7B3A4379">3.7-5 <span class="Heading"><code class="code"><Code></code> and 
                                  <code class="code"><C></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X875AF9B4812C5249">3.7-6 <span class="Heading"><code class="code"><File></code> and <code class="code"><F></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7929BA7D78A977FF">3.7-7 <span class="Heading"><code class="code"><Button></code> and <code class="code"><B></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7F4FFA877B775188">3.7-8 <span class="Heading"><code class="code"><Package></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7F531B157D656836">3.7-9 <span class="Heading"><code class="code"><Listing></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X810DEA1E83A57CFE">3.7-10 <span class="Heading"><code class="code"><Log></code> and
                                 <code class="code"><Example></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7F8C4D018346B2CF">3.7-11 <span class="Heading"><code class="code"><Verb></code></span></a>
</span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap3.html#X8145F6B37C04AA0A">3.8 <span class="Heading">Elements for Mathematical Formulae</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7AA02845868AA533">3.8-1 <span class="Heading"><code class="code"><Math></code> 
                              and <code class="code"><Display></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7ABF42328467E966">3.8-2 <span class="Heading"><code class="code"><M></code></span></a>
</span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap3.html#X7A0D26B180BEDE37">3.9 <span class="Heading">Everything else</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X850E69017945AE3E">3.9-1 <span class="Heading"><code class="code"><Alt></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X85D23A648444069F">3.9-2 <span class="Heading"><code class="code"><Par></code> and 
                                 <code class="code"><P></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7A3EF0647B10C1EC">3.9-3 <span class="Heading"><code class="code"><Br></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap3.html#X7A81FB717A30B485">3.9-4 <span class="Heading"><code class="code"><Ignore></code></span></a>
</span>
</div></div>
</div>

<h3>3 <span class="Heading">The Document Type Definition</span></h3>

<p>In this chapter we first explain what a <q>document type definition</q> is and then describe <code class="file">gapdoc.dtd</code> in detail. That file together with the current chapter define how a <strong class="pkg">GAPDoc</strong> document has to look like. It can be found in the main directory of the <strong class="pkg">GAPDoc</strong> package and it is reproduced in Appendix <a href="chapB.html#X85366C6480D58C51"><span class="RefLink">B</span></a>.</p>

<p>We do not give many examples in this chapter which is more intended as a formal reference for all <strong class="pkg">GAPDoc</strong> elements. Instead, we provide a separate help book, see <a href="../../../pkg/GAPDoc-1.6.7/example/chap2.html#X7A480B9A795EF264"><span class="RefLink">GAPDoc Example: Various types of text</span></a>. 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 <a href="chap1.html#X7D4EE663818DA109"><span class="RefLink">1</span></a>.</p>

<p><a id="X7B76F6F786521F6B" name="X7B76F6F786521F6B"></a></p>

<h4>3.1 <span class="Heading">What is a DTD?</span></h4>

<p>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 <a href="chap2.html#X8561F07A81CABDD6"><span class="RefLink">2.1-14</span></a>.</p>

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

<p>Note that a DTD can <em>not</em> 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>

<p>For the remaining part of this chapter we have divided the elements of <strong class="pkg">GAPDoc</strong> documents into several subsets, each of which will be discussed in one of the next sections.</p>

<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 <code class="file">gapdoc.dtd</code>. For precise descriptions of the syntax of DTD's see again the official standard in:



<p>  <span class="URL"><a href="https://www.xml.com/axml/axml.html">https://www.xml.com/axml/axml.html</a></span></p>

<p><a id="X7DB0F9E57879CC76" name="X7DB0F9E57879CC76"></a></p>

<h4>3.2 <span class="Heading">Overall Document Structure</span></h4>

<p>A <strong class="pkg">GAPDoc</strong> document contains on its top level exactly one element with name <code class="code">Book</code>. This element is declared in the DTD as follows:</p>

<p><a id="X7C7258A57B831934" name="X7C7258A57B831934"></a></p>

<h5>3.2-1 <span class="Heading"><code class="code"><Book></code></span></h5>


<div class="example"><pre>
<!ELEMENT Book (TitlePage,
                TableOfContents?,
                Body,
                Appendix*,
                Bibliography?,
                TheIndex?)>
<!ATTLIST Book Name CDATA #REQUIRED>
</pre></div>

<p>After the keyword <code class="code">ELEMENT</code> and the name <code class="code">Book</code> 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 <code class="code">Book</code> element. Each name in such a list can be followed by one of the characters <q><code class="code">?</code></q>, <q><code class="code">*</code></q> or <q><code class="code">+</code></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><code class="code">|</code></q> characters, this denotes any element with one of the names (i.e., <q><code class="code">|</code></q> means <q>or</q>).</p>

<p>So, the <code class="code">Book</code> element must contain first a <code class="code">TitlePage</code> element, then an optional <code class="code">TableOfContents</code> element, then a <code class="code">Body</code> element, then zero or more elements of type <code class="code">Appendix</code>, then an optional <code class="code">Bibliography</code> element, and finally an optional element of type <code class="code">TheIndex</code>.</p>

<p>Note that <em>only</em> these elements are allowed in the content of the <code class="code">Book</code> 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>

<p>The second declaration starts with the keyword <code class="code">ATTLIST</code> and the element name <code class="code">Book</code>. 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 (<code class="code">Name</code>) is the name of an attribute for a <code class="code">Book</code> element. The second (<code class="code">CDATA</code>) 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 <code class="code">#REQUIRED</code> means that this attribute must be specified with any <code class="code">Book</code> element. Later we will also see optional attributes which are declared as <code class="code">#IMPLIED</code>.</p>

<p><a id="X842B421A7FBCDD2C" name="X842B421A7FBCDD2C"></a></p>

<h5>3.2-2 <span class="Heading"><code class="code"><TitlePage></code></span></h5>


<div class="example"><pre>
<!ELEMENT TitlePage (Title, Subtitle?, Version?, TitleComment?, 
                     Author+, Date?, Address?, Abstract?, Copyright?, 
                     Acknowledgements? , Colophon? )>
</pre></div>

<p>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>

<p>Before going on with the other elements inside the <code class="code">Book</code> element we explain the elements for the title page.</p>

<p><a id="X7BCC8E6F79021294" name="X7BCC8E6F79021294"></a></p>

<h5>3.2-3 <span class="Heading"><code class="code"><Title></code></span></h5>


<div class="example"><pre>
<!ELEMENT Title (%Text;)*>
</pre></div>

<p>Here is the last construct you need to understand for reading <code class="file">gapdoc.dtd</code>. The expression <q><code class="code">%Text;</code></q> is a so-called <q>parameter entity</q>. It is something like a macro within the DTD. It is defined as follows:</p>


<div class="example"><pre>
<!ENTITY % Text "%InnerText; | List | Enum | Table">
</pre></div>

<p>This means, that every occurrence of <q><code class="code">%Text;</code></q> in the DTD is replaced by the expression</p>


<div class="example"><pre>%InnerText; | List | Enum | Table
</pre></div>

<p>which is then expanded further because of the following definition:</p>


<div class="example"><pre>
<!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" >
</pre></div>

<p>These are the only two parameter entities we are using. They expand to lists of element names which are explained in the sequel <em>and</em> the keyword <code class="code">#PCDATA</code> (concatenated with the <q>or</q> character <q><code class="code">|</code></q>).</p>

<p>So, the element (<code class="code">Title</code>) is of so-called <q>mixed content</q>: It can contain <em>parsed character data</em> which does not contain further markup (<code class="code">#PCDATA</code>) or any of the other above mentioned elements. Mixed content must always have the asterisk qualifier (like in <code class="code">Title</code>) such that any sequence of elements (of the above list) and character data can be contained in a <code class="code">Title</code> element.</p>

<p>The <code class="code">%Text;</code> parameter entity is used in all places in the DTD, where <q>normal text</q> should be allowed, including lists, enumerations, and tables, but <em>no</em> sectioning elements.</p>

<p>The <code class="code">%InnerText;</code> 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>

<p><a id="X82E82AF48217CC14" name="X82E82AF48217CC14"></a></p>

<h5>3.2-4 <span class="Heading"><code class="code"><Subtitle></code></span></h5>


<div class="example"><pre>
<!ELEMENT Subtitle (%Text;)*>
</pre></div>

<p>Contains the subtitle of the document.</p>

<p><a id="X876962807DCC52B3" name="X876962807DCC52B3"></a></p>

<h5>3.2-5 <span class="Heading"><code class="code"><Version></code></span></h5>


<div class="example"><pre>
<!ELEMENT Version (#PCDATA|Alt)*>
</pre></div>

<p>Note that the version can only contain character data and no further markup elements (except for <code class="code">Alt</code>, which is necessary to resolve the entities described in <a href="chap2.html#X7BDFF6D37FBED400"><span class="RefLink">2.2-3</span></a>). The converters will <em>not</em> put the word <q>Version</q> in front of the text in this element.</p>

<p><a id="X87E7CD5B79230B90" name="X87E7CD5B79230B90"></a></p>

<h5>3.2-6 <span class="Heading"><code class="code"><TitleComment></code></span></h5>


<div class="example"><pre>
<!ELEMENT TitleComment (%Text;)*>
</pre></div>

<p>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 <code class="code">Abstract</code> element (see <a href="chap3.html#X833110FE79628313"><span class="RefLink">3.2-10</span></a>) for longer explanations.</p>

<p><a id="X8731459C7E4C56DA" name="X8731459C7E4C56DA"></a></p>

<h5>3.2-7 <span class="Heading"><code class="code"><Author></code></span></h5>


<div class="example"><pre>
<!ELEMENT Author (%Text;)*>    <!-- There may be more than one Author! -->
</pre></div>

<p>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 <code class="code">Email</code>-address and/or WWW-<code class="code">Homepage</code> element for this author, see <a href="chap3.html#X8310C4F084CD9DB9"><span class="RefLink">3.5-6</span></a> and <a href="chap3.html#X7D5CC4267D04D7E7"><span class="RefLink">3.5-7</span></a>. You can also specify an individual postal address here, instead of using the <code class="code">Address</code> element described below, see <a href="chap3.html#X7EEF65A07A094F65"><span class="RefLink">3.2-9</span></a>.</p>

<p><a id="X8264A69D7DCDD773" name="X8264A69D7DCDD773"></a></p>

<h5>3.2-8 <span class="Heading"><code class="code"><Date></code></span></h5>


<div class="example"><pre>
<!ELEMENT Date (#PCDATA)>
</pre></div>

<p>Only character data is allowed in this element which gives a date for the document. No automatic formatting is done.</p>

<p><a id="X7EEF65A07A094F65" name="X7EEF65A07A094F65"></a></p>

<h5>3.2-9 <span class="Heading"><code class="code"><Address></code></span></h5>


<div class="example"><pre>
<!ELEMENT Address (#PCDATA|Alt|Br)*>
</pre></div>

<p>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 <code class="code">Address</code> elements inside the <code class="code">Author</code> elements.</p>

<p>Use the <code class="code">Br</code> element (see <a href="chap3.html#X7A3EF0647B10C1EC"><span class="RefLink">3.9-3</span></a>) to mark the line breaks in the usual formatting of the address on a letter.</p>

<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.</p>

<p><a id="X833110FE79628313" name="X833110FE79628313"></a></p>

<h5>3.2-10 <span class="Heading"><code class="code"><Abstract></code></span></h5>


<div class="example"><pre>
<!ELEMENT Abstract (%Text;)*>
</pre></div>

<p>This element contains an abstract of the whole book.</p>

<p><a id="X84BBD8307E08E62F" name="X84BBD8307E08E62F"></a></p>

<h5>3.2-11 <span class="Heading"><code class="code"><Copyright></code></span></h5>


<div class="example"><pre>
<!ELEMENT Copyright (%Text;)*>
</pre></div>

<p>This element is used for the copyright notice. Note the <code class="code">&copyright;</code> entity as described in section <a href="chap2.html#X7BDFF6D37FBED400"><span class="RefLink">2.2-3</span></a>.</p>

<p><a id="X8143972D7C17838E" name="X8143972D7C17838E"></a></p>

<h5>3.2-12 <span class="Heading"><code class="code"><Acknowledgements></code></span></h5>


<div class="example"><pre>
<!ELEMENT Acknowledgements (%Text;)*>
</pre></div>

<p>This element contains the acknowledgements.</p>

<p><a id="X7C09A3398059D18C" name="X7C09A3398059D18C"></a></p>

<h5>3.2-13 <span class="Heading"><code class="code"><Colophon></code></span></h5>


<div class="example"><pre>
<!ELEMENT Colophon (%Text;)*>
</pre></div>

<p>The <q>colophon</q> page is used to say something about the history of a document.</p>

<p><a id="X7E97263A83DC26E9" name="X7E97263A83DC26E9"></a></p>

<h5>3.2-14 <span class="Heading"><code class="code"><TableOfContents></code></span></h5>


<div class="example"><pre>
<!ELEMENT TableOfContents EMPTY>
</pre></div>

<p>This element may occur in the <code class="code">Book</code> element after the <code class="code">TitlePage</code> 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 <code class="code">EMPTY</code> one can use the abbreviation</p>


<div class="example"><pre>
<TableOfContents/>
</pre></div>

<p>to denote this empty element.</p>

<p><a id="X84F3DF21786A8751" name="X84F3DF21786A8751"></a></p>

<h5>3.2-15 <span class="Heading"><code class="code"><Bibliography></code>
</span></h5>


<div class="example"><pre>
<!ELEMENT Bibliography EMPTY>
<!ATTLIST Bibliography Databases CDATA #REQUIRED
                       Style CDATA #IMPLIED>
</pre></div>

<p>This element may occur in the <code class="code">Book</code> element after the last <code class="code">Appendix</code> element. If it is present, a bibliography section is generated and inserted into the document. The attribute <code class="code">Databases</code> must be specified, the names of several data files can be specified, separated by commas.</p>

<p>Two kinds of files can be specified in <code class="code">Databases</code>: The first are BibTeX files as defined in <a href="chapBib.html#biBLa85">[Lam85, Appendix B]</a>. Such files must have a name with extension <code class="file">.bib</code>, and in <code class="code">Databases</code> the name must be given <em>without</em> this extension. Note that such <code class="file">.bib</code>-files should be in latin1-encoding (or ASCII-encoding). The second are files in BibXMLext format as defined in Section <a href="chap7.html#X7FB8F6BD80D859D1"><span class="RefLink">7.2</span></a>. These files must have an extension <code class="file">.xml</code> and in <code class="code">Databases</code> the <em>full</em> name must be specified.</p>

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

<p>A bibliography style may be specified with the <code class="code">Style</code> attribute. The optional <code class="code">Style</code> attribute (for LaTeX output of the document) must also be specified without the <code class="file">.bst</code> extension (the default is <code class="code">alpha</code>). See also section <a href="chap3.html#X851DE9D279D8FB04"><span class="RefLink">3.5-3</span></a> for a description of the <code class="code">Cite</code> element which is used to include bibliography references into the text.</p>

<p><a id="X7C53615A8477F1E5" name="X7C53615A8477F1E5"></a></p>

<h5>3.2-16 <span class="Heading"><code class="code"><TheIndex></code></span></h5>


<div class="example"><pre><!ELEMENT TheIndex EMPTY></pre></div>

<p>This element may occur in the <code class="code">Book</code> element after the <code class="code">Bibliography</code> element. If it is present, an index is generated and inserted into the document. There are elements in <strong class="pkg">GAPDoc</strong> which implicitly generate index entries (e.g., <code class="code">Func</code> (<a href="chap3.html#X7C41A7B5845205C4"><span class="RefLink">3.4-2</span></a>)) and there is an element <code class="code">Index</code> (<a href="chap3.html#X811042BA78843777"><span class="RefLink">3.5-4</span></a>) for explicitly adding index entries.</p>

<p><a id="X80E2AD7481DD69D9" name="X80E2AD7481DD69D9"></a></p>

<h4>3.3 <span class="Heading">Sectioning Elements</span></h4>

<p>A <strong class="pkg">GAPDoc</strong> book is divided into <em>chapters</em>, <em>sections</em>, and <em>subsections</em>. 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>

<p><em>Appendices</em> are a flavor of chapters, occurring after all regular chapters. There is a special type of subsection called <q><code class="code">ManSection</code></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 <code class="code">ManSection</code>.</p>

<p>Cross referencing is done on the level of <code class="code">Subsection</code>s, respectively <code class="code">ManSection</code>s. The topics in <strong class="pkg">GAP</strong>'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>:</p>

<p><a id="X7B38415687510D0A" name="X7B38415687510D0A"></a></p>

<h5>3.3-1 <span class="Heading"><code class="code"><Body></code></span></h5>

<p>The <code class="code">Body</code> element marks the main part of the document. It must occur after the <code class="code">TableOfContents</code> element. There is a big difference between <em>inside</em> and <em>outside</em> of this element: Whereas regular text is allowed nearly everywhere in the <code class="code">Body</code> element and its subelements, this is not true for the <em>outside</em>. This has also implications on the handling of whitespace. <em>Outside</em> superfluous whitespace is usually ignored when it occurs between elements. <em>Inside</em> of the <code class="code">Body</code> element whitespace matters because character data is allowed nearly everywhere. Here is the definition in the DTD:</p>


<div class="example"><pre>
<!ELEMENT Body  ( %Text;| Chapter | Section )*>
</pre></div>

<p>The fact that <code class="code">Chapter</code> and <code class="code">Section</code> elements are allowed here leads to the possibility to omit the chapter level entirely in the document. For a description of <code class="code">%Text;</code> see <a href="chap3.html#X7BCC8E6F79021294"><span class="RefLink">here</span></a>.</p>

<p>(Remark: The purpose of this element is to make sure that a <em>valid</em> <strong class="pkg">GAPDoc</strong> document has a correct overall structure, which is only possible when the top element <code class="code">Book</code> has element content.)</p>

<p><a id="X7A86B2BA7D688B6B" name="X7A86B2BA7D688B6B"></a></p>

<h5>3.3-2 <span class="Heading"><code class="code"><Chapter></code></span></h5>


<div class="example"><pre>
<!ELEMENT Chapter (%Text;| Heading | Section)*>
<!ATTLIST Chapter Label CDATA #IMPLIED>    <!-- For reference purposes -->
</pre></div>

<p>A <code class="code">Chapter</code> element can have a <code class="code">Label</code> attribute, such that this chapter can be referenced later on with a <code class="code">Ref</code> element (see section <a href="chap3.html#X8656F2338007406E"><span class="RefLink">3.5-1</span></a>). Note that you have to specify a label to reference the chapter as there is no automatic labelling!</p>

<p><code class="code">Chapter</code> elements can contain text (for a description of <code class="code">%Text;</code> see <a href="chap3.html#X7BCC8E6F79021294"><span class="RefLink">here</span></a>), <code class="code">Section</code> elements, and <code class="code">Heading</code> elements.</p>

<p>The following <em>additional</em> rule cannot be stated in the DTD because we want a <code class="code">Chapter</code> element to have mixed content. There must be <em>exactly one</em> <code class="code">Heading</code> element in the <code class="code">Chapter</code> element, containing the heading of the chapter. Here is its definition:</p>

<p><a id="X79825E1C821D0B79" name="X79825E1C821D0B79"></a></p>

<h5>3.3-3 <span class="Heading"><code class="code"><Heading></code></span></h5>


<div class="example"><pre>
<!ELEMENT Heading (%InnerText;)*>
</pre></div>

<p>This element is used for headings in <code class="code">Chapter</code>, <code class="code">Section</code>, <code class="code">Subsection</code>, and <code class="code">Appendix</code> elements. It may only contain <code class="code">%InnerText;</code> (for a description see <a href="chap3.html#X7BCC8E6F79021294"><span class="RefLink">here</span></a>).</p>

<p>Each of the mentioned sectioning elements must contain exactly one direct <code class="code">Heading</code> element (i.e., one which is not contained in another sectioning element).</p>

<p><a id="X7C701B2779767556" name="X7C701B2779767556"></a></p>

<h5>3.3-4 <span class="Heading"><code class="code"><Appendix></code></span></h5>


<div class="example"><pre>
<!ELEMENT Appendix (%Text;| Heading | Section)*>
<!ATTLIST Appendix Label CDATA #IMPLIED>   <!-- For reference purposes -->
</pre></div>

<p>The <code class="code">Appendix</code> element behaves exactly like a <code class="code">Chapter</code> element (see <a href="chap3.html#X7A86B2BA7D688B6B"><span class="RefLink">3.3-2</span></a>) 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>

<p>Again there is an optional <code class="code">Label</code> attribute used for references.</p>

<p><a id="X844DC2B47FB37339" name="X844DC2B47FB37339"></a></p>

<h5>3.3-5 <span class="Heading"><code class="code"><Section></code></span></h5>


<div class="example"><pre>
<!ELEMENT Section (%Text;| Heading | Subsection | ManSection)*>
<!ATTLIST Section Label CDATA #IMPLIED>    <!-- For reference purposes -->
</pre></div>

<p>A <code class="code">Section</code> element can have a <code class="code">Label</code> attribute, such that this section can be referenced later on with a <code class="code">Ref</code> element (see section <a href="chap3.html#X8656F2338007406E"><span class="RefLink">3.5-1</span></a>). Note that you have to specify a label to reference the section as there is no automatic labelling!</p>

<p><code class="code">Section</code> elements can contain text (for a description of <code class="code">%Text;</code> see <a href="chap3.html#X7BCC8E6F79021294"><span class="RefLink">here</span></a>), <code class="code">Heading</code> elements, and subsections.</p>

<p>There must be exactly one direct <code class="code">Heading</code> element in a <code class="code">Section</code> element, containing the heading of the section.</p>

<p>Note that a subsection is either a <code class="code">Subsection</code> element or a <code class="code">ManSection</code> element.</p>

<p><a id="X803ACA187E292969" name="X803ACA187E292969"></a></p>

<h5>3.3-6 <span class="Heading"><code class="code"><Subsection></code></span></h5>


<div class="example"><pre>
<!ELEMENT Subsection (%Text;| Heading)*>
<!ATTLIST Subsection Label CDATA #IMPLIED> <!-- For reference purposes -->
</pre></div>

<p>The <code class="code">Subsection</code> element can have a <code class="code">Label</code> attribute, such that this subsection can be referenced later on with a <code class="code">Ref</code> element (see section <a href="chap3.html#X8656F2338007406E"><span class="RefLink">3.5-1</span></a>). Note that you have to specify a label to reference the subsection as there is no automatic labelling!</p>

<p><code class="code">Subsection</code> elements can contain text (for a description of <code class="code">%Text;</code> see <a href="chap3.html#X7BCC8E6F79021294"><span class="RefLink">here</span></a>), and <code class="code">Heading</code> elements.</p>

<p>There must be exactly one <code class="code">Heading</code> element in a <code class="code">Subsection</code> element, containing the heading of the subsection.</p>

<p>Another type of subsection is a <code class="code">ManSection</code>, explained now:</p>

<p><a id="X877B8B7C7EDD09E9" name="X877B8B7C7EDD09E9"></a></p>

<h4>3.4 <span class="Heading">ManSection–a special kind of subsection</span></h4>

<p><code class="code">ManSection</code>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.</p>

<p><a id="X8375D9CC8672A1D5" name="X8375D9CC8672A1D5"></a></p>

<h5>3.4-1 <span class="Heading"><code class="code"><ManSection></code></span></h5>


<div class="example"><pre>
<!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;)*>
</pre></div>

<p>The <code class="code">ManSection</code> element can have a <code class="code">Label</code> attribute, such that this subsection can be referenced later on with a <code class="code">Ref</code> element (see section <a href="chap3.html#X8656F2338007406E"><span class="RefLink">3.5-1</span></a>). But this is probably rarely necessary because the elements <code class="code">Func</code> and so on (explained below) generate automatically labels for cross referencing.</p>

<p>The content of a <code class="code">ManSection</code> element is one or more elements describing certain items in <strong class="pkg">GAP</strong>, each of them optionally followed by a <code class="code">Returns</code> element, followed by a <code class="code">Description</code> element, which contains <code class="code">%Text;</code> (see <a href="chap3.html#X7BCC8E6F79021294"><span class="RefLink">here</span></a>) describing it. (Remember to include examples in the description as often as possible, see <a href="chap3.html#X810DEA1E83A57CFE"><span class="RefLink">3.7-10</span></a>). The classes of items <strong class="pkg">GAPDoc</strong> knows of are: functions (<code class="code">Func</code>), operations (<code class="code">Oper</code>), constructors (<code class="code">Constr</code>), methods (<code class="code">Meth</code>), filters (<code class="code">Filt</code>), properties (<code class="code">Prop</code>), attributes (<code class="code">Attr</code>), variables (<code class="code">Var</code>), families (<code class="code">Fam</code>), and info classes (<code class="code">InfoClass</code>). One <code class="code">ManSection</code> should only describe several of such items when these are very closely related.</p>

<p>Each element for an item corresponding to a <strong class="pkg">GAP</strong> function can be followed by a <code class="code">Returns</code> 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 <code class="code">Returns</code> 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>

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

<p><a id="X7C41A7B5845205C4" name="X7C41A7B5845205C4"></a></p>

<h5>3.4-2 <span class="Heading"><code class="code"><Func></code></span></h5>


<div class="example"><pre>
<!ELEMENT Func EMPTY>
<!ATTLIST Func Name  CDATA #REQUIRED
               Label CDATA #IMPLIED
               Arg   CDATA #REQUIRED
               Comm  CDATA #IMPLIED>
</pre></div>

<p>This element is used within a <code class="code">ManSection</code> element to specify the usage of a function. The <code class="code">Name</code> attribute is required and its value is the name of the function. The value of the <code class="code">Arg</code> 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 <code class="code">"grp[, elm]"</code> or <code class="code">"xx[y[z] ]"</code>. If <strong class="pkg">GAP</strong> options are used, this can be followed by a colon <code class="code">:</code> and one or more assignments, like <code class="code">"n[, r]: tries := 100"</code>.</p>

<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 <em>always</em> be written with the <code class="code">Ref</code> element, see <a href="chap3.html#X8656F2338007406E"><span class="RefLink">3.5-1</span></a>. This allows to use a unique typesetting style for function names and automatic cross referencing.</p>

<p>If the optional <code class="code">Label</code> attribute is given, it is appended (with a colon <code class="code">:</code> 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.</p>


<div class="example"><pre>
<Func Arg="x[, y]" Name="LibFunc" Label="for my objects"/>
</pre></div>

<p>The optional <code class="code">Comm</code> attribute should be a short description of the function, usually at most one line long (this is currently nowhere used).</p>

<p>This element automatically produces an index entry with the name of the function and, if present, the text of the <code class="code">Label</code> attribute as subentry (see also <a href="chap3.html#X7C53615A8477F1E5"><span class="RefLink">3.2-16</span></a> and <a href="chap3.html#X811042BA78843777"><span class="RefLink">3.5-4</span></a>).</p>

<p><a id="X7A15825E818A81CD" name="X7A15825E818A81CD"></a></p>

<h5>3.4-3 <span class="Heading"><code class="code"><Oper></code></span></h5>


<div class="example"><pre>
<!ELEMENT Oper EMPTY>
<!ATTLIST Oper Name  CDATA #REQUIRED
               Label CDATA #IMPLIED
               Arg   CDATA #REQUIRED
               Comm  CDATA #IMPLIED>
</pre></div>

<p>This element is used within a <code class="code">ManSection</code> element to specify the usage of an operation. The attributes are used exactly in the same way as in the <code class="code">Func</code> element (see <a href="chap3.html#X7C41A7B5845205C4"><span class="RefLink">3.4-2</span></a>).</p>

<p>Note that multiple descriptions of the same operation may occur in a document because there may be several declarations in <strong class="pkg">GAP</strong>. Furthermore there may be several <code class="code">ManSection</code>s for methods of this operation (see <a href="chap3.html#X81196E2B7F286A01"><span class="RefLink">3.4-5</span></a>) which also use the same name. For reference purposes these must be distinguished by different <code class="code">Label</code> attributes.</p>

<p><a id="X7FBFD7A3786C7CAB" name="X7FBFD7A3786C7CAB"></a></p>

<h5>3.4-4 <span class="Heading"><code class="code"><Constr></code></span></h5>


<div class="example"><pre>
<!ELEMENT Constr EMPTY>
<!ATTLIST Constr Name  CDATA #REQUIRED
                 Label CDATA #IMPLIED
                 Arg   CDATA #REQUIRED
                 Comm  CDATA #IMPLIED>
</pre></div>

<p>This element is used within a <code class="code">ManSection</code> element to specify the usage of a constructor. The attributes are used exactly in the same way as in the <code class="code">Func</code> element (see <a href="chap3.html#X7C41A7B5845205C4"><span class="RefLink">3.4-2</span></a>).</p>

<p>Note that multiple descriptions of the same constructor may occur in a document because there may be several declarations in <strong class="pkg">GAP</strong>. Furthermore there may be several <code class="code">ManSection</code>s for methods of this constructor (see <a href="chap3.html#X81196E2B7F286A01"><span class="RefLink">3.4-5</span></a>) which also use the same name. For reference purposes these must be distinguished by different <code class="code">Label</code> attributes.</p>

<p><a id="X81196E2B7F286A01" name="X81196E2B7F286A01"></a></p>

<h5>3.4-5 <span class="Heading"><code class="code"><Meth></code></span></h5>


<div class="example"><pre>
<!ELEMENT Meth EMPTY>
<!ATTLIST Meth Name  CDATA #REQUIRED
               Label CDATA #IMPLIED
               Arg   CDATA #REQUIRED
               Comm  CDATA #IMPLIED>
</pre></div>

<p>This element is used within a <code class="code">ManSection</code> element to specify the usage of a method. The attributes are used exactly in the same way as in the <code class="code">Func</code> element (see <a href="chap3.html#X7C41A7B5845205C4"><span class="RefLink">3.4-2</span></a>).</p>

<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 <code class="code">ManSection</code>s. It is however required that these subsections and those describing the corresponding operation are distinguished by different <code class="code">Label</code> attributes.</p>

<p><a id="X7D8D2C38828D5854" name="X7D8D2C38828D5854"></a></p>

<h5>3.4-6 <span class="Heading"><code class="code"><Filt></code></span></h5>


<div class="example"><pre>
<!ELEMENT Filt EMPTY>
<!ATTLIST Filt Name  CDATA #REQUIRED
               Label CDATA #IMPLIED
               Arg   CDATA #IMPLIED
               Comm  CDATA #IMPLIED
               Type  CDATA #IMPLIED>
</pre></div>

<p>This element is used within a <code class="code">ManSection</code> element to specify the usage of a filter. The first four attributes are used in the same way as in the <code class="code">Func</code> element (see <a href="chap3.html#X7C41A7B5845205C4"><span class="RefLink">3.4-2</span></a>), except that the <code class="code">Arg</code> attribute is optional.</p>

<p>The <code class="code">Type</code> attribute can be any string, but it is thought to be something like <q><code class="code">Category</code></q> or <q><code class="code">Representation</code></q>.</p>

<p><a id="X7D6400A67C30B752" name="X7D6400A67C30B752"></a></p>

<h5>3.4-7 <span class="Heading"><code class="code"><Prop></code></span></h5>


<div class="example"><pre>
<!ELEMENT Prop EMPTY>
<!ATTLIST Prop Name  CDATA #REQUIRED
               Label CDATA #IMPLIED
               Arg   CDATA #REQUIRED
               Comm  CDATA #IMPLIED>
</pre></div>

<p>This element is used within a <code class="code">ManSection</code> element to specify the usage of a property. The attributes are used exactly in the same way as in the <code class="code">Func</code> element (see <a href="chap3.html#X7C41A7B5845205C4"><span class="RefLink">3.4-2</span></a>).</p>

<p><a id="X78CEEC5986987A97" name="X78CEEC5986987A97"></a></p>

<h5>3.4-8 <span class="Heading"><code class="code"><Attr></code></span></h5>


<div class="example"><pre>
<!ELEMENT Attr EMPTY>
<!ATTLIST Attr Name  CDATA #REQUIRED
               Label CDATA #IMPLIED
               Arg   CDATA #REQUIRED
               Comm  CDATA #IMPLIED>
</pre></div>

<p>This element is used within a <code class="code">ManSection</code> element to specify the usage of an attribute (in <strong class="pkg">GAP</strong>). The attributes are used exactly in the same way as in the <code class="code">Func</code> element (see <a href="chap3.html#X7C41A7B5845205C4"><span class="RefLink">3.4-2</span></a>).</p>

<p><a id="X7C3AACBE7BC6AABF" name="X7C3AACBE7BC6AABF"></a></p>

<h5>3.4-9 <span class="Heading"><code class="code"><Var></code></span></h5>


<div class="example"><pre>
<!ELEMENT Var  EMPTY>
<!ATTLIST Var  Name  CDATA #REQUIRED
               Label CDATA #IMPLIED
               Comm  CDATA #IMPLIED>
</pre></div>

<p>This element is used within a <code class="code">ManSection</code> element to document a global variable. The attributes are used exactly in the same way as in the <code class="code">Func</code> element (see <a href="chap3.html#X7C41A7B5845205C4"><span class="RefLink">3.4-2</span></a>) except that there is no <code class="code">Arg</code> attribute.</p>

<p><a id="X85EE992E7FED2FE6" name="X85EE992E7FED2FE6"></a></p>

<h5>3.4-10 <span class="Heading"><code class="code"><Fam></code></span></h5>


<div class="example"><pre>
<!ELEMENT Fam  EMPTY>
<!ATTLIST Fam  Name  CDATA #REQUIRED
               Label CDATA #IMPLIED
               Comm  CDATA #IMPLIED>
</pre></div>

<p>This element is used within a <code class="code">ManSection</code> element to document a family. The attributes are used exactly in the same way as in the <code class="code">Func</code> element (see <a href="chap3.html#X7C41A7B5845205C4"><span class="RefLink">3.4-2</span></a>) except that there is no <code class="code">Arg</code> attribute.</p>

<p><a id="X78F0D4D1811E5BAE" name="X78F0D4D1811E5BAE"></a></p>

<h5>3.4-11 <span class="Heading"><code class="code"><InfoClass></code></span></h5>


<div class="example"><pre>
<!ELEMENT InfoClass EMPTY>
<!ATTLIST InfoClass Name  CDATA #REQUIRED
                    Label CDATA #IMPLIED
                    Comm  CDATA #IMPLIED>
</pre></div>

<p>This element is used within a <code class="code">ManSection</code> element to document an info class. The attributes are used exactly in the same way as in the <code class="code">Func</code> element (see <a href="chap3.html#X7C41A7B5845205C4"><span class="RefLink">3.4-2</span></a>) except that there is no <code class="code">Arg</code> attribute.</p>

<p><a id="X78595FB585569617" name="X78595FB585569617"></a></p>

<h4>3.5 <span class="Heading">Cross Referencing and Citations</span></h4>

<p>Cross referencing in the <strong class="pkg">GAPDoc</strong> 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>

<p>Referencing is done with the <code class="code">Ref</code> element:</p>

<p><a id="X8656F2338007406E" name="X8656F2338007406E"></a></p>

<h5>3.5-1 <span class="Heading"><code class="code"><Ref></code></span></h5>


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

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

<p>The <code class="code">Ref</code> element is defined to be <code class="code">EMPTY</code>. If one of the attributes <code class="code">Func</code>, <code class="code">Oper</code>, <code class="code">Constr</code>, <code class="code">Meth</code>, <code class="code">Prop</code>, <code class="code">Attr</code>, <code class="code">Var</code>, <code class="code">Fam</code>, <code class="code">InfoClass</code>, <code class="code">Chap</code>, <code class="code">Sect</code>, <code class="code">Subsect</code>, <code class="code">Appendix</code> is given then there must be exactly one of these, making the reference one to the corresponding object. The <code class="code">Label</code> 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>

<p>A reference to a <code class="code">Label</code> element defined below (see <a href="chap3.html#X7C85CA5484344DB5"><span class="RefLink">3.5-2</span></a>) is done by giving the <code class="code">Label</code> attribute and optionally the <code class="code">Text</code> attribute. If the <code class="code">Text</code> attribute is present its value is typeset in place of the <code class="code">Ref</code> 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 <a href="chap3.html#X7F9CAA577EB4070B"><span class="RefLink">3.6-5</span></a>).</p>

<p>An external reference into another book can be specified by using the <code class="code">BookName</code> attribute. In this case the <code class="code">Label</code> 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 <strong class="pkg">GAP</strong>.</p>

<p>The optional attribute <code class="code">Style</code> can take only the values <code class="code">Text</code> and <code class="code">Number</code>. 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 <strong class="pkg">GAP</strong> object generate the name of the corresponding object with some additional link or sectioning information, which is the behavior of <code class="code">Style="Text"</code>. In case <code class="code">Style="Number"</code> in all cases an explicit section number is generated. So</p>


<div class="example"><pre>
<Ref Subsect="Func" Style="Text"/> described in section 
<Ref Subsect="Func" Style="Number"/>
</pre></div>

<p>produces: <a href="chap3.html#X7C41A7B5845205C4"><span class="RefLink"><span class="Heading"><code class="code"><Func></code></span></span></a> described in section <a href="chap3.html#X7C41A7B5845205C4"><span class="RefLink">3.4-2</span></a>.</p>

<p><a id="X7C85CA5484344DB5" name="X7C85CA5484344DB5"></a></p>

<h5>3.5-2 <span class="Heading"><code class="code"><Label></code></span></h5>


<div class="example"><pre>
<!ELEMENT Label EMPTY>
<!ATTLIST Label Name CDATA #REQUIRED>
</pre></div>

<p>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 <code class="code">Name</code> attribute must be unique under all <code class="code">Label</code> elements.</p>

<p><a id="X851DE9D279D8FB04" name="X851DE9D279D8FB04"></a></p>

<h5>3.5-3 <span class="Heading"><code class="code"><Cite></code></span></h5>


<div class="example"><pre>
<!ELEMENT Cite EMPTY>
<!ATTLIST Cite Key CDATA #REQUIRED
               Where CDATA #IMPLIED>
</pre></div>

<p>This element is for bibliography citations. It is <code class="code">EMPTY</code> by definition. The attribute <code class="code">Key</code> is the key for a lookup in a BibTeX database that has to be specified in the <code class="code">Bibliography</code> element (see <a href="chap3.html#X84F3DF21786A8751"><span class="RefLink">3.2-15</span></a>). The value of the <code class="code">Where</code> attribute specifies the position in the document as in the corresponding LaTeX syntax <code class="code">\cite[Where value]{Key value}</code>.</p>

<p><a id="X811042BA78843777" name="X811042BA78843777"></a></p>

<h5>3.5-4 <span class="Heading"><code class="code"><Index></code></span></h5>


<div class="example"><pre>
<!ELEMENT Index (%InnerText;|Subkey)*>
<!ATTLIST Index Key    CDATA #IMPLIED
                Subkey CDATA #IMPLIED>
<!ELEMENT Subkey (%InnerText;)*>
</pre></div>

<p>This element generates an index entry. The content of the element is typeset in the index. It can optionally contain a <code class="code">Subkey</code> element. If one or both of the attributes <code class="code">Key</code> and <code class="code">Subkey</code> 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 <code class="code">Func</code> and similar elements automatically generate index entries. If the <code class="code">TheIndex</code> element (<a href="chap3.html#X7C53615A8477F1E5"><span class="RefLink">3.2-16</span></a>) is not present in the document all <code class="code">Index</code> elements are ignored.</p>

<p><a id="X81B3E46F839E1C5B" name="X81B3E46F839E1C5B"></a></p>

<h5>3.5-5 <span class="Heading"><code class="code"><URL></code></span></h5>


<div class="example"><pre>
<!ELEMENT URL (#PCDATA|Alt|Link|LinkText)*>  <!-- Link, LinkText
     variant for case where text needs further markup -->
<!ATTLIST URL Text CDATA #IMPLIED>   <!-- This is for output formats
                                          that have links like HTML -->
<!ELEMENT Link     (%InnerText;)*> <!-- the URL -->
<!ELEMENT LinkText (%InnerText;)*> <!-- text for links, can contain markup -->

</pre></div>

--> --------------------

--> maximum size reached

--> --------------------

100%


¤ Dauer der Verarbeitung: 0.28 Sekunden  (vorverarbeitet)  ¤

*© Formatika GbR, Deutschland




Wurzel

Suchen

Beweissystem der NASA

Beweissystem Isabelle

NIST Cobol Testsuite

Cephes Mathematical Library

Wiener Entwicklungsmethode

Haftungshinweis

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.