[doc/ref] Fix descriptions of initializer list (#2284)

And other doc/ref fixes

Author: akinomyoga

doc/ref/chap-osh-assign.md

@@ -45,21 +45,21 @@ cleared before starting the modifications.  When the assignment is performed
 with `+=`, the modifications are applied to the existing content of the LHS
 value.
 
-An initializer list has the following form: `(<words>...)`, where each word has
-one of the following forms:
-
-- `[<key>]=<value>` ... This assigns `<value>` to an element of the LHS
-  specified by `<key>`.  The `<value>` is not subject to word splitting and
-  pathname expansions as if it is the RHS of an assignment.
-- `[<key>]+=<value>` ... This appends `<value>` to an element of the LHS
-  specified by `<key>`.  If the corresponding element does not exist, it simply
-  assigns `<value>` to a new element associated with `<key>`.  The `<value>` is
-  not subject to word splitting and pathname expansions.
-- `<value>` ... If the word does not have the above two forms, it is considered
-  a normal word.  In this case, this assigns `<value>` to the *next* element,
-  where the next element is determined by the LHS.  Unlike the previous two
-  forms, the `<value>` is subject to word splitting and pathname expansions as
-  if it is a normal argument to a command.
+An initializer list has the following form: `'(' ITEMS* ')'`, where each item
+has one of the following forms:
+
+- `[KEY]=VALUE` ... This assigns `VALUE` to an element of the LHS specified by
+  `KEY`.  The `VALUE` is not subject to word splitting and pathname expansions
+  as if it is the RHS of an assignment.
+- `[KEY]+=VALUE` ... This appends `VALUE` to an element of the LHS specified by
+  `KEY`.  If the corresponding element does not exist, it simply assigns
+  `VALUE` to a new element associated with `KEY`.  The `VALUE` is not subject
+  to word splitting and pathname expansions.
+- `VALUE` ... If the item does not have the above two forms, it is considered a
+  normal word.  In this case, this assigns `VALUE` to the *next* element, where
+  the next element is determined by the LHS.  Unlike the previous two forms,
+  the `VALUE` is subject to word splitting and pathname expansions as if it is
+  a normal argument to a command.
 
 The above three forms can be mixed within one initializer list, though there
 may be additional limitations depending on the type of the LHS of the
@@ -73,21 +73,20 @@ applied.
 In the first phase, the type adjustment is performed in the following way:
 
 - When the LHS variable is unset, the assignment creates an empty indexed array
-  (BashArray) and apply the initializer list to the created array.  If the
+  (BashArray).  If the
   assignment is performed through an assignment builtin and flag `-A` is
   supplied to the builtin, an empty associative array (BashAssoc) is created
   instead of an empty BashArray.
 - When the LHS is a scalar string, the assignment creates a BashArray with one
   element, where the original value is stored at index `0`.  If the assignment
   is performed through an assignment builtin and flag `-A` is supplied to the
   builtin, the assignment creates a BashAssoc with one element, where the
-  original value is stored at key `"0"` instead of a BashArray.  If the
+  original value is stored at key `"0"`, instead of a BashArray.  If the
   assignment operator is `+=`, OSH issues an error "Can't append an array to
   string", while Bash is permissive.
-- When the LHS is an indexed or associative arrays, the initializer list is
-  applied to the original array following [sh-array](#sh-array) (for an indexed
-  array) or [sh-assoc](#sh-assoc) (for an associative array).  If the
-  assignemnt is performed through an assignment builtin and mismatching flag
+- When the LHS is an indexed or associative arrays, the original array is
+  directly used for the modification target.  If the
+  assignment is performed through an assignment builtin and mismatching flag
   (i.e., `-A` and `-a` for BashArray and BashAssoc, respectively) is supplied,
   OSH discards the original array and creates a new empty BashArray (for flag
   `-a`) or BashAssoc (for flag `-A`), while Bash issues an error preserving the
@@ -116,7 +115,7 @@ These rules are summarized in the following table.
 - tr
   - <!-- empty -->
   - `-A`
-  - an empty BashArray
+  - an empty BashAssoc
   - <!-- empty -->
 - tr
   - Str
@@ -133,11 +132,6 @@ These rules are summarized in the following table.
   - `-A`
   - BashAssoc with one element, with the original string at key `"0"`
   - OSH does not accept `+=`, so the element is never used
-- tr
-  - <!-- empty -->
-  - `-A`
-  - an empty BashArray
-  - <!-- empty -->
 - tr
   - BashArray
   - (none)
@@ -168,12 +162,17 @@ These rules are summarized in the following table.
   - `-A`
   - the original BashAssoc
   - <!-- empty -->
+- tr
+  - (others)
+  - <!-- empty -->
+  - N/A
+  - Error
 
 </table>
 
 In the second phase, the modifications are applied depending on the result of
 the first phase.  When the result is BashArray, see [sh-array](#sh-array).
-When the result is BashAssoc, see [sh-array](#sh-array).
+When the result is BashAssoc, see [sh-assoc](#sh-assoc).
 
 ### sh-array
 
@@ -191,14 +190,14 @@ cleared if the assignment operator is `=`.  Then, an element of the array is
 modified for each item in the initializer list in order.  The index of the
 element to be modified is determined in the following way:
 
-- When the first initializer item does not have `[<key>]=` or `[<key>]+=`, the
+- When the first initializer item does not have `[KEY]=` or `[KEY]+=`, the
   index is the maximum existing index in the array plus one, or `0` if the
   array is empty.
-- When the second or later initializer item does not have `[<key>]=` or
-  `[<key>]+=`, the index is larger by one than the one modified by the previous
+- When the second or later initializer item does not have `[KEY]=` or
+  `[KEY]+=`, the index is larger by one than the one modified by the previous
   initializer item.
-- When the initialier item has `[<key>]=` or `[<key>]+=`, an arithmetic
-  evaluation is applied to `<key>` to obtain the index in `BigInt`
+- When the initializer item has `[KEY]=` or `[KEY]+=`, an arithmetic evaluation
+  is applied to `KEY` to obtain the index in `BigInt`
 
 Here are examples:
 
@@ -210,9 +209,9 @@ Here are examples:
     declare -a a=([k]=v 2)  # This creates a sparse array with two elements,
                             # ([10]=v [11]=2)
 
-    declare -a a+=(3 4)     # This appends two values to the existing array:
+    a+=(3 4)                # This appends two values to the existing array:
                             # ([10]=v [11]=2 [12]=3 [13]=4)
-    declare -a a+=([k]=5 6) # This overwrites two elements in the existing
+    a+=([k]=5 6)            # This overwrites two elements in the existing
                             # array: ([10]=5 [11]=6 [12]=3 [13]=4)
 
 In YSH, use a [list-literal][] to create a [List][] instance.
@@ -236,8 +235,8 @@ The initialization/mutation of BashAssoc is performed in a manner similar to
 BashArray.  The associative array is first cleared if the assignment operator
 is `=`.  Then, the modification of an element is performed for each initializer
 item in order.  An item in the initializer list must be in the forms
-`[<key>]=<value>` or `[<key>]=<value>`.  The element to be modified is
-specified by `<key>`.
+`[KEY]=VALUE` or `[KEY]=VALUE`.  The element to be modified is specified by
+`KEY`.
 
     declare -A a                # This creates an empty BashAssoc (OSH)
     declare -A a=()             # This creates an empty BashAssoc
@@ -249,9 +248,9 @@ specified by `<key>`.
     declare -A a=([k]=v)        # This creates a BashAssoc with one element,
                                 # (['k']=1).  Unlike BashArray, "k" is not
                                 # processed by arithmetic expansion.
-    declare -a a+=([a]=3 [b]=4) # This adds two elements to the existing array.
+    a+=([a]=3 [b]=4)            # This adds two elements to the original array.
                                 # The result is ([a]=3 [b]=4 [k]=v)
-    declare -a a+=([k]=5)       # This overwrites an element in the existing
+    a+=([k]=5)                  # This overwrites an element in the original
                                 # array. The result is ([a]=3 [b]=4 [k]=5).
 
 In YSH, use a [dict-literal][] to create a [Dict][] instance.