The Converters and an XML Parser

The &GAPDoc; package contains a set of programs which allow us to convert a &GAPDoc; book into several output versions and to make them available to &GAP;'s online help.

Currently the following output formats are provided: text for browsing inside a terminal running &GAP;, &LaTeX; with hyperref-package for cross references via hyperlinks and HTML for reading with a Web-browser.

Producing Documentation from Source Files

Here we explain how to use the functions which are described in more detail in the following sections. We assume that we have the main file MyBook.xml of a book "MyBook" in the directory /my/book/path. This contains <#Include ...>-statements as explained in Chapter . These refer to some other files as well as pieces of text which are found in the comments of some &GAP; source files ../lib/a.gd and ../lib/b.gi (relative to the path above). A &BibTeX; database MyBook.bib for the citations is also in the directory given above. We want to produce a text-, pdf- and HTML-version of the document. (A &LaTeX; version of the manual is produced, so it is also easy to compile dvi-, and postscript-versions.)

All the commands shown in this Section are collected in the single function .

First we construct the complete XML-document as a string with . This interprets recursively the <#Include ...>-statements.

gap> path := Directory("/my/book/path");; gap> main := "MyBook.xml";; gap> files := ["../lib/a.gd", "../lib/b.gi"];; gap> bookname := "MyBook";; gap> doc := ComposedDocument("GAPDoc", path, main, files, true);;

Now doc is a list with two entries, the first is a string containing the XML-document, the second gives information from which files and locations which part of the document was collected. This is useful in the next step, if there are any errors in the document.

Next we parse the document and store its structure in a tree-like data structure. The commands for this are and .

gap> r := ParseTreeXMLString(doc[1], doc[2]);; gap> CheckAndCleanGapDocTree(r); true

We start to produce a text version of the manual, which can be read in a terminal (window). The command is . This produces a record with the actual text and some additional information. The text can be written chapter-wise into files with . The names of these files are chap0.txt, chap1.txt and so on. The text contains some markup using ANSI escape sequences. This markup is substituted by the &GAP; help system (user configurable) to show the text with colors and other attributes. For the bibliography we have to tell the location of the &BibTeX; database by specifying a path as second argument.

gap> t := GAPDoc2Text(r, path);; gap> GAPDoc2TextPrintTextFiles(t, path);

This command constructs all parts of the document including table of contents, bibliography and index. The functions for formatting text paragraphs and for reading &BibTeX; files with &GAP; may be of independent interest.

With the text version we have also produced the information which is used for searching with &GAP;'s online help. Also, labels are produced which can be used by links in the HTML- and pdf-versions of the manual.

Next we produce a &LaTeX; version of the document. returns a string containing the &LaTeX; source. The utility function writes the content of a string to a file, we choose MyBook.tex.

gap> l := GAPDoc2LaTeX(r);; gap> FileString(Filename(path, Concatenation(bookname, ".tex")), l);

Assuming that you have a sufficiently good installation of &TeX; available (see for details) this can be processed with a series of commands like in the following example.

cd /my/book/path pdflatex MyBook bibtex MyBook pdflatex MyBook makeindex MyBook pdflatex MyBook mv MyBook.pdf manual.pdf

After this we have a pdf-version of the document in the file manual.pdf. It contains hyperlink information which can be used with appropriate browsers for convenient reading of the document on screen (e.g., xpdf is nice because it allows remote calls to display named locations of the document). Of course, we could also use other commands like latex or dvips to process the &LaTeX; source file.

Furthermore we have produced a file MyBook.pnr which is &GAP;-readable and contains the page number information for each (sub-)section of the document.

We can add this page number information to the indexing information collected by the text converter and then print a manual.six file which is read by &GAP; when the manual is loaded. This is done with and .

gap> AddPageNumbersToSix(r, Filename(path, "MyBook.pnr")); gap> PrintSixFile(Filename(path, "manual.six"), r, bookname);

Finally we produce an HTML-version of the document and write it (chapter-wise) into files chap0.html, chap1.html and so on. They can be read with any Web-browser. The commands are and . We also add a link from manual.html to chap0.html. You probably want to add a file manual.css, see for more details. The argument path of specifies the directory containing the &BibTeX; database files.

gap> h := GAPDoc2HTML(r, path);; gap> GAPDoc2HTMLPrintHTMLFiles(h, path);
This function collects all the commands for producing a text-, pdf- and HTML-version of a &GAPDoc; document as described in Section . It checks the .log file from the call of pdflatex and reports if there are errors, warnings or overfull boxes.

Note:
If this function works for you depends on your operating system and installed software. It will probably work on most UNIX systems with a standard &LaTeX; installation. If the function doesn't work for you look at the source code and adjust it to your system.

Here path must be the directory (as string or directory object) containing the main file main of the document (given with or without the .xml extension. The argument files is a list of (probably source code) files relative to path which contain pieces of documentation which must be included in the document, see Chapter . And bookname is the name of the book used by &GAP;'s online help. The optional argument gaproot must be a string which gives the relative path from path to the main &GAP; root directory. If this is given, the HTML files are produced with relative paths to external books.

Experimental: can be called with additional arguments "Tth" and/or "MathML". If these are given additional variants of the HTML conversion are called, see for details.

Parsing XML Documents
Arbitrary well-formed XML documents can be parsed and browsed by the following functions.

<#Include Label="ParseTreeXMLString">

<#Include Label="StringXMLElement">

<#Include Label="EntitySubstitution">

<#Include Label="DisplayXMLStructure">

<#Include Label="ApplyToNodesParseTree">

Here are two more utilities which use .

<#Include Label="GetTextXMLTree">

<#Include Label="XMLElements">

And here are utilities for processing &GAPDoc; XML documents.

<#Include Label="CheckAndCleanGapDocTree">

<#Include Label="AddParagraphNumbersGapDocTree">

<#Include Label="InfoXMLParser">

The Converters
Here are more details about the conversion programs for &GAPDoc; XML documents.

<#Include Label="GAPDoc2LaTeX">

<#Include Label="GAPDoc2Text">

<#Include Label="GAPDoc2TextPrintTextFiles">

<#Include Label="AddPageNumbersToSix">

<#Include Label="PrintSixFile">

<#Include Label="SetGAPDocTextTheme">

<#Include Label="GAPDoc2HTML">

<#Include Label="GAPDoc2HTMLPrintHTMLFiles">

<#Include Label="InfoGAPDoc">

Testing Manual Examples
We also provide some tools to check the examples given in <Example>-elements.

<#Include Label="ManualExamples">

<#Include Label="TestExamples">