[1X3 The Document Type Definition[0X In this chapter we first explain what a "document type definition" is and then describe [11Xgapdoc.dtd[0m in detail. That file together with the current chapter define how a [5XGAPDoc[0m document has to look like. It can be found in the main directory of the [5XGAPDoc[0m package and it is reproduced in Appendix [14XB[0m. We do not give many examples in this chapter which is more intended as a formal reference for all [5XGAPDoc[0m elements. Instead we provide an extra document with book name [10XGAPDocExample[0m (also accessible from the [5XGAP[0m 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[0m. [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[0m. 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[0m 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[0m 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[0m. For precise descriptions of the syntax of DTD's see again the official standard in:   [7Xhttp://www.xml.com/axml/axml.html[0m [1X3.2 Overall Document Structure[0X A [5XGAPDoc[0m document contains on its top level exactly one element with name [10XBook[0m. This element is declared in the DTD as follows: [1X3.2-1 [10X<Book>[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[0m and the name [10XBook[0m 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[0m element. Each name in such a list can be followed by one of the characters "[10X?[0m", "[10X*[0m" or "[10X+[0m", 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|[0m" characters, this denotes any element with one of the names (i.e., "[10X|[0m" means "or"). So, the [10XBook[0m element must contain first a [10XTitlePage[0m element, then an optional [10XTableOfContents[0m element, then a [10XBody[0m element, then zero or more elements of type [10XAppendix[0m, then an optional [10XBibliography[0m element, and finally an optional element of type [10XTheIndex[0m. Note that [13Xonly[0m these elements are allowed in the content of the [10XBook[0m 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[0m and the element name [10XBook[0m. 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[0m) is the name of an attribute for a [10XBook[0m element. The second ([10XCDATA[0m) 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[0m means that this attribute must be specified with any [10XBook[0m element. Later we will also see optional attributes which are declared as [10X#IMPLIED[0m. [1X3.2-2 [10X<TitlePage>[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[0m element we explain the elements for the title page. [1X3.2-3 [10X<Title>[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[0m. The expression "[10X%Text;[0m" 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;[0m" 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[0m the keyword [10X#PCDATA[0m (concatenated with the "or" character "[10X|[0m"). So, the element ([10XTitle[0m) is of so-called "mixed content": It can contain [13Xparsed character data[0m which does not contain further markup ([10X#PCDATA[0m) or any of the other above mentioned elements. Mixed content must always have the asterisk qualifier (like in [10XTitle[0m) such that any sequence of elements (of the above list) and character data can be contained in a [10XTitle[0m element. The [10X%Text;[0m parameter entity is used in all places in the DTD, where "normal text" should be allowed, including lists, enumerations, and tables, but [13Xno[0m sectioning elements. The [10X%InnerText;[0m 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>[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>[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[0m, which is necessary to resolve the entities described in [14X2.2-3[0m). The converters will [13Xnot[0m put the word "Version" in front of the text in this element. [1X3.2-6 [10X<TitleComment>[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[0m element (see [14X3.2-10[0m) for longer explanations. [1X3.2-7 [10X<Author>[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 element should contain the name of an author and probably an [10XEmail[0m-address and/or WWW-[10XHomepage[0m element for this author, see [14X3.5-6[0m and [14X3.5-7[0m. You can also specify an individual postal address here, instead of using the [10XAddress[0m element described below, see [14X3.2-9[0m. [1X3.2-8 [10X<Date>[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>[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[0m elements inside the [10XAuthor[0m elements. Use the [10XBr[0m element (see [14X3.9-3[0m) 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>[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>[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©right;[0m entity as described in section [14X2.2-3[0m. [1X3.2-12 [10X<Acknowledgements>[1X[0X [4X----------------------- From gapdoc.dtd ------------------------[0X [4X<!ELEMENT Acknowledgements (%Text;)*>[0X [4X------------------------------------------------------------------[0X This element contains the acknowledgements. [1X3.2-13 [10X<Colophon>[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>[1X[0X [4X----------------------- From gapdoc.dtd ------------------------[0X [4X<!ELEMENT TableOfContents EMPTY>[0X [4X------------------------------------------------------------------[0X This element may occur in the [10XBook[0m element after the [10XTitlePage[0m 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[0m one can use the abbreviation [4X--------------------------- Example ----------------------------[0X [4X<TableOfContents/>[0X [4X------------------------------------------------------------------[0X to denote this empty element. [1X3.2-15 [10X<Bibliography>[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[0m element after the last [10XAppendix[0m element. If it is present, a bibliography section is generated and inserted into the document. The attribute [10XDatabases[0m must be specified, the names of several data files can be specified, separated by commas. Two kinds of files can be specified in [10XDatabases[0m: The first are BibTeX files as defined in [Lam85, Appendix B]. Such files must have a name with extension [11X.bib[0m, and in [10XDatabases[0m the name must be given [13Xwithout[0m this extension. The second are files in BibXMLext format as defined in Section [14X7.2[0m. These files must have an extension [11X.xml[0m and in [10XDatabases[0m the [13Xfull[0m 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[0m attribute. The optional [10XStyle[0m attribute (for LaTeX output of the document) must also be specified without the [11X.bst[0m extension (the default is [10Xalpha[0m). See also section [14X3.5-3[0m for a description of the [10XCite[0m element which is used to include bibliography references into the text. [1X3.2-16 [10X<TheIndex>[1X[0X [4X----------------------- From gapdoc.dtd ------------------------[0X [4X<!ELEMENT TheIndex EMPTY>[0X [4X------------------------------------------------------------------[0X This element may occur in the [10XBook[0m element after the [10XBibliography[0m element. If it is present, an index is generated and inserted into the document. There are elements in [5XGAPDoc[0m which implicitly generate index entries (e.g., [10XFunc[0m ([14X3.4-2[0m)) and there is an element [10XIndex[0m ([14X3.5-4[0m) for explicitly adding index entries. [1X3.3 Sectioning Elements[0X A [5XGAPDoc[0m book is divided into [13Xchapters[0m, [13Xsections[0m, and [13Xsubsections[0m. 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[0m are a flavor of chapters, occurring after all regular chapters. There is a special type of subsection called "[10XManSection[0m". 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[0m. Cross referencing is done on the level of [10XSubsection[0ms, respectively [10XManSection[0ms. The topics in [5XGAP[0m'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>[1X[0X The [10XBody[0m element marks the main part of the document. It must occur after the [10XTableOfContents[0m element. There is a big difference between [13Xinside[0m and [13Xoutside[0m of this element: Whereas regular text is allowed nearly everywhere in the [10XBody[0m element and its subelements, this is not true for the [13Xoutside[0m. This has also implications on the handling of whitespace. [13XOutside[0m superfluous whitespace is usually ignored when it occurs between elements. [13XInside[0m of the [10XBody[0m 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[0m and [10XSection[0m elements are allowed here leads to the possibility to omit the chapter level entirely in the document. For a description of [10X%Text;[0m see [14X3.2-3[0m. (Remark: The purpose of this element is to make sure that a [13Xvalid[0m [5XGAPDoc[0m document has a correct overall structure, which is only possible when the top element [10XBook[0m has element content.) [1X3.3-2 [10X<Chapter>[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[0m element can have a [10XLabel[0m attribute, such that this chapter can be referenced later on with a [10XRef[0m element (see section [14X3.5-1[0m). Note that you have to specify a label to reference the chapter as there is no automatic labelling! [10XChapter[0m elements can contain text (for a description of [10X%Text;[0m see [14X3.2-3[0m), [10XSection[0m elements, and [10XHeading[0m elements. The following [13Xadditional[0m rule cannot be stated in the DTD because we want a [10XChapter[0m element to have mixed content. There must be [13Xexactly one[0m [10XHeading[0m element in the [10XChapter[0m element, containing the heading of the chapter. Here is its definition: [1X3.3-3 [10X<Heading>[1X[0X [4X----------------------- From gapdoc.dtd ------------------------[0X [4X<!ELEMENT Heading (%InnerText;)*>[0X [4X------------------------------------------------------------------[0X This element is used for headings in [10XChapter[0m, [10XSection[0m, [10XSubsection[0m, and [10XAppendix[0m elements. It may only contain [10X%InnerText;[0m (for a description see [14X3.2-3[0m). Each of the mentioned sectioning elements must contain exactly one direct [10XHeading[0m element (i.e., one which is not contained in another sectioning element). [1X3.3-4 [10X<Appendix>[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[0m element behaves exactly like a [10XChapter[0m element (see [14X3.3-2[0m) 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[0m attribute used for references. [1X3.3-5 [10X<Section>[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[0m element can have a [10XLabel[0m attribute, such that this section can be referenced later on with a [10XRef[0m element (see section [14X3.5-1[0m). Note that you have to specify a label to reference the section as there is no automatic labelling! [10XSection[0m elements can contain text (for a description of [10X%Text;[0m see [14X3.2-3[0m), [10XHeading[0m elements, and subsections. There must be exactly one direct [10XHeading[0m element in a [10XSection[0m element, containing the heading of the section. Note that a subsection is either a [10XSubsection[0m element or a [10XManSection[0m element. [1X3.3-6 [10X<Subsection>[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[0m element can have a [10XLabel[0m attribute, such that this subsection can be referenced later on with a [10XRef[0m element (see section [14X3.5-1[0m). Note that you have to specify a label to reference the subsection as there is no automatic labelling! [10XSubsection[0m elements can contain text (for a description of [10X%Text;[0m see [14X3.2-3[0m), and [10XHeading[0m elements. There must be exactly one [10XHeading[0m element in a [10XSubsection[0m element, containing the heading of the subsection. Another type of subsection is a [10XManSection[0m, explained now: [1X3.4 ManSectionâa special kind of subsection[0X [10XManSection[0ms 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>[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[0m element can have a [10XLabel[0m attribute, such that this subsection can be referenced later on with a [10XRef[0m element (see section [14X3.5-1[0m). But this is probably rarely necessary because the elements [10XFunc[0m and so on (explained below) generate automatically labels for cross referencing. The content of a [10XManSection[0m element is one or more elements describing certain items in [5XGAP[0m, each of them optionally followed by a [10XReturns[0m element, followed by a [10XDescription[0m element, which contains [10X%Text;[0m (see [14X3.2-3[0m) describing it. (Remember to include examples in the description as often as possible, see [14X3.7-10[0m). The classes of items [5XGAPDoc[0m knows of are: functions ([10XFunc[0m), operations ([10XOper[0m), methods ([10XMeth[0m), filters ([10XFilt[0m), properties ([10XProp[0m), attributes ([10XAttr[0m), variables ([10XVar[0m), families ([10XFam[0m), and info classes ([10XInfoClass[0m). One [10XManSection[0m should only describe several of such items when these are very closely related. Each element for an item corresponding to a [5XGAP[0m function can be followed by a [10XReturns[0m element. In output versions of the document the string "Returns: " will be put in front of the content text. The text in the [10XReturns[0m 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[0ms are also sectioning elements which count as subsections. Usually there should be no [10XHeading[0m-element in a [10XManSection[0m, in that case a heading is generated automatically from the first [10XFunc[0m-like element. Sometimes this default behaviour does not look appropriate, for example when there are several [10XFunc[0m-like elements. For such cases an optional [10XHeading[0m is allowed. [1X3.4-2 [10X<Func>[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[0m element to specify the usage of a function. The [10XName[0m attribute is required and its value is the name of the function. The value of the [10XArg[0m 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]"[0m or [10X"xx[y[z] ]"[0m. 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[0m be written with the [10XRef[0m element, see [14X3.5-1[0m. This allows to use a unique typesetting style for function names and automatic cross referencing. If the optional [10XLabel[0m attribute is given, it is appended (with a colon [10X:[0m 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[0m attribute should be a short description of the function, usually at most one line long (this is currently nowhere used). This element automatically produces an index entry with the name of the function and, if present, the text of the [10XLabel[0m attribute as subentry (see also [14X3.2-16[0m and [14X3.5-4[0m). [1X3.4-3 [10X<Oper>[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[0m element to specify the usage of an operation. The attributes are used exactly in the same way as in the [10XFunc[0m element (see [14X3.4-2[0m). Note that multiple descriptions of the same operation may occur in a document because there may be several declarations in [5XGAP[0m. Furthermore there may be several [10XManSection[0ms for methods of this operation (see [14X3.4-4[0m) which also use the same name. For reference purposes these must be distinguished by different [10XLabel[0m attributes. [1X3.4-4 [10X<Meth>[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[0m element to specify the usage of a method. The attributes are used exactly in the same way as in the [10XFunc[0m element (see [14X3.4-2[0m). 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[0ms. It is however required that these subsections and those describing the corresponding operation are distinguished by different [10XLabel[0m attributes. [1X3.4-5 [10X<Filt>[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[0m element to specify the usage of a filter. The first four attributes are used in the same way as in the [10XFunc[0m element (see [14X3.4-2[0m), except that the [10XArg[0m attribute is optional. The [10XType[0m attribute can be any string, but it is thought to be something like "[10XCategory[0m" or "[10XRepresentation[0m". [1X3.4-6 [10X<Prop>[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[0m element to specify the usage of a property. The attributes are used exactly in the same way as in the [10XFunc[0m element (see [14X3.4-2[0m). [1X3.4-7 [10X<Attr>[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[0m element to specify the usage of an attribute (in [5XGAP[0m). The attributes are used exactly in the same way as in the [10XFunc[0m element (see [14X3.4-2[0m). [1X3.4-8 [10X<Var>[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[0m element to document a global variable. The attributes are used exactly in the same way as in the [10XFunc[0m element (see [14X3.4-2[0m) except that there is no [10XArg[0m attribute. [1X3.4-9 [10X<Fam>[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[0m element to document a family. The attributes are used exactly in the same way as in the [10XFunc[0m element (see [14X3.4-2[0m) except that there is no [10XArg[0m attribute. [1X3.4-10 [10X<InfoClass>[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[0m element to document an info class. The attributes are used exactly in the same way as in the [10XFunc[0m element (see [14X3.4-2[0m) except that there is no [10XArg[0m attribute. [1X3.5 Cross Referencing and Citations[0X Cross referencing in the [5XGAPDoc[0m 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[0m element: [1X3.5-1 [10X<Ref>[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[0m element is defined to be [10XEMPTY[0m. If one of the attributes [10XFunc[0m, [10XOper[0m, [10XMeth[0m, [10XProp[0m, [10XAttr[0m, [10XVar[0m, [10XFam[0m, [10XInfoClass[0m, [10XChap[0m, [10XSect[0m, [10XSubsect[0m, [10XAppendix[0m is given then there must be exactly one of these, making the reference one to the corresponding object. The [10XLabel[0m 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[0m element defined below (see [14X3.5-2[0m) is done by giving the [10XLabel[0m attribute and optionally the [10XText[0m attribute. If the [10XText[0m attribute is present its value is typeset in place of the [10XRef[0m 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[0m). An external reference into another book can be specified by using the [10XBookName[0m attribute. In this case the [10XLabel[0m 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[0m. The optional attribute [10XStyle[0m can take only the values [10XText[0m and [10XNumber[0m. 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[0m object generate the name of the corresponding object with some additional link or sectioning information, which is the behavior of [10XStyle="Text"[0m. In case [10XStyle="Number"[0m 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>[0m[14X'[0m described in section [14X3.4-2[0m. [1X3.5-2 [10X<Label>[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[0m attribute must be unique under all [10XLabel[0m elements. [1X3.5-3 [10X<Cite>[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[0m by definition. The attribute [10XKey[0m is the key for a lookup in a BibTeX database that has to be specified in the [10XBibliography[0m element (see [14X3.2-15[0m). The value of the [10XWhere[0m attribute specifies the position in the document as in the corresponding LaTeX syntax [10X\cite[Where value]{Key value}[0m. [1X3.5-4 [10X<Index>[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[0m and [10XSubkey[0m 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[0m element, in this case the attribute value is used for sorting but the typeset text is taken from the content of [10XSubkey[0m. Note that all [10XFunc[0m and similar elements automatically generate index entries. If the [10XTheIndex[0m element ([14X3.2-16[0m) is not present in the document all [10XIndex[0m elements are ignored. [1X3.5-5 [10X<URL>[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[0m attribute (in this case the text cannot contain further markup), or the element contains the two elements [10XLink[0m and [10XLinkText[0m 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>[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:[0m". 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:[0m" prefix. [1X3.5-7 [10X<Homepage>[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[0m 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>[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[0m element. Every [10XItem[0m element is optionally preceded by a [10XMark[0m 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[0m and [10XNot[0m attributes can be used to specify, that the list is included into the output by only one type of converter ([10XOnly[0m) or all but one type of converter ([10XNot[0m). Of course at most one of the two attributes may occur in one element. The following values are allowed as of now: "[10XLaTeX[0m", "[10XHTML[0m", and "[10XText[0m". See also the [10XAlt[0m element in [14X3.9-1[0m for more about text alternatives for certain converters. [1X3.6-2 [10X<Mark>[1X[0X [4X----------------------- From gapdoc.dtd ------------------------[0X [4X<!ELEMENT Mark ( %InnerText;)*>[0X [4X------------------------------------------------------------------[0X This element is used in the [10XList[0m element to mark items. See [14X3.6-1[0m for an explanation. [1X3.6-3 [10X<Item>[1X[0X [4X----------------------- From gapdoc.dtd ------------------------[0X [4X<!ELEMENT Item ( %Text;)*>[0X [4X------------------------------------------------------------------[0X This element is used in the [10XList[0m, [10XEnum[0m, and [10XTable[0m elements to specify the items. See sections [14X3.6-1[0m, [14X3.6-4[0m, and [14X3.6-5[0m for further information. [1X3.6-4 [10X<Enum>[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 like the [10XList[0m element (see [14X3.6-1[0m) except that the items must not have marks attached to them. Instead, the items are numbered automatically. The same comments about the [10XOnly[0m and [10XNot[0m attributes as above apply. [1X3.6-5 [10X<Table>[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[0m consists of an optional [10XCaption[0m element followed by a sequence of [10XRow[0m and [10XHorLine[0m elements. A [10XHorLine[0m element produces a horizontal line in the table. A [10XRow[0m element consists of a sequence of [10XItem[0m elements as they also occur in [10XList[0m and [10XEnum[0m elements. The [10XOnly[0m and [10XNot[0m attributes have the same functionality as described in the [10XList[0m element in [14X3.6-1[0m. The [10XAlign[0m attribute is written like a LaTeX tabular alignment specifier but only the letters "[10Xl[0m", "[10Xr[0m", "[10Xc[0m", and "[10X|[0m" are allowed meaning left alignment, right alignment, centered alignment, and a vertical line as delimiter between columns respectively. If the [10XLabel[0m attribute is there, one can reference the table with the [10XRef[0m element (see [14X3.5-1[0m) using its [10XLabel[0m 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|[0m" column separators and [10XHorLine[0m 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[0m 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[0m elements to resolve the entities described in section [14X2.2-3[0m. [1X3.7-1 [10X<Emph>[1X and [10X<E>[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;[0m (see [14X3.2-3[0m). [1X3.7-2 [10X<Quoted>[1X and [10X<Q>[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;[0m (see [14X3.2-3[0m). [1X3.7-3 [10X<Keyword>[1X and [10X<K>[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[0m. Usually this will be a [5XGAP[0m keyword such as "[9Xif[0m" or "[9Xfor[0m". No further markup elements are allowed within this element except for the [10XAlt[0m element, which is necessary. [1X3.7-4 [10X<Arg>[1X and [10X<A>[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[0ms in [10XManSection[0ms to mark something as an [13Xargument[0m (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>[1X and [10X<C>[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[0m like for example a [5XGAP[0m expression. It is guaranteed that the converters typeset this exactly as in the [10XListing[0m element (compare section [14X3.7-9[0m. No further markup elements are allowed within this element. [1X3.7-6 [10X<File>[1X and [10X<F>[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[0m or a [13Xpathname[0m in the file system. No further markup elements are allowed within this element. [1X3.7-7 [10X<Button>[1X and [10X<B>[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[0m. It can also be used for other items in a graphical user interface like [13Xmenus[0m, [13Xmenu entries[0m, or [13Xkeys[0m. No further markup elements are allowed within this element. [1X3.7-8 [10X<Package>[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[0m. This is for example used to define the entities [5XGAP[0m, [5XXGAP[0m or [5XGAPDoc[0m (see section [14X2.2-3[0m). No further markup elements are allowed within this element. [1X3.7-9 [10X<Listing>[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[0m use the character entities described in section [14X2.2-3[0m but instead type the characters directly. Only the general XML rules from section [14X2.1[0m apply. Note especially the usage of [10X<![CDATA[[0m sections described there. It is guaranteed that all converters use a fixed width font for typesetting [10XListing[0m elements. Compare also the usage of the [10XCode[0m and [10XC[0m elements in [14X3.7-5[0m. The [10XType[0m attribute contains a comment about the type of listed code. It may appear in the output. [1X3.7-10 [10X<Log>[1X and [10X<Example>[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[0m element (see [14X3.7-9[0m). They are thought for protocols of [5XGAP[0m sessions. The only difference between the two is that [10XExample[0m sections are intended to be subject to an automatic manual checking mechanism used to ensure the correctness of the [5XGAP[0m manual whereas [10XLog[0m is not touched by this. [1X3.7-11 [10X<Verb>[1X[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[0m element to specify pre-formatted ASCII alternatives for complicated [10XDisplay[0m formulae or [10XTable[0ms. [1X3.8 Elements for Mathematical Formulae[0X [1X3.8-1 [10X<Math>[1X and [10X<Display>[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[0m they correspond to LaTeX's math and display math mode respectively. The formulae are typed in as in LaTeX, [13Xexcept[0m that the standard XML entities, see [14X2.1-9[0m (in particular the characters [10X<[0m and [10X&[0m), must be escaped - either by using the corresponding entities or by enclosing the formula between "[10X<![CDATA[[0m" and "[10X]]>[0m". (The main reference for LaTeX is [Lam85].) It is also possible to use some unicode characters for mathematical symbols directly, provided that it can be translated by [2XEncode[0m ([14X6.2-2[0m) into [10X"LaTeX"[0m encoding and that [2XSimplifiedUnicodeString[0m ([14X6.2-2[0m) with arguments [10X"latin1"[0m and [10X"single"[0m returns something sensible. Currently, we support entities [10X&CC;[0m, [10X&ZZ;[0m, [10X&NN;[0m, [10X&PP;[0m, [10X&QQ;[0m, [10X&HH;[0m, [10X&RR;[0m for the corresponding black board bold letters â, â¤, â,â, â, â and â, respectively. The only element type that is allowed within the formula elements is the [10XArg[0m or [10XA[0m element (see [14X3.7-4[0m), which is used to typeset identifiers that are arguments to [5XGAP[0m 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[0m (see [14X3.8-2[0m) 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[0m and [10XDisplay[0m elements or provide useful text substitutes for complicated formulae via [10XAlt[0m elements (see [14X3.9-1[0m and [14X3.7-11[0m). [1X3.8-2 [10X<M>[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[0m" 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[0m document the [10XM[0m and [10XMath[0m elements are equivalent. The remarks in [14X3.8-1[0m about special characters and the [10XArg[0m element apply here as well. A document which has all formulae enclosed in [10XM[0m 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*[0m | ---------------------------------- | \bf | [10X[0m | ---------------------------------- | \bmod | [10Xmod[0m | ---------------------------------- | \cdot | [10X*[0m | ---------------------------------- | \colon | [10X:[0m | ---------------------------------- | \equiv | [10X=[0m | ---------------------------------- | \geq | [10X>=[0m | ---------------------------------- | \germ | [10X[0m | ---------------------------------- | \hookrightarrow | [10X->[0m | ---------------------------------- | \iff | [10X<=>[0m | ---------------------------------- | \langle | [10X<[0m | ---------------------------------- | \ldots | [10X...[0m | ---------------------------------- | \left | [10X [0m | ---------------------------------- | \leq | [10X<=[0m | ---------------------------------- | \leftarrow | [10X<-[0m | ---------------------------------- | \Leftarrow | [10X<=[0m | ---------------------------------- | \limits | [10X [0m | ---------------------------------- | \longrightarrow | [10X-->[0m | ---------------------------------- | \Longrightarrow | [10X==>[0m | ---------------------------------- | \mapsto | [10X->[0m | ---------------------------------- | \mathbb | [10X [0m | ---------------------------------- | \mathop | [10X [0m | ---------------------------------- | \mid | [10X|[0m | ---------------------------------- | \pmod | [10Xmod[0m | ---------------------------------- | \prime | [10X'[0m | ---------------------------------- | \rangle | [10X>[0m | ---------------------------------- | \right | [10X [0m | ---------------------------------- | \rightarrow | [10X->[0m | ---------------------------------- | \Rightarrow | [10X=>[0m | ---------------------------------- | \rm, \sf, \textrm, \text | [10X[0m | ---------------------------------- | \setminus | [10X\[0m | ---------------------------------- | \thinspace | [10X [0m | ---------------------------------- | \times | [10Xx[0m | ---------------------------------- | \to | [10X->[0m | ---------------------------------- | \vert | [10X|[0m | ---------------------------------- | \! | [10X[0m | ---------------------------------- | \, | [10X[0m | ---------------------------------- | \; | [10X [0m | ---------------------------------- | \{ | [10X{[0m | ---------------------------------- | \} | [10X}[0m | ---------------------------------- [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{}[0m 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>[0m for [10Xx^12[0m and [10X<M>x_{{i+1}}</M>[0m for [10Xx_{i+1}[0m. [1X3.9 Everything else[0X [1X3.9-1 [10X<Alt>[1X[0X This element is used to specify alternatives for different output formats within normal text. See also sections [14X3.6-1[0m, [14X3.6-4[0m, and [14X3.6-5[0m 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[0m are: "[10XLaTeX[0m", "[10XHTML[0m", and "[10XText[0m". If the [10XOnly[0m attribute is specified then only the corresponding converter will include the content of the element into the output document. If the [10XNot[0m 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[0m documents. We fix a rule for handling the content of an [10XAlt[0m element with [10XOnly[0m 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;[0m (see [14X3.2-3[0m) 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>[1X and [10X<P>[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[0m 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[0m 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[0m or [10XPar[0m elements as above delegates this pain to the writer of a conversion program for [5XGAPDoc[0m documents.) [1X3.9-3 [10X<Br>[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[0m element, it does not start a new paragraph. Please, do not use this instead of a [10XPar[0m element, this would often lead to ugly output versions of your document. [1X3.9-4 [10X<Ignore>[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[0m 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[0m elements. Information on the type of the content can be stored in the optional attribute [10XRemark[0m.