SUBST (1)

NAME
     subst - substitute definitions into file(s)

SYNOPSIS
     subst [ -e editor ] -f substitutions victim ...

DESCRIPTION
     Subst makes substitutions into files, in  a  way  that  is  suitable  for
     customizing  software  to  local conditions.  Each victim file is altered
     according to the contents of the substitutions file.

     The substitutions file  contains  one  line  per  substitution.   A  line
     consists of two fields separated by one or more tabs.  The first field is
     the name of the substitution, the second is the  value.   Neither  should
     contain the character `#', and use of text-editor metacharacters like `&'
     and `\' is also unwise; the name in particular is best restricted  to  be
     alphanumeric.  A line starting with `#' is a comment and is ignored.

     In the victims, each line on which a substitution is to be made (a target
     line) must be preceded by a prototype 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.  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.

OPTIONS

     -e   Substitutions are done using the sed(1) editor, which must be  found
          in  either the /bin or /usr/bin directories.  To specify a different
          executable, use the ``-e'' flag.

EXAMPLE

     If the substitutions file is

          FIRST     111
          SECOND    222

     and the victim file is

          x = 2;
          /* =()<y = @<FIRST>@ + @<SECOND>@;>()= */
          y = 88 + 99;
          z = 5;

     then ``subst -f substitutions victim'' changes victim to:

          x = 2;
          /* =()<y = @<FIRST>@ + @<SECOND>@;>()= */
          y = 111 + 222;
          z = 5;


FILES
     victimdir/substtmp.new          new version being built
     victimdir/substtmp.old          old version during renaming

SEE ALSO
     sed(1)

DIAGNOSTICS
     Complains and halts if it is unable to create its temporary files  or  if
     they already exist.

HISTORY
     Written at U of Toronto by Henry Spencer.

     Rich $alz added the ``-e'' flag July, 1991.

BUGS
     When creating a file to be substed, it's easy to forget to insert a dummy
     target line after a prototype line; if you forget, subst ends up deleting
     whichever line did in fact follow the prototype line.