33841: explain array append a bit better

2 files changed, 20 insertions, 10 deletions

diff --git a/ChangeLog b/ChangeLog
index fad5d820d..c03501faf 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2014-12-04  Barton E. Schaefer  <schaefer@zsh.org>
+
+	* 33841: Doc/Zsh/params.yo: explain array append a bit better
+
 2014-12-03  Mikael Magnusson  <mikachu@gmail.com>
 
 	* Eric Cook: 33689: Completion/Unix/Command/_cp: make cp
@@ -23,7 +27,7 @@
 	Src/exec.c, Src/sort.c, Src/utils.c: fix types passed to sizeof
 	detected by coverity as being wrong
 
-2014-11-28  Barton E. Schaefer  <schaefer@brasslantern.com>
+2014-11-28  Barton E. Schaefer  <schaefer@zsh.org>
 
 	* 33819: Test/A06assign.ztst: regression tests for 33816
 
diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo
index dcca455d8..5833d6be9 100644
--- a/Doc/Zsh/params.yo
+++ b/Doc/Zsh/params.yo
@@ -94,7 +94,12 @@ indent(var(name)tt(=LPAR())var(value) ...tt(RPAR()))
 
 If no parameter var(name) exists, an ordinary array parameter is created.
 If the parameter var(name) exists and is a scalar, it is replaced by a new
-array.  Ordinary array parameters may also be explicitly declared with:
+array.  To append to an array without changing the existing values, use
+the syntax:
+ifzman()
+indent(var(name)tt(+=LPAR())var(value) ...tt(RPAR()))
+
+Ordinary array parameters may also be explicitly declared with:
 findex(typeset, use of)
 ifzman()
 indent(tt(typeset -a) var(name))
@@ -110,8 +115,13 @@ indent(set -A var(name) var(key) var(value) ...)
 indent(var(name)tt(=LPAR())var(key) var(value) ...tt(RPAR()))
 
 Every var(key) must have a var(value) in this case.  Note that this
-assigns to the entire array, deleting any elements that do not appear
-in the list.
+assigns to the entire array, deleting any elements that do not appear in
+the list.  The append syntax may also be used with an associative array:
+ifzman()
+indent(var(name)tt(+=LPAR())var(key) var(value) ...tt(RPAR()))
+
+This adds a new key/value pair if the key is not already present, and
+replaces the value for the existing key if it is.
 
 To create an empty array (including associative arrays), use one of:
 ifzman()
@@ -211,7 +221,6 @@ indent(tt(unset) tt(")var(name)tt([)var(exp)tt(]"))
 
 subsect(Subscript Flags)
 cindex(subscript flags)
-
 If the opening bracket, or the comma in a range, in any subscript
 expression is directly followed by an opening parenthesis, the string up
 to the matching closing one is considered to be a list of flags, as in
@@ -351,16 +360,13 @@ patterns used for reverse subscripting (the `tt(r)', `tt(R)', `tt(i)',
 etc. flags), but it may also affect parameter substitutions that appear
 as part of an arithmetic expression in an ordinary subscript.
 
-It is possible to avoid the use of subscripts in assignments to associative
-array elements by using the syntax:
+To avoid subscript parsing limitations in assignments to associative array
+elements, use the append syntax:
 
 example(
    aa+=('key with "*strange*" characters' 'value string')
 )
 
-This adds a new key/value pair if the key is not already present, and
-replaces the value for the existing key if it is.
-
 The basic rule to remember when writing a subscript expression is that all
 text between the opening `tt([)' and the closing `tt(])' is interpreted
 em(as if) it were in double quotes (\