In this chapter we give a more formal description of what you need to start to type documentation in GAPDoc XML format. Many details were already explained by example in Section 1.2 of the introduction.
We do not answer the question "How to write a GAPDoc document?" in this chapter. You can (hopefully) find an answer to this question by studying the example in the introduction, see 1.2, and learning about more details in the reference Chapter 3..
The definite source for all details of the official XML standard with useful annotations is:
http://www.xml.com/axml/axml.html
Although this document must be quite technical, it is surprisingly well readable.
We will now discuss the pieces of text which can occur in a general XML document. We start with those pieces which do not contribute to the actual content of the document.
Each XML document should have a head which states that it is an XML document in some encoding and which XML-defined language is used. In case of a GAPDoc document this should always look as in the following example.
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE Book SYSTEM "gapdoc.dtd"> |
See 2.1-12 for a remark on the "encoding" statement.
(There may be local entity definitions inside the DOCTYPE
statement, see Subsection 2.2-3 below.)
A "comment" in XML starts with the character sequence "<!--
" and ends with the sequence "-->
". Between these sequences there must not be two adjacent dashes "--
".
A "processing instruction" in XML starts with the character sequence "<?
" followed by a name ("xml
" is only allowed at the very beginning of the document to declare it being an XML document, see 2.1-1). After that any characters may follow, except that the ending sequence "?>
" must not occur within the processing instruction.
And now we turn to those parts of the document which contribute to its actual content.
A "name" in XML (used for element and attribute identifiers, see below) must start with a letter (in the encoding of the document) or with a colon ":
" or underscore "_
" character. The following characters may also be digits, dots ".
" or dashes "-
".
This is a simplified description of the rules in the standard, which are concerned with lots of unicode ranges to specify what a "letter" is.
Sequences only consisting of the following characters are considered as whitespace: blanks, tabs, carriage return characters and new line characters.
The actual content of an XML document consists of "elements". An element has some "content" with a leading "start tag" (2.1-6) and a trailing "end tag" (2.1-7). The content can contain further elements but they must be properly nested. One can define elements whose content is always empty, those elements can also be entered with a single combined tag (2.1-8).
A "start-tag" consists of a less-than-character "<
" directly followed (without whitespace) by an element name (see 2.1-4), optional attributes, optional whitespace, and a greater-than-character ">
".
An "attribute" consists of some whitespace and then its name followed by an equal sign "=
" which is optionally enclosed by whitespace, and the attribute value, which is enclosed either in single or double quotes. The attribute value may not contain the type of quote used as a delimiter or the characters "<
" and "&
".
Note especially that no whitespace is allowed between the starting "<
" character and the element name. The quotes around an attribute value cannot be omitted. The names of elements and attributes are case sensitive.
An "end tag" consists of the two characters "</
" directly followed by the element name, optional whitespace and a greater-than-character ">
".
Elements which always have empty content can be written with a single tag. This looks like a start tag (see 2.1-6) except that the trailing greater-than-character ">
" is substituted by the two character sequence "/>
".
An "entity" in XML is a macro for some substitution text. There are two types of entities.
A "character entity" can be used to specify characters in the encoding of the document (can be useful for entering non-ASCII characters which you cannot manage to type in directly). They are entered with a sequence "&#
", directly followed by either some decimal digits or an "x
" and some hexadecimal digits, directly followed by a semicolon ";
". Using such a character entity is just equivalent to typing the corresponding character directly.
Then there are references to "named entities". They are entered with an ampersand character "&
" directly followed by a name which is directly followed by a semicolon ";
". Such entities must be declared somewhere by giving a substitution text. This text is included in the document and the document is parsed again afterwards. The exact rules are a bit subtle but you probably want to use this only in simple cases. Important entities for GAPDoc are described in 2.1-10, 2.2-1 and 2.2-3.
We have seen that the less-than-character "<
" and the ampersand character "&
" start a tag or entity reference in XML. To get these characters into the document text one has to use entity references, namely "<
" to get "<
" and "&
" to get "&
". Furthermore ">
" should sometimes be used to get ">
".
Another possibility is to use a CDATA
statement explained in 2.1-11.
CDATA
Pieces of text which contain many characters which can be misinterpreted as markup can be enclosed by the character sequences "<![CDATA[
" and "]]>
". Everything between these sequences is considered as content of the document and is not further interpreted as XML text. All the rules explained so far in this section do not apply to such a part of the document. The only document content which cannot be entered directly inside a CDATA
statement is the sequence "]]>
". This can be entered as "]]>
" outside the CDATA
statement.
A nesting of tags like <a> <b> </a> </b> is not allowed. |
We suggest to use the ISO-8859-1 or ISO-latin1 encoding for writing GAPDoc XML documents. This character set contains the ASCII characters and all special characters from Western European languages like German umlauts or French accented characters. Text in this character set can be used directly with LaTeX and many current default terminal fonts support this character set.
We want to mention two further important words which are often used in the context of XML documents. A piece of text becomes a "well formed" XML document if all the formal rules described in this section are fulfilled.
But this says nothing about the content of the document. To give this content a meaning one needs a declaration of the element and corresponding attribute names as well as of named entities which are allowed. Furthermore there may be restrictions how such elements can be nested. This definition of an XML based markup language is done in a "document type definition". An XML document which contains only elements and entities declared in such a document type definition and obeys the rules given there is called "valid (with respect to this document type definition)".
The main file of the GAPDoc package is gapdoc.dtd
. This contains such a definition of a markup language. We are not going to explain the formal syntax rules for document type definitions in this section. But in Chapter 3. we will explain enough about it to understand the file gapdoc.dtd
and so the markup language defined there.
Here are some additional rules for writing GAPDoc XML documents.
Since one purpose of GAPDoc documents is to produce a high quality LaTeX output version we have to pay attention to characters with a special meaning in LaTeX or in XML. These are the following characters:
"&
", "<
", ">
", "#
", "$
", "%
", "~
", "\
", "{
", "}
", "_
", "^
" and "
" (the last one is a non-breakable space, similar to LaTeX's "~
" character).
The right way to access these symbols is by using "entities", see 2.1-9. The following table shows what to type to get these characters in the output text of the document.
& |
&tamp; |
< |
&tlt; |
> |
&tgt; |
# |
&hash; |
$ |
$ |
% |
&percent; |
~ |
˜ |
\ |
&bslash; |
{ |
&obrace; |
} |
&cbrace; |
_ |
&uscore; |
^ |
&circum; |
|
|
Note that the first three have an extra "t" at the beginning in comparison with the standard entities of XML described in 2.1-10. The difference is necessary because for example "&tamp;
" produces "\&
" for LaTeX to actually get an ampersand character in the printed version. Use "&
" if you want to pass an ampersand character without a backslash in front directly to LaTeX.
Inside attribute values you should not use these entities. Instead use the corresponding characters directly. The reason is that attribute values are often used as labels in LaTeX and it is easier to process this properly with the direct input of the characters.
Also, these entities are not used inside mathematical formulae, see 2.2-2 below.
Mathematical formulae in GAPDoc are typed as in LaTeX. They must be the content of one of three types of GAPDoc elements concerned with mathematical formulae: "Math
", "Display
", and "M
" (see Sections 3.8-1 and 3.8-2 for more details). The first two correspond to LaTeX's math mode and display math mode. The last one is a special form of the "Math
" element type, that imposes certain restrictions on the content. On the other hand the content of an "M
" element is processed in a well defined way for text terminal or HTML output.
The remarks about special characters in 2.2-1 do not apply to the content of these elements. But the special characters "<
" and "&
" for XML must be entered via the entities described in 2.1-10 or by using a CDATA
statement, see 2.1-11.
In GAPDoc there are some more predefined entities:
&GAP; |
GAP |
&GAPDoc; |
GAPDoc |
&TeX; |
TeX |
&LaTeX; |
LaTeX |
&BibTeX; |
BibTeX |
&MeatAxe; |
MeatAxe |
&XGAP; |
XGAP |
©right; |
(C) |
One can define further local entities right inside the head (see 2.1-1) of a GAPDoc XML document as in the following example.
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE Book SYSTEM "gapdoc.dtd" [ <!ENTITY MyEntity "some longish <E>text</E> possibly with markup"> ]> |
These additional definitions go into the <!DOCTYPE
tag in square brackets. Such new entities are used like this: &MyEntity;
generated by GAPDoc2HTML