[1X4 Distributing a Document into Several Files[0X In [5XGAPDoc[0m 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). [1X4.1 The Conventions[0X In this description we use the string [10XGAPDoc[0m for marking pieces of a document to collect. Pieces of documentation that shall be incorporated into another document are marked as follows: [4X--------------------------- Example ----------------------------[0X [4X## <#GAPDoc Label="MyPiece">[0X [4X## <E>This</E> is the piece.[0X [4X## The hash characters are removed.[0X [4X## <#/GAPDoc>[0X [4X------------------------------------------------------------------[0X This piece is then included into another file by a statement like: [10X<#Include Label="MyPiece">[0m Here are the exact rules, how pieces are gathered: -- All lines up to a line containing the character sequence "[10X<#GAPDoc Label="[0m" (exactly one space character) are ignored. The characters on the same line before this sequence are stored as "prefix". The characters after the sequence up to the next double quotes character are stored as "label". All other characters in the line are ignored. -- The following lines up to a line containing the character sequence "[10X<#/GAPDoc>[0m" are stored under the label. These lines are processed as follows: The longest possible substring from the beginning of the line that equals the corresponding substring of the prefix is removed. Having stored a list of labels and pieces of text gathered as above this can be used as follows. -- In [5XGAPDoc[0m documentation files all statements of the form "[10X<#Include Label="Key">[0m" are replaced by the sequence of lines stored under the label [10XKey[0m. -- Additionally, every occurrence of a statement of the form "[10X<#Include SYSTEM "Filename">[0m" is replaced by the whole file stored under the name [10XFilename[0m in the file system. -- These substitutions are done recursively (although one should probably avoid to use this extensively). Here is another example: [4X--------------------------- Example ----------------------------[0X [4X# # <#GAPDoc Label="AnotherPiece"> some characters[0X [4X# # This text is not indented.[0X [4X# This text is indented by one blank.[0X [4X#Not indented.[0X [4X#<#/GAPDoc>[0X [4X------------------------------------------------------------------[0X replaces [10X<#Include Label="AnotherPiece">[0m by [4X--------------------------- Example ----------------------------[0X [4XThis text is not indented.[0X [4X This text is indented by one blank. [0X [4XNot indented.[0X [4X------------------------------------------------------------------[0X 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 [5XGAPDoc[0m there is the [5XGAP[0m function [2XComposedDocument[0m ([14X4.2-1[0m) 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. [1X4.2 A Tool for Collecting a Document[0X [1X4.2-1 ComposedDocument[0m [2X> ComposedDocument( [0X[3Xtagname, path, main, source[, info][0X[2X ) __________[0Xfunction [2X> ComposedXMLString( [0X[3Xpath, main, source[, info][0X[2X ) __________________[0Xfunction [6XReturns:[0X a document as string, or a list with this string and information about the source positions The argument [3Xtagname[0m is the string used for the pseudo elements which mark the pieces of a document to collect. (In [14X4.1[0m we used [10XGAPDoc[0m as [3Xtagname[0m. The second function [2XComposedXMLString[0m[10X( ... )[0m is an abbreviation for [2XComposedDocument[0m[10X("GAPDoc", ... )[0m. The argument [3Xpath[0m must be a path to some directory (as string or directory object), [3Xmain[0m the name of a file in this directory and [3Xsource[0m a list of file names, all of these relative to [3Xpath[0m. The document is constructed via the mechanism described in Section [14X4.1[0m. First the files given in [3Xsource[0m are scanned for chunks of the document marked by [10X<#[3Xtagname[0m[10X Label="...">[0m and [10X</#[3Xtagname[0m[10X>[0m pairs. Then the file [3Xmain[0m is read and all [10X<#Include ... >[0m-tags are substituted recursively by other files or chunks of documentation found in the first step, respectively. If the optional argument [3Xinfo[0m is given and set to [9Xtrue[0m this function returns a list [10X[str, origin][0m, where [10Xstr[0m is a string containing the composed document and [10Xorigin[0m is a sorted list of entries of the form [10X[pos, filename, line][0m. Here [10Xpos[0m runs through all character positions of starting lines or text pieces from different files in [10Xstr[0m. The [10Xfilename[0m and [10Xline[0m describe the origin of this part of the collected document. Without the fourth argument only the string [10Xstr[0m is returned. [4X--------------------------- Example ----------------------------[0X [4Xgap> doc := ComposedDocument("GAPDoc", "/my/dir", "manual.xml", [0X [4X> ["../lib/func.gd", "../lib/func.gi"], true);;[0X [4X------------------------------------------------------------------[0X [1X4.2-2 OriginalPositionDocument[0m [2X> OriginalPositionDocument( [0X[3Xsrcinfo, pos[0X[2X ) _________________________[0Xfunction [6XReturns:[0X A pair [10X[filename, linenumber][0m. Here [3Xsrcinfo[0m must be a data structure as returned as second entry by [2XComposedDocument[0m ([14X4.2-1[0m) called with [3Xinfo[0m=[9Xtrue[0m. It returns for a given position [3Xpos[0m in the composed document the file name and line number from which that text was collected.