GAP (GAPDoc) - Chapter 5: 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.

5.1 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 4. 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 MakeGAPDocDoc (5.1-1).

First we construct the complete XML-document as a string with ComposedDocument (4.2-1). 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 ParseTreeXMLString (5.2-1) and CheckAndCleanGapDocTree (5.2-8).

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 GAPDoc2Text (5.3-2). This produces a record with the actual text and some additional information. The text can be written chapter-wise into files with GAPDoc2TextPrintTextFiles (5.3-3). 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 GAPDoc2Text (5.3-2) 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 FormatParagraph (6.1-4) for formatting text paragraphs and ParseBibFiles (7.1-1) 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. GAPDoc2LaTeX (5.3-1) returns a string containing the LaTeX source. The utility function FileString (6.3-5) 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 GAPDoc2LaTeX (5.3-1) 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 AddPageNumbersToSix (5.3-4) and PrintSixFile (5.3-5).

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 GAPDoc2HTML (5.3-7) and GAPDoc2HTMLPrintHTMLFiles (5.3-8). We also add a link from manual.html to chap0.html. You probably want to copy stylesheet files into the same directory, see 5.3-9 for more details. The argument path of GAPDoc2HTML (5.3-7) specifies the directory containing the BibTeX database files.

gap> h := GAPDoc2HTML(r, path);;
gap> GAPDoc2HTMLPrintHTMLFiles(h, path);

5.1-1 MakeGAPDocDoc

‣ MakeGAPDocDoc( path, main, files, bookname[, gaproot][, ...] ) ( function )

This function collects all the commands for producing a text-, pdf- and HTML-version of a GAPDoc document as described in Section 5.1. 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 4. 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.

If the string "nopdf" is given as optional argument then MakeGAPDocDoc will not produce a pdf-version of the help book (the source .tex-file is generated). Consequently, the index for the help system will not contain page numbers for the pdf-version. This variant of MakeGAPDocDoc should work independently of the operating system because no external programs are called. It is recommended that distributed manuals contain the pdf-version.

MakeGAPDocDoc can be called with additional arguments "MathJax", "Tth" and/or "MathML". If these are given additional variants of the HTML conversion are called, see GAPDoc2HTML (5.3-7) for details.

It is possible to use GAPDoc with other languages than English, see SetGapDocLanguage (5.3-13) for more details.

5.2 Parsing XML Documents

Arbitrary well-formed XML documents can be parsed and browsed by the following functions. A proper validation can be done with an external program, see XMLValidate (5.2-11) below.

5.2-1 ParseTreeXMLString

‣ ParseTreeXMLString( str[, srcinfo][, entitydict] ) ( function )

‣ ParseTreeXMLFile( fname[, entitydict] ) ( function )

The first function parses an XML-document stored in string str and returns the document in form of a tree.

The optional argument srcinfo must have the same format as in OriginalPositionDocument (4.2-2). If it is given then error messages refer to the original source of the text with the problem.

With the optional argument entitydict named entities can be given to the parser, for example entities which are defined in the .dtd-file (which is not read by this parser). The standard XML-entities do not need to be provided, and for GAPDoc documents the entity definitions from gapdoc.dtd are automatically provided. Entities in the document's <!DOCTYPE declaration are parsed and also need not to be provided here. The argument entitydict must be a record where each component name is an entity name (without the surrounding & and ;) to which is assigned its substitution string.

The second function is just a shortcut for ParseTreeXMLString( StringFile(fname), ... ), see StringFile (6.3-5).

After these functions return the list of named entities which were known during the parsing can be found in the record ENTITYDICT.

A node in the result tree corresponds to an XML element, or to some parsed character data. In the first case it looks as follows:

rec( name := "Book",
     attributes := rec( Name := "EDIM" ),
     content := [ ... list of nodes for content ...],
     start := 312,
     stop := 15610,
     next := 15611     )

This means that str{[312..15610]} looks like <Book Name="EDIM"> ... content ... </Book>.

The leaves of the tree encode parsed character data as in the following example:

