  
  [1m[4m[31m2. How To Type a [1mGAPDoc[1m[4m[31m Document[0m
  
  In  this chapter we give a more formal description of what you need to start
  to  type  documentation  in  [1mGAPDoc[0m  XML  format.  Many details were already
  explained by example in Section [1m1.2[0m of the introduction.
  
  We  do  [22m[36mnot[0m  answer  the  question "How to [22m[36mwrite[0m a [1mGAPDoc[0m document?" in this
  chapter. You can (hopefully) find an answer to this question by studying the
  example in the introduction, see [1m1.2[0m, and learning about more details in the
  reference Chapter [1m3.[0m.
  
  The definite source for all details of the official XML standard with useful
  annotations is:
  
  [34mhttp://www.xml.com/axml/axml.html[0m
  
  Although  this  document  must  be  quite technical, it is surprisingly well
  readable.
  
  
  [1m[4m[31m2.1 General XML Syntax[0m
  
  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.
  
  
  [1m[4m[31m2.1-1 Head of XML Document[0m
  
  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 [1mGAPDoc[0m
  document this should always look as in the following example.
  
  [22m[35m-----------------------------  Log  ------------------------------[0m
    [22m[35m<?xml version="1.0" encoding="ISO-8859-1"?>[0m
    [22m[35m<!DOCTYPE Book SYSTEM "gapdoc.dtd">[0m
  [22m[35m------------------------------------------------------------------[0m
  
  See [1m2.1-12[0m for a remark on the "encoding" statement.
  
  (There  may  be  local  entity definitions inside the [22m[32mDOCTYPE[0m statement, see
  Subsection [1m2.2-3[0m below.)
  
  
  [1m[4m[31m2.1-2 Comments[0m
  
  A  "comment"  in XML starts with the character sequence "[22m[32m<!--[0m" and ends with
  the  sequence  "[22m[32m-->[0m". Between these sequences there must not be two adjacent
  dashes "[22m[32m--[0m".
  
  
  [1m[4m[31m2.1-3 Processing Instructions[0m
  
  A  "processing  instruction"  in XML starts with the character sequence "[22m[32m<?[0m"
  followed  by  a  name  ("[22m[32mxml[0m"  is  only allowed at the very beginning of the
  document  to  declare  it  being an XML document, see [1m2.1-1[0m). After that any
  characters  may  follow, except that the ending sequence "[22m[32m?>[0m" must not occur
  within the processing instruction.
  
   
  
  And  now  we  turn  to  those  parts of the document which contribute to its
  actual content.
  
  
  [1m[4m[31m2.1-4 Names in XML and Whitespace[0m
  
  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 "[22m[32m:[0m" or
  underscore  "[22m[32m_[0m" character. The following characters may also be digits, dots
  "[22m[32m.[0m" or dashes "[22m[32m-[0m".
  
  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
  [22m[36mwhitespace[0m:   blanks,   tabs,   carriage  return  characters  and  new  line
  characters.
  
  
  [1m[4m[31m2.1-5 Elements[0m
  
  The actual content of an XML document consists of "elements". An element has
  some  "content"  with a leading "start tag" ([1m2.1-6[0m) and a trailing "end tag"
  ([1m2.1-7[0m).  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 ([1m2.1-8[0m).
  
  
  [1m[4m[31m2.1-6 Start Tags[0m
  
  A  "start-tag"  consists  of  a  less-than-character  "[22m[32m<[0m"  directly followed
  (without  whitespace)  by  an element name (see [1m2.1-4[0m), optional attributes,
  optional whitespace, and a greater-than-character "[22m[32m>[0m".
  
  An  "attribute" consists of some whitespace and then its name followed by an
  equal sign "[22m[32m=[0m" 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 "[22m[32m<[0m" and "[22m[32m&[0m".
  
  Note  especially  that  no  whitespace  is  allowed between the starting "[22m[32m<[0m"
  character  and the element name. The quotes around an attribute value cannot
  be omitted. The names of elements and attributes are [22m[36mcase sensitive[0m.
  
  
  [1m[4m[31m2.1-7 End Tags[0m
  
  An  "end  tag"  consists of the two characters "[22m[32m</[0m" directly followed by the
  element name, optional whitespace and a greater-than-character "[22m[32m>[0m".
  
  
  [1m[4m[31m2.1-8 Combined Tags for Empty Elements[0m
  
  Elements  which  always have empty content can be written with a single tag.
  This   looks   like  a  start  tag  (see [1m2.1-6[0m)  [22m[36mexcept[0m  that  the  trailing
  greater-than-character  "[22m[32m>[0m"  is  substituted  by  the two character sequence
  "[22m[32m/>[0m".
  
  
  [1m[4m[31m2.1-9 Entities[0m
  
  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 "[22m[32m&#[0m",
  directly  followed  by  either  some  decimal  digits  or  an  "[22m[32mx[0m"  and some
  hexadecimal  digits,  directly  followed  by  a  semicolon "[22m[32m;[0m". 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  "[22m[32m&[0m"  directly  followed  by  a  name which is directly
  followed  by  a  semicolon  "[22m[32m;[0m". 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
  [1mGAPDoc[0m are described in [1m2.1-10[0m, [1m2.2-1[0m and [1m2.2-3[0m.
  
  
  [1m[4m[31m2.1-10 Special Characters in XML[0m
  
  We  have  seen  that the less-than-character "[22m[32m<[0m" and the ampersand character
  "[22m[32m&[0m" start a tag or entity reference in XML. To get these characters into the
  document text one has to use entity references, namely "[22m[32m&lt;[0m" to get "[22m[32m<[0m" and
  "[22m[32m&amp;[0m" to get "[22m[32m&[0m". Furthermore "[22m[32m&gt;[0m" should sometimes be used to get "[22m[32m>[0m".
  
  Another possibility is to use a [22m[32mCDATA[0m statement explained in [1m2.1-11[0m.
  
  
  [1m[4m[31m2.1-11 [22m[32mCDATA[1m[4m[31m[0m
  
  Pieces  of text which contain many characters which can be misinterpreted as
  markup  can  be  enclosed  by the character sequences "[22m[32m<![CDATA[[0m" and "[22m[32m]]>[0m".
  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  [22m[36mnot  apply[0m  to  such a part of the document. The only
  document  content  which cannot be entered directly inside a [22m[32mCDATA[0m statement
  is  the  sequence  "[22m[32m]]>[0m".  This can be entered as "[22m[32m]]&gt;[0m" outside the [22m[32mCDATA[0m
  statement.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mA nesting of tags like <a> <b> </a> </b> is not allowed.[0m
  [22m[35m------------------------------------------------------------------[0m
  
  
  [1m[4m[31m2.1-12 Encoding of an XML document[0m
  
  We  suggest  to use the ISO-8859-1 or ISO-latin1 encoding for writing [1mGAPDoc[0m
  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.
  
  
  [1m[4m[31m2.1-13 Well Formed and Valid XML Documents[0m
  
  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 [22m[36mdefinition
  of  an XML based markup language[0m 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  [1mGAPDoc[0m package is [1mgapdoc.dtd[0m. 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 [1m3.[0m we will explain enough about it to understand the file [1mgapdoc.dtd[0m
  and so the markup language defined there.
  
  
  [1m[4m[31m2.2 Entering [1mGAPDoc[1m[4m[31m Documents[0m
  
  Here are some additional rules for writing [1mGAPDoc[0m XML documents.
  
  
  [1m[4m[31m2.2-1 More Special Characters[0m
  
  Since  one  purpose  of  [1mGAPDoc[0m 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:
  
  "[22m[32m&[0m", "[22m[32m<[0m", "[22m[32m>[0m", "[22m[32m#[0m", "[22m[32m$[0m", "[22m[32m%[0m", "[22m[32m~[0m", "[22m[32m\[0m", "[22m[32m{[0m", "[22m[32m}[0m", "[22m[32m_[0m", "[22m[32m^[0m" and "[22m[32m [0m" (the last
  one is a non-breakable space, similar to LaTeX's "[22m[32m~[0m" character).
  
  The right way to access these symbols is by using "entities", see [1m2.1-9[0m. The
  following  table  shows  what  to type to get these characters in the output
  text of the document.
  
     -------------------
      | [22m[32m&[0m | [22m[32m&tamp;[0m    | 
     -------------------
      | [22m[32m<[0m | [22m[32m&tlt;[0m     | 
     -------------------
      | [22m[32m>[0m | [22m[32m&tgt;[0m     | 
     -------------------
      | [22m[32m#[0m | [22m[32m&hash;[0m    | 
     -------------------
      | [22m[32m$[0m | [22m[32m&dollar;[0m  | 
     -------------------
      | [22m[32m%[0m | [22m[32m&percent;[0m | 
     -------------------
      | [22m[32m~[0m | [22m[32m&tilde;[0m   | 
     -------------------
      | [22m[32m\[0m | [22m[32m&bslash;[0m  | 
     -------------------
      | [22m[32m{[0m | [22m[32m&obrace;[0m  | 
     -------------------
      | [22m[32m}[0m | [22m[32m&cbrace;[0m  | 
     -------------------
      | [22m[32m_[0m | [22m[32m&uscore;[0m  | 
     -------------------
      | [22m[32m^[0m | [22m[32m&circum;[0m  | 
     -------------------
      | [22m[32m [0m | [22m[32m&nbsp;[0m    | 
     -------------------
  
       [1m[4m[31mTable:[0m What to type for special characters in character data
  
  
  Note  that  the first three have an extra "t" at the beginning in comparison
  with  the  standard  entities  of XML described in [1m2.1-10[0m. The difference is
  necessary  because  for example "[22m[32m&tamp;[0m" produces "[22m[32m\&[0m" for LaTeX to actually
  get  an  ampersand character in the printed version. Use "[22m[32m&amp;[0m" if you want
  to  pass  an  ampersand  character  without a backslash in front directly to
  LaTeX.
  
  Inside  attribute  values you should [22m[36mnot[0m 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 [22m[36mnot[0m used inside mathematical formulae, see  [1m2.2-2[0m
  below.
  
  
  [1m[4m[31m2.2-2 Mathematical Formulae[0m
  
  Mathematical  formulae  in  [1mGAPDoc[0m  are  typed as in LaTeX. They must be the
  content of one of three types of [1mGAPDoc[0m elements concerned with mathematical
  formulae:  "[22m[32mMath[0m", "[22m[32mDisplay[0m", and "[22m[32mM[0m" (see Sections [1m3.8-1[0m and [1m3.8-2[0m 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 "[22m[32mMath[0m" element type, that
  imposes  certain  restrictions on the content. On the other hand the content
  of  an  "[22m[32mM[0m"  element is processed in a well defined way for text terminal or
  HTML output.
  
  The remarks about special characters in [1m2.2-1[0m do not apply to the content of
  these  elements.  But  the  special  characters  "[22m[32m<[0m" and "[22m[32m&[0m" for XML must be
  entered  via the entities described in [1m2.1-10[0m or by using a [22m[32mCDATA[0m statement,
  see [1m2.1-11[0m.
  
  
  [1m[4m[31m2.2-3 More Entities[0m
  
  In [1mGAPDoc[0m there are some more predefined entities:
  
     ---------------------------
      | [22m[32m&GAP;[0m       | [1mGAP[0m     | 
     ---------------------------
      | [22m[32m&GAPDoc;[0m    | [1mGAPDoc[0m  | 
     ---------------------------
      | [22m[32m&TeX;[0m       | TeX     | 
     ---------------------------
      | [22m[32m&LaTeX;[0m     | LaTeX   | 
     ---------------------------
      | [22m[32m&BibTeX;[0m    | BibTeX  | 
     ---------------------------
      | [22m[32m&MeatAxe;[0m   | [1mMeatAxe[0m | 
     ---------------------------
      | [22m[32m&XGAP;[0m      | [1mXGAP[0m    | 
     ---------------------------
      | [22m[32m&copyright;[0m | (C)     | 
     ---------------------------
  
       [1m[4m[31mTable:[0m Predefined Entities in the [1mGAPDoc[0m system
  
  
  One can define further local entities right inside the head (see [1m2.1-1[0m) of a
  [1mGAPDoc[0m XML document as in the following example.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m<?xml version="1.0" encoding="ISO-8859-1"?>[0m
    [22m[35m[0m
    [22m[35m<!DOCTYPE Book SYSTEM "gapdoc.dtd"[0m
    [22m[35m  [ <!ENTITY MyEntity "some longish <E>text</E> possibly with markup">[0m
    [22m[35m  ]>[0m
  [22m[35m------------------------------------------------------------------[0m
  
  These  additional  definitions go into the [22m[32m<!DOCTYPE[0m tag in square brackets.
  Such new entities are used like this: [22m[32m&MyEntity;[0m
  
