Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Steve Dondley]

I’ve been looking over the documentation and I really can’t make sense out of what the PATH_SCRIPT option is supposed to do.

If it’s set, which it is by default, I think it’s supposed to look through directories PATH and try to find the command. But if it’s not set, it doesn’t look through directories in PATH.

At least that’s my understanding. But as a far as I can tell, I can run a command in /bin with or without PATH_SCRIPT option set.

I’m obviously confused about what the docs are saying. Can someone shed light on this for me? 

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Lawrence Velázquez]

On Thu, Jan 25, 2024, at 9:00 PM, Steve Dondley wrote:
> I’ve been looking over the documentation and I really can’t make sense 
> out of what the PATH_SCRIPT option is supposed to do.
>
> If it’s set, which it is by default, I think it’s supposed to look 
> through directories PATH and try to find the command. But if it’s not 
> set, it doesn’t look through directories in PATH.
>
> At least that’s my understanding. But as a far as I can tell, I can run 
> a command in /bin with or without PATH_SCRIPT option set.
>
> I’m obviously confused about what the docs are saying. Can someone shed 
> light on this for me?

The option affects how zsh behaves when invoked without -c or -s
and with a first non-option argument that doesn't contain any
slashes.  In this situation, shells generally try to find and run
a script with that name in the current directory; if there is no
such script, they try to find one in PATH.  PATH_SCRIPT lets you
control whether zsh performs that fallback PATH search.  (It does
not affect other PATH searches.)

	% cat foo.zsh
	cat: foo.zsh: No such file or directory
	% cat dir/foo.zsh
	print foo
	% PATH=./dir
	% /bin/zsh -o PATH_SCRIPT foo.zsh
	foo
	% /bin/zsh +o PATH_SCRIPT foo.zsh
	/bin/zsh: can't open input file: foo.zsh

-- 
vq

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Steve Dondley]