rec( name := "PCDATA", 
     content := "text without markup "     )

This function checks whether the XML document is well formed, see 2.1-14 for an explanation. If an error in the XML structure is found, a break loop is entered and the text around the position where the problem starts is shown. With Show(); one can browse the original input in the Pager (Reference: Pager), starting with the line where the error occurred. All entities are resolved when they are either entities defined in the GAPDoc package (in particular the standard XML entities) or if their definition is included in the <!DOCTYPE ..> tag of the document.

Note that ParseTreeXMLString does not parse and interpret the corresponding document type definition (the .dtd-file given in the <!DOCTYPE ..> tag). Hence it also does not check the validity of the document (i.e., it is no validating XML parser).

If you are using this function to parse a GAPDoc document you can use CheckAndCleanGapDocTree (5.2-8) for some validation and additional checking of the document structure.

5.2-2 StringXMLElement

‣ StringXMLElement( tree ) ( function )

The argument tree must have a format of a node in the parse tree of an XML document as returned by ParseTreeXMLString (5.2-1) (including the root node representing the full document). This function computes a pair [string, positions] where string contains XML code which is equivalent to the code which was parsed to get tree. And positions is a list of lists of four numbers [eltb, elte, contb, conte]. There is one such list for each XML element occuring in string, where eltb and elte are the begin and end position of this element in string and where contb and conte are begin and end position of the content of this element, or both are 0 if there is no content.

Note that parsing XML code is an irreversible task, we can only expect to get equivalent XML code from this function. But parsing the resulting string again and applying StringXMLElement again gives the same result. See the function EntitySubstitution (5.2-3) for back-substitutions of entities in the result.

5.2-3 EntitySubstitution

‣ EntitySubstitution( xmlstring, entities ) ( function )

The argument xmlstring must be a string containing XML code or a pair [string, positions] as returned by StringXMLElement (5.2-2). The argument entities specifies entity names (without the surrounding & and ;) and their substitution strings, either a list of pairs of strings or as a record with the names as components and the substitutions as values.

This function tries to substitute non-intersecting parts of string by the given entities. If the positions information is given then only parts of the document which allow a valid substitution by an entity are considered. Otherwise a simple text substitution without further check is done.

Note that in general the entity resolution in XML documents is a complicated and non-reversible task. But nevertheless this utility may be useful in not too complicated situations.

5.2-4 DisplayXMLStructure

‣ DisplayXMLStructure( tree ) ( function )

This utility displays the tree structure of an XML document as it is returned by ParseTreeXMLString (5.2-1) (without the PCDATA leaves).

Since this is usually quite long the result is shown using the Pager (Reference: Pager).

5.2-5 ApplyToNodesParseTree

‣ ApplyToNodesParseTree( tree, fun ) ( function )

‣ AddRootParseTree( tree ) ( function )

‣ RemoveRootParseTree( tree ) ( function )

The function ApplyToNodesParseTree applies a function fun to all nodes of the parse tree tree of an XML document returned by ParseTreeXMLString (5.2-1).

The function AddRootParseTree is an application of this. It adds to all nodes a component .root to which the top node tree tree is assigned. These components can be removed afterwards with RemoveRootParseTree.

5.2-6 GetTextXMLTree

‣ GetTextXMLTree( tree ) ( function )

The argument tree must be a node of a parse tree of some XML document, see ParseTreeXMLFile (5.2-1). This function collects the content of this and all included elements recursively into a string.

5.2-7 XMLElements

‣ XMLElements( tree, eltnames ) ( function )

The argument tree must be a node of a parse tree of some XML document, see ParseTreeXMLFile (5.2-1). This function returns a list of all subnodes of tree (possibly including tree) of elements with name given in the list of strings eltnames. Use "PCDATA" as name for leave nodes which contain the actual text of the document. As an abbreviation eltnames can also be a string which is then put in a one element list.

5.2-8 CheckAndCleanGapDocTree

‣ CheckAndCleanGapDocTree( tree ) ( function )

