Just because Linux does not split whitespace on #! lines does not mean
that all operating systems behave the same. Mention the recent
coreutils 8.30 'env -S' addition for working around interpreter
argument limitations, as well as the use of env to locate bash even
when it is not in /bin.
---
doc/bashref.texi | 20 ++++++++++++--------
1 file changed, 12 insertions(+), 8 deletions(-)
diff --git a/doc/bashref.texi b/doc/bashref.texi
index 231356e5..53075c5c 100644
--- a/doc/bashref.texi
+++ b/doc/bashref.texi
@@ -3340,18 +3340,22 @@ an interpreter for the program.
Thus, you can specify Bash, @code{awk}, Perl, or some other
interpreter and write the rest of the script file in that language.
-The arguments to the interpreter
-consist of a single optional argument following the interpreter
-name on the first line of the script file, followed by the name of
-the script file, followed by the rest of the arguments. Bash
-will perform this action on operating systems that do not handle it
-themselves. Note that some older versions of Unix limit the interpreter
-name and argument to a maximum of 32 characters.
+The details of how the interpreter line is split depends on the
+operating system, then the result of that split is combined with the
+name of the script file and the rest of the command line arguments.
+Bash will perform this action on operating systems that do not handle
+it themselves. Note that some older versions of Unix limit the
+interpreter name and a single argument to a maximum of 32 characters.
+For maximum portability, you must assume that the script can only
+embed a single optional argument following the interpreter name. If
+your platform supports @code{env -S}, you can use that to work around
+the single argument limit.
Bash scripts often begin with @code{#! /bin/bash} (assuming that
Bash has been installed in @file{/bin}), since this ensures that
Bash will be used to interpret the script, even if it is executed
-under another shell.
+under another shell. Another common practice is the use of
+@code{#!/bin/env bash} to find the first instance of bash on @env{PATH}.
@node Shell Builtin Commands
@chapter Shell Builtin Commands
--
2.21.0
