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

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

[zeurkous]

#?patch
#
# 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.
#
# 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.
 
 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

--- Doc/..v/5.8/zshmisc.1	Fri Feb 14 22:13:03 2020
+++ Doc/zshmisc.1	Sun Apr 11 10:55:17 2021
@@ -1,4 +1,4 @@
-.TH "ZSHMISC" "1" "February 14, 2020" "zsh 5\&.8"
+.TH "ZSHMISC" "1" "April 11, 2021" "zsh 5\&.8"
 .SH "NAME"
 zshmisc \- everything and then some
 .\" Yodl file: Zsh/grammar.yo
@@ -1171,7 +1171,10 @@
 Otherwise, the shell searches each element of \fB$path\fP 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\&.
+.PP
+If execution fails because of insufficient permissions, or because the
+file is a directory, the shell prints an error message and returns 126\&.
 .PP
 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

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

[Daniel Shahaf]

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
> 

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

[zeurkous]

Haai,

"Daniel Shahaf" <d.s@daniel.shahaf.name> wrote:
> 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?

No, it's a "shehuh" (me own convention), to indicate the format (in this
case: input to patch(1)). Ignore it if you wish. The rest of the '#'
lines are just comments (meknows patch(1) will relay && discard any
lines before the actual patch, but IMO it shouldn't, hence the prefix).

patch(1) will eat all this fine (at least it does on me side).

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

Thanks, but me doesn't use git (me has me own, very sufficient, ways to
keep track of things). So me just used 'diff -u'.

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

Alright, me didn't realize. Me just has this little patch and me doesn't
know if me'll ever have anything to contribute again...

>
>> # 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».

Me wishes me had a guarantee. It probably differs from system to system
(me runs OpenBSD); this is me best shot (for now).

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

In me defense: the whole text is a bit vague, and me's not sure me
understands the subtleties enough to do a {,partial }rewrite of the
section.

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

Why would someone stop reading there...?

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

In all honesty: to me, the whole text is so unnecessarily unclear that
me'd apply me usual solution of writing exit statuses in a table:

 If execution fails: one of the following values is returned.
 .Pp
 .Bl -tag -width 126 -compact
 .It Li 126
 [...summarize the condition{,s} that cause{,s} it to return that...]
 .It Li 127
 [...idem...]
 .El

(That's in mdoc(7), not in man(7). Sorry.)

However, if you folks would desire that: me has no idea how to write
that in yodl, so mecan't provide a patch.

> Should this part of the manual mention the AUTO_CD option?

Dunno. It could unnecessarily complicate it.

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

Me'd say that if the text above would be made sufficiently clear (with
quotes of both diagnostic messages), that paragraph could be
significantly curtailed, instead of extended.

> Thanks for the patch!

You're welcome :)

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

Yeah.

> Cheers,
>
> Daniel

Take care,

         --zeurkous.

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

-- 
Friggin' Machines!

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

[Daniel Shahaf]

zeurkous@volny.cz wrote on Tue, Apr 13, 2021 at 20:03:41 +0200:
> "Daniel Shahaf" <d.s@daniel.shahaf.name> wrote:
> > 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?
> 
> No, it's a "shehuh" (me own convention), to indicate the format (in this
> case: input to patch(1)). Ignore it if you wish. The rest of the '#'
> lines are just comments (meknows patch(1) will relay && discard any
> lines before the actual patch, but IMO it shouldn't, hence the prefix).
> 
> patch(1) will eat all this fine (at least it does on me side).

Every patch(1) implementation in the last few decades behaves this way.

> > 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.
> 
> Thanks, but me doesn't use git (me has me own, very sufficient, ways to
> keep track of things). So me just used 'diff -u'.

You can get svn working copies and tar.gz or zip exports from
https://github.com/zsh-users/zsh/.

> >> # 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».
> 
> Me wishes me had a guarantee. It probably differs from system to system
> (me runs OpenBSD); this is me best shot (for now).

Does that mean you won't be submitting a revised patch?  No problem if
so; just want to make it explicit whether or not revising the patch is
a task that's up for grabs.

> > 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.
> 
> In me defense: the whole text is a bit vague, and me's not sure me
> understands the subtleties enough to do a {,partial }rewrite of the
> section.
> 
> > 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.
> 
> Why would someone stop reading there...?

People skim.

