chapB.txt

  
  B The File gapdoc.dtd
  
  For  easier  reference  we  repeat  here  the  complete  content of the file
  gapdoc.dtd.
  
    gapdoc.dtd  
    <?xml version="1.0" encoding="UTF-8"?>
    <!-- ==================================================================
         gapdoc.dtd - XML Document type definition for GAP documentation
         By Frank Lübeck and Max Neunhöffer
         ================================================================== -->
    
    
    <!-- Note that this definition goes "bottom-up" because entities can only
         be used after their definition in the file. -->
    
    
    <!-- ==================================================================
         Some entities:
         ================================================================== -->
    
    <!-- The standard XML entities: -->
    
    <!ENTITY lt     "&#38;#60;"> 
    <!ENTITY gt     "&#62;"> 
    <!ENTITY amp    "&#38;#38;"> 
    <!ENTITY apos   "&#39;"> 
    <!ENTITY quot   "&#34;">
    
    
    <!-- The following were introduced in GAPDoc version < 1.0, it is no longer
         necessary to take care of LaTeX special characters
         (we keep the entities with simplified definitions for compatibility) -->
         
    <!ENTITY tamp "&amp;">
    <!ENTITY tlt "&lt;">
    <!ENTITY tgt "&gt;">
    <!ENTITY hash "#">
    <!ENTITY dollar "$">
    <!ENTITY percent "&#37;">
    <!ENTITY tilde "~">
    <!ENTITY bslash "\\">
    <!ENTITY obrace "{">
    <!ENTITY cbrace "}">
    <!ENTITY uscore "_">
    <!ENTITY circum "^">
    
    <!-- ==================================================================
         Our predefined entities:
         ================================================================== -->
    
    <!ENTITY nbsp "&#160;">
    <!ENTITY ndash "&#x2013;">
    <!ENTITY GAP    "<Package>GAP</Package>">
    <!ENTITY GAPDoc "<Package>GAPDoc</Package>">
    <!ENTITY TeX    
      "<Alt Only='LaTeX'>{\TeX}</Alt><Alt Not='LaTeX'>TeX</Alt>">
    <!ENTITY LaTeX  
      "<Alt Only='LaTeX'>{\LaTeX}</Alt><Alt Not='LaTeX'>LaTeX</Alt>">
    <!ENTITY BibTeX 
      "<Alt Only='LaTeX'>{Bib\TeX}</Alt><Alt Not='LaTeX'>BibTeX</Alt>">
    <!ENTITY MeatAxe "<Package>MeatAxe</Package>">
    <!ENTITY XGAP   "<Package>XGAP</Package>">
    <!ENTITY copyright "&#169;">
    
    <!-- and unicode math symbols -->
    <!ENTITY CC "&#x2102;" > <!-- double struck -->
    <!ENTITY ZZ "&#x2124;" >
    <!ENTITY NN "&#x2115;" >
    <!ENTITY PP "&#x2119;" >
    <!ENTITY QQ "&#x211a;" >
    <!ENTITY HH "&#x210d;" >
    <!ENTITY RR "&#x211d;" >
    
    
    <!-- ==================================================================
         The following describes the "innermost" documentation text which 
         can occur at various places in the document like for example
         section headings. It does neither contain further sectioning 
         elements nor environments like Enums or Lists. 
         ================================================================== -->
    
    <!ENTITY % InnerText "#PCDATA |
                          Alt |
                          Emph | E |
                          Par | P | Br |
                          Keyword | K | Arg | A | Quoted | Q | Code | C | 
                          File | F | Button | B | Package |
                          M | Math | Display | 
                          Example | Listing | Log | Verb |
                          URL | Email | Homepage | Address | Cite | Label | 
                          Ref | Index |
                          Ignore" >
    
    
    <!ELEMENT Alt (%InnerText;)*>     <!-- This is only to allow "Only" and
                                           "Not" attributes for normal text -->
    <!ATTLIST Alt Only CDATA #IMPLIED
                  Not  CDATA #IMPLIED>
    
    <!-- The following elements declare a certain block of InnerText to
         have a certain property. They are non-terminal and can contain
         any InnerText recursively. -->
    
    <!ELEMENT Emph (%InnerText;)*>    <!-- Emphasize something -->
    <!ELEMENT E    (%InnerText;)*>    <!-- the same as shortcut -->
    
    
    <!-- The following is an empty element marking a paragraph boundary. -->
    
    <!ELEMENT Par EMPTY>    <!-- this is intentionally empty! -->
    <!ELEMENT P EMPTY>      <!-- the same as shortcut  -->
    
    <!-- And here is an element for forcing a line break, not starting
         a new paragraph. -->
    
    <!ELEMENT Br EMPTY>     <!-- a forced line break  -->
    
    <!-- The following elements mark a word or sentence to be of a certain
         kind, such that it can  be typeset differently. They are terminal
         elements that should only contain  character data. But we have to
         allow  Alt elements  for handling  special characters.  For these
         elements we introduce  a long name - which is  easy to remember -
         and a  short name - which  you may prefer because  of the shorter
         markup. -->
    
    <!ELEMENT Keyword (#PCDATA|Alt)*>  <!-- Keyword -->
    <!ELEMENT K (#PCDATA|Alt)*>        <!-- Keyword (shortcut) -->
    
    <!ELEMENT Arg (#PCDATA|Alt)*>      <!-- Argument -->
    <!ELEMENT A (#PCDATA|Alt)*>        <!-- Argument (shortcut) -->
    
    <!ELEMENT Code (#PCDATA|Alt|A|Arg)*> <!-- GAP code -->
    <!ELEMENT C (#PCDATA|Alt|A|Arg)*>    <!-- GAP code (shortcut) -->
    
    <!ELEMENT File (#PCDATA|Alt)*>     <!-- Filename -->
    <!ELEMENT F (#PCDATA|Alt)*>        <!-- Filename (shortcut) -->
    
    <!ELEMENT Button (#PCDATA|Alt)*>   <!-- "Button" (also Menu, Key) -->
    <!ELEMENT B (#PCDATA|Alt)*>        <!-- "Button" (shortcut) -->
    
    <!ELEMENT Package (#PCDATA|Alt)*>  <!-- A package name -->
    
    <!ELEMENT Quoted (%InnerText;)*>   <!-- Quoted (in quotes) text -->
    <!ELEMENT Q (%InnerText;)*>        <!-- Quoted text (shortcut) -->
    
    
    <!-- The following elements contain mathematical formulae. They are 
         terminal elements that contain character data in TeX notation. -->
    
    <!-- Math with well defined translation to text output -->
    <!ELEMENT M (#PCDATA|A|Arg|Alt)*>
    <!-- Normal TeX math mode formula -->
    <!ELEMENT Math (#PCDATA|A|Arg|Alt)*>   
    <!-- TeX displayed math mode formula -->
    <!ELEMENT Display (#PCDATA|A|Arg|Alt)*>
    <!-- Mode="M" causes <M>-style formatting -->
    <!ATTLIST Display Mode CDATA #IMPLIED>  
    
    
    <!-- The  following  elements  contain  GAP related  text  like  code,
         session  logs or  examples. They  are all  terminal elements  and
         consist of character data which is normally typeset verbatim. The
         different  types  of  the  elements only  control  how  they  are
         treated. -->
    
    <!ELEMENT Example (#PCDATA)>  <!-- This is subject to the automatic 
                                       example checking mechanism -->
    <!ELEMENT Log (#PCDATA)>      <!-- This not -->
    <!ELEMENT Listing (#PCDATA)>  <!-- This is just for code listings -->
    <!ATTLIST Listing Type CDATA #IMPLIED> <!-- a comment about the type of
                                                listed code, may appear in
                                                output -->
    
    <!-- One  further  verbatim element,  this is truely  verbatim without
         any processing and intended  for ASCII substitutes of complicated
         displayed formulae or tables. -->
    
    <!ELEMENT Verb  (#PCDATA)> 
    
    <!-- The following  elements are  for cross-referencing  purposes like
         URLs, citations,  references, and  the index. All  these elements
         are  terminal and  need special  methods  to make  up the  actual
         output during document generation. -->
    
    <!ELEMENT URL (#PCDATA|Alt|Link|LinkText)*>  <!-- Link, LinkText
         variant for case where text needs further markup -->
    <!ATTLIST URL Text CDATA #IMPLIED>   <!-- This is for output formats
                                              that have links like HTML -->
    <!ELEMENT Link     (%InnerText;)*> <!-- the URL -->
    <!ELEMENT LinkText (%InnerText;)*> <!-- text for links, can contain markup -->
    <!-- The following two are actually URLs, but the element name determines
         the type. -->
    <!ELEMENT Email (#PCDATA|Alt|Link|LinkText)*>
    <!ELEMENT Homepage (#PCDATA|Alt|Link|LinkText)*>
    
    <!-- Those who still want to give postal addresses can use the following
         element. Use <Br/> for specifying typical line breaks  -->
    
    <!ELEMENT Address (#PCDATA|Alt|Br)*>
    
    <!ELEMENT Cite EMPTY>
    <!ATTLIST Cite Key CDATA #REQUIRED
                   Where CDATA #IMPLIED>
                   
    <!ELEMENT Label EMPTY>
    <!ATTLIST Label Name CDATA #REQUIRED>
    
    <!ELEMENT Ref EMPTY>
    <!ATTLIST Ref Func      CDATA #IMPLIED
                  Oper      CDATA #IMPLIED
                  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 -->
    
    <!-- Note that  only one attribute  of Ref is used  normally. BookName
         and  Style  can  be  specified in  addition  to  handle  external
         references and the typesetting style of the reference. -->
    
    <!-- For explicit index entries (Func and so on should cause an
         automatically generated index entry). Use the attributes Key,
         Subkey for sorting (simplified, without markup). The Subkey value
         also gets printed. Use the optional Subkey element if the printed
         version needs some markup.                                        -->
    <!ELEMENT Index (%InnerText;|Subkey)*>
    <!ATTLIST Index Key    CDATA #IMPLIED
                    Subkey CDATA #IMPLIED>
    <!ELEMENT Subkey (%InnerText;)*>
    
    
    <!-- ==================================================================
         The following  describes the normal documentation  text which can
         occur  at various  places in  the document.  It does  not contain
         further sectioning elements. In addition to InnerText it can contain 
         environments like enumerations, lists, and such.
         ================================================================== -->
    
    <!ENTITY % Text "%InnerText; | List | Enum | Table">
    
    <!ELEMENT Item ( %Text;)*>
    <!ELEMENT Mark ( %InnerText;)*>
    
    <!ELEMENT List ( ((Mark,Item)|Item)+ )>
    <!ATTLIST List Only CDATA #IMPLIED
                   Not  CDATA #IMPLIED>
    <!ELEMENT Enum ( Item+ )>
    <!ATTLIST Enum Only CDATA #IMPLIED
                   Not  CDATA #IMPLIED>
    
    <!ELEMENT Table ( Caption?, (Row | HorLine)+ )>
    <!ATTLIST Table Label   CDATA #IMPLIED
                    Only    CDATA #IMPLIED
                    Not     CDATA #IMPLIED
                    Align   CDATA #REQUIRED>    <!-- A TeX tabular string -->
                    <!-- We allow | and l,c,r, nothing else -->
    <!ELEMENT Row   ( Item+ )>
    <!ELEMENT HorLine EMPTY>
    <!ELEMENT Caption ( %InnerText;)*>
    
    <!-- ==================================================================
         We start defining some things within the overall structure:
         ================================================================== -->
    
    <!-- The TitlePage consists of several sub-elements: -->
    
    <!ELEMENT TitlePage (Title, Subtitle?, Version?, TitleComment?, 
                         Author+, Date?, Address?, Abstract?, Copyright?, 
                         Acknowledgements? , Colophon? )>
    
    <!ELEMENT Title (%Text;)*>
    <!ELEMENT Subtitle (%Text;)*>
    <!ELEMENT Version (%Text;)*>
    <!ELEMENT TitleComment (%Text;)*>
    <!ELEMENT Author (%Text;)*>    <!-- There may be more than one Author! -->
    <!ELEMENT Date (%Text;)*>
    <!ELEMENT Abstract (%Text;)*>
    <!ELEMENT Copyright (%Text;)*>
    <!ELEMENT Acknowledgements (%Text;)*>  
    <!ELEMENT Colophon (%Text;)*>
    
    
    <!-- The following things just specify some information about the
         corresponding parts of the Book: -->
    
    <!ELEMENT TableOfContents EMPTY>
    <!ELEMENT Bibliography EMPTY>
    <!ATTLIST Bibliography Databases CDATA #REQUIRED
                           Style CDATA #IMPLIED>
    <!ELEMENT TheIndex EMPTY>
    
    <!-- ==================================================================
         The Ignore element can be used everywhere to include further
         information in a GAPDoc document which is not intended for the 
         standard converters (e.g., source code, not yet finished stuff,
         and so on. This information can be extracted by special converter 
         routines, more precise information about the content of an Ignore
         element can be given by the "Remark" attribute.
         ================================================================== -->
    
    <!ELEMENT Ignore (%Text;| Chapter | Section | Subsection | ManSection |
                      Heading)*>
    <!ATTLIST Ignore Remark CDATA #IMPLIED>
         
    <!-- ==================================================================
         Now we go on with the overall structure by defining the sectioning 
         structure, which includes the Synopsis element: 
         ================================================================== -->
    
    
    <!ELEMENT Subsection (%Text;| Heading)*>
    <!ATTLIST Subsection Label CDATA #IMPLIED> <!-- For reference purposes -->
    
    <!ELEMENT ManSection ( Heading?, 
                          ((Func, Returns?) | (Oper, Returns?) | 
                           (Meth, Returns?) | (Filt, Returns?) | 
                           (Prop, Returns?) | (Attr, Returns?) |
                           (Constr, Returns?) |
                           Var | Fam | InfoClass)+, Description )>
    <!ATTLIST ManSection Label CDATA #IMPLIED> <!-- For reference purposes -->
    
    <!ELEMENT Returns (%Text;)*>
    <!ELEMENT Description (%Text;)*>
    
    
    <!-- Note that  the ManSection element  is actually a  subsection with
         respect  to labelling,  referencing, and  counting of  sectioning
         elements. -->
    
    <!ELEMENT Func EMPTY>
    <!ATTLIST Func Name  CDATA #REQUIRED
                   Label CDATA #IMPLIED
                   Arg   CDATA #REQUIRED
                   Comm  CDATA #IMPLIED>
    
    <!-- Note  that Arg  contains the  full list  of arguments,  including
         optional  parts,  which  are   denoted  by  square  brackets  [].
         Arguments   are  separated   by  whitespace,   commas  count   as
         whitespace. -->
    
    <!-- Note further that although Name and Label are  CDATA (and not ID)
         Label must make up a unique identifier. -->
    
    <!ELEMENT Oper EMPTY>
    <!ATTLIST Oper Name  CDATA #REQUIRED
                   Label CDATA #IMPLIED
                   Arg   CDATA #REQUIRED
                   Comm  CDATA #IMPLIED>
    
    <!ELEMENT Constr EMPTY>
    <!ATTLIST Constr Name  CDATA #REQUIRED
                     Label CDATA #IMPLIED
                     Arg   CDATA #REQUIRED
                     Comm  CDATA #IMPLIED>
    
    <!ELEMENT Meth EMPTY>
    <!ATTLIST Meth Name  CDATA #REQUIRED
                   Label CDATA #IMPLIED
                   Arg   CDATA #REQUIRED
                   Comm  CDATA #IMPLIED>
    
    <!ELEMENT Filt EMPTY>
    <!ATTLIST Filt Name  CDATA #REQUIRED
                   Label CDATA #IMPLIED
                   Arg   CDATA #IMPLIED
                   Comm  CDATA #IMPLIED
                   Type  CDATA #IMPLIED>  
    
    <!ELEMENT Prop EMPTY>
    <!ATTLIST Prop Name  CDATA #REQUIRED
                   Label CDATA #IMPLIED
                   Arg   CDATA #REQUIRED
                   Comm  CDATA #IMPLIED>
    
    <!ELEMENT Attr EMPTY>
    <!ATTLIST Attr Name  CDATA #REQUIRED
                   Label CDATA #IMPLIED
                   Arg   CDATA #REQUIRED
                   Comm  CDATA #IMPLIED>
    
    <!ELEMENT Var  EMPTY>
    <!ATTLIST Var  Name  CDATA #REQUIRED
                   Label CDATA #IMPLIED
                   Comm  CDATA #IMPLIED>
    
    <!ELEMENT Fam  EMPTY>
    <!ATTLIST Fam  Name  CDATA #REQUIRED
                   Label CDATA #IMPLIED
                   Comm  CDATA #IMPLIED>
    
    <!ELEMENT InfoClass EMPTY>
    <!ATTLIST InfoClass Name  CDATA #REQUIRED
                        Label CDATA #IMPLIED
                        Comm  CDATA #IMPLIED>
    
    
    <!ELEMENT Heading (%InnerText;)*>
    
    <!ELEMENT Section (%Text;| Heading | Subsection | ManSection)*>
    <!ATTLIST Section Label CDATA #IMPLIED>    <!-- For reference purposes -->
    
    
    <!ELEMENT Chapter (%Text;| Heading | Section)*>
    <!ATTLIST Chapter Label CDATA #IMPLIED>    <!-- For reference purposes -->
    
    
    <!-- Note that  the entity %InnerText; is  documentation that contains
         neither sectioning  elements nor environments  like enumerations,
         but  only  formulae,  labels, references,  citations,  and  other
         terminal elements. -->
    
    <!ELEMENT Appendix (%Text;| Heading | Section)*>
    <!ATTLIST Appendix Label CDATA #IMPLIED>   <!-- For reference purposes -->
    
    <!-- Note that  an Appendix  is exactly  the same  as a  Chapter. They
         differ only in the numbering. -->
    
    <!-- ==================================================================
         At last we define the overall structure of a gapdoc Book:
         ================================================================== -->
    
    <!ELEMENT Body  ( %Text;| Chapter | Section )*>
    
    <!ELEMENT Book (TitlePage,
                    TableOfContents?,
                    Body,
                    Appendix*,
                    Bibliography?,
                    TheIndex?)>
    <!ATTLIST Book Name CDATA #REQUIRED>
                   
    <!-- Note  that  the  entity  %Text; is  documentation  that  contains
         no  further sectioning  elements but  possibly environments  like
         enumerations,  and formulae,  labels, references,  and citations.
         -->
    
    <!-- ============================================================== -->