The argument tree of this function is a parse tree from ParseTreeXMLString (5.2-1) of some GAPDoc document. This function does an (incomplete) validity check of the document according to the document type declaration in gapdoc.dtd. It also does some additional checks which cannot be described in the DTD (like checking whether chapters and sections have a heading). For elements with element content the whitespace between these elements is removed.

In case of an error the break loop is entered and the position of the error in the original XML document is printed. With Show(); one can browse the original input in the Pager (Reference: Pager).

5.2-9 AddParagraphNumbersGapDocTree

‣ AddParagraphNumbersGapDocTree( tree ) ( function )

The argument tree must be an XML tree returned by ParseTreeXMLString (5.2-1) applied to a GAPDoc document. This function adds to each node of the tree a component .count which is of form [Chapter[, Section[, Subsection, Paragraph] ] ]. Here the first three numbers should be the same as produced by the LaTeX version of the document. Text before the first chapter is counted as chapter 0 and similarly for sections and subsections. Some elements are always considered to start a new paragraph.

5.2-10 InfoXMLParser

‣ InfoXMLParser ( info class )

The default level of this info class is 1. Functions like ParseTreeXMLString (5.2-1) are then printing some information, in particular in case of errors. You can suppress it by setting the level of InfoXMLParser to 0. With level 2 there may be some more information for debugging purposes.

5.2-11 XMLValidate

‣ XMLValidate( doc, dtdpath ) ( function )

The argument doc must be a string which is an XML document, and dtdpath is a path containing the corresponding DTD file.

Otherwise the document is validated via the external program xmllint via the function IO_PipeThroughWithError (IO: IO_PipeThroughWithError), and its resulting record is returned.

5.2-12 ValidateGAPDoc

‣ ValidateGAPDoc( doc ) ( function )

The argument doc must be a string which is a GAPDoc XML document or a pair of a string and list as returned by ComposedDocument (4.2-1) with argument info set to true.

Otherwise the document is validated using XMLValidate (5.2-11). If the validation was successful this function returns true. In the case of validation errors some information is printed and the result of XMLValidate (5.2-11) is returned.

gap> fn := Filename(DirectoriesPackageLibrary("gapdoc", ""), 
>                                             "3k+1/3k+1.xml");;
gap> doc := ComposedDocument("GAPDoc", "", fn, [], true);;
gap> doc[1][220] := 't';;
gap> check := ValidateGAPDoc(doc);;
ValidateGAPDoc found problems:
Line 11:  parser error : Opening and ending tag mismatch
   source position: /opt/gap/pkg/GAPDoc-1.6.4/3k+1/3k+1.xml, line 11

5.3 The Converters

Here are more details about the conversion programs for GAPDoc XML documents.

5.3-1 GAPDoc2LaTeX

‣ GAPDoc2LaTeX( tree ) ( function )

‣ SetGapDocLaTeXOptions( [...] ) ( function )

The argument tree for this function is a tree describing a GAPDoc XML document as returned by ParseTreeXMLString (5.2-1) (probably also checked with CheckAndCleanGapDocTree (5.2-8)). The output is a string containing a version of the document which can be written to a file and processed with LaTeX or pdfLaTeX (and probably BibTeX and makeindex).

The output uses the report document class and needs the following LaTeX packages: amssymb, inputenc, makeidx, color, fancyvrb, psnfss, pslatex, enumitem and hyperref. These are for example provided by the texlive distribution of TeX (which in turn is used for most TeX packages of current Linux distributions); see https://www.tug.org/texlive/.

In particular, the resulting pdf-output (and dvi-output) contains (internal and external) hyperlinks which can be very useful for onscreen browsing of the document.

The LaTeX processing also produces a file with extension .pnr which is GAP readable and contains the page numbers for all (sub)sections of the document. This can be used by GAP's online help; see AddPageNumbersToSix (5.3-4). Non-ASCII characters in the GAPDoc document are translated to LaTeX input in ASCII-encoding with the help of Encode (6.2-2) and the option "LaTeX". See the documentation of Encode (6.2-2) for how to proceed if you have a character which is not handled (yet).