> > 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?
> 
> In all honesty: to me, the whole text is so unnecessarily unclear that
> me'd apply me usual solution of writing exit statuses in a table:
> 
>  If execution fails: one of the following values is returned.
>  .Pp
>  .Bl -tag -width 126 -compact
>  .It Li 126
>  [...summarize the condition{,s} that cause{,s} it to return that...]
>  .It Li 127
>  [...idem...]
>  .El
> 
> (That's in mdoc(7), not in man(7). Sorry.)
> 
> However, if you folks would desire that: me has no idea how to write
> that in yodl, so mecan't provide a patch.

In this case, a startsitem() would probably work well.  There's plenty
of examples in our tree.

> > Should this part of the manual mention the AUTO_CD option?
> 
> Dunno. It could unnecessarily complicate it.
> 

"Unnecessarily"?  Doesn't AUTO_CD logically belong in that part of the manual?

> > A few paragraph below the value, 127, is mentioned again. Does that
> > sentence need to be updated?
> 
> Me'd say that if the text above would be made sufficiently clear (with
> quotes of both diagnostic messages), that paragraph could be
> significantly curtailed, instead of extended.

That's what I meant.

Daniel

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

[zeurkous]

Haai,

"Daniel Shahaf" <d.s@daniel.shahaf.name> wrote:
> zeurkous@volny.cz wrote on Tue, Apr 13, 2021 at 20:03:41 +0200:
>> "Daniel Shahaf" <d.s@daniel.shahaf.name> wrote:
>> > 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?
>>
>> No, it's a "shehuh" (me own convention), to indicate the format (in this
>> case: input to patch(1)). Ignore it if you wish. The rest of the '#'
>> lines are just comments (meknows patch(1) will relay && discard any
>> lines before the actual patch, but IMO it shouldn't, hence the prefix).
>>
>> patch(1) will eat all this fine (at least it does on me side).
>
> Every patch(1) implementation in the last few decades behaves this way.

That's me experience, as well. However, me can't really guarantee that
some clever-ass (like me :) didn't write a patch(1) w/ diff behaviour,
hence the caveat.

>> > 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.
>>
>> Thanks, but me doesn't use git (me has me own, very sufficient, ways to
>> keep track of things). So me just used 'diff -u'.
>
> You can get svn working copies and tar.gz or zip exports from
> https://github.com/zsh-users/zsh/.

Me'll keep that in mind, should me have another contribution.

>> >> # 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».
>>
>> Me wishes me had a guarantee. It probably differs from system to system
>> (me runs OpenBSD); this is me best shot (for now).
>
> Does that mean you won't be submitting a revised patch? No problem if
> so; just want to make it explicit whether or not revising the patch is
> a task that's up for grabs.

It's me best shot at understanding the behaviour, sorry for not being
clear meself here. Me's a bit busy but me might well come up w/ a
revised patch in a little while -- me'll let you folks know. 

>> > 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.
>>
>> Why would someone stop reading there...?
>
> People skim.

That's understandable, but also at their own risk, me'd argue.

>> > 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?
>>
>> In all honesty: to me, the whole text is so unnecessarily unclear that
>> me'd apply me usual solution of writing exit statuses in a table:
>>
>> If execution fails: one of the following values is returned.
>> .Pp
>> .Bl -tag -width 126 -compact
>> .It Li 126
>> [...summarize the condition{,s} that cause{,s} it to return that...]
>> .It Li 127
>> [...idem...]
>> .El
>>
>> (That's in mdoc(7), not in man(7). Sorry.)
>>
>> However, if you folks would desire that: me has no idea how to write
>> that in yodl, so mecan't provide a patch.
>
> In this case, a startsitem() would probably work well. There's plenty
> of examples in our tree.

Thanks for the reference, me'll probably have a look.

>> > Should this part of the manual mention the AUTO_CD option?
>>
>> Dunno. It could unnecessarily complicate it.
>>
>
> "Unnecessarily"? Doesn't AUTO_CD logically belong in that part of the manual?

Me doesn't use AUTO_CD, but if me understands the functionality
correctly: it allows a dir path name to be specified as a program name,
with the effect of a cd into the specified directory. To  me, that's a
translation: '/blaat/' -> 'cd /blaat/'. The return status of the former
should then naturally be the return status of the latter.

At least, that's me take on it.

>> > A few paragraph below the value, 127, is mentioned again. Does that
>> > sentence need to be updated?
>>
>> Me'd say that if the text above would be made sufficiently clear (with
>> quotes of both diagnostic messages), that paragraph could be
>> significantly curtailed, instead of extended.
>
> That's what I meant.

