loops/doc/gapdoc.dtd
2017-10-16 21:43:09 +02:00

438 lines
17 KiB
XML

<?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
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 BigMark ( %InnerText;)*>
<!ELEMENT List ( ((Mark,Item)|(BigMark,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?) |
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 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.
-->
<!-- ============================================================== -->