ctie/ctiedoc.tex

   1 % ctiedoc.tex    Jan 2002, last updated Apr 2003
   2 %-----------------------------------------------
   3
   4 % A minor rewrite of tiedoc.tex for the CTIE changes.
   5
   6
   7 \documentclass{article}
   8
   9 \let\mc=\small
  10 \def\CEE/{{\mc C\spacefactor1000}}
  11 \let\.=\texttt
  12
  13 \begin{document}
  14
  15 \begin{center}
  16 \Large The \.{CTIE} Processor
  17
  18 \bigskip
  19 \large
  20 Julian Gilbey\\
  21 \.{jdg@debian.org}
  22
  23 \bigskip
  24 Based on the original \.{TIE} documentation by:\\
  25 Klaus Guntermann\\
  26 TH Darmstadt\\
  27 Fachbereich Informatik\\
  28 Institut f\"ur Theoretische Informatik
  29
  30 \bigskip
  31 January 2002, updated April 2003
  32
  33 \end{center}
  34
  35 \bigskip
  36
  37 \section{Introduction}
  38
  39 When installing a program on a particular computer system, certain
  40 system dependent changes are often needed.  The original \.{WEB}
  41 programs (\.{WEAVE} and \.{TANGLE}) handled this problem by using
  42 \textit{change files}, which work very much like a patch file and are
  43 read by \.{WEAVE} and \.{TANGLE} along with the main \.{WEB} file.
  44 This allows the original \.{WEB} file to remain intact and the
  45 particular system dependencies to be isolated.
  46
  47 Sometimes it is good practice to develop a set of multiple change
  48 files for a given \.{WEB} file to distinguish between different
  49 changes such as program enhancements, bug fixes, system dependent
  50 changes and output device dependent modifications.  Additionally this
  51 allows combinations of changes that can be used with a set of programs
  52 that share some common features, such as \.{WEAVE} and \.{TANGLE}
  53 themselves.
  54
  55 Unfortunately, the processors \.{TANGLE} and \.{WEAVE} can handle only
  56 one change file.  Rather than modifying these processors to handle
  57 multiple change files, it is easier to combine them in a preprocessing
  58 step.  The \.{TIE} processor was written to perform this task.  It is
  59 able to create either a new master file or a single change file that
  60 comprises the effect of all change files.
  61
  62 The \.{CWEB} system was later developed in order to open up the
  63 \.{WEB} system of literate programming to \CEE/ programmers.  It
  64 functions in an essentially identical way to the original Pascal
  65 \.{WEB} system, and the syntax of change files is the same.  So it
  66 should be possible to use the \.{TIE} processor for \.{CWEB} source
  67 files.  However, one significant enhancement was made to \.{CWEB}
  68 which makes this sometimes impossible.  \.{CWEB} supports
  69 \textit{include files}, which are introduced by a line beginning
  70 `\.{@i} \textit{filename}', which includes the \.{CWEB} file
  71 specified, just like the \CEE/ preprocessor command \.{\#include}.  As
  72 these include commands are effectively expanded before the change file
  73 is applied, both in the master file and the change file, it is clear
  74 that \.{TIE} needs to interpret \.{@i} commands in order to work for
  75 all \.{CWEB} files.  Thus \.{CTIE} was born: it essentially combines
  76 the traditional behaviour of \.{TIE} with the ability to handle
  77 \.{CWEB} include files.
  78
  79
  80 \section{Application}
  81
  82 The current version of \.{CTIE} accepts a master file and up to
  83 32~change files.  In general it is important to use the change files
  84 in the correct sequence, as later change files may modify the results
  85 of applying earlier changes.  Thus the order of the change files on
  86 the command line is taken to specify the order in which the change
  87 files should be applied.  Conceptually, each change file is applied to
  88 the master file in turn to create a new master file, to which the next
  89 change file is applied; in practice, though, a more space-efficient
  90 algorithm is used which only requires storage space for one line per
  91 file, so the lengths of the individual files or changes are irrelevant
  92 for storage requirements.
  93
  94 Note that \.{CTIE} will expand all \.{@i} include lines, including the
  95 specified files whether or not they are modified by any change files.
  96 So another application of \.{CTIE} is to simply expand all of these
  97 include files, producing an expanded master file.  (Thanks to Hartmut
  98 Henkel \.{<hartmut\_henkel@gmx.de>} for this observation.)
  99
 100 \.{CTIE} must be called with at least 3~parameters as follows:
 101 $$\texttt{ctie -[cm] outfile master changefile(s)}$$
 102 where the parameters are (in order):
 103 \begin{enumerate}
 104
 105 \item Either the option \.{-c} or \.{-m}.  This option determines
 106   whether an amalgamated change file or a new master file is created.
 107
 108 \item The name of the output file.
 109
 110 \item The name of the master file.
 111
 112 \item The name(s) of the change file(s), if any.
 113
 114 \end{enumerate}
 115
 116 Unlike the \.{CWEB} programs \.{CWEAVE} and \.{CTANGLE}, no attempt to
 117 add default suffixes such as \.{.w} or \.{.ch} is made; the filenames
 118 must be the full filenames.  If \.{CTIE} has been compiled with
 119 \.{kpathsea} support, then the \.{kpathsea} library will be used to
 120 search for the files using the \.{CWEBINPUTS} variable, otherwise just
 121 the current directory and the directory specified by the
 122 \.{CWEBINPUTS} environment variable will be searched, in that order.
 123
 124 Also, \.{CTIE} can be called with the single argument \.{--help} or
 125 \.{--version} to get basic help or version information.
 126
 127 \clearpage
 128
 129
 130 \def\eof{$\langle$\textrm{\mc EOF}$\rangle$}
 131 \tabcolsep=1em
 132 \parindent=0pt
 133
 134 \section{Example}
 135
 136 To illustrate the actions \.{CTIE} performs you may inspect the
 137 following example that exercises some of the borderline cases.
 138
 139 \begin{center}
 140 \ttfamily
 141 \begin{tabular}{llll}
 142 \multicolumn1{c}{\textbf{\textrm{ctie.tie}}}&
 143       \multicolumn1{c}{\textbf{\textrm{ctie.cf1}}}&
 144       \multicolumn1{c}{\textbf{\textrm{ctie.cf2}}}&
 145       \multicolumn1{c}{\textbf{\textrm{ctie.cf3}}}\\[1pt]
 146 \hline
 147 line 1          &@x             &@x             &@x\\
 148 line 2          &line 2         &line 1         &changed line 4\\
 149 line 3          &line 3         &changed line 2 &@y\\
 150 line 4          &@y             &changed line 3 &final line 4\\
 151 line 5          &changed line 2 &inserted line  &@z\\
 152 @i ctie.inc     &changed line 3 &line 4\\
 153 line 6          &inserted line  &@y             &@x\\
 154 line 7          &@z             &final line 2   &changed inc line 1\\
 155 line 8          &               &final line 3   &inserted inc line\\
 156 line 9          &@x             &changed line 4 &@y\\
 157 line 10         &line 7         &@z             &final inc line 1\\
 158 \eof            &@y             &               &@i "ctie.inc2"\\
 159                 &changed line 7 &@x             &@z\\
 160                 &@z             &inc line 1     &\eof\\
 161                 &\eof           &@y\\
 162                 &               &changed inc line 1\\
 163                 &               &inserted inc line\\
 164                 &               &@z\\
 165                 &               &\\
 166                 &               &@x\\
 167                 &               &changed line 7\\
 168                 &               &line 8\\
 169                 &               &@y\\
 170                 &               &final line 7\\
 171                 &               &final line 8\\
 172                 &               &@z\\
 173                 &               &\eof\\
 174 \end{tabular}
 175 \end{center}
 176
 177 The included files are as follows:
 178
 179 \begin{center}
 180 \ttfamily
 181 \begin{tabular}{lll}
 182 \multicolumn1{c}{\textbf{\textrm{ctie.inc}}}&
 183       \multicolumn1{c}{\textbf{\textrm{ctie.inc1}}}&
 184       \multicolumn1{c}{\textbf{\textrm{ctie.inc2}}}\\[1pt]
 185 \hline
 186 inc line 1      &included inc line      &final inserted inc line\\
 187 inc line 2      &\eof                   &\eof\\
 188 @i ctie.inc1\\
 189 inc line 3\\
 190 \eof\\
 191 \end{tabular}
 192 \end{center}
 193
 194 \clearpage
 195
 196 Using these input files and running \.{CTIE} with the following
 197 commands to create a new master file and a new change file will result
 198 in the following output files.
 199
 200 \begin{tabbing}
 201   \quad For the master file:\qquad\=\texttt{ctie -m ctie.outm ctie.cf1
 202   ctie.cf2 ctie.cf3}\\
 203   \quad For the change file:\>\texttt{ctie -c ctie.outc ctie.cf1
 204   ctie.cf2 ctie.cf3}
 205 \end{tabbing}
 206
 207 \begin{center}
 208 \ttfamily
 209 \begin{tabular}{ll}
 210 \multicolumn1{c}{\textbf{\textrm{ctie.outm}}}&
 211       \multicolumn1{c}{\textbf{\textrm{ctie.outc}}}\\[1pt]
 212 \hline
 213 final line 2            &@x\\
 214 final line 3            &line 1\\
 215 final line 4            &line 2\\
 216 line 5                  &line 3\\
 217 final inc line 1        &line 4\\
 218 final inserted inc line &@y\\
 219 inc line 2              &final line 2\\
 220 included inc line       &final line 3\\
 221 inc line 3              &final line 4\\
 222 line 6                  &@z\\
 223 final line 7            &\\
 224 final line 8            &@x\\
 225 line 9                  &inc line 1\\
 226 line 10                 &@y\\
 227                         &final inc line 1\\
 228                         &final inserted inc line\\
 229                         &@z\\
 230                         &\\
 231                         &@x\\
 232                         &line 7\\
 233                         &line 8\\
 234                         &@y\\
 235                         &final line 7\\
 236                         &final line 8\\
 237                         &@z\\
 238 \end{tabular}
 239 \end{center}
 240
 241
 242 \end{document}