Then we agree on that one :)

> Daniel

         --zeurkous.

-- 
Friggin' Machines!

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

[zeurkous]

#?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.
-

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

[Daniel Shahaf]

zeurkous@volny.cz wrote on Fri, 23 Apr 2021 12:18 +00:00:
> # The copied use of startsitem() was suggested on the same mailing list.
> # Me hopes me did it right.

Not quite; sitem()() takes two arguments.  See, for instance,
http://zsh.sourceforge.net/Doc/Release/User-Contributions.html#index-zmv
and Doc/Zsh/contrib.yo:4573.

> # 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).

I wouldn't mind losing that habit, actually.  It's not zsh's business to
copyedit a library message, especially when that breaks some use-cases
(case-sensitive grepping/skimming) and is downright wrong in some cases
(e.g., in German <https://bugs.debian.org/419233>, or if the error
message happens to start with word that changes meaning when
decapitalized, such as "Perl" or "English").

#419233 has a patch which should still work.

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

Read the new text and don't have any comments.  It's an improvement,
even if a mention of AUTO_CD hasn't been added.  Anyone else wants
to review?

Thanks,

Daniel

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

[Daniel Shahaf]

Daniel Shahaf wrote on Fri, 23 Apr 2021 16:07 +00:00:
> zeurkous@volny.cz wrote on Fri, 23 Apr 2021 12:18 +00:00:
> > # The copied use of startsitem() was suggested on the same mailing list.
> > # Me hopes me did it right.
> 
> Not quite; sitem()() takes two arguments.  See, for instance,
> http://zsh.sourceforge.net/Doc/Release/User-Contributions.html#index-zmv
> and Doc/Zsh/contrib.yo:4573.
> 
> > # 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).
> 
> I wouldn't mind losing that habit, actually.  It's not zsh's business to
> copyedit a library message, especially when that breaks some use-cases
> (case-sensitive grepping/skimming) and is downright wrong in some cases
> (e.g., in German <https://bugs.debian.org/419233>, or if the error
> message happens to start with word that changes meaning when
> decapitalized, such as "Perl" or "English").

Also, if strerror(3) returns an empty string, the fputs() call will
dereference a past-the-end pointer.

> #419233 has a patch which should still work.
> 
> > # 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 @@
> 
> Read the new text and don't have any comments.  It's an improvement,
> even if a mention of AUTO_CD hasn't been added.  Anyone else wants
> to review?
> 
> Thanks,
> 
> Daniel
> 
> 

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

[zeurkous]

Haai,

"Daniel Shahaf" <d.s@daniel.shahaf.name> wrote:
> zeurkous@volny.cz wrote on Fri, 23 Apr 2021 12:18 +00:00:
>> # The copied use of startsitem() was suggested on the same mailing list.
>> # Me hopes me did it right.
>
> Not quite; sitem()() takes two arguments. See, for instance,
> http://zsh.sourceforge.net/Doc/Release/User-Contributions.html#index-zmv
> and Doc/Zsh/contrib.yo:4573.

Oops, sorry. Could you fix that, or do you want me to do another
revision...?

>> # 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).
>
> I wouldn't mind losing that habit, actually. It's not zsh's business to
> copyedit a library message, especially when that breaks some use-cases
> (case-sensitive grepping/skimming) and is downright wrong in some cases
> (e.g., in German <https://bugs.debian.org/419233>, or if the error
> message happens to start with word that changes meaning when
> decapitalized, such as "Perl" or "English").

Agreed, let's lose it :)

>
> #419233 has a patch which should still work.
>
>> # 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 @@
>
> Read the new text and don't have any comments. It's an improvement,
> even if a mention of AUTO_CD hasn't been added.

Good to hear.

> Anyone else wants
> to review?
>
> Thanks,
>
> Daniel

NP,
          --zeurkous.

-- 
Friggin' Machines!

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

[Lawrence Velázquez]

On Fri, Apr 23, 2021, at 8:18 AM, zeurkous@volny.cz wrote:
> +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.

This sentence is awkward.  I would write something more like:

"The executable file has insufficient permissions, is a directory
or special file, or is a non-script in a format unrecognized by the
operating system."

-- 
vq

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