[-- Attachment #1: Type: text/plain, Size: 1845 bytes --]

Sorry, I’ve got a bad misconcepiton somewhere. I stil don’t get it.

I do: PATH=.dir

When I do: setopt pathscript
And then do: foo.zsh

It finds foo in the ./dir directory and executes it.


Then when i do: unsetopt pathscript
And then I do: foo.zsh

It stil finds foo.zsh in the ./dir directory.

So I’m not seeing how it behaves any differently. 





> On Jan 25, 2024, at 10:05 PM, Lawrence Velázquez <larryv@zsh.org> wrote:
> 
> On Thu, Jan 25, 2024, at 9:00 PM, Steve Dondley wrote:
>> I’ve been looking over the documentation and I really can’t make sense 
>> out of what the PATH_SCRIPT option is supposed to do.
>> 
>> If it’s set, which it is by default, I think it’s supposed to look 
>> through directories PATH and try to find the command. But if it’s not 
>> set, it doesn’t look through directories in PATH.
>> 
>> At least that’s my understanding. But as a far as I can tell, I can run 
>> a command in /bin with or without PATH_SCRIPT option set.
>> 
>> I’m obviously confused about what the docs are saying. Can someone shed 
>> light on this for me?
> 
> The option affects how zsh behaves when invoked without -c or -s
> and with a first non-option argument that doesn't contain any
> slashes.  In this situation, shells generally try to find and run
> a script with that name in the current directory; if there is no
> such script, they try to find one in PATH.  PATH_SCRIPT lets you
> control whether zsh performs that fallback PATH search.  (It does
> not affect other PATH searches.)
> 
> 	% cat foo.zsh
> 	cat: foo.zsh: No such file or directory
> 	% cat dir/foo.zsh
> 	print foo
> 	% PATH=./dir
> 	% /bin/zsh -o PATH_SCRIPT foo.zsh
> 	foo
> 	% /bin/zsh +o PATH_SCRIPT foo.zsh
> 	/bin/zsh: can't open input file: foo.zsh
> 
> -- 
> vq


[-- Attachment #2: Type: text/html, Size: 11291 bytes --]

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Steve Dondley]

[-- Attachment #1: Type: text/plain, Size: 2342 bytes --]

Small type in the last. That first line should read PATH=./dir

I also put a foo.zsh in the current directory and it is never called regardless of whether pathscript is on or off. The foo.zsh script in ./dir is called every time. 

Thanks,
Steve Dondley
Owner, Prometheus Labor Communications
Westfield, MA

413-537-4451




> On Jan 25, 2024, at 10:21 PM, Steve Dondley <s@dondley.com> wrote:
> 
> Sorry, I’ve got a bad misconcepiton somewhere. I stil don’t get it.
> 
> I do: PATH=.dir
> 
> When I do: setopt pathscript
> And then do: foo.zsh
> 
> It finds foo in the ./dir directory and executes it.
> 
> 
> Then when i do: unsetopt pathscript
> And then I do: foo.zsh
> 
> It stil finds foo.zsh in the ./dir directory.
> 
> So I’m not seeing how it behaves any differently. 
> 
> 
> 
> 
> 
>> On Jan 25, 2024, at 10:05 PM, Lawrence Velázquez <larryv@zsh.org> wrote:
>> 
>> On Thu, Jan 25, 2024, at 9:00 PM, Steve Dondley wrote:
>>> I’ve been looking over the documentation and I really can’t make sense 
>>> out of what the PATH_SCRIPT option is supposed to do.
>>> 
>>> If it’s set, which it is by default, I think it’s supposed to look 
>>> through directories PATH and try to find the command. But if it’s not 
>>> set, it doesn’t look through directories in PATH.
>>> 
>>> At least that’s my understanding. But as a far as I can tell, I can run 
>>> a command in /bin with or without PATH_SCRIPT option set.
>>> 
>>> I’m obviously confused about what the docs are saying. Can someone shed 
>>> light on this for me?
>> 
>> The option affects how zsh behaves when invoked without -c or -s
>> and with a first non-option argument that doesn't contain any
>> slashes.  In this situation, shells generally try to find and run
>> a script with that name in the current directory; if there is no
>> such script, they try to find one in PATH.  PATH_SCRIPT lets you
>> control whether zsh performs that fallback PATH search.  (It does
>> not affect other PATH searches.)
>> 
>> 	% cat foo.zsh
>> 	cat: foo.zsh: No such file or directory
>> 	% cat dir/foo.zsh
>> 	print foo
>> 	% PATH=./dir
>> 	% /bin/zsh -o PATH_SCRIPT foo.zsh
>> 	foo
>> 	% /bin/zsh +o PATH_SCRIPT foo.zsh
>> 	/bin/zsh: can't open input file: foo.zsh
>> 
>> -- 
>> vq
> 


[-- Attachment #2: Type: text/html, Size: 12180 bytes --]

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Lawrence Velázquez]

On Thu, Jan 25, 2024, at 10:21 PM, Steve Dondley wrote:
> Sorry, I’ve got a bad misconcepiton somewhere. I stil don’t get it.
>
> I do: PATH=.dir
>
> When I do: setopt pathscript
> And then do: foo.zsh
>
> It finds foo in the ./dir directory and executes it.
>
>
> Then when i do: unsetopt pathscript
> And then I do: foo.zsh
>
> It stil finds foo.zsh in the ./dir directory.
>
> So I’m not seeing how it behaves any differently. 

You doing something completely different from what I described and
demonstrated.  PATH_SCRIPT *only* affects how zsh behaves when you
invoke it to run a script (e.g., ''zsh script_name'').  It does not
affect PATH searches performed as part of command execution.

-- 
vq

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Steve Dondley]

[-- Attachment #1: Type: text/plain, Size: 1684 bytes --]

I guess I never realized that, when it comes to options, there is a difference between running a script directly and passing it as an argument to zsh. 

But even still, If I do this:

> echo $PATH
/usr/bin:./dir

> ls dir
-rwxr--r-- 1 root root 9 Jan 26 03:26 foo.zsh

> setopt pathscript

> zsh foo.zsh
zsh: can't open input file: foo.zsh

> unsetopt pathscript

> zsh foo.zsh
zsh: can't open input file: foo.zsh


So I’m still seeing no difference between execution of the script with path script on or off in these cases.

HOWEVER, I discovered if I put this in my .zshrc:

setopt pathscript

and do:

> zsh -i foo.zsh

It works.


Or, if I do

> setopt pathscript

and then do

> zsh -c foo.zsh

This also works.

> zsh -i foo.zsh wil also work in this case, too. 




> On Jan 25, 2024, at 10:45 PM, Lawrence Velázquez <larryv@zsh.org> wrote:
> 
> On Thu, Jan 25, 2024, at 10:21 PM, Steve Dondley wrote:
>> Sorry, I’ve got a bad misconcepiton somewhere. I stil don’t get it.
>> 
>> I do: PATH=.dir
>> 
>> When I do: setopt pathscript
>> And then do: foo.zsh
>> 
>> It finds foo in the ./dir directory and executes it.
>> 
>> 
>> Then when i do: unsetopt pathscript
>> And then I do: foo.zsh
>> 
>> It stil finds foo.zsh in the ./dir directory.
>> 
>> So I’m not seeing how it behaves any differently. 
> 
> You doing something completely different from what I described and
> demonstrated.  PATH_SCRIPT *only* affects how zsh behaves when you
> invoke it to run a script (e.g., ''zsh script_name'').  It does not
> affect PATH searches performed as part of command execution.
> 
> -- 
> vq


[-- Attachment #2: Type: text/html, Size: 22647 bytes --]

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Lawrence Velázquez]

On Thu, Jan 25, 2024, at 9:00 PM, Steve Dondley wrote:
> I’ve been looking over the documentation and I really can’t make sense 
> out of what the PATH_SCRIPT option is supposed to do.
>
> If it’s set, which it is by default

This is not true.  PATH_SCRIPT is only set by default in ksh/sh
emulation.

-- 
vq

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Lawrence Velázquez]

On Thu, Jan 25, 2024, at 11:17 PM, Steve Dondley wrote:
> I guess I never realized that, when it comes to options, there is a 
> difference between running a script directly and passing it as an 
> argument to zsh. 

You're overgeneralizing.  PATH_SCRIPT is defined to only affect the
latter scenario, but you are confused because you have been trying
to apply it to the former scenario.  There is no broader lesson
about options here.

It's like being confused that POSIX_CD doesn't make the jobs(1)
builtin more POSIX-conformant, even though it never claimed to.
It is a category mistake.


> But even still, If I do this:
>
>> echo $PATH
> /usr/bin:./dir
>
>> ls dir
> -rwxr--r-- 1 root root 9 Jan 26 03:26 foo.zsh
>
>> setopt pathscript
>
>> zsh foo.zsh
> zsh: can't open input file: foo.zsh
>
>> unsetopt pathscript
>
>> zsh foo.zsh
> zsh: can't open input file: foo.zsh
>
>
> So I’m still seeing no difference between execution of the script with 
> path script on or off in these cases.

Options are not inherited by child shells created in this manner.
That is why my demonstration used -o and +o.

	% ([[ -o EXTENDED_GLOB ]]; print $?)
	1
	% setopt EXTENDED_GLOB
	% ([[ -o EXTENDED_GLOB ]]; print $?)
	0
	% zsh -c '[[ -o EXTENDED_GLOB ]]; print $?'
	1


> HOWEVER, I discovered if I put this in my .zshrc:
>
> setopt pathscript
>
> and do:
>
>> zsh -i foo.zsh
>
> It works.

Yes, because interactive shells source .zshrc.


> Or, if I do
>
>> setopt pathscript
>
> and then do
>
>> zsh -c foo.zsh
>
> This also works.

No, you are conflating unrelated things again.  With -c, zsh evaluates
the "foo.zsh" argument as a complete script, so it performs a PATH
search as usual.  As I said earlier, PATH_SCRIPT *does not apply* to
''zsh -c''; its status is irrelevant.

	% cat foo.sh
	cat: foo.sh: No such file or directory
	% cat dir/foo.sh
	echo foo
	% PATH=./dir /bin/zsh -o PATH_SCRIPT -c foo.sh 
	foo
	% PATH=./dir /bin/zsh +o PATH_SCRIPT -c foo.sh
	foo


-- 
vq

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Steve Dondley]

