438 lines
17 KiB
XML
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 "&#60;">
|
|
<!ENTITY gt ">">
|
|
<!ENTITY amp "&#38;">
|
|
<!ENTITY apos "'">
|
|
<!ENTITY quot """>
|
|
|
|
|
|
<!-- 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 "&">
|
|
<!ENTITY tlt "<">
|
|
<!ENTITY tgt ">">
|
|
<!ENTITY hash "#">
|
|
<!ENTITY dollar "$">
|
|
<!ENTITY percent "%">
|
|
<!ENTITY tilde "~">
|
|
<!ENTITY bslash "\\">
|
|
<!ENTITY obrace "{">
|
|
<!ENTITY cbrace "}">
|
|
<!ENTITY uscore "_">
|
|
<!ENTITY circum "^">
|
|
|
|
<!-- ==================================================================
|
|
Our predefined entities:
|
|
================================================================== -->
|
|
|
|
<!ENTITY nbsp " ">
|
|
<!ENTITY ndash "–">
|
|
<!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 "©">
|
|
|
|
<!-- and unicode math symbols -->
|
|
<!ENTITY CC "ℂ" > <!-- double struck -->
|
|
<!ENTITY ZZ "ℤ" >
|
|
<!ENTITY NN "ℕ" >
|
|
<!ENTITY PP "ℙ" >
|
|
<!ENTITY QQ "ℚ" >
|
|
<!ENTITY HH "ℍ" >
|
|
<!ENTITY RR "ℝ" >
|
|
|
|
|
|
<!-- ==================================================================
|
|
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.
|
|
-->
|
|
|
|
<!-- ============================================================== -->
|