GAP (GAPDoc) - Chapter 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 [GAP06]). 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 https://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.

<?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).

<!--   A complete "fake package" documentation   
-->

Everything in a XML file between  is a comment and not part of the document content.

<!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:

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

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

<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:

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


      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.

      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

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

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

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 Introduction and Example

1.1 XML

1.2 A complete example

1.3 Some questions