[-- Attachment #1: Type: text/plain, Size: 2987 bytes --]

OK, thanks.

At the risk of dragging this on, allow me to ask this simple question to make sure I got it:

Is there any way to run this command by itself on the command line:

> setopt pathscript

And have it affect the outcome of any subsequent commands? It looks like the answer is no. 

It looks to me like the pathscript setting can only affect future commands if it’s either:

a) used with +o or -o as part of an argument passed directly to zsh while running a script
b) or if it’s set in a .zshrc file (or other config file) and then sourced when a new shell (interactive mode)

Please tell me I have this correct otherwise I’m still badly confused. 




> On Jan 25, 2024, at 11:58 PM, Lawrence Velázquez <larryv@zsh.org> wrote:
> 
> On Thu, Jan 25, 2024, at 11:17 PM, Steve Dondley wrote:
>> I guess I never realized that, when it comes to options, there is a 
>> difference between running a script directly and passing it as an 
>> argument to zsh. 
> 
> You're overgeneralizing.  PATH_SCRIPT is defined to only affect the
> latter scenario, but you are confused because you have been trying
> to apply it to the former scenario.  There is no broader lesson
> about options here.
> 
> It's like being confused that POSIX_CD doesn't make the jobs(1)
> builtin more POSIX-conformant, even though it never claimed to.
> It is a category mistake.
> 
> 
>> But even still, If I do this:
>> 
>>> echo $PATH
>> /usr/bin:./dir
>> 
>>> ls dir
>> -rwxr--r-- 1 root root 9 Jan 26 03:26 foo.zsh
>> 
>>> setopt pathscript
>> 
>>> zsh foo.zsh
>> zsh: can't open input file: foo.zsh
>> 
>>> unsetopt pathscript
>> 
>>> zsh foo.zsh
>> zsh: can't open input file: foo.zsh
>> 
>> 
>> So I’m still seeing no difference between execution of the script with 
>> path script on or off in these cases.
> 
> Options are not inherited by child shells created in this manner.
> That is why my demonstration used -o and +o.
> 
> 	% ([[ -o EXTENDED_GLOB ]]; print $?)
> 	1
> 	% setopt EXTENDED_GLOB
> 	% ([[ -o EXTENDED_GLOB ]]; print $?)
> 	0
> 	% zsh -c '[[ -o EXTENDED_GLOB ]]; print $?'
> 	1
> 
> 
>> HOWEVER, I discovered if I put this in my .zshrc:
>> 
>> setopt pathscript
>> 
>> and do:
>> 
>>> zsh -i foo.zsh
>> 
>> It works.
> 
> Yes, because interactive shells source .zshrc.
> 
> 
>> Or, if I do
>> 
>>> setopt pathscript
>> 
>> and then do
>> 
>>> zsh -c foo.zsh
>> 
>> This also works.
> 
> No, you are conflating unrelated things again.  With -c, zsh evaluates
> the "foo.zsh" argument as a complete script, so it performs a PATH
> search as usual.  As I said earlier, PATH_SCRIPT *does not apply* to
> ''zsh -c''; its status is irrelevant.
> 
> 	% cat foo.sh
> 	cat: foo.sh: No such file or directory
> 	% cat dir/foo.sh
> 	echo foo
> 	% PATH=./dir /bin/zsh -o PATH_SCRIPT -c foo.sh 
> 	foo
> 	% PATH=./dir /bin/zsh +o PATH_SCRIPT -c foo.sh
> 	foo
> 
> 
> -- 
> vq


[-- Attachment #2: Type: text/html, Size: 38224 bytes --]

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Bart Schaefer]

On Thu, Jan 25, 2024 at 9:20 PM Steve Dondley <s@dondley.com> wrote:
>
> It looks to me like the pathscript setting can only affect future commands if it’s either:
>
> a) used with +o or -o as part of an argument passed directly to zsh while running a script
> b) or if it’s set in a .zshrc file (or other config file) and then sourced when a new shell (interactive mode)
>
> Please tell me I have this correct otherwise I’m still badly confused.

