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

[Daniel Shahaf <d.s@daniel.shahaf.name>]

Thanks for the patch.  Review:

zeurkous@volny.cz wrote on Sun, Apr 11, 2021 at 14:15:20 +0200:
> #?patch
> #

What's this header line?  Is this a standard format for unidiffs with
log messages?  Should Functions/VCS_Info/VCS_INFO_patch2subject grow
support for it?

zsh's source code is in git.  git's interchange format is `[PATCH]' in
the subject line, then in the body, everything up to a "---" line is
part of the log message, and everything after is not.  See
git-format-patch(1) for details.

More below.

> # These patches add, to the zshmisc(1) manual page, clarity about the
> # exit status on exec failure.
> #
> # Me understands that, strictly considered, only Doc/Zsh/exec.yo needs
> # updating; however, as me doesn't have yodl, me updated Doc/zshmisc.1
> # as well.

Thanks, but there's no need to manually update the .1 files; they aren't
in version control.

> # Hope this is useful (it is to me),
> #
> #         --zeurkous, Sun Apr 11 11:12:21 UTC 2021.
> #
> --- Doc/Zsh/..v/5.8/exec.yo	Mon Dec  4 14:09:35 2017
> +++ Doc/Zsh/exec.yo	Sun Apr 11 10:42:15 2021
> @@ -16,7 +16,10 @@
>  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.
> +127.
> +
> +If execution fails because of insufficient permissions, or because the
> +file is a directory, the shell prints an error message and returns 126.
>  

Does this sentence cover every possible case of returning 126?  The
condition in the source is «== EACCES || == ENOEXEC».  Moreover, the
very next sentence says "the file is not in executable format", and it
would be odd to refer to the same condition by different noun phrases in
two consecutive sentences.

I don't like the newly-added paragraph break.  Anyone who stops reading
at the end of that paragraph will think the return code is 127, period.
Also, stating the return values before going on to say that if the file
isn't a directory then it's exeuted anyway could be confusing, couldn't it?

Should this part of the manual mention the AUTO_CD option?

A few paragraph below the value, 127, is mentioned again.  Does that
sentence need to be updated?

Thanks for the patch!  I realize the review is actually longer than the
patch, but, it's still shorter than the cumulative number of times the
new text will be read.

Cheers,

Daniel

>  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
>