This function works by running recursively through the document tree and calling a handler function for each GAPDoc XML element. Many of these handler functions (usually in GAPDoc2LaTeXProcs.<ElementName>) are not difficult to understand (the greatest complications are some commands for index entries, labels or the output of page number information). So it should be easy to adjust layout details to your own taste by slight modifications of the program.

Former versions of GAPDoc supported some XML processing instructions to add some extra lines to the preamble of the LaTeX document. Its use is now deprecated, use the much more flexible SetGapDocLaTeXOptions instead: The default layout of the resulting documents can be changed with SetGapDocLaTeXOptions. This changes parts of the header of the LaTeX file produced by GAPDoc. You can see the header with some placeholders by Page(GAPDoc2LaTeXProcs.Head);. The placeholders are filled with components from the record GAPDoc2LaTeXProcs.DefaultOptions. The arguments of SetGapDocLaTeXOptions can be records with the same structure (or parts of it) with different values. As abbreviations there are also three strings supported as arguments. These are "nocolor" for switching all colors to black; then "nopslatex" to use standard LaTeX fonts instead of postscript fonts; and finally "utf8" to choose UTF-8 as input encoding for the LaTeX document.

5.3-2 GAPDoc2Text

‣ GAPDoc2Text( tree[, bibpath][, width] ) ( function )

The argument tree for this function is a tree describing a GAPDoc XML document as returned by ParseTreeXMLString (5.2-1) (probably also checked with CheckAndCleanGapDocTree (5.2-8)). This function produces a text version of the document which can be used with GAP's online help (with the "screen" viewer, see SetHelpViewer (Reference: SetHelpViewer)). It includes title page, bibliography and index. The bibliography is made from BibXMLext or BibTeX databases, see 7. Their location must be given with the argument bibpath (as string or directory object).

The output is a record with one component for each chapter (with names "0", "1", ..., "Bib" and "Ind"). Each such component is again a record with the following components:

The result can be written into files with the command GAPDoc2TextPrintTextFiles (5.3-3).

As a side effect this function also produces the manual.six information which is used for searching in GAP's online help. This is stored in tree.six and can be printed into a manual.six file with PrintSixFile (5.3-5) (preferably after producing a LaTeX version of the document as well and adding the page number information to tree.six, see GAPDoc2LaTeX (5.3-1) and AddPageNumbersToSix (5.3-4)).

The text produced by this function contains some markup via ANSI escape sequences. The sequences used here are usually ignored by terminals. But the GAP help system will substitute them by interpreted color and attribute sequences (see TextAttr (6.1-2)) before displaying them. There is a default markup used for this but it can also be configured by the user, see SetGAPDocTextTheme (5.3-6). Furthermore, the text produced is in UTF-8 encoding. The encoding is also translated on the fly, if GAPInfo.TermEncoding is set to some encoding supported by Encode (6.2-2), e.g., "ISO-8859-1" or "latin1".

With the optional argument width a different length of the output text lines can be chosen. The default is 76 and all lines in the resulting text start with two spaces. This looks good on a terminal with a standard width of 80 characters and you probably don't want to use this argument.

5.3-3 GAPDoc2TextPrintTextFiles

‣ GAPDoc2TextPrintTextFiles( t[, path] ) ( function )

The first argument must be a result returned by GAPDoc2Text (5.3-2). The second argument is a path for the files to write, it can be given as string or directory object. The text of each chapter is written into a separate file with name chap0.txt, chap1.txt, ..., chapBib.txt, and chapInd.txt.

If you want to make your document accessible via the GAP online help you must put at least these files for the text version into a directory, together with the file manual.six, see PrintSixFile (5.3-5). Then specify the path to the manual.six file in the packages PackageInfo.g file, see Reference: The PackageInfo.g File.

