[PATCH] Clarify documentation of parameter-assignment behaviour

[dana <dana@dana.is>]

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