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
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>GAP (GAPDoc) - Chapter 4: Distributing a Document into Several Files</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
<meta name="generator" content="GAPDoc2HTML" />
<link rel="stylesheet" type="text/css" href="manual.css" />
<script src="manual.js" type="text/javascript"></script>
<script type="text/javascript">overwriteStyle();</script>
</head>
<body class="chap4" onload="jscontent()">
<div class="chlinktop"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a> <a href="chap1.html">1</a> <a href="chap2.html">2</a> <a href="chap3.html">3</a> <a href="chap4.html">4</a> <a href="chap5.html">5</a> <a href="chap6.html">6</a> <a href="chap7.html">7</a> <a href="chapA.html">A</a> <a href="chapB.html">B</a> <a href="chapC.html">C</a> <a href="chapBib.html">Bib</a> <a href="chapInd.html">Ind</a> </div>
<div class="chlinkprevnexttop"> <a href="chap0.html">[Top of Book]</a> <a href="chap0.html#contents">[Contents]</a> <a href="chap3.html">[Previous Chapter]</a> <a href="chap5.html">[Next Chapter]</a> </div>
<p id="mathjaxlink" class="pcenter"><a href="chap4_mj.html">[MathJax on]</a></p>
<p><a id="X7A3355C07F57C280" name="X7A3355C07F57C280"></a></p>
<div class="ChapSects"><a href="chap4.html#X7A3355C07F57C280">4 <span class="Heading">Distributing a Document into Several Files</span></a>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap4.html#X7CE078A07E8256DC">4.1 <span class="Heading">The Conventions</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap4.html#X81E07B0F83EBDA5F">4.2 <span class="Heading">A Tool for Collecting a Document</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap4.html#X857D77557D12559D">4.2-1 ComposedDocument</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap4.html#X86D1141E7EDCAAC8">4.2-2 OriginalPositionDocument</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap4.html#X81E67E4678FB6843">4.2-3 FilenameGAP</a></span>
</div></div>
</div>
<h3>4 <span class="Heading">Distributing a Document into Several Files</span></h3>
<p>In <strong class="pkg">GAPDoc</strong> 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>
<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>
<p><a id="X7CE078A07E8256DC" name="X7CE078A07E8256DC"></a></p>
<h4>4.1 <span class="Heading">The Conventions</span></h4>
<p>In this description we use the string <code class="code">GAPDoc</code> for marking pieces of a document to collect.</p>
<p>Pieces of documentation that shall be incorporated into another document are marked as follows:</p>
<div class="example"><pre>
## <#GAPDoc Label="MyPiece">
## <E>This</E> is the piece.
## The hash characters are removed.
## <#/GAPDoc>
</pre></div>
<p>This piece is then included into another file by a statement like: <code class="code"><#Include Label="MyPiece"></code> Here are the exact rules, how pieces are gathered:</p>
<ul>
<li><p>All lines up to a line containing the character sequence <q><code class="code"><#GAPDoc Label="</code></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.</p>
</li>
<li><p>The following lines up to a line containing the character sequence <q><code class="code"><#/GAPDoc></code></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.</p>
</li>
</ul>
<p>Having stored a list of labels and pieces of text gathered as above this can be used as follows.</p>
<ul>
<li><p>In <strong class="pkg">GAPDoc</strong> documentation files all statements of the form <q><code class="code"><#Include Label="Key"></code></q> are replaced by the sequence of lines stored under the label <code class="code">Key</code>.</p>
</li>
<li><p>Additionally, every occurrence of a statement of the form <q><code class="code"><#Include SYSTEM "Filename"></code></q> is replaced by the whole file stored under the name <code class="code">Filename</code> in the file system.</p>
</li>
<li><p>These substitutions are done recursively (although one should probably avoid to use this extensively).</p>
</li>
</ul>
<p>Here is another example:</p>
<div class="example"><pre>
# # <#GAPDoc Label="AnotherPiece"> some characters
# # This text is not indented.
# This text is indented by one blank.
#Not indented.
#<#/GAPDoc>
</pre></div>
<p>replaces <code class="code"><#Include Label="AnotherPiece"></code> by</p>
<div class="example"><pre>
This text is not indented.
This text is indented by one blank.
Not indented.
</pre></div>
<p>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 <strong class="pkg">GAPDoc</strong> there is the <strong class="pkg">GAP</strong> function <code class="func">ComposedDocument</code> (<a href="chap4.html#X857D77557D12559D"><span class="RefLink">4.2-1</span></a>) which does this.</p>
<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.</p>
<p><a id="X81E07B0F83EBDA5F" name="X81E07B0F83EBDA5F"></a></p>
<h4>4.2 <span class="Heading">A Tool for Collecting a Document</span></h4>
<p><a id="X857D77557D12559D" name="X857D77557D12559D"></a></p>
<h5>4.2-1 ComposedDocument</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ ComposedDocument</code>( <var class="Arg">tagname</var>, <var class="Arg">path</var>, <var class="Arg">main</var>, <var class="Arg">source</var>[, <var class="Arg">info</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ ComposedXMLString</code>( <var class="Arg">path</var>, <var class="Arg">main</var>, <var class="Arg">source</var>[, <var class="Arg">info</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>Returns: a document as string, or a list with this string and information about the source positions</p>
<p>The argument <var class="Arg">tagname</var> is the string used for the pseudo elements which mark the pieces of a document to collect. (In <a href="chap4.html#X7CE078A07E8256DC"><span class="RefLink">4.1</span></a> we used <code class="code">GAPDoc</code> as <var class="Arg">tagname</var>. The second function <code class="func">ComposedXMLString</code><code class="code">( ... )</code> is an abbreviation for <code class="func">ComposedDocument</code><code class="code">("GAPDoc", ... )</code>.</p>
<p>The argument <var class="Arg">path</var> must be a path to some directory (as string or directory object), <var class="Arg">main</var> the name of a file and <var class="Arg">source</var> a list of file names. These file names are relative to <var class="Arg">path</var>, except they start with <code class="code">"/"</code> to specify an absolute path or they start with <code class="code">"gap://"</code> to specify a file relative to the <strong class="pkg">GAP</strong> roots (see <code class="func">FilenameGAP</code> (<a href="chap4.html#X81E67E4678FB6843"><span class="RefLink">4.2-3</span></a>)). The document is constructed via the mechanism described in Section <a href="chap4.html#X7CE078A07E8256DC"><span class="RefLink">4.1</span></a>.</p>
<p>First the files given in <var class="Arg">source</var> are scanned for chunks of the document marked by <code class="code"><#<var class="Arg">tagname</var> Label="..."></code> and <code class="code"></#<var class="Arg">tagname</var>></code> pairs. Then the file <var class="Arg">main</var> is read and all <code class="code"><#Include ... ></code>-tags are substituted recursively by other files or chunks of documentation found in the first step, respectively.</p>
<p>If the optional argument <var class="Arg">info</var> is given and set to <code class="keyw">true</code> this function returns a list <code class="code">[str, origin]</code>, where <code class="code">str</code> is a string containing the composed document and <code class="code">origin</code> is a sorted list of entries of the form <code class="code">[pos, filename, line]</code>. Here <code class="code">pos</code> runs through all character positions of starting lines or text pieces from different files in <code class="code">str</code>. The <code class="code">filename</code> and <code class="code">line</code> describe the origin of this part of the collected document.</p>
<p>Without the fourth argument only the string <code class="code">str</code> is returned.</p>
<p>By default <code class="func">ComposedDocument</code> runs into an error if an <code class="code"><#Include ...></code>-tag cannot be substituted (because a file or chunk is missing). This behaviour can be changed by setting <code class="code">DOCCOMPOSEERROR := false;</code>. Then the missing parts are substituted by a short note about what is missing. Of course, this feature is only useful if the resulting document is a valid XML document (e.g., when the missing pieces are complete paragraphs or sections).</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">doc := ComposedDocument("GAPDoc", "/my/dir", "manual.xml", </span>
<span class="GAPprompt">></span> <span class="GAPinput">["../lib/func.gd", "../lib/func.gi"], true);;</span>
</pre></div>
<p><a id="X86D1141E7EDCAAC8" name="X86D1141E7EDCAAC8"></a></p>
<h5>4.2-2 OriginalPositionDocument</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ OriginalPositionDocument</code>( <var class="Arg">srcinfo</var>, <var class="Arg">pos</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>Returns: A pair <code class="code">[filename, linenumber]</code>.</p>
<p>Here <var class="Arg">srcinfo</var> must be a data structure as returned as second entry by <code class="func">ComposedDocument</code> (<a href="chap4.html#X857D77557D12559D"><span class="RefLink">4.2-1</span></a>) called with <var class="Arg">info</var>=<code class="keyw">true</code>. It returns for a given position <var class="Arg">pos</var> in the composed document the file name and line number from which that text was collected.</p>
<p><a id="X81E67E4678FB6843" name="X81E67E4678FB6843"></a></p>
<h5>4.2-3 FilenameGAP</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ FilenameGAP</code>( <var class="Arg">fname</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>Returns: file name as string or fail</p>
<p>This functions returns the full path of a file with name <var class="Arg">fname</var> relative to a <strong class="pkg">GAP</strong> root path, or <code class="keyw">fail</code> if such a file does not exist. The argument <var class="Arg">fname</var> can optionally start with the prefix <code class="code">"gap://"</code> which will be removed.</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">FilenameGAP("hsdkfhs.g");</span>
fail
<span class="GAPprompt">gap></span> <span class="GAPinput">FilenameGAP("lib/system.g");</span>
"/usr/local/gap4/lib/system.g"
<span class="GAPprompt">gap></span> <span class="GAPinput">FilenameGAP("gap://lib/system.g");</span>
"/usr/local/gap4/lib/system.g"
</pre></div>
<div class="chlinkprevnextbot"> <a href="chap0.html">[Top of Book]</a> <a href="chap0.html#contents">[Contents]</a> <a href="chap3.html">[Previous Chapter]</a> <a href="chap5.html">[Next Chapter]</a> </div>
<div class="chlinkbot"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a> <a href="chap1.html">1</a> <a href="chap2.html">2</a> <a href="chap3.html">3</a> <a href="chap4.html">4</a> <a href="chap5.html">5</a> <a href="chap6.html">6</a> <a href="chap7.html">7</a> <a href="chapA.html">A</a> <a href="chapB.html">B</a> <a href="chapC.html">C</a> <a href="chapBib.html">Bib</a> <a href="chapInd.html">Ind</a> </div>
<hr />
<p class="foot">generated by <a href="https://www.math.rwth-aachen.de/~Frank.Luebeck/GAPDoc">GAPDoc2HTML</a></p>
</body>
</html>
|
