Goto Chapter: Top 1 2 3 4 5 6 7 A B C Bib Ind
 [Top of Book]  [Contents]   [Previous Chapter]   [Next Chapter] 

4 Distributing a Document into Several Files
 4.1 The Conventions
 4.2 A Tool for Collecting a Document

4 Distributing a Document into Several Files

In GAPDoc there are facilities to distribute a single document over several files. This is for example interesting, if one wants to store the documentation of some code in the same file as the code itself. Or, if one just wants to store chapters of a document in separate files. There is a set of conventions how this is done and some tools to collect the text for further processing.

The technique can also be used to distribute and collect other types of documents into respectively from several files (e.g., source code, examples).

4.1 The Conventions

In this description we use the string GAPDoc for marking pieces of a document to collect.

Pieces of documentation that shall be incorporated into another document are marked as follows:

##  <#GAPDoc Label="MyPiece">
##  <E>This</E> is the piece.
##  The hash characters are removed.
##  <#/GAPDoc>

This piece is then included into another file by a statement like: <#Include Label="MyPiece"> Here are the exact rules, how pieces are gathered:

Having stored a list of labels and pieces of text gathered as above this can be used as follows.

Here is another example:

# # <#GAPDoc Label="AnotherPiece">  some characters
# # This text is not indented.
#  This text is indented by one blank.
#Not indented.
#<#/GAPDoc>

replaces <#Include Label="AnotherPiece"> by

This text is not indented.
 This text is indented by one blank. 
Not indented.

Since these rules are very simple it is quite easy to write a program in almost any programming language which does this gathering of text pieces and the substitutions. In GAPDoc there is the GAP function ComposedDocument (4.2-1) which does this.

Note that the XML-tag-like markup we have used here is not a legal XML markup, since the hash character is not allowed in element names. The mechanism described here is a preprocessing step which composes a document.

4.2 A Tool for Collecting a Document

4.2-1 ComposedDocument
‣ ComposedDocument( tagname, path, main, source[, info] )( function )
‣ ComposedXMLString( path, main, source[, info] )( function )

Returns: a document as string, or a list with this string and information about the source positions

The argument tagname is the string used for the pseudo elements which mark the pieces of a document to collect. (In 4.1 we used GAPDoc as tagname. The second function ComposedXMLString( ... ) is an abbreviation for ComposedDocument("GAPDoc", ... ).

The argument path must be a path to some directory (as string or directory object), main the name of a file and source a list of file names. These file names are relative to path, except they start with "/" to specify an absolute path or they start with "gap://" to specify a file relative to the GAP roots (see FilenameGAP (4.2-3)). The document is constructed via the mechanism described in Section 4.1.

First the files given in source are scanned for chunks of the document marked by <#tagname Label="..."> and </#tagname> pairs. Then the file main is read and all <#Include ... >-tags are substituted recursively by other files or chunks of documentation found in the first step, respectively.

If the optional argument info is given and set to true this function returns a list [str, origin], where str is a string containing the composed document and origin is a sorted list of entries of the form [pos, filename, line]. Here pos runs through all character positions of starting lines or text pieces from different files in str. The filename and line describe the origin of this part of the collected document.

Without the fourth argument only the string str is returned.

By default ComposedDocument runs into an error if an <#Include ...>-tag cannot be substituted (because a file or chunk is missing). This behaviour can be changed by setting DOCCOMPOSEERROR := false;. Then the missing parts are substituted by a short note about what is missing. Of course, this feature is only useful if the resulting document is a valid XML document (e.g., when the missing pieces are complete paragraphs or sections).

gap> doc := ComposedDocument("GAPDoc", "/my/dir", "manual.xml", 
> ["../lib/func.gd", "../lib/func.gi"], true);;

4.2-2 OriginalPositionDocument
‣ OriginalPositionDocument( srcinfo, pos )( function )

Returns: A pair [filename, linenumber].

Here srcinfo must be a data structure as returned as second entry by ComposedDocument (4.2-1) called with info=true. It returns for a given position pos in the composed document the file name and line number from which that text was collected.

4.2-3 FilenameGAP
‣ FilenameGAP( fname )( function )

Returns: file name as string or fail

This functions returns the full path of a file with name fname relative to a GAP root path, or fail if such a file does not exist. The argument fname can optionally start with the prefix "gap://" which will be removed.

gap> FilenameGAP("hsdkfhs.g");
fail
gap> FilenameGAP("lib/system.g");
"/usr/local/gap4/lib/system.g"
gap> FilenameGAP("gap://lib/system.g");
"/usr/local/gap4/lib/system.g"
 [Top of Book]  [Contents]   [Previous Chapter]   [Next Chapter] 
Goto Chapter: Top 1 2 3 4 5 6 7 A B C Bib Ind

generated by GAPDoc2HTML