  
  [1X4. Distributing a Document into Several Files[0X
  
  In  [5XGAPDoc[0X 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[0X  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">[0X Here are the exact rules, how pieces are gathered:
  
  --    All   lines   up   to   a   line  containing  the  character  sequence
        "[10X<#GAPDoc Label="[0X"  (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>[0X"  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[0X  documentation  files all statements of the form "[10X<#Include
        Label="Key">[0X"  are  replaced by the sequence of lines stored under the
        label [10XKey[0X.
  
  --    Additionally,  every  occurrence of a statement of the form "[10X<#Include
        SYSTEM  "Filename">[0X"  is  replaced  by the whole file stored under the
        name [10XFilename[0X 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">[0X 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[0X  there  is the [5XGAP[0X function [2XComposedDocument[0X
  ([14X4.2-1[0X) 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[0X
  
  [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[0X is the string used for the pseudo elements which mark
  the  pieces of a document to collect. (In [14X4.1[0X we used [10XGAPDoc[0X as [3Xtagname[0X. The
  second   function   [2XComposedXMLString[0X[10X(   ...   )[0X   is  an  abbreviation  for
  [2XComposedDocument[0X[10X("GAPDoc", ... )[0X.
  
  The  argument  [3Xpath[0X must be a path to some directory (as string or directory
  object), [3Xmain[0X the name of a file in this directory and [3Xsource[0X a list of file
  names,  all  of  these relative to [3Xpath[0X. The document is constructed via the
  mechanism described in Section [14X4.1[0X.
  
  First  the  files  given  in  [3Xsource[0X  are scanned for chunks of the document
  marked  by  [10X<#[3Xtagname[0X Label="...">[0X and [10X</#[3Xtagname[0X>[0X pairs. Then the file [3Xmain[0X
  is  read  and  all [10X<#Include ... >[0X-tags are substituted recursively by other
  files  or  chunks of documentation found in the first step, respectively. If
  the  optional argument [3Xinfo[0X is given and set to [9Xtrue[0X this function returns a
  list  [10X[str,  origin][0X, where [10Xstr[0X is a string containing the composed document
  and  [10Xorigin[0X  is  a sorted list of entries of the form [10X[pos, filename, line][0X.
  Here  [10Xpos[0X  runs  through  all  character positions of starting lines or text
  pieces  from  different  files  in  [10Xstr[0X.  The [10Xfilename[0X and [10Xline[0X describe the
  origin  of  this part of the collected document. Without the fourth argument
  only the string [10Xstr[0X is returned.
  
  [4X-----------------------------  Log  ------------------------------[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[0X
  
  [2X> OriginalPositionDocument( [0X[3Xsrcinfo, pos[0X[2X ) _________________________[0Xfunction
  [6XReturns:[0X  A pair [10X[filename, linenumber][0X.
  
  Here  [3Xsrcinfo[0X  must  be  a  data  structure  as  returned as second entry by
  [2XComposedDocument[0X  ([14X4.2-1[0X)  called  with  [3Xinfo[0X=[9Xtrue[0X.  It  returns for a given
  position  [3Xpos[0X  in  the  composed document the file name and line number from
  which that text was collected.
  
