.TH SUBST 1 local
.DA 25 Feb 1990
.SH NAME
subst \- substitute definitions into file(s)
.SH SYNOPSIS
.B subst
.B \-f
substitutions
victim ...
.SH DESCRIPTION
.I Subst
makes substitutions into files, in a way that is suitable for customizing
software to local conditions.
Each
.I victim
file
is altered according to the contents of
the
.I substitutions
file.
.PP
The
.I substitutions
file contains one line per substitution.
A line consists of two fields separated by one or more tabs.
The first field is the \fIname\fR of the substitution, the second
is the \fIvalue\fR.
Neither should contain the character `#', and use of text-editor
metacharacters like `&' and `\e' is also unwise;
the name in particular is best restricted to be alphanumeric.
A line starting with `#' is a comment and is ignored.
.PP
In the \fIvictim\fRs,
each line on which a substitution is to be made
(a \fItarget\fR line)
must be preceded by a
\fIprototype\fR line.
The prototype line should be delimited in such a way that it will be
taken as a comment by whatever program processes the file later.
The prototype line must contain a ``prototype'' of the target line bracketed
by `=(\&)<' and `>(\&)=';
everything else on the prototype line is ignored.
.I Subst
extracts the prototype, changes all instances of substitution names
bracketed by `@<' and `>@' to their values,
and then replaces the target line with the result.
.SH EXAMPLE
.PP
If the \fIsubstitutions\fR file is
.PP
.RS
.nf
.ta \w'SECOND'u+4n
FIRST	111
SECOND	222
.fi
.RE
.PP
and the \fIvictim\fR file is
.PP
.RS
.nf
x = 2;
/* =\&()<y = @<FIRST>@ + @<SECOND>@;>()\&= */
y = 88 + 99;
z = 5;
.fi
.RE
.PP
then ``\fBsubst \-f \fIsubstitutions victim\fR'' changes \fIvictim\fR to:
.PP
.RS
.nf
x = 2;
/* =()\&<y = @<FIRST>@ + @<SECOND>@;>()\&= */
y = 111 + 222;
z = 5;
.fi
.RE
.SH FILES
.ta \w'\fIvictimdir\fR/substtmp.old'u+4n
\fIvictimdir\fR/substtmp.new	new version being built
.br
\fIvictimdir\fR/substtmp.old	old version during renaming
.SH SEE ALSO
sed(1)
.SH DIAGNOSTICS
Complains and halts if it is unable to create its temporary files
or if they already exist.
.SH HISTORY
Written at U of Toronto by Henry Spencer.
.SH BUGS
When creating a file to be \fIsubst\fRed, it's easy to forget to insert
a dummy target line after a prototype line;
if you forget, \fIsubst\fR ends up deleting whichever line did in fact
follow the prototype line.