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 char-
       acter `#', 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  pro-
       cesses  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  tempo-
       rary 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.