You have this almost correct.  Sourcing for interactive mode has
nothing to do with it.  It always applies to the scriptname argument
passed to a new zsh, so it has to be in effect before zsh searches for
the script.

For completeness, the following also enable path_script:

c) "zsh --emulate sh scriptname" or "zsh --emulate ksh scriptname"
d) zsh is invoked by the name "sh" or "ksh" via a filesystem link
e) ARGV0=sh or ARGV0=ksh is in the environment when zsh is invoked

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Lawrence Velázquez]

On Fri, Jan 26, 2024, at 12:20 AM, Steve Dondley wrote:
> OK, thanks.
>
> At the risk of dragging this on, allow me to ask this simple question 
> to make sure I got it:
>
> Is there any way to run this command by itself on the command line:
>
>> setopt pathscript
>
> And have it affect the outcome of any subsequent commands? It looks 
> like the answer is no.

Correct.  It does not affect regular command execution (and is not
intended to).


> It looks to me like the pathscript setting can only affect future 
> commands if it’s either:
>
> a) used with +o or -o as part of an argument passed directly to zsh 
> while running a script
> b) or if it’s set in a .zshrc file (or other config file) and then 
> sourced when a new shell (interactive mode)

Those are two ways to enable PATH_SEARCH for a new zsh process,
sure.  Bart listed some more.

But "affecting future commands" is not really the way to look at
it; the option is not that general.  PATH_SCRIPT affects one very
specific behavior: whether or not ''zsh foo'' searches PATH for a
script "foo" if ./foo doesn't exist.  It does not affect anything
else, including PATH search *within* that script.

Probably should have asked earlier, but:  What were you trying to
achieve with PATH_SEARCH, exactly?


-- 
vq

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Lawrence Velázquez]

On Fri, Jan 26, 2024, at 12:52 AM, Bart Schaefer wrote:
> For completeness, the following also enable path_script:
>
> c) "zsh --emulate sh scriptname" or "zsh --emulate ksh scriptname"
> d) zsh is invoked by the name "sh" or "ksh" via a filesystem link
> e) ARGV0=sh or ARGV0=ksh is in the environment when zsh is invoked

f) zsh is invoked as "sh" or "ksh" via "exec -a", exec*(3), etc.

-- 
vq

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Lawrence Velázquez]

On Fri, Jan 26, 2024, at 1:25 AM, Lawrence Velázquez wrote:
> Those are two ways to enable PATH_SEARCH for a new zsh process,
> sure.  Bart listed some more.
>
> But "affecting future commands" is not really the way to look at
> it; the option is not that general.  PATH_SCRIPT affects one very
> specific behavior: whether or not ''zsh foo'' searches PATH for a
> script "foo" if ./foo doesn't exist.  It does not affect anything
> else, including PATH search *within* that script.
>
> Probably should have asked earlier, but:  What were you trying to
> achieve with PATH_SEARCH, exactly?

Sorry, it's late here.  Everywhere I have accidentally written
"PATH_SEARCH", I meant "PATH_SCRIPT".

-- 
vq

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Steve Dondley]

> 
> Probably should have asked earlier, but:  What were you trying to
> achieve with PATH_SEARCH, exactly?
> 

I wasn’t trying to do anything. I was just reading through the manual to bone up on things and tried running commands with and without PATH_SCRIPT set and I didn’t see a difference. I couldn’t figure out why not. 

Thanks for all the help and time.

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Steve Dondley]