Optionally you can add the dvi- and pdf-versions of the document which are produced with GAPDoc2LaTeX (5.3-1) to this directory. The files must have the names manual.dvi and manual.pdf, respectively. Also you can add the files of the HTML version produced with GAPDoc2HTML (5.3-7) to this directory, see GAPDoc2HTMLPrintHTMLFiles (5.3-8). The handler functions in GAP for this help format detect automatically which of the optional formats of a book are actually available.

5.3-4 AddPageNumbersToSix

‣ AddPageNumbersToSix( tree, pnrfile ) ( function )

Here tree must be the XML tree of a GAPDoc document, returned by ParseTreeXMLString (5.2-1). Running latex on the result of GAPDoc2LaTeX(tree) produces a file pnrfile (with extension .pnr). The command GAPDoc2Text(tree) creates a component tree.six which contains all information about the document for the GAP online help, except the page numbers in the .dvi, .ps, .pdf versions of the document. This command adds the missing page number information to tree.six.

5.3-5 PrintSixFile

‣ PrintSixFile( tree, bookname, fname ) ( function )

This function prints the .six file fname for a GAPDoc document stored in tree with name bookname. Such a file contains all information about the book which is needed by the GAP online help. This information must first be created by calls of GAPDoc2Text (5.3-2) and AddPageNumbersToSix (5.3-4).

5.3-6 SetGAPDocTextTheme

‣ SetGAPDocTextTheme( [optrec1[, optrec2], ...] ) ( function )

This utility function is for readers of the screen version of GAP manuals which are generated by the GAPDoc package. It allows to configure the color and attribute layout of the displayed text. There is a default which can be reset by calling this function without argument.

As an abbreviation the arguments optrec1 and so on can be strings for the known name of a theme. Information about valid names is shown with SetGAPDocTextTheme("");.

Otherwise, optrec1 and so on must be a record. Its entries overwrite the corresponding entries in the default and in previous arguments. To construct valid markup you can use TextAttr (6.1-2). Entries must be either pairs of strings, which are put before and after the corresponding text, or as an abbreviation it can be a single string. In the latter case, the second string is implied; if the string contains an escape sequence the second string is TextAttr.reset, otherwise the given string is used. The following components are recognized:

gap> # use no colors for GAP examples and 
gap> # change display of headings to bold green
gap> SetGAPDocTextTheme("noColorPrompt", 
>            rec(Heading:=Concatenation(TextAttr.bold, TextAttr.2)));

5.3-7 GAPDoc2HTML

‣ GAPDoc2HTML( tree[, bibpath[, gaproot]][, mtrans] ) ( function )

The argument tree for this function is a tree describing a GAPDoc XML document as returned by ParseTreeXMLString (5.2-1) (probably also checked with CheckAndCleanGapDocTree (5.2-8)). Without an mtrans argument this function produces an HTML version of the document which can be read with any Web-browser and also be used with GAP's online help (see SetHelpViewer (Reference: SetHelpViewer)). It includes title page, bibliography, and index. The bibliography is made from BibTeX databases. Their location must be given with the argument bibpath (as string or directory object, if not given the current directory is used). If the third argument gaproot is given and is a string then this string is interpreted as relative path to GAP's main root directory. Reference-URLs to external HTML-books which begin with the GAP root path are then rewritten to start with the given relative path. This makes the HTML-documentation portable provided a package is installed in some standard location below the GAP root.

The output is a record with one component for each chapter (with names "0", "1", ..., "Bib", and "Ind"). Each such component is again a record with the following components:

The HTML code produced with this converter conforms to the W3C specification XHTML 1.0 strict, see https://www.w3.org/TR/xhtml1. First, this means that the HTML files are valid XML files. Secondly, the extension strict says in particular that the code doesn't contain any explicit font or color information.

Mathematical formulae are handled as in the text converter GAPDoc2Text (5.3-2). We don't want to assume that the browser can use symbol fonts. Some GAP users like to browse the online help with lynx, see SetHelpViewer (Reference: SetHelpViewer), which runs inside the same terminal windows as GAP.

