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.

                                           25 Feb 1990                                   SUBST(1)