[-- Attachment #1: Type: text/plain, Size: 589 bytes --]


> 
> You have this almost correct.  Sourcing for interactive mode has
> nothing to do with it.  It always applies to the scriptname argument
> passed to a new zsh, so it has to be in effect before zsh searches for
> the script.

I may not be following you here.

If I have a script at ./dir/some_script and I do:

> PATH=./dir
> setopt pathscript

Then do

> /bin/zsh some_script

It will not look for the script in $PATH as far as I can tell and fails with zsh: can't open input file: some_script

You are saying my last command above should work with pathscript on? 

[-- Attachment #2: Type: text/html, Size: 1531 bytes --]

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Mark J. Reed]

[-- Attachment #1: Type: text/plain, Size: 1343 bytes --]

When you set an option with *setopt*, that sets it for the shell you are
already in and typing commands to.

When you run */bin/zsh* as a command, you are starting up a brand new shell
that does not inherit those options.

*zsh% setopt pathscript                *
*zsh% set -o | grep pathscript         *
*pathscript            on*
*zsh% zsh -c 'set -o | grep pathscript'*
*pathscript            off*


So doing *setopt pathscript* has no effect whatsoever on what a
subsequent */bin/zsh
some_script* will do. You have to do this instead:

*/bin/zsh -o pathscript some_script*



On Fri, Jan 26, 2024 at 10:50 AM Steve Dondley <s@dondley.com> wrote:

>
>
> You have this almost correct.  Sourcing for interactive mode has
> nothing to do with it.  It always applies to the scriptname argument
> passed to a new zsh, so it has to be in effect before zsh searches for
> the script.
>
>
> I may not be following you here.
>
> If I have a script at ./dir/some_script and I do:
>
> > PATH=./dir
> > setopt pathscript
>
> Then do
>
> > /bin/zsh some_script
>
> It will not look for the script in $PATH as far as I can tell and fails
> with zsh: can't open input file: some_script
>
> You are saying my last command above should work with pathscript on?
>


-- 
Mark J. Reed <markjreed@gmail.com>

[-- Attachment #2: Type: text/html, Size: 2975 bytes --]

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Mark J. Reed]

[-- Attachment #1: Type: text/plain, Size: 677 bytes --]

(Sorry, I neglected to trim the recipients list in my reply and sent Steve
and Bart duplicates.).

I just have one addendum to my previous message:

On Fri, Jan 26, 2024 at 11:07 AM Mark J. Reed <markjreed@gmail.com> wrote:

> So doing *setopt pathscript* has no effect whatsoever on what a
> subsequent */bin/zsh some_script* will do. You have to do this instead:
>
> */bin/zsh -o pathscript some_script*
>
>
This is why the documentation for the PATH_SCRIPT option in zshoptions(1)
points you to the INVOCATION section of the main zsh manual: the option is
really only useful when specified on the command line.


-- 
Mark J. Reed <markjreed@gmail.com>

[-- Attachment #2: Type: text/html, Size: 1469 bytes --]

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Steve Dondley]

[-- Attachment #1: Type: text/plain, Size: 858 bytes --]

> 
> This is why the documentation for the PATH_SCRIPT option in zshoptions(1) points you to the INVOCATION section of the main zsh manual: the option is really only useful when specified on the command line.
> 

I’ve got lots of quibbles with how that section is written. It is not for mere mortals.Take just the first sentence, for example:

"The following flags are interpreted by the shell when invoked to determine where the shell will read commands from:"

“when invoked” is bad jargon. The use of passive voice is confusing and “to determine where the shell will read commands from” is just torturous wording.

Instead:

A user or script can use the appropriate command, usually /bin/zsh, to launch a new z shell process. Optional flags passed to the command control where the shell looks for new commands to interpret:





[-- Attachment #2: Type: text/html, Size: 1414 bytes --]

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Ray Andrews]

[-- Attachment #1: Type: text/plain, Size: 944 bytes --]


On 2024-01-26 09:21, Steve Dondley wrote:
>>
>> This is why the documentation for the PATH_SCRIPT option in 
>> zshoptions(1) points you to the INVOCATION section of the main zsh 
>> manual: the option is really only useful when specified on the 
>> command line.
>>
>
> I’ve got lots of quibbles with how that section is written. It is not 
> for mere mortals.
  Nice to have another mere moral around.  We will understand each 
other's frustrations with the docs.  Technical writing is usually bad, 
and it seems that in the 'nix word that is particularly true. zsh isn't 
the worst tho, some 'man' pages are designed to baffle. In some ways the 
zsh manual is a masterpiece of a certain kind of doc -- a compendium of 
everything that's true -- but helpful it ain't.  I like to say that the 
guy who wrote it (Paul F. I presume) was so knowledgeable and so 
intelligent that writing for mere mortals would have been difficult for him.

[-- Attachment #2: Type: text/html, Size: 1738 bytes --]

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Roman Perepelitsa]

On Fri, Jan 26, 2024 at 7:29 PM Ray Andrews <rayandrews@eastlink.ca> wrote:
>
> Technical writing is usually bad, and it seems that in the 'nix word that is particularly true.

I respectfully disagree. In my experience, Unix man pages, in
particular zsh documentation, are excellent resources, effectively
tailored to their intended audience. I'm part of that demographic and
find them incredibly useful. Difficulty in understanding content, like
cooking recipes in my case, often stems from it not being designed for
our specific knowledge base. This doesn't diminish the quality of the
content itself.

Roman.

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Steve Dondley]

[-- Attachment #1: Type: text/plain, Size: 2269 bytes --]

> 
> I respectfully disagree. In my experience, Unix man pages, in
> particular zsh documentation, are excellent resources, effectively
> tailored to their intended audience. I'm part of that demographic and
> find them incredibly useful. Difficulty in understanding content, like
> cooking recipes in my case, often stems from it not being designed for
> our specific knowledge base. This doesn't diminish the quality of the
> content itself.


Well, I like to talk about specific examples. Speaking in generalities about whether documentation is good/bad gets us nowhere.

So if you got to Chapter 5, paragraph 2, you’ll see:
It is also possible for a file in $ZDOTDIR to re-enable GLOBAL_RCS. Both RCS and GLOBAL_RCS are set by default.


Now, I’m not exactly a newb but I’m far from an expert. But I fell like I’m getting assaulted out of the blue with this before unmentioned $ZDOTDIR variable. Immediately my mind starts spinning with questions:

1) where is this variable set?
2) what are some typical values for it?
3) do I have to worry about this if I’m using the XDG config
4) does the OS handle this for me? 
5) This looks like an environment variable? Is it an environment variable or something different?

Yes, I'm getting technically accurate information about this variable. But nowhere does the documentation give me any clue on how to use this setting in a practical way and why it might be useful to me.

So next I search through the manual. I see ZDOTDIR listed in the “Parameters” chapter. I have no idea what a “Parameter” is. Is this an environment variable? And I don’t get any of my other questions answered. 

I could go on. But my main point is that it feels like the documentation makes the assumption you know how a typical shell works and that you are familiar with the many common features between the different kinds of shells. That’s fine, but it feels like the documenation could put in a much better effort of at least giving you a bit more of a big picture clue if you don’t have one.

