README.md: add interpreter-script section

README.md

@@ -296,6 +296,72 @@ Or the following line to the dosh `~/.dosh_profile`:
 Alternatively, use the convenient wrapper script [posh](support/posh) to run
 [dosh] using [podman] underneath without touching the Shell and *dosh* files.
 
+### USE AS INTERPRETER FOR SHELL SCRIPT
+
+[dosh(1)] is usable as an interpreter for shell script.
+
+According to [execve(2)]:
+
+> Interpreter scripts
+>
+> An interpreter script is a text file that has execute permission enabled and
+> whose first line is of the form:
+>
+>	#!interpreter [optional-arg]
+>
+> The interpreter must be a valid pathname for an executable file.
+>
+> If the pathname argument of execve() specifies an interpreter script, then
+> interpreter will be invoked with the following arguments:
+>	
+>	interpreter [optional-arg] pathname arg...
+>	
+> where pathname is the pathname of the file specified as the first argument of
+> execve(), and arg... is the series of words pointed to by the argv argument
+> of execve(), starting at argv[1]. Note that there is no way to get the
+> argv[0] that was passed to the execve() call.
+>	
+> For portable use, optional-arg should either be absent, or be specified as a
+> single word (i.e., it should not contain white space); see NOTES below.
+>
+> Since Linux 2.6.28, the kernel permits the interpreter of a script to itself
+> be a script. This permission is recursive, up to a limit of four recursions,
+> so that the interpreter may be a script which is interpreted by a script, and
+> so on.
+>
+> Notes
+>
+> Linux ignores the set-user-ID and set-group-ID bits on scripts. 
+>
+> A maximum line length of 127 characters is allowed for the first line in a #!
+> executable shell script. 
+>
+> The semantics of the optional-arg argument of an interpreter script vary
+> across implementations. On Linux, the entire string following the interpreter
+> name is passed as a single argument to the interpreter, and this string can
+> include white space. However, behavior differs on some other systems. Some
+> systems use the first white space to terminate optional-arg. On some systems,
+> an interpreter script can have multiple arguments, and white spaces in
+> optional-arg are used to delimit the arguments. 
+
+A typical shebang to run a shell script via *dosh* is `#!/usr/bin/dosh`.
+
+However, the abosulte path to *dosh* is unpredictable since it may be installed
+in `/bin`, `/usr/bin`, `/usr/local/bin`, or in the user home `~/.local/bin`, or
+even in `/opt`.
+
+Therefore, the most appropriate shebang to run *dosh* is `#!/usr/bin/env dosh`.
+
+Additionally, consider using the [env(1)] split option `-S` (since [coreutils
+8.30]) if using *dosh* arguments such as `#!/usr/bin/env -S dosh --home`.
+
+_Important_: *dosh* warns and splits the list of arguments itself if using the
+absolute path (i.e. `#!/usr/bin/dosh --docker support/Dockerfile`) instead of
+using *env* and its split option (i.e. `#!/usr/bin/env -S dosh --dockerfile
+support/Dockerfile`). This feature is unportable; it is deprecated in version 7
+and it is going for removal in a next release. Consider moving the shebang to
+[env(1)] and its `-S` since the half of [2018][coreutils 8.30].
+
 ## LINKS
 
 Check for [man-pages][dosh(1)] and its [examples].
@@ -342,7 +408,10 @@ later version.
 [dosh]: dosh
 [dosh(1)]: dosh.1.adoc
 [environment-variables]: https://github.com/gportay/dosh/blob/master/dosh.1.adoc#environment-variables
+[execve(2)]: https://linux.die.net/man/2/execve
+[env(1)]: https://linux.die.net/man/1/env
 [examples]: dosh.1.adoc#examples
 [yadutaf]: https://blog.yadutaf.fr/2017/09/10/running-a-graphical-app-in-a-docker-container-on-a-remote-server/
 [podman]: https://github.com/containers/podman
 [posh]: support/posh
+[coreutils 8.30]: https://github.com/coreutils/coreutils/commit/668306ed86c8c79b0af0db8b9c882654ebb66db2