From ad547a6b5986815fda458221149728d9d9ab1d87 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Thu, 25 Feb 2021 19:22:25 +0000 Subject: restore Build,TODO from r57911 git-svn-id: svn://tug.org/texlive/trunk@57915 c570f23f-e606-0410-a88d-b1316a301751 --- Build/source/texk/web2c/ctiedir/ctiedoc.tex | 242 ++++++++++++++++++++++++++++ 1 file changed, 242 insertions(+) create mode 100644 Build/source/texk/web2c/ctiedir/ctiedoc.tex (limited to 'Build/source/texk/web2c/ctiedir/ctiedoc.tex') diff --git a/Build/source/texk/web2c/ctiedir/ctiedoc.tex b/Build/source/texk/web2c/ctiedir/ctiedoc.tex new file mode 100644 index 00000000000..972bfff44d4 --- /dev/null +++ b/Build/source/texk/web2c/ctiedir/ctiedoc.tex @@ -0,0 +1,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 \.{} 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} -- cgit v1.2.3