Couple this problem with wording that is stylistically like nails on a chalkboard  and you are in for a very tough slog. You have to have a huge amount of time on your hands to get through it. 

[-- Attachment #2: Type: text/html, Size: 3799 bytes --]

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Roman Perepelitsa]

On Fri, Jan 26, 2024 at 8:17 PM Steve Dondley <s@dondley.com> wrote:
>
> I see ZDOTDIR listed in the “Parameters” chapter. I have no idea
> what a “Parameter” is.

Consider a cookie recipe that starts with "Cream the butter and sugar
until light and fluffy." It assumes a basic understanding of baking
techniques. Similarly, the zsh documentation, with terms like
"Parameter", presupposes basic shell knowledge. It's geared towards
those who have this baseline, much like the recipe book is for those
with rudimentary cooking skills.

> But my main point is that it feels like the documentation makes the
> assumption you know how a typical shell works and that you are
> familiar with the many common features between the different kinds
> of shells.

Your observation is correct. All documentation, including zsh's, must
assume some level of prior knowledge. When our understanding doesn't
meet this level, it can be challenging and frustrating, but we can
bridge this gap through other resources. On the other hand, if the
documentation were too basic, covering familiar ground, it would be
inefficient for advanced users, leaving them to sift through redundant
information.

Roman.

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Ray Andrews]

[-- Attachment #1: Type: text/plain, Size: 1309 bytes --]


On 2024-01-26 10:38, Roman Perepelitsa wrote:
> I respectfully disagree. In my experience, Unix man pages, in
> particular zsh documentation, are excellent resources, effectively
> tailored to their intended audience. I'm part of that demographic and
> find them incredibly useful.
They are indispencible in the same way that the blueprints of a nuclear 
power station are indicpencible and if you are already an expert you may 
find them even friendly.  But if you aren't an expert the docs are cold 
help becoming one.  It's like trying to learn Hungarian by reading a 
Hungarian grammar written in Hungarian from one Hungarian grammarian to 
another.
>   Difficulty in understanding content, like
> cooking recipes in my case, often stems from it not being designed for
> our specific knowledge base. This doesn't diminish the quality of the
> content itself.

Quality is not in question, rather presumed reader and specific goals.  
Again, if you are already an expert the manual is your reference to 
recall some detail or other and it could hardly be better.  But if you 
want to *understand* the shell, best to read Peter's book or some other 
resource.  The manual stores information but explains nothing.  It is 
also written in shell jargon which if fine if you already speak shell 
jargon.


[-- Attachment #2: Type: text/html, Size: 1984 bytes --]

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Steve Dondley]

Right. I’m just suggesting the documentation could put in more effort giving a nod and helping hand to those who don’t have a lot of experience with shells.

For example, instead of just dropping ZDOTDIR on my head like I already knew what it was, it could instead say:

On most systems,, a user’s zsh configuration files are kept in their $HOME directory by default. If you wish to store these modules in a different location, this can be modified by setting the value of the ZDOTDIR parameter to a directory path of your choosing. For example, if you wish your user to follow the XDG specification, you might set the value to $HOME/.config/zsh. Typically, this value is set in the /some/config/file configuration file but consult your OS’s manual for details.  

This is a much gentler way of introducing this variable to me. 

> On Jan 26, 2024, at 2:38 PM, Roman Perepelitsa <roman.perepelitsa@gmail.com> wrote:
> 
> On Fri, Jan 26, 2024 at 8:17 PM Steve Dondley <s@dondley.com> wrote:
>> 
>> I see ZDOTDIR listed in the “Parameters” chapter. I have no idea
>> what a “Parameter” is.
> 
> Consider a cookie recipe that starts with "Cream the butter and sugar
> until light and fluffy." It assumes a basic understanding of baking
> techniques. Similarly, the zsh documentation, with terms like
> "Parameter", presupposes basic shell knowledge. It's geared towards
> those who have this baseline, much like the recipe book is for those
> with rudimentary cooking skills.
> 
>> But my main point is that it feels like the documentation makes the
>> assumption you know how a typical shell works and that you are
>> familiar with the many common features between the different kinds
>> of shells.
> 
> Your observation is correct. All documentation, including zsh's, must
> assume some level of prior knowledge. When our understanding doesn't
> meet this level, it can be challenging and frustrating, but we can
> bridge this gap through other resources. On the other hand, if the
> documentation were too basic, covering familiar ground, it would be
> inefficient for advanced users, leaving them to sift through redundant
> information.
> 
> Roman.

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Ray Andrews]

On 2024-01-26 11:17, Steve Dondley wrote:
>>
> Yes, I'm getting technically accurate information about this variable. 
> But nowhere does the documentation give me any clue on how to use this 
> setting in a practical way and why it might be useful to me.
Just to be devil's advocate, I don't think the manual is intended to do 
that -- however much is wish it was.
>
> So next I search through the manual. I see ZDOTDIR listed in the 
> “Parameters” chapter. I have no idea what a “Parameter” is. Is this an 
> environment variable? And I don’t get any of my other questions answered.
Yeah, the jargon.  When I came over from DOS,  I tried desperately to 
find some doc: "Linux jargon for DOS-speakers".  It took me countless 
hours to figure out that a batch file is a script.  A variable is a 
parameter.  A switch is an option.  Then the cultural assumptions!  A 
Connecticut Yankee in King Arthur's Court.
>
> I could go on. But my main point is that it feels like the 
> documentation makes the assumption you know how a typical shell works 
> and that you are familiar with the many common features between the 
> different kinds of shells. That’s fine, but it feels like the 
> documenation could put in a much better effort of at least giving you 
> a bit more of a big picture clue if you don’t have one.
>
> Couple this problem with wording that is stylistically like nails on a 
> chalkboard  and you are in for a very tough slog. You have to have a 
> huge amount of time on your hands to get through it.

