3. The Document Type Definition

In this chapter we first explain what a "document type definition" is and then describe gapdoc.dtd in detail. That file together with the current chapter define how a GAPDoc document has to look like. It can be found in the main directory of the GAPDoc package and it is reproduced in Appendix B..

We do not give many examples in this chapter which is more intended as a formal reference for all GAPDoc elements. Instead we provide an extra document with book name GAPDocExample (also accessible from the GAP 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 1..

3.1 What is a DTD?

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

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 not 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 GAPDoc 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 gapdoc.dtd. For precise descriptions of the syntax of DTD's see again the official standard in:

  http://www.xml.com/axml/axml.html

3.2 Overall Document Structure

A GAPDoc document contains on its top level exactly one element with name Book. This element is declared in the DTD as follows:

3.2-1

<!ELEMENT Book (TitlePage,
                TableOfContents?,
                Body,
                Appendix*,
                Bibliography?,
                TheIndex?)>
<!ATTLIST Book Name CDATA #REQUIRED>

After the keyword ELEMENT and the name Book 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 Book element. Each name in such a list can be followed by one of the characters "?", "*" or "+", 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 "|" characters, this denotes any element with one of the names (i.e., "|" means "or").

So, the Book element must contain first a TitlePage element, then an optional TableOfContents element, then a Body element, then zero or more elements of type Appendix, then an optional Bibliography element, and finally an optional element of type TheIndex.

Note that only these elements are allowed in the content of the Book 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 ATTLIST and the element name Book. 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 (Name) is the name of an attribute for a Book element. The second (CDATA) is always the same for all of our declarations, it means that the value of the attribute consists of "character data". The third parameter #REQUIRED means that this attribute must be specified with any Book element. Later we will also see optional attributes which are declared as #IMPLIED.

3.2-2

<!ELEMENT TitlePage (Title, Subtitle?, Version?, Author+, Date?, Abstract?,
                     Copyright? , Acknowledgements? , Colophon? )>

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 Book element we explain the elements for the title page.

3.2-3