[PATCH] docs: More hints on #! parsing

[Eric Blake]

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