You need to read Peter's book.  Even there, as an expert he can't help 
but have a hard time putting himself in the mind of a neophyte.  As I 
always say, help material is best written by someone who needs the help 
and just now figured it out and knows what it was they needed to hear.  
Experts can't do that.

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Steve Dondley]

> On Jan 26, 2024, at 2:54 PM, Ray Andrews <rayandrews@eastlink.ca> wrote:
> 
> 
> On 2024-01-26 11:17, Steve Dondley wrote:
>>> 
>> Yes, I'm getting technically accurate information about this variable. But nowhere does the documentation give me any clue on how to use this setting in a practical way and why it might be useful to me.
> Just to be devil's advocate, I don't think the manual is intended to do that -- however much is wish it was.

Yeah, I get this. I don’t expect it to be a full blown tutorial holding your hand on basic points. But maybe just mentioning vague, big picture points in passing from time to time might help a light bulb go off. This manual seems to make little effort in that direction. 

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Ray Andrews]

[-- Attachment #1: Type: text/plain, Size: 1986 bytes --]


On 2024-01-26 11:52, Steve Dondley wrote:
> On most systems,, a user’s zsh configuration files are kept in their $HOME directory by default. If you wish to store these modules in a different location, this can be modified by setting the value of the ZDOTDIR parameter to a directory path of your choosing. For example, if you wish your user to follow the XDG specification, you might set the value to $HOME/.config/zsh. Typically, this value is set in the /some/config/file configuration file but consult your OS’s manual for details.
>
> This is a much gentler way of introducing this variable to me.

You and I have essentially identical ideas about how it should read.  
Even if the manual is to be a manual, not a 'zsh for dummies', the 
language could be much more helpful.  But it's as long as the Bible, and 
who's going to spend a year giving it a workover?

But my main point is that it feels like the documentation makes the
>>> assumption you know how a typical shell works and that you are
>>> familiar with the many common features between the different kinds
>>> of shells.
Yes, it does, and so it must.
>> Your observation is correct. All documentation, including zsh's, must
>> assume some level of prior knowledge. When our understanding doesn't
>> meet this level, it can be challenging and frustrating, but we can
>> bridge this gap through other resources. On the other hand, if the
>> documentation were too basic, covering familiar ground, it would be
>> inefficient for advanced users, leaving them to sift through redundant
>> information.

Yup, so there's the dilemma.  But even then, as Steve's little example 
above shows, within the culture of a manual (not a help resource) things 
could be better.  If it were up to me I'd paste Steve's little edit 
above into the manual -- subject to a close look by the experts of 
course.  The devs have admitted a few changes, but much more could be 
done IMHO.  Things don't have to be terse and obscure.


[-- Attachment #2: Type: text/html, Size: 3062 bytes --]

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Roman Perepelitsa]

On Fri, Jan 26, 2024 at 8:43 PM Ray Andrews <rayandrews@eastlink.ca> wrote:
>
> They are indispencible in the same way that the blueprints of a nuclear power station are indicpencible

Exactly, zsh documentation is a nuclear power station blueprints.
Transforming it into a basic physics tutorial would dilute its
effectiveness as a specialized blueprint. For foundational knowledge,
there are plenty of resources on the basics of physics.

On Fri, Jan 26, 2024 at 8:52 PM Steve Dondley <s@dondley.com> wrote:
>
> [...] instead of just dropping ZDOTDIR on my head like I already
> knew what it was, it could instead say:
>
> On most systems,, a user’s zsh configuration files are kept in
> their $HOME directory by default. If you wish to store these
> modules in a different location, this can be modified by setting
> the value of the ZDOTDIR parameter to a directory path of your
> choosing. For example, if you wish your user to follow the XDG
> specification, you might set the value to $HOME/.config/zsh.
> Typically, this value is set in the /some/config/file configuration
> file but consult your OS’s manual for details.
>
> This is a much gentler way of introducing this variable to me.

I agree that your version would be better for someone unfamiliar with
this concept. But can you see that it might be less efficient for
someone who already understands it? And consider where to draw the
line with foundational explanations. Should we also explain what $HOME
is, what a directory means, or what 'consult' implies?

I understand it's frustrating to read something you're not yet
familiar with. This happens with any technical text. The documentation
works well for those at a certain knowledge level. You can get to that
level too, but you might need to learn from other sources first.

Roman.

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Lawrence Velázquez]

On Fri, Jan 26, 2024, at 3:06 PM, Ray Andrews wrote:
> Yup, so there's the dilemma.  But even then, as Steve's little example 
> above shows, within the culture of a manual (not a help resource) 
> things could be better.  If it were up to me I'd paste Steve's little 
> edit above into the manual -- subject to a close look by the experts of 
> course.  The devs have admitted a few changes, but much more could be 
> done IMHO.  Things don't have to be terse and obscure.

I'm going to go ahead and nip this in the bud.

