<!-- $Id: distr.xml,v 1.7 2007/05/18 14:37:09 gap Exp $ -->
<Chapter Label="Distributing">
<Heading>Distributing a Document into Several Files</Heading>

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. <P/>

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

<Section Label="DistrConv">
<Index Key="Include"><C>&lt;#Include></C></Index>
<Index Key="GAPDoc"><C>&lt;#GAPDoc></C></Index>

<Heading>The Conventions</Heading>

In this description we use the string <C>GAPDoc</C> for marking pieces
of a document to collect.
<P/>

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

<Listing Type="Example">
<![CDATA[##  <#GAPDoc Label="MyPiece">
##  <E>This</E> is the piece.
##  The hash characters are removed.
##  <#/GAPDoc>]]>
</Listing>

This piece is then included into another file by a statement like:
<!-- <Listing Type="Example"> -->
<C>&lt;#Include Label="MyPiece"></C>
<!--</Listing> -->

Here are the exact rules, how pieces are gathered:

<List>
<Item>
All lines up to a line containing the character sequence 
<Q><C>&lt;#GAPDoc&nbsp;Label="</C></Q> (exactly one space
character) are ignored. The characters
on the same line before this sequence are stored as <Q>prefix</Q>. 
The characters after the sequence up to the next double quotes character
are stored as <Q>label</Q>. All other characters in the line are ignored. 
</Item>

<Item>
The following lines up to a line containing the character sequence
<Q><C>&lt;#/GAPDoc></C></Q> 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.
</Item>
</List>

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

<List>
<Item>
In &GAPDoc; documentation files all statements
of the form <Q><C>&lt;#Include Label="Key"></C></Q> are 
replaced by the 
sequence of lines stored under the label <C>Key</C>. 
</Item>

<Item>
Additionally, every occurrence of a statement of the form
<Q><C>&lt;#Include SYSTEM "Filename"></C></Q> is replaced by the
whole file stored under the name <C>Filename</C> in the file system.
</Item>

<Item>
These substitutions are done recursively (although one should probably avoid to use this extensively).
</Item>
</List>

Here is another example:

<Listing Type="Example">
<![CDATA[# # <#GAPDoc Label="AnotherPiece">  some characters
# # This text is not indented.
#  This text is indented by one blank.
#Not indented.
#<#/GAPDoc>]]>
</Listing>

replaces <C>&lt;#Include Label="AnotherPiece"></C> by

<Listing Type="Example">
<![CDATA[This text is not indented.
 This text is indented by one blank. 
Not indented.]]>
</Listing>

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  <Ref
Func="ComposedDocument"/> which does this.<P/>

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.

</Section>

<Section >
<Heading>A Tool for Collecting a Document</Heading>

<#Include Label="ComposedDocument">

<#Include Label="OriginalPositionDocument">

</Section>

</Chapter>