To view the generated files in graphical browsers, stylesheet files with layout configuration should be copied into the directory with the generated HTML files, see 5.3-9.

Currently, there are three variants of this converter available which handle mathematical formulae differently. They are accessed via the optional last mtrans argument.

If mtrans is set to "MathJax" the formulae are essentially translated as for LaTeX documents (there is no processing of <M> elements as decribed in 3.8-2). Inline formulae are delimited by \( and \) and displayed formulae by \[ and \]. With MathJax webpages can contain nicely formatted scalable and searchable formulae. The resulting files link by default to https://www.jsdelivr.com/ to get the MathJax script and fonts. This means that they can only be used on computers with internet access. An alternative URL can be set by overwriting GAPDoc2HTMLProcs.MathJaxURL before building the HTML version of a manual. This way a local installation of MathJax could be used. See https://www.mathjax.org/ for more details.

The following possibilities for mtrans are still supported, but since the MathJax approach seems much better, their use is deprecated.

If the argument mtrans is set to "Tth" it is assumed that you have installed the LaTeX to HTML translation program tth. This is used to translate the contents of the M, Math and Display elements into HTML code. Note that the resulting code is not compliant with any standard. Formally it is XHTML 1.0 Transitional, it contains explicit font specifications and the characters of mathematical symbols are included via their position in a Symbol font. Some graphical browsers can be configured to display this in a useful manner, check the Tth homepage for more details.

This function works by running recursively through the document tree and calling a handler function for each GAPDoc XML element. Many of these handler functions (usually in GAPDoc2TextProcs.<ElementName>) are not difficult to understand (the greatest complications are some commands for index entries, labels or the output of page number information). So it should be easy to adjust certain details to your own taste by slight modifications of the program.

The result of this converter can be written to files with the command GAPDoc2HTMLPrintHTMLFiles (5.3-8).

There are two user preferences for reading the HTML manuals produced by GAPDoc. A user can choose among several style files which determine the appearance of the manual pages with SetUserPreference("GAPDoc", "HTMLStyle", [...]); where the list in the third argument are arguments for SetGAPDocHTMLStyle (5.3-11). The second preference is set by SetUserPreference("GAPDoc", "UseMathJax", ...); where the third argument is true or false (default). If this is set to true, the GAP help system displays the MathJax version of the HTML manuals.

5.3-8 GAPDoc2HTMLPrintHTMLFiles

‣ GAPDoc2HTMLPrintHTMLFiles( t[, path] ) ( function )

The first argument must be a result returned by GAPDoc2HTML (5.3-7). The second argument is a path for the files to write, it can be given as string or directory object. The text of each chapter is written into a separate file with name chap0.html, chap1.html, ..., chapBib.html, and chapInd.html.

The MathJax versions are written to files chap0_mj.html, ..., chapInd_mj.html.

The experimental version which is produced with tth uses different names for the files, namely chap0_sym.html, and so on for files which need symbol fonts.

You should also add stylesheet files to the directory with the HTML files, see 5.3-9.

5.3-9 Stylesheet files

For graphical browsers the layout of the generated HTML manuals can be highly configured by cascading stylesheet (CSS) and javascript files. Such files are provided in the styles directory of the GAPDoc package.

We recommend that these files are copied into each manual directory (such that each of them is selfcontained). There is a utility function CopyHTMLStyleFiles (5.3-10) which does this. Of course, these files may be changed or new styles may be added. New styles may also be sent to the GAPDoc authors for possible inclusion in future versions.

The generated HTML files refer to the file manual.css which conforms to the W3C specification CSS 2.0, see https://www.w3.org/TR/REC-CSS2, and the javascript file manual.js (only in browsers which support CSS or javascript, respectively; but the HTML files are also readable without any of them). To add a style mystyle one or both of mystyle.css and mystyle.js must be provided; these can overwrite default settings and add new javascript functions. For more details see the comments in manual.js.

5.3-10 CopyHTMLStyleFiles

‣ CopyHTMLStyleFiles( dir ) ( function )

This utility function copies the *.css and *.js files from the styles directory of the GAPDoc package into the directory dir.