If you have specific suggestions, as Steve does, that feedback is
welcome.  Otherwise, I'm going to ask that you stop flooding the
mailing list with your periodic, unhelpful "the manual is useless!"
diatribes.  In practice, they are wholly unpersuasive and accomplish
nothing except irritating those who have contributed to the manual
or might be inclined to do so in the future.

-- 
vq

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Steve Dondley]

> 
> I agree that your version would be better for someone unfamiliar with
> this concept. But can you see that it might be less efficient for
> someone who already understands it? And consider where to draw the
> line with foundational explanations. Should we also explain what $HOME
> is, what a directory means, or what 'consult' implies?

You are right. It’s a judgement call and you have to draw the line somewhere. 

What I’m saying I’ve been using shells since the late 90s. I know some things but there’s still a lot I don’t know because I never studied shells in any detail.

If a manual can’t help a user like me or if I find it frustrating to read and use it, I’d have to say it is probably erring in the direction of being to concise. That might be great fo the 10% of users who are hard core developers doing all kinds of fancy things. But in my opinion it should also strive to help reach a wider audience that use a shell as a means to a different end.

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Ray Andrews]

[-- Attachment #1: Type: text/plain, Size: 1335 bytes --]


On 2024-01-26 12:08, Roman Perepelitsa wrote:
> Exactly, zsh documentation is a nuclear power station blueprints.
> Transforming it into a basic physics tutorial

I quite agree.  A manual is not a tutorial.  Still, that's no reason for 
the manual to be impenetrable -- as if that was somehow a virtue.  A 
while back Peter rewrote something and it went from being baffling to 
being helpful.  Why *not* make things as clear as possible?


> I agree that your version would be better for someone unfamiliar withthis concept.But can you see that it might be less efficient for
> someone who already understands it? And consider where to draw the
> line with foundational explanations. Should we also explain what $HOME
> is, what a directory means, or what 'consult' implies?

It's always a matter of judgement where one draws the line.  It goes 
without saying that things should not be dumbed down to the point of 
dilution.  Within, say, a thousand words, why not make those thousand 
words as clear as they can be?  Steve's sample -- what is *lost*?  What 
utility is compromised?  If much is gained and nothing is lost, I say 
it's a plain improvement.  Put it this way: if my needs and your needs 
are in conflict as to the manual, yours must prevail.  But what if my 
needs could be met without compromising yours?



[-- Attachment #2: Type: text/html, Size: 2330 bytes --]

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[Steve Dondley]

[-- Attachment #1: Type: text/plain, Size: 766 bytes --]


> 
> You need to read Peter's book.  Even there, as an expert he can't help but have a hard time putting himself in the mind of a neophyte.  As I always say, help material is best written by someone who needs the help and just now figured it out and knows what it was they needed to hear.  Experts can't do that.
> 
> 
> 

Thanks, I’ll check it out. The first book that came up was: https://zsh.sourceforge.io/Guide/zshguide.pdf

I think what I need is a book for intermediate users to help get me take things to the next level. If zsh was a chess rating, I’d probably be at 1200. I know how all the pieces move and I’m decent at knowing what a good board position is but I don’t have any opening gambits memorized and I make lots of dumb mistakes.

[-- Attachment #2: Type: text/html, Size: 1151 bytes --]

Re: Can't tell the difference in operation between PATH_SCRIPT and NO_PATH_SCRIPT

[.m0rph]

Am Fri, 26 Jan 2024 14:17:14 -0500
schrieb Steve Dondley <s@dondley.com>:

> > 
> > I respectfully disagree.

And so do I ...

> [...] I see ZDOTDIR listed in the
> “Parameters” chapter. I have no idea what a “Parameter” is. Is this
> an environment variable? And I don’t get any of my other questions
> answered.

man zshparam

First Section "DESCRIPTION"
First Paragraph

[cite]
A parameter has a name, a value, and a number of attributes. 
A name may be any sequence of alphanumeric characters and underscores,
or the single characters ‘*', ‘@', ‘#', ‘?', ‘-', ‘$', or ‘!'. A
parameter whose name begins with an alphanumeric or underscore is also
referred to as a variable.
[/cite]

For me this definitely adequately describes what exactly a 'parameter'
is.

   --> arguments <--==--> parameters <--==--> variables <--

Is just depends on the angle from which I have the view to them.

And the $ZDOTDIR:
   https://zsh.sourceforge.io/Intro/intro_3.html

So, if you want to have the zsh startup files, e.g. your sysop mounts
your team account to somewhere else than

/home/user,

then he will probably set

ZDOTDIR=/srv/teams/coders/user


Have a lot of Fun...

-uw
-- 
+----------------------------------------------------------------------+
| .m0rph@work                       | https://twitter.com/m0rphisto/   |
|                                   | https://github.com/m0rphisto/    |
|                                   |                          .--.    |
|                   _          _ _   _ _                      |o_o |   |
| ^__^             | | __     | (_) | (_)                     |:_/ |   |
| (oo)________     | |/ /  _ _| |_  | |_ _ __  _   ___  __   //   \ \  |
| (__)\       )/\/ | ` / / _` | | | | | | '_ \| | | \ \/ /  (|     | ) |
|     ||----W |    | , \| (_| | | | | | | | | | |_| |>  <  /'\_   _/`\ |
|     ||     ||    |_|\_\\__,_|_|_| |_|_|_| |_|\__,_/_/\_\ \___)=(___/ |
+----------------------------------------------------------------------+