1 Introduction and Example
  
  The  main  purpose  of  the  GAPDoc  package  is to define a file format for
  documentation of GAP-programs and -packages (see [GAP]). The problem is that
  such documentation should be readable in several output formats. For example
  it should be possible to read the documentation inside the terminal in which
  GAP is running (a text mode) and there should be a printable version in high
  typesetting quality (produced by some version of TeX). It is also popular to
  view  GAP's  online  help  with  a  Web-browser  via  an HTML-version of the
  documentation.  Nowadays  one  can use LaTeX and standard viewer programs to
  produce  and  view  on  the  screen  dvi-  or pdf-files with full support of
  internal  and external hyperlinks. Certainly there will be other interesting
  document formats and tools in this direction in the future.
  
  Our  aim  is  to  find a format for writing the documentation which allows a
  relatively easy translation into the output formats just mentioned and which
  hopefully makes it easy to translate to future output formats as well.
  
  To  make documentation written in the GAPDoc format directly usable, we also
  provide   a  set  of  programs,  called  converters,  which  produce  text-,
  hyperlinked  LaTeX-  and  HTML-output  versions  of a GAPDoc document. These
  programs are developed by the first named author. They run completely inside
  GAP, i.e., no external programs are needed. You only need latex and pdflatex
  to process the LaTeX output. These programs are described in Chapter 5.
  
  
  1.1 XML
  
  The  definition  of  the  GAPDoc  format  uses  XML,  the "eXtendible Markup
  Language".   This  is  a  standard  (defined  by  the  W3C  consortium,  see
  http://www.w3c.org) which lays down a syntax for adding markup to a document
  or  to  some  data.  It allows to define document structures via introducing
  markup  elements  and  certain  relations  between  them.  This is done in a
  document  type definition. The file gapdoc.dtd contains such a document type
  definition and is the central part of the GAPDoc package.
  
  The easiest way for getting a good idea about this is probably to look at an
  example.  The Appendix A contains a short but complete GAPDoc document for a
  fictitious  share  package.  In  the  next  section  we will go through this
  document,  explain  basic  facts about XML and the GAPDoc document type, and
  give pointers to more details in later parts of this documentation.
  
  In  the  last Section 1.3 of this introductory chapter we try to answer some
  general questions about the decisions which lead to the GAPDoc package.
  
  
  1.2 A complete example
  
  In  this section we recall the lines from the example document in Appendix A
  and give some explanations.
  
  ------------------------  from 3k+1.xml  -------------------------
    <?xml version="1.0" encoding="UTF-8"?> 
  ------------------------------------------------------------------
  
  This line just tells a human reader and computer programs that the file is a
  document with XML markup and that the text is encoded in the UTF-8 character
  set (other common encodings are ASCII or ISO-8895-X encodings).
  
  ------------------------  from 3k+1.xml  -------------------------
    <!--   A complete "fake package" documentation   
       $Id: intro.xml,v 1.13 2007/10/04 22:02:12 gap Exp $
    -->
  ------------------------------------------------------------------
  
  Everything  in a XML file between "<!--" and "-->" is a comment and not part
  of the document content.
  
  ------------------------  from 3k+1.xml  -------------------------
    <!DOCTYPE Book SYSTEM "gapdoc.dtd">
  ------------------------------------------------------------------
  
  This  line  says  that  the document contains markup which is defined in the
  system  file  gapdoc.dtd  and that the markup obeys certain rules defined in
  that file (the ending dtd means "document type definition"). It further says
  that  the  actual  content  of the document consists of an element with name
  "Book".  And  we  can  really  see  that  the  remaining part of the file is
  enclosed as follows:
  
  ------------------------  from 3k+1.xml  -------------------------
    <Book Name="3k+1">
      [...] (content omitted)
    </Book>
  ------------------------------------------------------------------
  
  This demonstrates the basics of the markup in XML. This part of the document
  is  an  "element".  It  consists  of the "start tag" <Book Name="3k+1">, the
  "element content" and the "end tag" </Book> (end tags always start with </).
  This element also has an "attribute" Name whose "value" is 3k+1.
  
  If  you  know  HTML,  this  will  look  familiar  to you. But there are some
  important  differences:  The  element  name Book and attribute name Name are
  case sensitive. The value of an attribute must always be enclosed in quotes.
  In  XML  every  element  has  a start and end tag (which can be combined for
  elements defined as "empty", see for example <TableOfContents/> below).
  
  If  you  know  LaTeX, you are familiar with quite different types of markup,
  for example: The equivalent of the Book element in LaTeX is \begin{document}
  ...  \end{document}.  The  sectioning in LaTeX is not done by explicit start
  and  end  markup,  but  implicitly via heading commands like \section. Other
  markup  is done by using braces {} and putting some commands inside. And for
  mathematical  formulae  one  can  use the $ for the start and the end of the
  markup. In XML all markup looks similar to that of the Book element.
  
  The content of the book starts with a title page.
  
  ------------------------  from 3k+1.xml  -------------------------
    <TitlePage>
      <Title>The <Package>ThreeKPlusOne</Package> Package</Title>
      <Version>Version 42</Version>
      <Author>Dummy Authör
        <Email>3kplusone@dev.null</Email>
      </Author>
    
      <Copyright>&copyright; 2000 The Author. <P/>
        You can do with this package what you want.<P/> Really.
      </Copyright>
    </TitlePage>
  ------------------------------------------------------------------
  
  The  content  of  the  TitlePage  element  consists  again  of  elements. In
  Chapter 3 we describe which elements are allowed within a TitlePage and that
  their  ordering  is  prescribed  in  this  case. In the (stupid) name of the
  author  you  see  that  a  German  umlaut  is  used  directly (in ISO-latin1
  encoding).
  
  Contrary to LaTeX- or HTML-files this markup does not say anything about the
  actual  layout  of  the title page in any output version of the document. It
  just adds information about the meaning of pieces of text.
  
  Within  the  Copyright  element there are two more things to learn about XML
  markup.  The <P/> is a complete element. It is a combined start and end tag.
  This  shortcut  is  allowed  for  elements  which  are  defined to be always
  "empty", i.e., to have no content. You may have already guessed that <P/> is
  used  as  a  paragraph  separator.  Note  that  empty  lines do not separate
  paragraphs (contrary to LaTeX).
  
  The  other  construct  we  see here is &copyright;. This is an example of an
  "entity"  in  XML  and is a macro for some substitution text. Here we use an
  entity  as  a  shortcut for a complicated expression which makes it possible
  that  the  term  copyright is printed as some text like (C) in text terminal
  output  and  as  a copyright character in other output formats. In GAPDoc we
  predefine  some  entities.  Certain  "special  characters" must be typed via
  entities,  for  example "<", ">" and "&" to avoid a misinterpretation as XML
  markup.  It  is  possible  to  define  additional entities for your document
  inside the <!DOCTYPE ...> declaration, see 2.2-3.
  
  Note  that  elements  in  XML  must  always  be  properly nested, as in this
  example. A construct like <a><b>...</a></b> is not allowed.
  
  ------------------------  from 3k+1.xml  -------------------------
    <TableOfContents/>
  ------------------------------------------------------------------
  
  This is another example of an "empty element". It just means that a table of
  contents  for  the whole document should be included into any output version
  of the document.
  
  After  this  the main text of the document follows inside certain sectioning
  elements:
  
  ------------------------  from 3k+1.xml  -------------------------
    <Body>
      <Chapter> <Heading>The <M>3k+1</M> Problem</Heading>
        <Section Label="sec:theory"> <Heading>Theory</Heading>
          [...] (content omitted)
        </Section>
        <Section> <Heading>Program</Heading>
          [...] (content omitted) 
        </Section>
      </Chapter>
    </Body>
  ------------------------------------------------------------------
  
  These elements are used similarly to "\chapter" and "\section" in LaTeX. But
  note that the explicit end tags are necessary here.
  
  The  sectioning commands allow to assign an optional attribute "Label". This
  can be used for referring to a section inside the document.
  
  The  text of the first section starts as follows. The whitespace in the text
  is unimportant and the indenting is not necessary.
  
  ------------------------  from 3k+1.xml  -------------------------
    
          Let  <M>k \in  &NN;</M> be  a  natural number.  We consider  the
          sequence <M>n(i, k), i \in &NN;,</M> with <M>n(1, k) = k</M> and
          else 
  ------------------------------------------------------------------
  
  Here  we  come to the interesting question how to type mathematical formulae
  in  a  GAPDoc document. We did not find any alternative for writing formulae
  in  TeX  syntax. (There is MATHML, but even simple formulae contain a lot of
  markup, become quite unreadable and they are cumbersome to type. Furthermore
  there  seem to be no tools available which translate such formulae in a nice
  way  into  TeX  and  text.)  So, formulae are essentially typed as in LaTeX.
  (Actually,   it  is  also  possible  to  type  unicode  characters  of  some
  mathematical  symbols directly, or via an entity like the &NN; above.) There
  are  three types of elements containing formulae: "M", "Math" and "Display".
  The  first  two  are  for  in-text  formulae  and the third is for displayed
  formulae.  Here  "M"  and  "Math"  are equivalent, when translating a GAPDoc
  document into LaTeX. But they are handled differently for terminal text (and
  HTML)  output. For the content of an "M"-element there are defined rules for
  a  translation  into  well readable terminal text. More complicated formulae
  are  in  "Math"  or "Display" elements and they are just printed as they are
  typed  in text output. So, to make a section well readable inside a terminal
  window you should try to put as many formulae as possible into "M"-elements.
  In  our  example text we used the notation n(i, k) instead of n_i(k) because
  it  is  easier  to  read  in  text mode. See Sections 2.2-2 and 3.9 for more
  details.
  
  A few lines further on we find two non-internal references.
  
  ------------------------  from 3k+1.xml  -------------------------
          problem, see <Cite Key="Wi98"/> or
          <URL>http://mathsrv.ku-eichstaett.de/MGF/homes/wirsching/</URL>
  ------------------------------------------------------------------
  
  The  first within the "Cite"-element is the citation of a book. In GAPDoc we
  use  the  widely  used BibTeX database format for reference lists. This does
  not  use XML but has a well documented structure which is easy to parse. And
  many people have collections of references readily available in this format.
  The reference list in an output version of the document is produced with the
  empty element
  
  ------------------------  from 3k+1.xml  -------------------------
    <Bibliography Databases="3k+1" />
  ------------------------------------------------------------------
  
  close  to  the  end  of our example file. The attribute "Databases" give the
  name(s) of the database (.bib) files which contain the references.
  
  Putting a Web-address into an "URL"-element allows one to create a hyperlink
  in output formats which allow this.
  
  The  second  section  of  our  example contains a special kind of subsection
  defined in GAPDoc.
  
  ------------------------  from 3k+1.xml  -------------------------
          <ManSection> 
            <Func Name="ThreeKPlusOneSequence" Arg="k[, max]"/>
            <Description>
              This  function computes  for a  natural number  <A>k</A> the
              beginning of the sequence  <M>n(i, k)</M> defined in section
              <Ref Sect="sec:theory"/>.  The sequence  stops at  the first
              <M>1</M>  or at  <M>n(<A>max</A>, k)</M>,  if <A>max</A>  is
              given.
    <Example>
    gap> ThreeKPlusOneSequence(101);
    "Sorry, not yet implemented. Wait for Version 84 of the package"
    </Example>
            </Description>
          </ManSection>
  ------------------------------------------------------------------
  
  A "ManSection" contains the description of some function, operation, method,
  filter and so on. The "Func"-element describes the name of a function (there
  are  also  similar  elements "Oper", "Meth", "Filt" and so on) and names for
  its   arguments,   optional  arguments  enclosed  in  square  brackets.  See
  Section 3.4 for more details.
  
  In  the  "Description"  we  write the argument names as "A"-elements. A good
  description  of a function should usually contain an example of its use. For
  this  there  are some verbatim-like elements in GAPDoc, like "Example" above
  (here,   clearly,   whitespace  matters  which  causes  a  slightly  strange
  indenting).
  
  The  text  contains  an  internal  reference  to  the  first section via the
  explicitly defined label sec:theory.
  
  The first section also contains a "Ref"-element which refers to the function
  described  here.  Note that there is no explicit label for such a reference.
  The  pair  <Func  Name="ThreeKPlusOneSequence"  Arg="k[,  max]"/>  and  <Ref
  Func="ThreeKPlusOneSequence"/>  does the cross referencing (and hyperlinking
  if possible) implicitly via the name of the function.
  
  Here  is  one  further  element  from  our example document which we want to
  explain.
  
  ------------------------  from 3k+1.xml  -------------------------
    <TheIndex/>
  ------------------------------------------------------------------
  
  This is again an empty element which just says that an output version of the
  document  should  contain an index. Many entries for the index are generated
  automatically  because  the  "Func"  and similar elements implicitly produce
  such  entries. It is also possible to include explicit additional entries in
  the index.
  
  
  1.3 Some questions
  
  Are those XML files too ugly to read and edit?
        Just have a look and decide yourself. The markup needs more characters
        than  most  TeX  or LaTeX markup. But the structure of the document is
        easier  to see. If you configure your favorite editor well, you do not
        need more key strokes for typing the markup than in LaTeX.
  
  Why do we not use LaTeX alone?
        LaTeX  is  good  for  writing  books.  But  LaTeX  files are generally
        difficult  to  parse  and to process to other output formats like text
        for  browsing  in  a terminal window or HTML (or new formats which may
        become popular in the future). GAPDoc markup is one step more abstract
        than  LaTeX  insofar  as it describes meaning instead of appearance of
        text. The inner workings of LaTeX are too complicated to learn without
        pain,  which  makes  it  difficult  to  overcome  problems  that occur
        occasionally.
  
  Why XML and not a newly defined markup language?
        XML is a well defined standard that is more and more widely used. Lots
        of  people  have  thought about it. Years of experience with SGML went
        into  the  design.  It  is  easy to explain, easy to parse and lots of
        tools are available, there will be more in the future.