5.3-11 SetGAPDocHTMLStyle

‣ SetGAPDocHTMLStyle( [style1[, style2], ...] ) ( function )

This utility function is for readers of the HTML version of GAP manuals which are generated by the GAPDoc package. It allows to configure the display style of the manuals. This will only have an effect if you are using a browser that supports javascript. There is a default which can be reset by calling this function without argument.

The arguments style1 and so on must be strings. You can find out about the valid strings by following the [Style] link on top of any manual page. (Going back to the original page, its address has a setting for GAPDocStyle which is the list of strings, separated by commas, you want to use here.)

gap> # show/hide subsections in tables on contents only after click,
gap> # and don't use colors in GAP examples
gap> SetGAPDocHTMLStyle("toggless", "nocolorprompt");

5.3-12 InfoGAPDoc

‣ InfoGAPDoc ( info class )

The default level of this info class is 1. The converter functions for GAPDoc documents are then printing some information. You can suppress this by setting the level of InfoGAPDoc to 0. With level 2 there may be some more information for debugging purposes.

5.3-13 SetGapDocLanguage

‣ SetGapDocLanguage( [lang] ) ( function )

The GAPDoc converter programs sometimes produce text which is not explicit in the document, e.g., headers like Abstract, Appendix, links to Next Chapter, variable types function and so on.

With SetGapDocLanguage the language for these texts can be changed. The argument lang must be a string. Calling without argument or with a language name for which no translations are available is the same as using the default "english".

If your language lang is not yet available, look at the record GAPDocTexts.english and translate all the strings to lang. Then assign this record to GAPDocTexts.(lang) and send it to the GAPDoc authors for inclusion in future versions of GAPDoc. (Currently, there are translations for english, german, russian and ukrainian.)

Further hints: To get strings produced by LaTeX right you will probably use the babel package with option lang, see SetGapDocLaTeXOptions (5.3-1). If lang cannot be encoded in latin1 encoding you can consider the use of "utf8" with SetGapDocLaTeXOptions (5.3-1).

5.4 Testing Manual Examples

We also provide some tools to check and adjust the examples given in <Example>-elements.

Former versions of GAPDoc provided functions ManualExamples and TestManualExamples. These functions are still available, but no longer documented. Their use is deprecated.

5.4-1 ExtractExamples

‣ ExtractExamples( path, main, files, units[, withLog] ) ( function )

‣ ExtractExamplesXMLTree( tree, units[, withLog] ) ( function )

The argument tree must be a parse tree of a GAPDoc document, see ParseTreeXMLFile (5.2-1). The function ExtractExamplesXMLTree returns a data structure representing the <Example> elements of the document. The return value can be used with RunExamples (5.4-2) to check and optionally update the examples of the document.

Depending on the argument units several examples are collected in one list. Recognized values for units are "Chapter", "Section", "Subsection" or "Single". The latter means that each example is in a separate list. For all other value of units just one list with all examples is returned.

The arguments path, main and files of ExtractExamples are the same as for ComposedDocument (4.2-1). This function first contructs and parses the GAPDoc document and then applies ExtractExamplesXMLTree.

If the optional argument withLog is given and true then <Log> elements are handled like <Example> elements. This allows to put examples which can only run under certain conditions, e.g., when certain external programs are available, into <Log> elements. (Put example code which should also not be included by this variant into <Listing> elements.)

5.4-2 RunExamples

‣ RunExamples( exmpls[, optrec] ) ( function )

The argument exmpls must be the output of a call to ExtractExamples (5.4-1) or ExtractExamplesXMLTree (5.4-1). The optional argument optrec must be a record, its components can change the default behaviour of this function.

By default this function runs the GAP input of all examples and compares the actual output with the output given in the examples. If differences occur these are displayed together with information on the location of the source code of that example. Before running the examples in each unit (entry of exmpls) the function START_TEST (Reference: START_TEST) is called and the screen width is set to 72 characters.

5 The Converters and an XML Parser