  
  [1X3. The Document Type Definition[0X
  
  In  this  chapter  we first explain what a "document type definition" is and
  then  describe  [11Xgapdoc.dtd[0X  in  detail.  That file together with the current
  chapter  define  how  a [5XGAPDoc[0X document has to look like. It can be found in
  the   main  directory  of  the  [5XGAPDoc[0X  package  and  it  is  reproduced  in
  Appendix [14XB.[0X.
  
  We  do  not  give  many examples in this chapter which is more intended as a
  formal  reference  for  all  [5XGAPDoc[0X  elements.  Instead  we provide an extra
  document  with  book name [10XGAPDocExample[0X (also accessible from the [5XGAP[0X online
  help).  This  uses all the constructs introduced in this chapter and you can
  easily compare the source code and how it looks like in the different output
  formats.  Furthermore  recall  that  many basic things about XML markup were
  already explained by example in the introductory chapter [14X1.[0X.
  
  
  [1X3.1 What is a DTD?[0X
  
  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 [14X2.1-14[0X.
  
  The  main  thing  a  DTD  does  is  to  specify  which elements may occur in
  documents  of  a  certain  document  type,  how they can be nested, and what
  attributes they can or must have. So, for each element there is a rule.
  
  Note  that  a DTD can [13Xnot[0X ensure that a document which is "valid" also makes
  sense  to  the converters! It only says something about the formal structure
  of the document.
  
  For  the  remaining  part  of  this  chapter we have divided the elements of
  [5XGAPDoc[0X  documents  into  several subsets, each of which will be discussed in
  one of the next sections.
  
  See the following three subsections to learn by example, how a DTD works. We
  do  not want to be too formal here, but just enable the reader to understand
  the  declarations  in  [11Xgapdoc.dtd[0X. For precise descriptions of the syntax of
  DTD's see again the official standard in:
  
    [7Xhttp://www.xml.com/axml/axml.html[0X
  
  
  [1X3.2 Overall Document Structure[0X
  
  A  [5XGAPDoc[0X  document  contains on its top level exactly one element with name
  [10XBook[0X. This element is declared in the DTD as follows:
  
  
  [1X3.2-1 [10X<Book>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Book (TitlePage,[0X
    [4X                TableOfContents?,[0X
    [4X                Body,[0X
    [4X                Appendix*,[0X
    [4X                Bibliography?,[0X
    [4X                TheIndex?)>[0X
    [4X<!ATTLIST Book Name CDATA #REQUIRED>[0X
  [4X------------------------------------------------------------------[0X
  
  After  the keyword [10XELEMENT[0X and the name [10XBook[0X 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 [10XBook[0X element. Each name in such a list can
  be  followed  by  one  of  the  characters "[10X?[0X", "[10X*[0X" or "[10X+[0X", 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 "[10X|[0X" characters,
  this denotes any element with one of the names (i.e., "[10X|[0X" means "or").
  
  So,  the  [10XBook[0X  element  must  contain  first  a  [10XTitlePage[0X element, then an
  optional  [10XTableOfContents[0X  element,  then  a [10XBody[0X element, then zero or more
  elements  of  type  [10XAppendix[0X,  then  an  optional  [10XBibliography[0X element, and
  finally an optional element of type [10XTheIndex[0X.
  
  Note  that  [13Xonly[0X  these  elements  are  allowed  in  the content of the [10XBook[0X
  element.  No  other  elements or text is allowed in between. An exception of
  this  is  that  there  may  be whitespace between the end tag of one and the
  start  tag of the next element - this should be ignored when the document is
  processed  to  some output format. An element like this is called an element
  with "element content".
  
  The  second declaration starts with the keyword [10XATTLIST[0X and the element name
  [10XBook[0X.  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 ([10XName[0X) is the name of an attribute for a [10XBook[0X element. The
  second ([10XCDATA[0X) is always the same for all of our declarations, it means that
  the value of the attribute consists of "character data". The third parameter
  [10X#REQUIRED[0X means that this attribute must be specified with any [10XBook[0X element.
  Later we will also see optional attributes which are declared as [10X#IMPLIED[0X.
  
  
  [1X3.2-2 [10X<TitlePage>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT TitlePage (Title, Subtitle?, Version?, TitleComment?, [0X
    [4X                     Author+, Date?, Address?, Abstract?, Copyright?, [0X
    [4X                     Acknowledgements? , Colophon? )>[0X
  [4X------------------------------------------------------------------[0X
  
  Within  this  element information for the title page is collected. Note that
  more  than  one  author  can  be specified. The elements must appear in this
  order  because  there  is no sensible way to specify in a DTD something like
  "the following elements may occur in any order but each exactly once".
  
  Before  going  on with the other elements inside the [10XBook[0X element we explain
  the elements for the title page.
  
  
  [1X3.2-3 [10X<Title>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Title (%Text;)*>[0X
  [4X------------------------------------------------------------------[0X
  
  Here  is  the  last construct you need to understand for reading [11Xgapdoc.dtd[0X.
  The  expression  "[10X%Text;[0X" is a so-called "parameter entity". It is something
  like a macro within the DTD. It is defined as follows:
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ENTITY % Text "%InnerText; | List | Enum | Table">[0X
  [4X------------------------------------------------------------------[0X
  
  This  means, that every occurrence of "[10X%Text;[0X" in the DTD is replaced by the
  expression
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X%InnerText; | List | Enum | Table[0X
  [4X------------------------------------------------------------------[0X
  
  which is then expanded further because of the following definition:
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ENTITY % InnerText "#PCDATA |[0X
    [4X                      Alt |[0X
    [4X                      Emph | E |[0X
    [4X                      Par | P | Br |[0X
    [4X                      Keyword | K | Arg | A | Quoted | Q | Code | C | [0X
    [4X                      File | F | Button | B | Package |[0X
    [4X                      M | Math | Display | [0X
    [4X                      Example | Listing | Log | Verb |[0X
    [4X                      URL | Email | Homepage | Address | Cite | Label | [0X
    [4X                      Ref | Index" > [0X
  [4X------------------------------------------------------------------[0X
  
  These are the only two parameter entities we are using. They expand to lists
  of  element  names which are explained in the sequel [13Xand[0X the keyword [10X#PCDATA[0X
  (concatenated with the "or" character "[10X|[0X").
  
  So,  the  element  ([10XTitle[0X)  is  of so-called "mixed content": It can contain
  [13Xparsed character data[0X which does not contain further markup ([10X#PCDATA[0X) or any
  of  the  other  above mentioned elements. Mixed content must always have the
  asterisk  qualifier  (like  in [10XTitle[0X) such that any sequence of elements (of
  the above list) and character data can be contained in a [10XTitle[0X element.
  
  The  [10X%Text;[0X parameter entity is used in all places in the DTD, where "normal
  text"  should  be allowed, including lists, enumerations, and tables, but [13Xno[0X
  sectioning elements.
  
  The  [10X%InnerText;[0X  parameter  entity  is used in all places in the DTD, where
  "inner  text"  should be allowed. This means, that no structures like lists,
  enumerations, and tables are allowed. This is used for example in headings.
  
  
  [1X3.2-4 [10X<Subtitle>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Subtitle (%Text;)*>[0X
  [4X------------------------------------------------------------------[0X
  
  Contains the subtitle of the document.
  
  
  [1X3.2-5 [10X<Version>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Version (#PCDATA|Alt)*>[0X
  [4X------------------------------------------------------------------[0X
  
  Note  that the version can only contain character data and no further markup
  elements  (except  for  [10XAlt[0X,  which  is  necessary  to  resolve the entities
  described in [14X2.2-3[0X). The converters will [13Xnot[0X put the word "Version" in front
  of the text in this element.
  
  
  [1X3.2-6 [10X<TitleComment>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT TitleComment (%Text;)*>[0X
  [4X------------------------------------------------------------------[0X
  
  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 [10XAbstract[0X element (see [14X3.2-10[0X) for longer explanations.
  
  
  [1X3.2-7 [10X<Author>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Author (%Text;)*>    <!-- There may be more than one Author! -->[0X
  [4X------------------------------------------------------------------[0X
  
  As  noted  in  the  comment there may be more than one element of this type.
  This  elements  should  contain  the  name  of  an  author  and  probably an
  [10XEmail[0X-address   and/or  WWW-[10XHomepage[0X  element  for  this  author,  see [14X3.5-6[0X
  and [14X3.5-7[0X.  You  can also specify an individual postal address here, instead
  of using the [10XAddress[0X element described below, see [14X3.2-9[0X.
  
  
  [1X3.2-8 [10X<Date>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Date (#PCDATA)>[0X
  [4X------------------------------------------------------------------[0X
  
  Only  character  data  is allowed in this element which gives a date for the
  document. No automatic formatting is done.
  
  
  [1X3.2-9 [10X<Address>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Address (#PCDATA|Alt|Br)*>[0X
  [4X------------------------------------------------------------------[0X
  
  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 [10XAddress[0X elements inside the [10XAuthor[0X elements.
  
  Use  the  [10XBr[0X  element  (see [14X3.9-3[0X)  to  mark  the  line  breaks in the usual
  formatting of the address on a letter.
  
  Note  that  often  it  is not necessary to use this element because a postal
  address is easy to find via a link to a personal web page.
  
  
  [1X3.2-10 [10X<Abstract>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Abstract (%Text;)*>[0X
  [4X------------------------------------------------------------------[0X
  
  This element contains an abstract of the whole book.
  
  
  [1X3.2-11 [10X<Copyright>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Copyright (%Text;)*>[0X
  [4X------------------------------------------------------------------[0X
  
  This  element  is used for the copyright notice. Note the [10X&copyright;[0X entity
  as described in section [14X2.2-3[0X.
  
  
  [1X3.2-12 [10X<Acknowledgements>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Acknowledgements (%Text;)*>[0X
  [4X------------------------------------------------------------------[0X
  
  This element contains the acknowledgements.
  
  
  [1X3.2-13 [10X<Colophon>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Colophon (%Text;)*>[0X
  [4X------------------------------------------------------------------[0X
  
  The  "colophon"  page  is  used  to  say  something  about  the history of a
  document.
  
  
  [1X3.2-14 [10X<TableOfContents>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT TableOfContents EMPTY>[0X
  [4X------------------------------------------------------------------[0X
  
  This  element  may occur in the [10XBook[0X element after the [10XTitlePage[0X 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 [10XEMPTY[0X one can use
  the abbreviation
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X<TableOfContents/>[0X
  [4X------------------------------------------------------------------[0X
  
  to denote this empty element.
  
  
  [1X3.2-15 [10X<Bibliography>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Bibliography EMPTY>[0X
    [4X<!ATTLIST Bibliography Databases CDATA #REQUIRED[0X
    [4X                       Style CDATA #IMPLIED>[0X
  [4X------------------------------------------------------------------[0X
  
  This  element may occur in the [10XBook[0X element after the last [10XAppendix[0X element.
  If  it is present, a bibliography section is generated and inserted into the
  document.  The  attribute  [10XDatabases[0X must be specified, the names of several
  data files can be specified, separated by commas.
  
  Two kinds of files can be specified in [10XDatabases[0X: The first are BibTeX files
  as  defined  in [Lam85,  Appendix  B].  Such  files  must  have  a name with
  extension  [11X.bib[0X,  and  in  [10XDatabases[0X  the  name  must  be given [13Xwithout[0X this
  extension.   The  second  are  files  in  BibXMLext  format  as  defined  in
  Section [14X7.2[0X.  These  files  must have an extension [11X.xml[0X and in [10XDatabases[0X the
  [13Xfull[0X name must be specified.
  
  We  suggest  to  use  the  BibXMLext  format  because  it  allows to produce
  potentially nicer bibliography entries in text and HTML documents.
  
  A bibliography style may be specified with the [10XStyle[0X attribute. The optional
  [10XStyle[0X  attribute  (for  LaTeX output of the document) must also be specified
  without  the  [11X.bst[0X  extension (the default is [10Xalpha[0X). See also section [14X3.5-3[0X
  for  a description of the [10XCite[0X element which is used to include bibliography
  references into the text.
  
  
  [1X3.2-16 [10X<TheIndex>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT TheIndex EMPTY>[0X
  [4X------------------------------------------------------------------[0X
  
  This  element  may occur in the [10XBook[0X element after the [10XBibliography[0X element.
  If  it  is  present,  an  index is generated and inserted into the document.
  There  are elements in [5XGAPDoc[0X which implicitly generate index entries (e.g.,
  [10XFunc[0X  ([14X3.4-2[0X))  and  there  is an element [10XIndex[0X ([14X3.5-4[0X)for explicitly adding
  index entries.
  
  
  [1X3.3 Sectioning Elements[0X
  
  A  [5XGAPDoc[0X book is divided into [13Xchapters[0X, [13Xsections[0X, and [13Xsubsections[0X. 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.
  
  [13XAppendices[0X  are  a flavor of chapters, occurring after all regular chapters.
  There  is  a  special  type  of  subsection  called  "[10XManSection[0X". 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 [10XManSection[0X.
  
  Cross  referencing  is  done  on  the  level  of  [10XSubsection[0Xs,  respectively
  [10XManSection[0Xs.   The  topics  in  [5XGAP[0X's  online  help  are  also  pointing  to
  subsections. So, they should not be too long.
  
  We start our description of the sectioning elements "top-down":
  
  
  [1X3.3-1 [10X<Body>[0X[1X[0X
  
  The  [10XBody[0X  element  marks the main part of the document. It must occur after
  the  [10XTableOfContents[0X  element.  There is a big difference between [13Xinside[0X and
  [13Xoutside[0X  of  this element: Whereas regular text is allowed nearly everywhere
  in  the  [10XBody[0X element and its subelements, this is not true for the [13Xoutside[0X.
  This   has   also  implications  on  the  handling  of  whitespace.  [13XOutside[0X
  superfluous  whitespace  is usually ignored when it occurs between elements.
  [13XInside[0X  of  the  [10XBody[0X  element  whitespace matters because character data is
  allowed nearly everywhere. Here is the definition in the DTD:
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Body  ( %Text;| Chapter | Section )*>[0X
  [4X------------------------------------------------------------------[0X
  
  The  fact  that  [10XChapter[0X  and [10XSection[0X elements are allowed here leads to the
  possibility  to  omit  the  chapter  level  entirely  in the document. For a
  description of [10X%Text;[0X see [14X3.2-3[0X.
  
  (Remark:  The  purpose  of  this element is to make sure that a [13Xvalid[0X [5XGAPDoc[0X
  document  has  a  correct overall structure, which is only possible when the
  top element [10XBook[0X has element content.)
  
  
  [1X3.3-2 [10X<Chapter>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Chapter (%Text;| Heading | Section)*>[0X
    [4X<!ATTLIST Chapter Label CDATA #IMPLIED>    <!-- For reference purposes -->[0X
  [4X------------------------------------------------------------------[0X
  
  A  [10XChapter[0X element can have a [10XLabel[0X attribute, such that this chapter can be
  referenced  later  on  with a [10XRef[0X element (see section [14X3.5-1[0X). Note that you
  have  to  specify  a label to reference the chapter as there is no automatic
  labelling!
  
  [10XChapter[0X  elements  can contain text (for a description of [10X%Text;[0X see [14X3.2-3[0X),
  [10XSection[0X elements, and [10XHeading[0X elements.
  
  The  following [13Xadditional[0X rule cannot be stated in the DTD because we want a
  [10XChapter[0X  element  to  have  mixed content. There must be [13Xexactly one[0X [10XHeading[0X
  element  in the [10XChapter[0X element, containing the heading of the chapter. Here
  is its definition:
  
  
  [1X3.3-3 [10X<Heading>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Heading (%InnerText;)*>[0X
  [4X------------------------------------------------------------------[0X
  
  This  element  is  used  for  headings  in [10XChapter[0X, [10XSection[0X, [10XSubsection[0X, and
  [10XAppendix[0X  elements.  It  may only contain [10X%InnerText;[0X (for a description see
  [14X3.2-3[0X).
  
  Each  of  the  mentioned sectioning elements must contain exactly one direct
  [10XHeading[0X  element  (i.e.,  one  which  is not contained in another sectioning
  element).
  
  
  [1X3.3-4 [10X<Appendix>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Appendix (%Text;| Heading | Section)*>[0X
    [4X<!ATTLIST Appendix Label CDATA #IMPLIED>   <!-- For reference purposes -->[0X
  [4X------------------------------------------------------------------[0X
  
  The  [10XAppendix[0X  element  behaves  exactly  like a [10XChapter[0X element (see [14X3.3-2[0X)
  except  for  the  position  within  the  document  and  the numbering. While
  chapters  are  counted  with  numbers  (1.,  2., 3., ...) the appendices are
  counted with capital letters (A., B., ...).
  
  Again there is an optional [10XLabel[0X attribute used for references.
  
  
  [1X3.3-5 [10X<Section>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Section (%Text;| Heading | Subsection | ManSection)*>[0X
    [4X<!ATTLIST Section Label CDATA #IMPLIED>    <!-- For reference purposes -->[0X
  [4X------------------------------------------------------------------[0X
  
  A  [10XSection[0X element can have a [10XLabel[0X attribute, such that this section can be
  referenced  later  on  with a [10XRef[0X element (see section [14X3.5-1[0X). Note that you
  have  to  specify  a label to reference the section as there is no automatic
  labelling!
  
  [10XSection[0X  elements  can contain text (for a description of [10X%Text;[0X see [14X3.2-3[0X),
  [10XHeading[0X elements, and subsections.
  
  There  must  be  exactly  one  direct  [10XHeading[0X element in a [10XSection[0X element,
  containing the heading of the section.
  
  Note  that  a  subsection  is  either  a  [10XSubsection[0X element or a [10XManSection[0X
  element.
  
  
  [1X3.3-6 [10X<Subsection>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Subsection (%Text;| Heading)*>[0X
    [4X<!ATTLIST Subsection Label CDATA #IMPLIED> <!-- For reference purposes -->[0X
  [4X------------------------------------------------------------------[0X
  
  The [10XSubsection[0X element can have a [10XLabel[0X attribute, such that this subsection
  can be referenced later on with a [10XRef[0X element (see section [14X3.5-1[0X). Note that
  you  have  to  specify  a  label  to reference the subsection as there is no
  automatic labelling!
  
  [10XSubsection[0X  elements  can  contain  text  (for  a  description of [10X%Text;[0X see
  [14X3.2-3[0X), and [10XHeading[0X elements.
  
  There  must  be  exactly  one  [10XHeading[0X  element  in  a  [10XSubsection[0X  element,
  containing the heading of the subsection.
  
  Another type of subsection is a [10XManSection[0X, explained now:
  
  
  [1X3.4 ManSection–a special kind of subsection[0X
  
  [10XManSection[0Xs   are  intended  to  describe  a  function,  operation,  method,
  variable,  or some other technical instance. It is analogous to a manpage in
  the UNIX environment.
  
  
  [1X3.4-1 [10X<ManSection>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT ManSection ( Heading?, [0X
    [4X                      ((Func, Returns?) | (Oper, Returns?) | [0X
    [4X                       (Meth, Returns?) | (Filt, Returns?) | [0X
    [4X                       (Prop, Returns?) | (Attr, Returns?) |[0X
    [4X                       Var | Fam | InfoClass)+, Description )>[0X
    [4X<!ATTLIST ManSection Label CDATA #IMPLIED> <!-- For reference purposes -->[0X
    [4X[0X
    [4X<!ELEMENT Returns (%Text;)*>[0X
    [4X<!ELEMENT Description (%Text;)*>[0X
  [4X------------------------------------------------------------------[0X
  
  The [10XManSection[0X element can have a [10XLabel[0X attribute, such that this subsection
  can  be referenced later on with a [10XRef[0X element (see section [14X3.5-1[0X). But this
  is  probably rarely necessary because the elements [10XFunc[0X and so on (explained
  below) generate automatically labels for cross referencing.
  
  The  content  of  a  [10XManSection[0X  element  is one or more elements describing
  certain items in [5XGAP[0X, each of them optionally followed by a [10XReturns[0X element,
  followed  by  a  [10XDescription[0X  element,  which  contains  [10X%Text;[0X  (see [14X3.2-3[0X)
  describing  it. (Remember to include examples in the description as often as
  possible,  see [14X3.7-10[0X).  The classes of items [5XGAPDoc[0X knows of are: functions
  ([10XFunc[0X),  operations  ([10XOper[0X),  methods  ([10XMeth[0X),  filters  ([10XFilt[0X),  properties
  ([10XProp[0X), attributes ([10XAttr[0X), variables ([10XVar[0X), families ([10XFam[0X), and info classes
  ([10XInfoClass[0X).  One [10XManSection[0X should only describe several of such items when
  these are very closely related.
  
  Each  element for an item corresponding to a [5XGAP[0X function can be followed by
  a [10XReturns[0X element. In output versions of the document the string "Returns: "
  will  be  put  in front of the content text. The text in the [10XReturns[0X 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).
  
  [10XManSection[0Xs are also sectioning elements which count as subsections. Usually
  there  should  be no [10XHeading[0X-element in a [10XManSection[0X, in that case a heading
  is  generated automatically from the first [10XFunc[0X-like element. Sometimes this
  default  behaviour  does  not  look  appropriate, for example when there are
  several [10XFunc[0X-like elements. For such cases an optional [10XHeading[0X is allowed.
  
  
  [1X3.4-2 [10X<Func>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Func EMPTY>[0X
    [4X<!ATTLIST Func Name  CDATA #REQUIRED[0X
    [4X               Label CDATA #IMPLIED[0X
    [4X               Arg   CDATA #REQUIRED[0X
    [4X               Comm  CDATA #IMPLIED>[0X
  [4X------------------------------------------------------------------[0X
  
  This  element  is used within a [10XManSection[0X element to specify the usage of a
  function.  The  [10XName[0X  attribute is required and its value is the name of the
  function.  The  value of the [10XArg[0X 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  [10X"grp[, elm]"[0X  or
  [10X"xx[y[z] ]"[0X.
  
  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
  [13Xalways[0X  be  written  with  the  [10XRef[0X element, see [14X3.5-1[0X. This allows to use a
  unique typesetting style for function names and automatic cross referencing.
  
  If  the optional [10XLabel[0X attribute is given, it is appended (with a colon [10X:[0X 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.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X<Func Arg="x[, y]" Name="LibFunc" Label="for my objects"/>[0X
  [4X------------------------------------------------------------------[0X
  
  The  optional  [10XComm[0X attribute should be a short description of the function,
  usually at most one line long.
  
  This  element  automatically  produces  an  index entry with the name of the
  function  and,  if present, the text of the [10XLabel[0X attribute as subentry (see
  also [14X3.2-16[0X and [14X3.5-4[0X).
  
  
  [1X3.4-3 [10X<Oper>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Oper EMPTY>[0X
    [4X<!ATTLIST Oper Name  CDATA #REQUIRED[0X
    [4X               Label CDATA #IMPLIED[0X
    [4X               Arg   CDATA #REQUIRED[0X
    [4X               Comm  CDATA #IMPLIED>[0X
  [4X------------------------------------------------------------------[0X
  
  This  element is used within a [10XManSection[0X element to specify the usage of an
  operation.  The  attributes  are used exactly in the same way as in the [10XFunc[0X
  element (see [14X3.4-2[0X).
  
  Note  that  multiple  descriptions  of  the  same  operation  may occur in a
  document because there may be several declarations in [5XGAP[0X. Furthermore there
  may  be  several [10XManSection[0Xs for methods of this operation (see [14X3.4-4[0X) which
  also  use  the same name. For reference purposes these must be distinguished
  by different [10XLabel[0X attributes.
  
  
  [1X3.4-4 [10X<Meth>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Meth EMPTY>[0X
    [4X<!ATTLIST Meth Name  CDATA #REQUIRED[0X
    [4X               Label CDATA #IMPLIED[0X
    [4X               Arg   CDATA #REQUIRED[0X
    [4X               Comm  CDATA #IMPLIED>[0X
  [4X------------------------------------------------------------------[0X
  
  This  element  is used within a [10XManSection[0X element to specify the usage of a
  method.  The  attributes  are  used  exactly  in the same way as in the [10XFunc[0X
  element (see [14X3.4-2[0X).
  
  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 [10XManSection[0Xs. It is
  however   required   that   these   subsections  and  those  describing  the
  corresponding operation are distinguished by different [10XLabel[0X attributes.
  
  
  [1X3.4-5 [10X<Filt>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Filt EMPTY>[0X
    [4X<!ATTLIST Filt Name  CDATA #REQUIRED[0X
    [4X               Label CDATA #IMPLIED[0X
    [4X               Arg   CDATA #IMPLIED[0X
    [4X               Comm  CDATA #IMPLIED[0X
    [4X               Type  CDATA #IMPLIED>[0X
  [4X------------------------------------------------------------------[0X
  
  This  element  is used within a [10XManSection[0X element to specify the usage of a
  filter.  The  first  four attributes are used in the same way as in the [10XFunc[0X
  element (see [14X3.4-2[0X), except that the [10XArg[0X attribute is optional.
  
  The [10XType[0X attribute can be any string, but it is thought to be something like
  "[10XCategory[0X" or "[10XRepresentation[0X".
  
  
  [1X3.4-6 [10X<Prop>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Prop EMPTY>[0X
    [4X<!ATTLIST Prop Name  CDATA #REQUIRED[0X
    [4X               Label CDATA #IMPLIED[0X
    [4X               Arg   CDATA #REQUIRED[0X
    [4X               Comm  CDATA #IMPLIED>[0X
  [4X------------------------------------------------------------------[0X
  
  This  element  is used within a [10XManSection[0X element to specify the usage of a
  property.  The  attributes  are  used exactly in the same way as in the [10XFunc[0X
  element (see [14X3.4-2[0X).
  
  
  [1X3.4-7 [10X<Attr>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Attr EMPTY>[0X
    [4X<!ATTLIST Attr Name  CDATA #REQUIRED[0X
    [4X               Label CDATA #IMPLIED[0X
    [4X               Arg   CDATA #REQUIRED[0X
    [4X               Comm  CDATA #IMPLIED>[0X
  [4X------------------------------------------------------------------[0X
  
  This  element is used within a [10XManSection[0X element to specify the usage of an
  attribute  (in  [5XGAP[0X).  The attributes are used exactly in the same way as in
  the [10XFunc[0X element (see [14X3.4-2[0X).
  
  
  [1X3.4-8 [10X<Var>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Var  EMPTY>[0X
    [4X<!ATTLIST Var  Name  CDATA #REQUIRED[0X
    [4X               Label CDATA #IMPLIED[0X
    [4X               Comm  CDATA #IMPLIED>[0X
  [4X------------------------------------------------------------------[0X
  
  This  element  is  used  within  a  [10XManSection[0X  element to document a global
  variable.  The  attributes  are  used exactly in the same way as in the [10XFunc[0X
  element (see [14X3.4-2[0X) except that there is no [10XArg[0X attribute.
  
  
  [1X3.4-9 [10X<Fam>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Fam  EMPTY>[0X
    [4X<!ATTLIST Fam  Name  CDATA #REQUIRED[0X
    [4X               Label CDATA #IMPLIED[0X
    [4X               Comm  CDATA #IMPLIED>[0X
  [4X------------------------------------------------------------------[0X
  
  This  element  is used within a [10XManSection[0X element to document a family. The
  attributes  are  used  exactly  in  the same way as in the [10XFunc[0X element (see
  [14X3.4-2[0X) except that there is no [10XArg[0X attribute.
  
  
  [1X3.4-10 [10X<InfoClass>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT InfoClass EMPTY>[0X
    [4X<!ATTLIST InfoClass Name  CDATA #REQUIRED[0X
    [4X                    Label CDATA #IMPLIED[0X
    [4X                    Comm  CDATA #IMPLIED>[0X
  [4X------------------------------------------------------------------[0X
  
  This  element is used within a [10XManSection[0X element to document an info class.
  The  attributes are used exactly in the same way as in the [10XFunc[0X element (see
  [14X3.4-2[0X) except that there is no [10XArg[0X attribute.
  
  
  [1X3.5 Cross Referencing and Citations[0X
  
  Cross  referencing  in  the [5XGAPDoc[0X system is somewhat different to the usual
  LaTeX  cross  referencing  in  so far, that a reference knows "which type of
  object"  it  is  referencing.  For  example  a  "reference to a function" is
  distinguished from a "reference to a chapter". The idea of this is, that the
  markup  must  contain  this information such that the converters can produce
  better  output.  The  HTML  converter  can  for  example  typeset a function
  reference just as the name of the function with a link to the description of
  the  function,  or  a chapter reference as a number with a link in the other
  case.
  
  Referencing is done with the [10XRef[0X element:
  
  
  [1X3.5-1 [10X<Ref>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Ref EMPTY>[0X
    [4X<!ATTLIST Ref Func      CDATA #IMPLIED[0X
    [4X              Oper      CDATA #IMPLIED[0X
    [4X              Meth      CDATA #IMPLIED[0X
    [4X              Filt      CDATA #IMPLIED[0X
    [4X              Prop      CDATA #IMPLIED[0X
    [4X              Attr      CDATA #IMPLIED[0X
    [4X              Var       CDATA #IMPLIED[0X
    [4X              Fam       CDATA #IMPLIED[0X
    [4X              InfoClass CDATA #IMPLIED[0X
    [4X              Chap      CDATA #IMPLIED[0X
    [4X              Sect      CDATA #IMPLIED[0X
    [4X              Subsect   CDATA #IMPLIED[0X
    [4X              Appendix  CDATA #IMPLIED[0X
    [4X              Text      CDATA #IMPLIED[0X
    [4X[0X
    [4X              Label     CDATA #IMPLIED[0X
    [4X              BookName  CDATA #IMPLIED[0X
    [4X              Style (Text | Number) #IMPLIED>  <!-- normally automatic -->[0X
  [4X------------------------------------------------------------------[0X
  
  The [10XRef[0X element is defined to be [10XEMPTY[0X. If one of the attributes [10XFunc[0X, [10XOper[0X,
  [10XMeth[0X,  [10XProp[0X,  [10XAttr[0X,  [10XVar[0X,  [10XFam[0X,  [10XInfoClass[0X, [10XChap[0X, [10XSect[0X, [10XSubsect[0X, [10XAppendix[0X is
  given  then  there must be exactly one of these, making the reference one to
  the  corresponding  object. The [10XLabel[0X attribute can be specified in addition
  to  make  the  reference  unique, for example if more than one method with a
  given name is present. (Note that there is no way to specify in the DTD that
  exactly  one  of  the  first  listed  attributes  must  be given, this is an
  additional rule.)
  
  A  reference  to a [10XLabel[0X element defined below (see [14X3.5-2[0X) is done by giving
  the [10XLabel[0X attribute and optionally the [10XText[0X attribute. If the [10XText[0X attribute
  is  present  its value is typeset in place of the [10XRef[0X 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 [14X3.6-5[0X).
  
  An  external  reference  into  another  book  can  be specified by using the
  [10XBookName[0X  attribute.  In  this  case  the [10XLabel[0X attribute or, if this is not
  given,  the  function  or  section  like  attribute,  is used to resolve the
  reference.  The  generated  reference  points  to  the first hit when asking
  "?book name: label" inside [5XGAP[0X.
  
  The  optional  attribute  [10XStyle[0X can take only the values [10XText[0X and [10XNumber[0X. 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 [5XGAP[0X
  object  generate  the  name of the corresponding object with some additional
  link  or  sectioning  information, which is the behavior of [10XStyle="Text"[0X. In
  case [10XStyle="Number"[0X in all cases an explicit section number is generated. So
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X<Ref Subsect="Func" Style="Text"/> described in section [0X
    [4X<Ref Subsect="Func" Style="Number"/>[0X
  [4X------------------------------------------------------------------[0X
  
  produces: [14X'[10X<Func>[0X'[0X described in section [14X3.4-2[0X.
  
  
  [1X3.5-2 [10X<Label>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Label EMPTY>[0X
    [4X<!ATTLIST Label Name CDATA #REQUIRED>[0X
  [4X------------------------------------------------------------------[0X
  
  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 [10XName[0X attribute must be unique
  under all [10XLabel[0X elements.
  
  
  [1X3.5-3 [10X<Cite>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Cite EMPTY>[0X
    [4X<!ATTLIST Cite Key CDATA #REQUIRED[0X
    [4X               Where CDATA #IMPLIED>[0X
  [4X------------------------------------------------------------------[0X
  
  This  element  is for bibliography citations. It is [10XEMPTY[0X by definition. The
  attribute  [10XKey[0X  is  the key for a lookup in a BibTeX database that has to be
  specified  in  the [10XBibliography[0X element (see [14X3.2-15[0X). The value of the [10XWhere[0X
  attribute  specifies  the  position  in the document as in the corresponding
  LaTeX syntax [10X\cite[Where value]{Key value}[0X.
  
  
  [1X3.5-4 [10X<Index>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Index (%InnerText;|Subkey)*>[0X
    [4X<!ATTLIST Index Key    CDATA #IMPLIED[0X
    [4X                Subkey CDATA #IMPLIED>[0X
    [4X<!ELEMENT Subkey (%InnerText;)*>[0X
  [4X------------------------------------------------------------------[0X
  
  This  element  generates  an  index  entry.  The  text within the element is
  typeset  in  the  index  entry,  which  is  sorted  under the value, that is
  specified  in  the [10XKey[0X and [10XSubkey[0X attributes. If they are not specified, the
  typeset text itself is used as the key.
  
  A  subkey  can be specified in the simpler version as an attribute, but then
  no  further  markup  can be used for the subkey. Optionally, the subkey text
  can  be  given in a [10XSubkey[0X element, in this case the attribute value is used
  for sorting but the typeset text is taken from the content of [10XSubkey[0X.
  
  Note  that  all  [10XFunc[0X  and  similar  elements  automatically  generate index
  entries. If the [10XTheIndex[0X element ([14X3.2-16[0X) is not present in the document all
  [10XIndex[0X elements are ignored.
  
  
  [1X3.5-5 [10X<URL>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT URL (#PCDATA|Alt|Link|LinkText)*>  <!-- Link, LinkText[0X
    [4X     variant for case where text needs further markup -->[0X
    [4X<!ATTLIST URL Text CDATA #IMPLIED>   <!-- This is for output formats[0X
    [4X                                          that have links like HTML -->[0X
    [4X<!ELEMENT Link     (%InnerText;)*> <!-- the URL -->[0X
    [4X<!ELEMENT LinkText (%InnerText;)*> <!-- text for links, can contain markup -->[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  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 [10XText[0X attribute (in
  this  case  the text cannot contain further markup), or the element contains
  the  two  elements  [10XLink[0X  and [10XLinkText[0X which in turn contain the URL and the
  text, respectively. The default value for the text is the URL itself.
  
  
  [1X3.5-6 [10X<Email>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Email (#PCDATA|Alt|Link|LinkText)*>[0X
  [4X------------------------------------------------------------------[0X
  
  This element type is the special case of an URL specifying an email address.
  The  content  of  the element should be the email address without any prefix
  like  "[10Xmailto:[0X". 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 "[10Xmailto:[0X" prefix.
  
  
  [1X3.5-7 [10X<Homepage>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Homepage (#PCDATA|Alt|Link|LinkText)*>[0X
  [4X------------------------------------------------------------------[0X
  
  This element type is the special case of an URL specifying a WWW-homepage.
  
  
  [1X3.6 Structural Elements like Lists[0X
  
  The  [5XGAPDoc[0X  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.
  
  
  [1X3.6-1 [10X<List>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT List ( ((Mark,Item)|(BigMark,Item)|Item)+ )>[0X
    [4X<!ATTLIST List Only CDATA #IMPLIED[0X
    [4X               Not  CDATA #IMPLIED>[0X
  [4X------------------------------------------------------------------[0X
  
  This  element  produces a list. Each item in the list corresponds to an [10XItem[0X
  element.  Every  [10XItem[0X  element is optionally preceded by a [10XMark[0X element. The
  content  of this is used as a marker for the item. Note that this marker can
  be  a  whole  word or even a sentence. It will be typeset in some emphasized
  fashion  and  most  converters will provide some indentation for the rest of
  the item.
  
  The  [10XOnly[0X  and  [10XNot[0X  attributes  can  be  used  to specify, that the list is
  included into the output by only one type of converter ([10XOnly[0X) or all but one
  type  of  converter  ([10XNot[0X).  Of course at most one of the two attributes may
  occur  in  one element. The following values are allowed as of now: "[10XLaTeX[0X",
  "[10XHTML[0X",  and  "[10XText[0X".  See also the [10XAlt[0X element in [14X3.9-1[0X for more about text
  alternatives for certain converters.
  
  
  [1X3.6-2 [10X<Mark>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Mark ( %InnerText;)*>[0X
  [4X------------------------------------------------------------------[0X
  
  This  element  is  used  in the [10XList[0X element to mark items. See [14X3.6-1[0X for an
  explanation.
  
  
  [1X3.6-3 [10X<Item>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Item ( %Text;)*>[0X
  [4X------------------------------------------------------------------[0X
  
  This  element  is  used in the [10XList[0X, [10XEnum[0X, and [10XTable[0X elements to specify the
  items. See sections [14X3.6-1[0X, [14X3.6-4[0X, and [14X3.6-5[0X for further information.
  
  
  [1X3.6-4 [10X<Enum>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Enum ( Item+ )>[0X
    [4X<!ATTLIST Enum Only CDATA #IMPLIED[0X
    [4X               Not  CDATA #IMPLIED>[0X
  [4X------------------------------------------------------------------[0X
  
  This element is used identically to the [10XList[0X element (see [14X3.6-1[0X) except that
  the  items  may  not  have  marks  attached  to them. Instead, the items are
  numbered  automatically. The same comments about the [10XOnly[0X and [10XNot[0X attributes
  as above apply.
  
  
  [1X3.6-5 [10X<Table>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Table ( Caption?, (Row | HorLine)+ )>[0X
    [4X<!ATTLIST Table Label   CDATA #IMPLIED[0X
    [4X                Only    CDATA #IMPLIED[0X
    [4X                Not     CDATA #IMPLIED[0X
    [4X                Align   CDATA #REQUIRED>[0X
    [4X                <!-- We allow | and l,c,r, nothing else -->[0X
    [4X<!ELEMENT Row   ( Item+ )>[0X
    [4X<!ELEMENT HorLine EMPTY>[0X
    [4X<!ELEMENT Caption ( %InnerText;)*>[0X
  [4X------------------------------------------------------------------[0X
  
  A  table  in  [5XGAPDoc[0X  consists  of an optional [10XCaption[0X element followed by a
  sequence  of  [10XRow[0X  and  [10XHorLine[0X  elements.  A  [10XHorLine[0X  element  produces  a
  horizontal  line  in the table. A [10XRow[0X element consists of a sequence of [10XItem[0X
  elements  as  they  also  occur  in [10XList[0X and [10XEnum[0X elements. The [10XOnly[0X and [10XNot[0X
  attributes  have  the same functionality as described in the [10XList[0X element in
  [14X3.6-1[0X.
  
  The  [10XAlign[0X attribute is written like a LaTeX tabular alignment specifier but
  only  the letters "[10Xl[0X", "[10Xr[0X", "[10Xc[0X", and "[10X|[0X" are allowed meaning left alignment,
  right  alignment,  centered  alignment,  and  a  vertical  line as delimiter
  between columns respectively.
  
  If  the  [10XLabel[0X  attribute is there, one can reference the table with the [10XRef[0X
  element (see [14X3.5-1[0X) using its [10XLabel[0X attribute.
  
  Usually  only  simple tables should be used. If you want a complicated table
  in  the  LaTeX  output  you  should  provide  alternatives for text and HTML
  output.  Note  that in HTML-4.0 there is no possibility to interpret the "[10X|[0X"
  column  separators and [10XHorLine[0X elements as intended. There are lines between
  all columns and rows or no lines at all.
  
  
  [1X3.7 Types of Text[0X
  
  This  section  covers the markup of text. Various types of "text" exist. The
  following  elements  are used in the [5XGAPDoc[0X system to mark them. They mostly
  come  in  pairs, one long name which is easier to remember and a shortcut to
  make the markup "lighter".
  
  Most  of  the  following elements are thought to contain only character data
  and  no  further  markup  elements.  It  is  however  necessary to allow [10XAlt[0X
  elements to resolve the entities described in section [14X2.2-3[0X.
  
  
  [1X3.7-1 [10X<Emph>[0X[1X and [10X<E>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Emph (%InnerText;)*>    <!-- Emphasize something -->[0X
    [4X<!ELEMENT E    (%InnerText;)*>    <!-- the same as shortcut -->[0X
  [4X------------------------------------------------------------------[0X
  
  This  element  is  used  to  emphasize  some  piece  of text. It may contain
  [10X%InnerText;[0X (see [14X3.2-3[0X).
  
  
  [1X3.7-2 [10X<Quoted>[0X[1X and [10X<Q>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Quoted (%InnerText;)*>   <!-- Quoted (in quotes) text -->[0X
    [4X<!ELEMENT Q (%InnerText;)*>        <!-- Quoted text (shortcut) -->[0X
  [4X------------------------------------------------------------------[0X
  
  This  element  is  used  to  put  some piece of text into " "-quotes. It may
  contain [10X%InnerText;[0X (see [14X3.2-3[0X).
  
  
  [1X3.7-3 [10X<Keyword>[0X[1X and [10X<K>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Keyword (#PCDATA|Alt)*>  <!-- Keyword -->[0X
    [4X<!ELEMENT K (#PCDATA|Alt)*>        <!-- Keyword (shortcut) -->[0X
  [4X------------------------------------------------------------------[0X
  
  This  element is used to mark something as a [13Xkeyword[0X. Usually this will be a
  [5XGAP[0X  keyword  such  as "[9Xif[0X" or "[9Xfor[0X". No further markup elements are allowed
  within this element except for the [10XAlt[0X element, which is necessary.
  
  
  [1X3.7-4 [10X<Arg>[0X[1X and [10X<A>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Arg (#PCDATA|Alt)*>      <!-- Argument -->[0X
    [4X<!ELEMENT A (#PCDATA|Alt)*>        <!-- Argument (shortcut) -->[0X
  [4X------------------------------------------------------------------[0X
  
  This element is used inside [10XDescription[0Xs in [10XManSection[0Xs to mark something as
  an  [13Xargument[0X  (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.
  
  
  [1X3.7-5 [10X<Code>[0X[1X and [10X<C>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Code (#PCDATA|Alt)*>     <!-- GAP code -->[0X
    [4X<!ELEMENT C (#PCDATA|Alt)*>        <!-- GAP code (shortcut) -->[0X
  [4X------------------------------------------------------------------[0X
  
  This element is used to mark something as a piece of [13Xcode[0X like for example a
  [5XGAP[0X expression. It is guaranteed that the converters typeset this exactly as
  in  the  [10XListing[0X  element (compare section [14X3.7-9[0X. No further markup elements
  are allowed within this element.
  
  
  [1X3.7-6 [10X<File>[0X[1X and [10X<F>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT File (#PCDATA|Alt)*>     <!-- Filename -->[0X
    [4X<!ELEMENT F (#PCDATA|Alt)*>        <!-- Filename (shortcut) -->[0X
  [4X------------------------------------------------------------------[0X
  
  This  element  is  used to mark something as a [13Xfilename[0X or a [13Xpathname[0X in the
  file system. No further markup elements are allowed within this element.
  
  
  [1X3.7-7 [10X<Button>[0X[1X and [10X<B>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Button (#PCDATA|Alt)*>   <!-- "Button" (also Menu, Key, ...) -->[0X
    [4X<!ELEMENT B (#PCDATA|Alt)*>        <!-- "Button" (shortcut) -->[0X
  [4X------------------------------------------------------------------[0X
  
  This  element is used to mark something as a [13Xbutton[0X. It can also be used for
  other items in a graphical user interface like [13Xmenus[0X, [13Xmenu entries[0X, or [13Xkeys[0X.
  No further markup elements are allowed within this element.
  
  
  [1X3.7-8 [10X<Package>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Package (#PCDATA|Alt)*>   <!-- A package name -->[0X
  [4X------------------------------------------------------------------[0X
  
  This  element  is used to mark something as a name of a [13Xpackage[0X. This is for
  example used to define the entities [5XGAP[0X, [5XXGAP[0X or [5XGAPDoc[0X (see section [14X2.2-3[0X).
  No further markup elements are allowed within this element.
  
  
  [1X3.7-9 [10X<Listing>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Listing (#PCDATA)>  <!-- This is just for GAP code listings -->[0X
    [4X<!ATTLIST Listing Type CDATA #IMPLIED> <!-- a comment about the type of[0X
    [4X                                            listed code, may appear in[0X
    [4X                                            output -->[0X
  [4X------------------------------------------------------------------[0X
  
  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
  [13Xnot[0X  use  the character entities described in section [14X2.2-3[0X but instead type
  the  characters directly. Only the general XML rules from section [14X2.1[0X apply.
  Note  especially  the  usage  of  [10X<![CDATA[[0X  sections described there. It is
  guaranteed  that  all  converters  use  a  fixed  width font for typesetting
  [10XListing[0X  elements.  Compare  also  the  usage  of the [10XCode[0X and [10XC[0X elements in
  [14X3.7-5[0X.
  
  The  [10XType[0X attribute contains a comment about the type of listed code. It may
  appear in the output.
  
  
  [1X3.7-10 [10X<Log>[0X[1X and [10X<Example>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Example (#PCDATA)>  <!-- This is subject to the automatic [0X
    [4X                                   example checking mechanism -->[0X
    [4X<!ELEMENT Log (#PCDATA)>      <!-- This not -->[0X
  [4X------------------------------------------------------------------[0X
  
  These two elements behave exactly like the [10XListing[0X element (see [14X3.7-9[0X). They
  are  thought  for protocols of [5XGAP[0X sessions. The only difference between the
  two  is  that  [10XExample[0X  sections  are intended to be subject to an automatic
  manual  checking  mechanism used to ensure the correctness of the [5XGAP[0X manual
  whereas [10XLog[0X is not touched by this.
  
  
  [1X3.7-11 <Verb>[0X
  
  There is one further type of verbatim-like element.
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Verb  (#PCDATA)> [0X
  [4X------------------------------------------------------------------[0X
  
  The  content  of  such  an  element  is  guaranteed to be put into an output
  version  exactly  as it is using some fixed width font. Before the content a
  new  line is started. If the line after the end of the start tag consists of
  whitespace only then this part of the content is skipped.
  
  This element is intended to be used together with the [10XAlt[0X element to specify
  pre-formatted ASCII alternatives for complicated [10XDisplay[0X formulae or [10XTable[0Xs.
  
  
  [1X3.8 Elements for Mathematical Formulae[0X
  
  
  [1X3.8-1 [10X<Math>[0X[1X and [10X<Display>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!-- Normal TeX math mode formula -->[0X
    [4X<!ELEMENT Math (#PCDATA|A|Arg|Alt)*>   [0X
    [4X<!-- TeX displayed math mode formula -->[0X
    [4X<!ELEMENT Display (#PCDATA|A|Arg|Alt)*>[0X
  [4X------------------------------------------------------------------[0X
  
  These  elements  are used for mathematical formulae. As described in section
  [14X2.2-2[0X they correspond to LaTeX's math and display math mode respectively.
  
  The  formulae  are  typed  in  as  in  LaTeX,  [13Xexcept[0X  that the standard XML
  entities,  see [14X2.1-9[0X (in particular the characters [10X<[0X and [10X&[0X), must be escaped
  -  either  by  using  the corresponding entities or by enclosing the formula
  between "[10X<![CDATA[[0X" and "[10X]]>[0X". (The main reference for LaTeX is [Lam85].)
  
  The only element type that is allowed within the formula elements is the [10XArg[0X
  or  [10XA[0X  element  (see  [14X3.7-4[0X),  which is used to typeset identifiers that are
  arguments to [5XGAP[0X functions or operations.
  
  In  text  and HTML output these formulae are shown as LaTeX source code. For
  simple formulae (and you should try to make all your formulae simple!) there
  is  the  element [10XM[0X (see [14X3.8-2[0X) 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 [10XMath[0X and [10XDisplay[0X elements or
  provide  useful  text  substitutes for complicated formulae via [10XAlt[0X elements
  (see [14X3.9-1[0X and [14X3.7-11[0X).
  
  
  [1X3.8-2 [10X<M>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!-- Math with well defined translation to text output -->[0X
    [4X<!ELEMENT M (#PCDATA|A|Arg|Alt)*>[0X
  [4X------------------------------------------------------------------[0X
  
  The  "[10XM[0X" element type is intended for formulae in the running text for which
  there  is  a  sensible  ASCII  version.  For  the  LaTeX version of a [5XGAPDoc[0X
  document  the [10XM[0X and [10XMath[0X elements are equivalent. The remarks in [14X3.8-1[0X about
  special  characters and the [10XArg[0X element apply here as well. A document which
  has  all  formulae  enclosed  in  [10XM[0X  elements  can  be well readable in text
  terminal output and printed output versions.
  
  The  following  LaTeX  macros  have  a  sensible  ASCII  translation and are
  guaranteed to be translated accordingly by text (and HTML) converters:
  
     ---------------------------
      | \ast            | [10X*[0X   | 
     ---------------------------
      | \cdot           | [10X*[0X   | 
     ---------------------------
      | \colon          | [10X:[0X   | 
     ---------------------------
      | \equiv          | [10X=[0X   | 
     ---------------------------
      | \geq            | [10X>=[0X  | 
     ---------------------------
      | \hookrightarrow | [10X->[0X  | 
     ---------------------------
      | \iff            | [10X<=>[0X | 
     ---------------------------
      | \langle         | [10X<[0X   | 
     ---------------------------
      | \ldots          | [10X...[0X | 
     ---------------------------
      | \left           | [10X [0X   | 
     ---------------------------
      | \leq            | [10X<=[0X  | 
     ---------------------------
      | \leftarrow      | [10X<-[0X  | 
     ---------------------------
      | \Leftarrow      | [10X<=[0X  | 
     ---------------------------
      | \limits         | [10X [0X   | 
     ---------------------------
      | \longrightarrow | [10X-->[0X | 
     ---------------------------
      | \Longrightarrow | [10X==>[0X | 
     ---------------------------
      | \mapsto         | [10X->[0X  | 
     ---------------------------
      | \mathbb         | [10X [0X   | 
     ---------------------------
      | \mathop         | [10X [0X   | 
     ---------------------------
      | \mid            | [10X|[0X   | 
     ---------------------------
      | \pmod           | [10Xmod[0X | 
     ---------------------------
      | \rangle         | [10X>[0X   | 
     ---------------------------
      | \right          | [10X [0X   | 
     ---------------------------
      | \rightarrow     | [10X->[0X  | 
     ---------------------------
      | \Rightarrow     | [10X=>[0X  | 
     ---------------------------
      | \setminus       | [10X\[0X   | 
     ---------------------------
      | \times          | [10Xx[0X   | 
     ---------------------------
      | \to             | [10X->[0X  | 
     ---------------------------
  
       [1XTable:[0X LaTeX macros with special text translation
  
  
  In  all other macros only the backslash is removed. Whitespace is normalized
  (to  one  blank)  but not removed. Note that whitespace is not added, so you
  may  want  to  add  a  few  more  spaces  than  you usually do in your LaTeX
  documents.
  
  Braces  [10X{}[0X  are  removed  in  general,  however  pairs  of double braces are
  converted to one pair of braces. This can be used to write [10X<M>x^{12}</M>[0X for
  [10Xx^12[0X and [10X<M>x_{{i+1}}</M>[0X for [10Xx_{i+1}[0X.
  
  
  [1X3.9 Everything else[0X
  
  
  [1X3.9-1 [10X<Alt>[0X[1X[0X
  
  This  element  is  used to specify alternatives for different output formats
  within   normal  text.  See  also  sections  [14X3.6-1[0X,  [14X3.6-4[0X,  and  [14X3.6-5[0X  for
  alternatives in lists and tables.
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Alt (%InnerText;)*>  <!-- This is only to allow "Only" and[0X
    [4X                                    "Not" attributes for normal text -->[0X
    [4X<!ATTLIST Alt Only CDATA #IMPLIED[0X
    [4X              Not  CDATA #IMPLIED>[0X
  [4X------------------------------------------------------------------[0X
  
  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 [5XGAPDoc[0X are: "[10XLaTeX[0X", "[10XHTML[0X", and "[10XText[0X". If the [10XOnly[0X attribute
  is  specified then only the corresponding converter will include the content
  of  the  element into the output document. If the [10XNot[0X attribute is specified
  the  corresponding converter will ignore the content of the element. You can
  use  other  words  to  specify  special alternatives for other converters of
  [5XGAPDoc[0X documents.
  
  We  fix  a  rule  for  handling  the  content  of  an  [10XAlt[0X element with [10XOnly[0X
  attribute.  In  their  content  code  for the corresponding output format is
  included  directly. So, in case of HTML the content is HTML code, in case of
  LaTeX  the content is LaTeX code. The converters don't apply any handling of
  special characters to this content.
  
  Within  the  element  only  [10X%InnerText;[0X  (see  [14X3.2-3[0X) is allowed. This is to
  ensure  that  the same set of chapters, sections, and subsections show up in
  all output formats.
  
  
  [1X3.9-2 [10X<Par>[0X[1X and [10X<P>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Par EMPTY>    <!-- this is intentionally empty! -->[0X
    [4X<!ELEMENT P EMPTY>      <!-- the same as shortcut  -->[0X
  [4X------------------------------------------------------------------[0X
  
  This [10XEMPTY[0X element marks the boundary of paragraphs. Note that an empty line
  in  the  input  does  not  mark  a  new  paragraph  as  opposed to the LaTeX
  convention.
  
  (Remark:  it  would be much easier to parse a document and to understand its
  sectioning  and  paragraph structure when there was an element whose [13Xcontent[0X
  is  the  text  of a paragraph. But in practice many paragraph boundaries are
  implicitly  clear  which  would  make  it  somewhat  painful to enclose each
  paragraph  in extra tags. The introduction of the [10XP[0X or [10XPar[0X elements as above
  delegates  this  pain  to  the  writer  of  a  conversion program for [5XGAPDoc[0X
  documents.)
  
  
  [1X3.9-3 [10X<Br>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Br EMPTY>     <!-- a forced line break  -->[0X
  [4X------------------------------------------------------------------[0X
  
  This  element  can be used to force a line break in the output versions of a
  [5XGAPDoc[0X  element,  it does not start a new paragraph. Please, do not use this
  instead  of  a [10XPar[0X element, this would often lead to ugly output versions of
  your document.
  
  
  [1X3.9-4 [10X<Ignore>[0X[1X[0X
  
  [4X-----------------------  From gapdoc.dtd  ------------------------[0X
    [4X<!ELEMENT Ignore (%Text;| Chapter | Section | Subsection | ManSection |[0X
    [4X                  Heading)*>[0X
    [4X<!ATTLIST Ignore Remark CDATA #IMPLIED>[0X
  [4X------------------------------------------------------------------[0X
  
  This  element  can  appear  anywhere. Its content is ignored by the standard
  converters.  It can be used, for example, to include data which are not part
  of  the  actual  [5XGAPDoc[0X  document, like source code, or to make not finished
  parts of the document invisible.
  
  Of course, one can use special converter programs which extract the contents
  of  [10XIgnore[0X elements. Information on the type of the content can be stored in
  the optional attribute [10XRemark[0X.
  
