revised patch: zshmisc(1) clarify non-successful exit statuses

[<zeurkous@xxxxxxxx>]

#?patch
#
# This revised patch adds, to the zshmisc(1) manual page, clarity about
# the exit status on exec failure.
#
# Due to a comment on the original patches, made on the zsh-workers
# mailing list: me didn't include a patch to zshmisc.1 this time.
#
# As me still doesn't use yodl: the immediately above does mean that
# me hasn't seen how it actually looks after typesetting.
#
# The copied use of startsitem() was suggested on the same mailing list.
# Me hopes me did it right.
#
# Note that the "operating system-dependent" part is made more
# complicated by zsh' habit of de-capitalizing the initial character of
# the string returned by strerror(3).
#
# Hope this is more useful (it is to me),
#
#         --zeurkous, Fri Apr 23 12:09:47 UTC 2021.
#
--- Doc/Zsh/..v/5.8/exec.yo	Mon Dec  4 14:09:35 2017
+++ Doc/Zsh/exec.yo	Fri Apr 23 12:02:30 2021
@@ -14,10 +14,22 @@
 
 vindex(path, use of)
 Otherwise, the shell searches each element of tt($path) for a
-directory containing an executable file by that name.  If the
-search is unsuccessful, the shell prints an error message and returns
-a nonzero exit status.
+directory containing an executable file by that name.
 
+If execution fails: an error message is printed, and one of the
+following values is returned.
+
+startsitem()
+sitem(127)
+The search was unsuccessful.  The error message is
+`tt(command not found:) var(cmd)'.
+sitem(126)
+The executable file has insufficient permissions, or is a directory or
+other type of special file, or is not a script (see below) and in a
+format unrecognized by the operating system.  The exact conditions and
+error message are operating system-dependent; see manref(execve)(2).
+endsitem()
+
 If execution fails because the file is not in executable format,
 and the file is not a directory, it is assumed to be a shell
 script.  tt(/bin/sh) is spawned to execute it.  If the program
@@ -29,10 +41,6 @@
 If no external command is found but a function tt(command_not_found_handler)
 exists the shell executes this function with all
 command line arguments.  The return status of the function becomes the
-status of the command.  If the function wishes to mimic the
-behaviour of the shell when the command is not found, it should
-print the message `tt(command not found:) var(cmd)' to standard error
-and return status 127.  Note that the handler is executed in a
+status of the command.  Note that the handler is executed in a
 subshell forked to execute an external command, hence changes to
 directories, shell parameters, etc. have no effect on the main shell.
-