  
  [1m[4m[31m4. Distributing a Document into Several Files[0m
  
  In  [1mGAPDoc[0m there are facilities to distribute a document into 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. Basically, there is only a
  set  of  conventions how this is done and some tools to collect the text for
  further processing.
  
  
  [1m[4m[31m4.1 The Conventions[0m
  
  Pieces of documentation that shall be incorporated into another document are
  marked as follows:
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m##  <#GAPDoc Label="MyPiece">[0m
    [22m[35m##  <E>This</E> is the piece.[0m
    [22m[35m##  The hash characters are removed.[0m
    [22m[35m##  <#/GAPDoc>[0m
  [22m[35m------------------------------------------------------------------[0m
  
  This piece is then included into another file by a statement like: [22m[32m<#Include
  Label="MyPiece">[0m Here are the exact rules, how pieces are gathered:
  
  --    All  lines  up  to  a line containing the character sequence "[22m[32m<#GAPDoc
        Label="[0m"  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
        "[22m[32m<#/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  [1mGAPDoc[0m  documentation  files all statements of the form "[22m[32m<#Include
        Label="Key">[0m"  are  replaced by the sequence of lines stored under the
        label [22m[32mKey[0m.
  
  --    Additionally,  every  occurrence of a statement of the form "[22m[32m<#Include
        SYSTEM  "Filename">[0m"  is  replaced  by the whole file stored under the
        name [22m[32mFilename[0m in the file system.
  
  --    These substitutions are done recursively (although one should probably
        avoid to use this extensively).
  
  Here is another example:
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m# # <#GAPDoc Label="AnotherPiece">  some characters[0m
    [22m[35m# # This text is not indented.[0m
    [22m[35m#  This text is indented by one blank.[0m
    [22m[35m#Not indented.[0m
    [22m[35m#<#/GAPDoc>[0m
  [22m[35m------------------------------------------------------------------[0m
  
  replaces [22m[32m<#Include Label="AnotherPiece">[0m by
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mThis text is not indented.[0m
    [22m[35m This text is indented by one blank. [0m
    [22m[35mNot indented.[0m
  [22m[35m------------------------------------------------------------------[0m
  
  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  [1mGAPDoc[0m  there is the [1mGAP[0m function [1m[34mComposedXMLString[0m
  ([1m4.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 an XML
  document.
  
  
  [1m[4m[31m4.2 A Tool for Collecting a Document[0m
  
  [1m[4m[31m4.2-1 ComposedXMLString[0m
  
  [1m[34m> ComposedXMLString( [0m[22m[34mpath, main, source[0m[1m[34m ) __________________________[0mfunction
  [1mReturns:[0m  XML document as string
  
  This  function returns a string containing a [1mGAPDoc[0m XML document constructed
  from several source files.
  
  Here  [22m[34mpath[0m must be a path to some directory (as string or directory object),
  [22m[34mmain[0m  the  name of a file in this directory and [22m[34msource[0m a list of file names,
  all of these relative to [22m[34mpath[0m. The document is constructed via the mechanism
  described in Section [1m4.1[0m.
  
  First   the   files   given   in   [22m[34msource[0m   are   scanned   for   chunks  of
  [1mGAPDoc[0m-documentation  marked  by [22m[32m<#GAPDoc Label="...">[0m and [22m[32m</#GAPDoc>[0m pairs.
  Then  the  file  [22m[34mmain[0m  is  read and all [22m[32m<#Include ... >[0m-tags are substituted
  recursively  by  other  files  or chunks of documentation found in the first
  step, respectively.
  
  [22m[35m-----------------------------  Log  ------------------------------[0m
    [22m[35mgap> doc := ComposedXMLString("/my/dir", "manual.xml", [0m
    [22m[35m> ["../lib/func.gd", "../lib/func.gi"]);;[0m
  [22m[35m------------------------------------------------------------------[0m
  
