The Converters

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 &tlt;&hash;Include ...&tgt;-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-, dvi-, pdf-, postscript- and HTML-version of the document.

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 &tlt;&hash;Include ...&tgt;-statements.

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

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

gap> r := ParseTreeXMLString(str);; gap> CheckAndCleanGapDocTree(r); true

We first 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 latex MyBook bibtex MyBook latex MyBook makeindex MyBook latex MyBook mv MyBook.dvi manual.dvi dvips -o manual.ps manual.dvi rm MyBook.aux pdflatex MyBook pdflatex MyBook mv MyBook.pdf manual.pdf

After this we have a dvi-, pdf- and postscript version of the document in the files manual.dvi, manual.pdf and manual.ps. The first two versions contain hyperlink information which can be used with appropriate browsers for convenient reading of the document on screen (e.g., current versions of xdvi, respectively xpdf or acroread.

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 will use this later.

Next we produce a text version 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 color markup using ANSI escape sequences. One can use this with a terminal which interprets these sequences appropriately after setting the &GAP; variable ANSI&uscore;COLORS to true. 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. We can add the page number information from the &LaTeX; version of the document and then print a manual.six file which is read by &GAP; when the document 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 may also 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 dvi-, pdf-, postscript-, text- and HTML-version of a &GAPDoc; document as described in Section .

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 &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="DisplayXMLStructure">

<#Include Label="ApplyToNodesParseTree">

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

<#Include Label="CheckAndCleanGapDocTree">

<#Include Label="AddParagraphNumbersGapDocTree">

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="GAPDoc2HTML">

<#Include Label="GAPDoc2HTMLPrintHTMLFiles">

Parsing &BibTeX; Files

Here are functions for parsing, normalizing and printing reference lists in &BibTeX; format. The reference describing this format is .

<#Include Label="ParseBibFiles">

<#Include Label="NormalizeNameAndKey">

<#Include Label="WriteBibFile">

Text Utilities

This section describes some utility functions for handling texts within &GAP;. They are used by the functions in the &GAPDoc; package but may be useful for other purposes as well. We start with some variables containing useful strings and go on with functions for parsing and reformatting text.

<#Include Label="CharsColls">

<#Include Label="TextAttr">

<#Include Label="FormatParagraph">

<#Include Label="SubstitutionSublist">

<#Include Label="StripBeginEnd">

<#Include Label="StripEscapeSequences">

<#Include Label="RepeatedString">

<#Include Label="NumberDigits">

<#Include Label="PositionMatchingDelimiter">

<#Include Label="WordsString">

Print Utilities

The following printing utilities turned out to be useful for interactive work with texts in &GAP;. But they are more general and so we document them here.

<#Include Label="PrintTo1">

<#Include Label="StringPrint">

<#Include Label="PrintFormattedString">

<#Include Label="Page">

<#Include Label="StringFile">