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

<!-- ============================================================== -->