[zeurkous]

"Lawrence Velázquez" <larryv@zsh.org> wrote:
> On Fri, Apr 23, 2021, at 8:18 AM, zeurkous@volny.cz wrote:
>> +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.
>
> This sentence is awkward. I would write something more like:
> "The executable file has insufficient permissions, is a directory
> or special file, or is a non-script in a format unrecognized by the
> operating system."

YMMV -- especially the word "non-script" is awkward to me.

But that's bikeshedding...

        --zeurkous.

-- 
Friggin' Machines!

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

[Lawrence Velázquez]

On Fri, Apr 23, 2021, at 4:29 PM, zeurkous@volny.cz wrote:
> YMMV -- especially the word "non-script" is awkward to me.

That final clause is admittedly difficult to express cleanly, and
I'm not completely pleased with my result.  But "is not a script
and in a format unrecognized by the operating system" is ungrammatical
and shouldn't be committed as is.

Perhaps:

"The executable file has insufficient permissions, is a directory
or special file, or is not a script and is in a format unrecognized
by the operating system."

> But that's bikeshedding...

I don't consider grammar correction to be bikeshedding.

-- 
vq

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

[zeurkous]

"Lawrence Velázquez" <larryv@zsh.org> writes:
> On Fri, Apr 23, 2021, at 4:29 PM, zeurkous@volny.cz wrote:
>> YMMV -- especially the word "non-script" is awkward to me.
>
> That final clause is admittedly difficult to express cleanly, and
> I'm not completely pleased with my result. But "is not a script
> and in a format unrecognized by the operating system" is ungrammatical
> and shouldn't be committed as is.

"Ungrammatical" is a term me doesn't often see (or hear). It seems
subjective.

> Perhaps:
>
> "The executable file has insufficient permissions, is a directory
> or special file, or is not a script and is in a format unrecognized
> by the operating system."

Sure, reads fine to me.

>> But that's bikeshedding...
>
> I don't consider grammar correction to be bikeshedding.

Of course not. Grammar (and language in general) is however not as exact
a matter as many would take it to be. Hence "YMMV", too.

        --zeurkous.

-- 
Friggin' Machines!

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

[Bart Schaefer]

On Fri, Apr 23, 2021 at 5:19 AM <zeurkous@volny.cz> wrote:
>
>  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.

I would leave this paragraph unchanged.  It's not necessary to delete
the reference to "a nonzero exit status" in order to later explain
what the nonzero values are.

> +If execution fails: an error message is printed, and one of the
> +following values is returned.

I would move this along with the sitem list to the very end, to follow
the paragraph about the command_not_found handler.

Then change "If execution fails:" to "When there is no handler and
execution fails,".

> +startsitem()
> +sitem(127)
> +The search was unsuccessful.  The error message is
> +`tt(command not found:) var(cmd)'.

As Daniel mentioned, this should be

sitem(127)(Your new text
goes here)

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

[zeurkous]

"Bart Schaefer" <schaefer@brasslantern.com> wrote:
> On Fri, Apr 23, 2021 at 5:19 AM <zeurkous@volny.cz> wrote:
>>
>> 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.
>
> I would leave this paragraph unchanged. It's not necessary to delete
> the reference to "a nonzero exit status" in order to later explain
> what the nonzero values are.

Heh, me reason was the exact opposite: it didn't seem necessary to
duplicate it.

>> +If execution fails: an error message is printed, and one of the
>> +following values is returned.
>
> I would move this along with the sitem list to the very end, to follow
> the paragraph about the command_not_found handler.
>
> Then change "If execution fails:" to "When there is no handler and
> execution fails,".

That opens up a question: what happens when execution fails inside the
handler?

>> +startsitem()
>> +sitem(127)
>> +The search was unsuccessful. The error message is
>> +`tt(command not found:) var(cmd)'.
>
> As Daniel mentioned, this should be
>
> sitem(127)(Your new text
> goes here)

Yeah, that's been noted :)

        --zeurkous.

-- 
Friggin' Machines!

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

[Bart Schaefer]

On Fri, Apr 23, 2021 at 2:03 PM <zeurkous@volny.cz> wrote:
>
> That opens up a question: what happens when execution fails inside the
> handler?

Besides "The return status of the function becomes the status of the command." ?

If the handler is sufficiently badly written that it invokes the same
command name again (with first installing it or some such), you get a
fork-bomb.

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

