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

[Steve Dondley <s@xxxxxxxxxxx>]

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.