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
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
|
% ctiedoc.tex Jan 2002, last updated Apr 2003
%-----------------------------------------------
% A minor rewrite of tiedoc.tex for the CTIE changes.
\documentclass{article}
\let\mc=\small
\def\CEE/{{\mc C\spacefactor1000}}
\let\.=\texttt
\begin{document}
\begin{center}
\Large The \.{CTIE} Processor
\bigskip
\large
Julian Gilbey\\
\.{jdg@debian.org}
\bigskip
Based on the original \.{TIE} documentation by:\\
Klaus Guntermann\\
TH Darmstadt\\
Fachbereich Informatik\\
Institut f\"ur Theoretische Informatik
\bigskip
January 2002, updated April 2003
\end{center}
\bigskip
\section{Introduction}
When installing a program on a particular computer system, certain
system dependent changes are often needed. The original \.{WEB}
programs (\.{WEAVE} and \.{TANGLE}) handled this problem by using
\textit{change files}, which work very much like a patch file and are
read by \.{WEAVE} and \.{TANGLE} along with the main \.{WEB} file.
This allows the original \.{WEB} file to remain intact and the
particular system dependencies to be isolated.
Sometimes it is good practice to develop a set of multiple change
files for a given \.{WEB} file to distinguish between different
changes such as program enhancements, bug fixes, system dependent
changes and output device dependent modifications. Additionally this
allows combinations of changes that can be used with a set of programs
that share some common features, such as \.{WEAVE} and \.{TANGLE}
themselves.
Unfortunately, the processors \.{TANGLE} and \.{WEAVE} can handle only
one change file. Rather than modifying these processors to handle
multiple change files, it is easier to combine them in a preprocessing
step. The \.{TIE} processor was written to perform this task. It is
able to create either a new master file or a single change file that
comprises the effect of all change files.
The \.{CWEB} system was later developed in order to open up the
\.{WEB} system of literate programming to \CEE/ programmers. It
functions in an essentially identical way to the original Pascal
\.{WEB} system, and the syntax of change files is the same. So it
should be possible to use the \.{TIE} processor for \.{CWEB} source
files. However, one significant enhancement was made to \.{CWEB}
which makes this sometimes impossible. \.{CWEB} supports
\textit{include files}, which are introduced by a line beginning
`\.{@i} \textit{filename}', which includes the \.{CWEB} file
specified, just like the \CEE/ preprocessor command \.{\#include}. As
these include commands are effectively expanded before the change file
is applied, both in the master file and the change file, it is clear
that \.{TIE} needs to interpret \.{@i} commands in order to work for
all \.{CWEB} files. Thus \.{CTIE} was born: it essentially combines
the traditional behaviour of \.{TIE} with the ability to handle
\.{CWEB} include files.
\section{Application}
The current version of \.{CTIE} accepts a master file and up to
32~change files. In general it is important to use the change files
in the correct sequence, as later change files may modify the results
of applying earlier changes. Thus the order of the change files on
the command line is taken to specify the order in which the change
files should be applied. Conceptually, each change file is applied to
the master file in turn to create a new master file, to which the next
change file is applied; in practice, though, a more space-efficient
algorithm is used which only requires storage space for one line per
file, so the lengths of the individual files or changes are irrelevant
for storage requirements.
Note that \.{CTIE} will expand all \.{@i} include lines, including the
specified files whether or not they are modified by any change files.
So another application of \.{CTIE} is to simply expand all of these
include files, producing an expanded master file. (Thanks to Hartmut
Henkel \.{<hartmut\_henkel@gmx.de>} for this observation.)
\.{CTIE} must be called with at least 3~parameters as follows:
$$\texttt{ctie -[cm] outfile master changefile(s)}$$
where the parameters are (in order):
\begin{enumerate}
\item Either the option \.{-c} or \.{-m}. This option determines
whether an amalgamated change file or a new master file is created.
\item The name of the output file.
\item The name of the master file.
\item The name(s) of the change file(s), if any.
\end{enumerate}
Unlike the \.{CWEB} programs \.{CWEAVE} and \.{CTANGLE}, no attempt to
add default suffixes such as \.{.w} or \.{.ch} is made; the filenames
must be the full filenames. If \.{CTIE} has been compiled with
\.{kpathsea} support, then the \.{kpathsea} library will be used to
search for the files using the \.{CWEBINPUTS} variable, otherwise just
the current directory and the directory specified by the
\.{CWEBINPUTS} environment variable will be searched, in that order.
Also, \.{CTIE} can be called with the single argument \.{--help} or
\.{--version} to get basic help or version information.
\clearpage
\def\eof{$\langle$\textrm{\mc EOF}$\rangle$}
\tabcolsep=1em
\parindent=0pt
\section{Example}
To illustrate the actions \.{CTIE} performs you may inspect the
following example that exercises some of the borderline cases.
\begin{center}
\ttfamily
\begin{tabular}{llll}
\multicolumn1{c}{\textbf{\textrm{ctie.tie}}}&
\multicolumn1{c}{\textbf{\textrm{ctie.cf1}}}&
\multicolumn1{c}{\textbf{\textrm{ctie.cf2}}}&
\multicolumn1{c}{\textbf{\textrm{ctie.cf3}}}\\[1pt]
\hline
line 1 &@x &@x &@x\\
line 2 &line 2 &line 1 &changed line 4\\
line 3 &line 3 &changed line 2 &@y\\
line 4 &@y &changed line 3 &final line 4\\
line 5 &changed line 2 &inserted line &@z\\
@i ctie.inc &changed line 3 &line 4\\
line 6 &inserted line &@y &@x\\
line 7 &@z &final line 2 &changed inc line 1\\
line 8 & &final line 3 &inserted inc line\\
line 9 &@x &changed line 4 &@y\\
line 10 &line 7 &@z &final inc line 1\\
\eof &@y & &@i "ctie.inc2"\\
&changed line 7 &@x &@z\\
&@z &inc line 1 &\eof\\
&\eof &@y\\
& &changed inc line 1\\
& &inserted inc line\\
& &@z\\
& &\\
& &@x\\
& &changed line 7\\
& &line 8\\
& &@y\\
& &final line 7\\
& &final line 8\\
& &@z\\
& &\eof\\
\end{tabular}
\end{center}
The included files are as follows:
\begin{center}
\ttfamily
\begin{tabular}{lll}
\multicolumn1{c}{\textbf{\textrm{ctie.inc}}}&
\multicolumn1{c}{\textbf{\textrm{ctie.inc1}}}&
\multicolumn1{c}{\textbf{\textrm{ctie.inc2}}}\\[1pt]
\hline
inc line 1 &included inc line &final inserted inc line\\
inc line 2 &\eof &\eof\\
@i ctie.inc1\\
inc line 3\\
\eof\\
\end{tabular}
\end{center}
\clearpage
Using these input files and running \.{CTIE} with the following
commands to create a new master file and a new change file will result
in the following output files.
\begin{tabbing}
\quad For the master file:\qquad\=\texttt{ctie -m ctie.outm ctie.cf1
ctie.cf2 ctie.cf3}\\
\quad For the change file:\>\texttt{ctie -c ctie.outc ctie.cf1
ctie.cf2 ctie.cf3}
\end{tabbing}
\begin{center}
\ttfamily
\begin{tabular}{ll}
\multicolumn1{c}{\textbf{\textrm{ctie.outm}}}&
\multicolumn1{c}{\textbf{\textrm{ctie.outc}}}\\[1pt]
\hline
final line 2 &@x\\
final line 3 &line 1\\
final line 4 &line 2\\
line 5 &line 3\\
final inc line 1 &line 4\\
final inserted inc line &@y\\
inc line 2 &final line 2\\
included inc line &final line 3\\
inc line 3 &final line 4\\
line 6 &@z\\
final line 7 &\\
final line 8 &@x\\
line 9 &inc line 1\\
line 10 &@y\\
&final inc line 1\\
&final inserted inc line\\
&@z\\
&\\
&@x\\
&line 7\\
&line 8\\
&@y\\
&final line 7\\
&final line 8\\
&@z\\
\end{tabular}
\end{center}
\end{document}
|