[zeurkous]

"Bart Schaefer" <schaefer@brasslantern.com> wrote:
> On Fri, Apr 23, 2021 at 2:03 PM <zeurkous@volny.cz> wrote:
>>
>> That opens up a question: what happens when execution fails inside the
>> handler?
>
> Besides "The return status of the function becomes the status of the command." ?

Yes.

> If the handler is sufficiently badly written that it invokes the same
> command name again

Or another command that fails execution?

> (with first installing it or some such), you get a
> fork-bomb.

,s/with/without/ :?

         --zeurkous.

-- 
Friggin' Machines!

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

[Bart Schaefer]

On Fri, Apr 23, 2021 at 2:18 PM <zeurkous@volny.cz> wrote:
>
> "Bart Schaefer" <schaefer@brasslantern.com> wrote:
> > If the handler is sufficiently badly written that it invokes the same
> > command name again
>
> Or another command that fails execution?

If it does that unconditionally, that just devolves to the "same name
again" case, so yes.

> > (with first installing it or some such), you get a
> > fork-bomb.
>
> ,s/with/without/ :?

Yes, typing too fast.

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

[zeurkous]

Making another revision. A question (well, two) below. 

"Bart Schaefer" <schaefer@brasslantern.com> wrote:
> On Fri, Apr 23, 2021 at 5:19 AM <zeurkous@volny.cz> wrote:
>
>> +If execution fails: an error message is printed, and one of the
>> +following values is returned.
>
> I would move this along with the sitem list to the very end, to follow
> the paragraph about the command_not_found handler.
>
> Then change "If execution fails:" to "When there is no handler and
> execution fails,".

Presuming that most people won't bother to install such a handler: isn't
it better to put the more-used information first?

Besides, isn't the handler an additional feature like AUTO_CD, that
modifies the earlier-stated behaviour...?

        --zeurkous.

-- 
Friggin' Machines!

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

[Daniel Shahaf]

zeurkous@volny.cz wrote on Mon, Apr 26, 2021 at 18:25:12 +0200:
> Making another revision. A question (well, two) below. 
> 
> "Bart Schaefer" <schaefer@brasslantern.com> wrote:
> > On Fri, Apr 23, 2021 at 5:19 AM <zeurkous@volny.cz> wrote:
> >
> >> +If execution fails: an error message is printed, and one of the
> >> +following values is returned.
> >
> > I would move this along with the sitem list to the very end, to follow
> > the paragraph about the command_not_found handler.
> >
> > Then change "If execution fails:" to "When there is no handler and
> > execution fails,".
> 
> Presuming that most people won't bother to install such a handler: isn't
> it better to put the more-used information first?
> 

Sounds good to me: describe the common/default case first and layer on
exceptions second.  Bart, WDYT?

> Besides, isn't the handler an additional feature like AUTO_CD, that
> modifies the earlier-stated behaviour...?

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

[Lawrence Velázquez]

On Thu, Apr 29, 2021, at 10:20 AM, Daniel Shahaf wrote:
> zeurkous@volny.cz wrote on Mon, Apr 26, 2021 at 18:25:12 +0200:
> > Making another revision. A question (well, two) below. 
> > 
> > "Bart Schaefer" <schaefer@brasslantern.com> wrote:
> > > On Fri, Apr 23, 2021 at 5:19 AM <zeurkous@volny.cz> wrote:
> > >
> > >> +If execution fails: an error message is printed, and one of the
> > >> +following values is returned.
> > >
> > > I would move this along with the sitem list to the very end, to follow
> > > the paragraph about the command_not_found handler.
> > >
> > > Then change "If execution fails:" to "When there is no handler and
> > > execution fails,".
> > 
> > Presuming that most people won't bother to install such a handler: isn't
> > it better to put the more-used information first?
> > 
> 
> Sounds good to me: describe the common/default case first and layer on
> exceptions second.  Bart, WDYT?

gentle nudge

-- 
vq

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

[Lawrence Velázquez]

