<!-- $Id: conv.xml,v 1.27 2007/09/25 09:30:35 gap Exp $ --> <Chapter Label="ch:conv"> <Heading>The Converters and an XML Parser</Heading> 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.<P/> Currently the following output formats are provided: text for browsing inside a terminal running &GAP;, &LaTeX; with <C>hyperref</C>-package for cross references via hyperlinks and HTML for reading with a Web-browser.<P/> <Section Label="MakeDoc"> <Heading>Producing Documentation from Source Files</Heading> 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 <F>MyBook.xml</F> of a book <C>"MyBook"</C> in the directory <F>/my/book/path</F>. This contains <C><#Include ...></C>-statements as explained in Chapter <Ref Sect="Distributing"/>. These refer to some other files as well as pieces of text which are found in the comments of some &GAP; source files <F>../lib/a.gd</F> and <F>../lib/b.gi</F> (relative to the path above). A &BibTeX; database <F>MyBook.bib</F> for the citations is also in the directory given above. We want to produce a text-, <C>pdf-</C> and HTML-version of the document. (A &LaTeX; version of the manual is produced, so it is also easy to compile <C>dvi</C>-, and postscript-versions.)<P/> All the commands shown in this Section are collected in the single function <Ref Func="MakeGAPDocDoc"/>.<P/> First we construct the complete XML-document as a string with <Ref Func="ComposedDocument"/>. This interprets recursively the <C><#Include ...></C>-statements. <Log> 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);; </Log> Now <C>doc</C> 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. <P/> Next we parse the document and store its structure in a tree-like data structure. The commands for this are <Ref Func="ParseTreeXMLString"/> and <Ref Func="CheckAndCleanGapDocTree"/>. <Log> gap> r := ParseTreeXMLString(doc[1], doc[2]);; gap> CheckAndCleanGapDocTree(r); true </Log> We start to produce a text version of the manual, which can be read in a terminal (window). The command is <Ref Func="GAPDoc2Text"/>. This produces a record with the actual text and some additional information. The text can be written chapter-wise into files with <Ref Func="GAPDoc2TextPrintTextFiles"/>. The names of these files are <F>chap0.txt</F>, <F>chap1.txt</F> 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 <Ref Func="GAPDoc2Text"/> the location of the &BibTeX; database by specifying a <C>path</C> as second argument. <Log> gap> t := GAPDoc2Text(r, path);; gap> GAPDoc2TextPrintTextFiles(t, path); </Log> This command constructs all parts of the document including table of contents, bibliography and index. The functions <Ref Func="FormatParagraph"/> for formatting text paragraphs and <Ref Func="ParseBibFiles"/> for reading &BibTeX; files with &GAP; may be of independent interest.<P/> 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 <C>pdf</C>-versions of the manual. <P/> Next we produce a &LaTeX; version of the document. <Ref Func="GAPDoc2LaTeX"/> returns a string containing the &LaTeX; source. The utility function <Ref Func="FileString"/> writes the content of a string to a file, we choose <F>MyBook.tex</F>. <Log> gap> l := GAPDoc2LaTeX(r);; gap> FileString(Filename(path, Concatenation(bookname, ".tex")), l); </Log> Assuming that you have a sufficiently good installation of &TeX; available (see <Ref Func="GAPDoc2LaTeX"/> for details) this can be processed with a series of commands like in the following example. <Log> cd /my/book/path pdflatex MyBook bibtex MyBook pdflatex MyBook makeindex MyBook pdflatex MyBook mv MyBook.pdf manual.pdf </Log> After this we have a <C>pdf</C>-version of the document in the file <F>manual.pdf</F>. It contains hyperlink information which can be used with appropriate browsers for convenient reading of the document on screen (e.g., <C>xpdf</C> is nice because it allows remote calls to display named locations of the document). Of course, we could also use other commands like <C>latex</C> or <C>dvips</C> to process the &LaTeX; source file. Furthermore we have produced a file <F>MyBook.pnr</F> which is &GAP;-readable and contains the page number information for each (sub-)section of the document. <P/> We can add this page number information to the indexing information collected by the text converter and then print a <F>manual.six</F> file which is read by &GAP; when the manual is loaded. This is done with <Ref Func="AddPageNumbersToSix"/> and <Ref Func="PrintSixFile"/>. <Log> gap> AddPageNumbersToSix(r, Filename(path, "MyBook.pnr")); gap> PrintSixFile(Filename(path, "manual.six"), r, bookname); </Log> Finally we produce an HTML-version of the document and write it (chapter-wise) into files <F>chap0.html</F>, <F>chap1.html</F> and so on. They can be read with any Web-browser. The commands are <Ref Func="GAPDoc2HTML"/> and <Ref Func="GAPDoc2HTMLPrintHTMLFiles"/>. We also add a link from <F>manual.html</F> to <F>chap0.html</F>. You probably want to add a file <F>manual.css</F>, see <Ref Func="GAPDoc2HTMLPrintHTMLFiles"/> for more details. The argument <C>path</C> of <Ref Func="GAPDoc2HTML"/> specifies the directory containing the &BibTeX; database files. <Log> gap> h := GAPDoc2HTML(r, path);; gap> GAPDoc2HTMLPrintHTMLFiles(h, path); </Log> <ManSection > <Func Arg="path, main, files, bookname[, gaproot]" Name="MakeGAPDocDoc" /> <Description> This function collects all the commands for producing a text-, <C>pdf</C>- and HTML-version of a &GAPDoc; document as described in Section <Ref Sect="MakeDoc"/>. It checks the <C>.log</C> file from the call of <C>pdflatex</C> and reports if there are errors, warnings or overfull boxes.<P/> <Emph>Note:</Emph> If this function works for you depends on your operating system and installed software. It will probably work on most <C>UNIX</C> 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. <P/> Here <A>path</A> must be the directory (as string or directory object) containing the main file <A>main</A> of the document (given with or without the <C>.xml</C> extension. The argument <A>files</A> is a list of (probably source code) files relative to <A>path</A> which contain pieces of documentation which must be included in the document, see Chapter <Ref Chap="Distributing"/>. And <A>bookname</A> is the name of the book used by &GAP;'s online help. The optional argument <A>gaproot</A> must be a string which gives the relative path from <A>path</A> to the main &GAP; root directory. If this is given, the HTML files are produced with relative paths to external books.<P/> Experimental: <Ref Func="MakeGAPDocDoc"/> can be called with additional arguments <C>"Tth"</C> and/or <C>"MathML"</C>. If these are given additional variants of the HTML conversion are called, see <Ref Func="GAPDoc2HTML"/> for details.<P/> It is possible to use &GAPDoc; with other languages than English, see <Ref Func="SetGapDocLanguage"/> for more details.<P/> </Description> </ManSection> </Section> <Section Label="ParseXML"> <Heading>Parsing XML Documents</Heading> 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 <Ref Func="ApplyToNodesParseTree"/>. <#Include Label="GetTextXMLTree"> <#Include Label="XMLElements"> And here are utilities for processing &GAPDoc; XML documents. <#Include Label="CheckAndCleanGapDocTree"> <#Include Label="AddParagraphNumbersGapDocTree"> <#Include Label="InfoXMLParser"> </Section> <Section Label="Converters"> <Heading>The Converters</Heading> 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"> <#Include Label="SetGapDocLanguage"> </Section> <Section Label="Sec:TestExample"> <Heading>Testing Manual Examples</Heading> We also provide some tools to check the examples given in <C><Example></C>-elements. <#Include Label="ManualExamples"> <#Include Label="TestExamples"> </Section> </Chapter>