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 suit-
     able  for  customizing  software  to local conditions.  Each
     victim file is altered according to the contents of the sub-
     stitutions 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 `>()='; every-
     thing 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 direc-
          tories.  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.