On Sun, May 9, 2021, at 3:04 PM, Lawrence Velázquez wrote:
> On Thu, Apr 29, 2021, at 10:20 AM, Daniel Shahaf wrote:
> > zeurkous@volny.cz wrote on Mon, Apr 26, 2021 at 18:25:12 +0200:
> > > Making another revision. A question (well, two) below. 
> > > 
> > > "Bart Schaefer" <schaefer@brasslantern.com> wrote:
> > > > On Fri, Apr 23, 2021 at 5:19 AM <zeurkous@volny.cz> wrote:
> > > >
> > > >> +If execution fails: an error message is printed, and one of the
> > > >> +following values is returned.
> > > >
> > > > I would move this along with the sitem list to the very end, to follow
> > > > the paragraph about the command_not_found handler.
> > > >
> > > > Then change "If execution fails:" to "When there is no handler and
> > > > execution fails,".
> > > 
> > > Presuming that most people won't bother to install such a handler: isn't
> > > it better to put the more-used information first?
> > > 
> > 
> > Sounds good to me: describe the common/default case first and layer on
> > exceptions second.  Bart, WDYT?
> 
> gentle nudge

Hi, do you think you'll be able to send that updated patch soon?
No worries if not.

-- 
vq

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

[Bart Schaefer]

On Sun, May 30, 2021 at 6:10 PM Lawrence Velázquez <larryv@zsh.org> wrote:
>
> On Sun, May 9, 2021, at 3:04 PM, Lawrence Velázquez wrote:
> > On Thu, Apr 29, 2021, at 10:20 AM, Daniel Shahaf wrote:
> > > zeurkous@volny.cz wrote on Mon, Apr 26, 2021 at 18:25:12 +0200:
> > > > "Bart Schaefer" <schaefer@brasslantern.com> wrote:
> > > > > On Fri, Apr 23, 2021 at 5:19 AM <zeurkous@volny.cz> wrote:
>
> Hi, do you think you'll be able to send that updated patch soon?

To whom was that directed?

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

[Lawrence Velázquez]

> On May 31, 2021, at 12:09 AM, Bart Schaefer <schaefer@brasslantern.com> wrote:
> 
> On Sun, May 30, 2021 at 6:10 PM Lawrence Velázquez <larryv@zsh.org> wrote:
>> Hi, do you think you'll be able to send that updated patch soon?
> 
> To whom was that directed?
> 

My fault, that was for the original poster. Sorry for not quoting more clearly:

Begin forwarded message:

> From: <zeurkous@volny.cz>
> Subject: RE: revised patch: zshmisc(1) clarify non-successful exit statuses
> Date: April 26, 2021 at 12:25:12 PM EDT
> To: Bart Schaefer <schaefer@brasslantern.com>
> Cc: <zsh-workers@zsh.org>
> 
> Making another revision. A question (well, two) below.



-- 
vq

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

[zeurkous]

"Lawrence Velázquez" <larryv@zsh.org> wrote:
> On Sun, May 9, 2021, at 3:04 PM, Lawrence Velázquez wrote:
>> On Thu, Apr 29, 2021, at 10:20 AM, Daniel Shahaf wrote:
>> > zeurkous@volny.cz wrote on Mon, Apr 26, 2021 at 18:25:12 +0200:
>> > > Making another revision. A question (well, two) below.
>> > >
>> > > "Bart Schaefer" <schaefer@brasslantern.com> wrote:
>> > > > On Fri, Apr 23, 2021 at 5:19 AM <zeurkous@volny.cz> wrote:
>> > > >
>> > > >> +If execution fails: an error message is printed, and one of the
>> > > >> +following values is returned.
>> > > >
>> > > > I would move this along with the sitem list to the very end, to follow
>> > > > the paragraph about the command_not_found handler.
>> > > >
>> > > > Then change "If execution fails:" to "When there is no handler and
>> > > > execution fails,".
>> > >
>> > > Presuming that most people won't bother to install such a handler: isn't
>> > > it better to put the more-used information first?
>> > >
>> >
>> > Sounds good to me: describe the common/default case first and layer on
>> > exceptions second. Bart, WDYT?
>>
>> gentle nudge
>
> Hi, do you think you'll be able to send that updated patch soon?
> No worries if not.

Sorry for replying so late; recent IRL events have overwhelmed me.

The answer is: yes, me thinks so, give me a few days.

         --zeurkous.

-- 
Friggin' Machines!

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

[Lawrence Velázquez]

On Wed, Jun 30, 2021, at 1:51 PM, zeurkous@volny.cz wrote:
> Sorry for replying so late; recent IRL events have overwhelmed me.
> 
> The answer is: yes, me thinks so, give me a few days.

Thanks for letting us know!  There's no rush, so feel free to take
your time.

-- 
vq