1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
|
<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><#Include></C></Index>
<Index Key="GAPDoc"><C><#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><#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><#GAPDoc 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
(which should not contain whitespace) 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><#/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><#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><#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><#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">
<#Include Label="FilenameGAP">
</Section>
</Chapter>
|
