Describe the .SHELL target.

Reviewed by:	ru

usr.bin/make/make.1

@@ -32,7 +32,7 @@
 .\"	@(#)make.1	8.8 (Berkeley) 6/13/95
 .\" $FreeBSD$
 .\"
-.Dd August 18, 2004
+.Dd December 2, 2004
 .Dt MAKE 1
 .Os
 .Sh NAME
@@ -1224,6 +1224,114 @@ If no sources are specified, the
 .Ic .PRECIOUS
 attribute is applied to every
 target in the file.
+.It Ic .SHELL
+Select another shell.
+The sources of this target have the format
+.Ar key Ns = Ns Ar value .
+The
+.Ar key
+is one of:
+.Bl -tag -width ".Va hasErrCtl"
+.It Va path
+Specify the path to the new shell.
+.It Va name
+Specify the name of the new shell.
+This may be either one of the three builtin shells (see below) or any
+other name.
+.It Va quiet
+Specify the shell command to turn echoing off.
+.It Va echo
+Specify the shell command to turn echoing on.
+.It Va filter
+Usually shells print the echo off command before turning echoing off.
+This is the exact string that will be printed by the shell and is used
+to filter the shell output to remove the echo off command.
+.It Va echoFlag
+The shell option that turns echoing on.
+.It Va errFlag
+The shell option to turn on error checking.
+If error checking is on, the shell should exit if a command returns
+a non-zero status.
+.It Va hasErrCtl
+True if the shell has error control.
+.It Va check
+If
+.Va hasErrCtl
+is true then this is the shell command to turn error checking on.
+If
+.Va hasErrCtl
+is false then this is a command template to echo commands for which error
+checking is disabled.
+The template must contain a
+.Ql %s .
+.It Va ignore
+If
+.Va hasErrCtl
+is true, this is the shell command to turn error checking off.
+If
+.Va hasErrCtl
+is false, this is a command template to execute a command so that errors
+are ignored.
+The template must contain a
+.Ql %s .
+.El
+.Pp
+Values that are strings must be surrounded by double quotes.
+Boolean values are specified as
+.Ql T
+or
+.Ql Y
+(in either case) to mean true.
+Any other value is taken to mean false.
+.Pp
+There are several uses of the
+.Ic .SHELL
+target:
+.Bl -bullet
+.It
+Selecting one of the builtin shells.
+This is done by just specifying the name of the shell with the
+.Va name
+keyword.
+It is also possible to modify the parameters of the builtin shell by just
+specifying other keywords (except for
+.Va path ) .
+.It
+Using another executable for one of the builtin shells.
+This is done by specifying the path to the executable with the
+.Va path
+keyword.
+If the last component is the same as the name of the builtin shell, no
+name needs to be specified; if it is different, the name must be given:
+.Bd -literal -offset indent
+\&.SHELL: path="/usr/local/bin/sh"
+.Ed
+.Pp
+selects the builtin shell
+.Dq Li sh
+but will execute it from
+.Pa /usr/local/bin/sh .
+Like in the previous case, it is possible to modify parameters of the builtin
+shell by just specifying them.
+.It
+Using an entirely different shell.
+This is done by specifying all keywords.
+.El
+.Pp
+The builtin shells are
+.Dq Li sh ,
+.Dq Li csh
+and
+.Dq Li ksh .
+Because
+.Fx
+has no
+.Nm ksh
+in
+.Pa /bin ,
+it is unwise to specify
+.Va name Ns = Ns Qq Li ksh
+without also specifying a path.
 .It Ic .SILENT
 Apply the
 .Ic .SILENT