[PATCH] Clarify documentation of parameter-assignment behaviour

[PATCH] Clarify documentation of parameter-assignment behaviour

[dana]

Someone asked on IRC if it was 'safe' to perform an assignment like a=$b when
sh_word_split is enabled. I quoted the documentation where it says that the RHS
is always expanded as a single string, but then i realised that this isn't
actually as explicit as it seems when it comes to 'splitting' features like
sh_word_split. Consider the following:

  % a='foo      bar'
  % ( setopt sh_word_split; b=$a; typeset b )
  b='foo      bar'
  % ( b=$=a; typeset b )
  b='foo      bar'
  % ( b=${(s< >)a}; typeset b )
  b='foo      bar'

In each case, it's not unreasonable to assume (IMO) that the value of b will be
the result of *splitting and then rejoining* the expanded value of a, similar to
what you'd get if a was an array. But that's not what happens — the splitting
operation is effectively ignored in all three examples. To get the other
behaviour, you can nest the expansion:

  % a='foo      bar'
  % ( setopt sh_word_split; b=${${a}}; typeset b )
  b='foo bar'
  % ( b=${${=a}}; typeset b )
  b='foo bar'
  % ( b=${${(s< >)a}}; typeset b )
  b='foo bar'

Hopefully this explains it without being too confusing?

dana


diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo
index 9ad228679..4fabbe5c5 100644
--- a/Doc/Zsh/params.yo
+++ b/Doc/Zsh/params.yo
@@ -54,7 +54,10 @@ indent(var(name)tt(=)var(value))
 
 In scalar assignment, var(value) is expanded as a single string, in
 which the elements of arrays are joined together; filename expansion is
-not performed unless the option tt(GLOB_ASSIGN) is set.
+not performed unless the option tt(GLOB_ASSIGN) is set, and the effects
+of `splitting' features (the tt(SH_WORD_SPLIT) option, the tt($=)var(name)
+expansion form, and expansion flags like tt(f) and tt(s)) are not applied
+to outer-level parameter expansions.
 
 When the integer attribute, tt(-i), or a floating point attribute, tt(-E)
 or tt(-F), is set for var(name), the var(value) is subject to arithmetic

Re: [PATCH] Clarify documentation of parameter-assignment behaviour

[Bart Schaefer]

We need to come to some sort of decision on what we're accomplishing
in the zsh doc.

Historical context:  Zsh was originally conceived as a way to migrate
csh (later tcsh) users to a shell with a more well-defined syntax
based on Bourne shell syntax.  So originally the documentation assumed
you knew how to use csh and the doc was mostly concerned with how zsh
differed from that, not how shells work in general.  Then it began to
pick up features derived from reading the ksh documentation (because
ksh itself was still closed-source and not freely available) so those
had to be explained, too.  Then as people began to migrate to zsh from
bash and ksh, the doc had to explain how zsh differed from those
(which revealed a whole lot of mis-interpretation of the ksh doc when
trying to copy ksh functionality).  Through all of this the underlying
assumption was the reader had some shell background, and the zsh doc
only had to explain how zsh was special.

Now we're getting people who complain that the zsh doc doesn't cover
all that previously-assumed background.  As Peter said, "One of our
big problems is people finding the existing documentation too thick to
get through.  We can go on making it wordier and harder to get through
till the cows come home and it still won't make it a basic shell
primer."

Splitting doesn't happen on scalar assignment in any shell.  It would
break the prefix-assignment syntax (var=$value command args...) among
other things.  So this isn't a way in which zsh differs.

There's little point in not applying this patch now that it's written,
but it's philosophically similar to Sebastian's code patch that
optimizes something the compiler ought to be able to optimize, and
we're going to be up to our rafters in cows if we don't start leaving
some of them out in the pasture.

Re: [PATCH] Clarify documentation of parameter-assignment behaviour

[dana]

On 17 Oct 2018, at 17:26, Bart Schaefer <schaefer@brasslantern.com> wrote:
>Through all of this the underlying
>assumption was the reader had some shell background, and the zsh doc
>only had to explain how zsh was special.

Considering huge portions of the manual are dedicated to explaining the most
fundamental aspects of shell functionality (how commands are resolved, how to
redirect files, what a pipe-line is, &c.), and AFAICT it's been that way since i
was a child, it kind of seems like that assumption went out the window a pretty
long time ago

But i don't feel strongly about this cow, obv. No need to let it in if it'll
just make a mess

dana

Re: [PATCH] Clarify documentation of parameter-assignment behaviour

[Bart Schaefer]

On Wed, Oct 17, 2018 at 3:56 PM dana <dana@dana.is> wrote:
>
> Considering huge portions of the manual are dedicated to explaining the most
> fundamental aspects of shell functionality (how commands are resolved, how to
> redirect files, what a pipe-line is, &c.), and AFAICT it's been that way since i
> was a child, it kind of seems like that assumption went out the window a pretty
> long time ago

Some of those things are different in zsh, and some of the differences
can't be explained in isolation.  You can't explain how a while-loop
or an if-else differs from csh without explaining concepts like "list"
and "sublist", even though a bash user probably knows.  You have to at
least enumerate all redirection syntax if you're going to add
explanation of file descriptor duplication and process substitution.

But yes, extra details have been coming in for a long time.  I meant
to encourage some sort of agreement on when enough is enough, but
maybe that's impossible (to know, not to agree on).