debian man page for subst

SUBST(1)						      General Commands Manual							  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  tar-
       get 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 dif-
	      ferent 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)