Further doucmentation improvements after comments from Bart and Oliver

2 files changed, 32 insertions, 23 deletions

diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index 9d0d04903..33f112225 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -1729,7 +1729,7 @@ xitem(tt(typeset )[ {tt(PLUS())|tt(-)}tt(AHUaghlmprtux) ] \
 [ {tt(PLUS())|tt(-)}tt(EFLRZi) [ var(n) ] ])
 xitem(SPACES()[ tt(+) | var(name)[tt(=)var(value)] ... ])
 xitem(tt(typeset )tt(-T) [ {tt(PLUS())|tt(-)}tt(Uglprux) ] [ {tt(PLUS())|tt(-)}tt(LRZ) [ var(n) ] ])
-xitem(SPACES()[ tt(+) | var(SCALAR)[tt(=)var(value)] var(array) [ var(sep) ] ])
+xitem(SPACES()[ tt(+) | var(SCALAR)[tt(=)var(value)] var(array)[tt(=)LPAR()var(value)RPAR()] [ var(sep) ] ])
 item(tt(typeset) tt(-f) [ {tt(PLUS())|tt(-)}tt(TUkmtuz) ] [ tt(+) | var(name) ... ])(
 Set or display attributes and values for shell parameters.
 
@@ -1746,32 +1746,36 @@ For each var(name)tt(=)var(value) assignment, the parameter
 var(name) is set to var(value).  All forms of the command
 handle scalar assignment.
 
-If the reserved word tt(declare), tt(export), tt(float), tt(integer),
-tt(local), tt(readonly) or tt(typeset) is matched when the line is
-parsed (N.B. not when it is executed), and the reserved word has not
-been disabled with tt(disable -r), the shell will try to parse arguments
-as assignments, except that the `tt(+=)' syntax and the tt(GLOB_ASSIGN)
-option are not supported. This has two major differences from normal
-command line argument parsing: array assignment is possible, and scalar
-values after tt(=) are not split further into words even if expanded
-(regardless of the setting of the tt(KSH_TYPESET) option; this option
-is obsolete).  Here is an example:
+If any of the reserved words tt(declare), tt(export), tt(float),
+tt(integer), tt(local), tt(readonly) or tt(typeset) is matched when the
+line is parsed (N.B. not when it is executed) the shell will try to parse
+arguments as assignments, except that the `tt(+=)' syntax and the
+tt(GLOB_ASSIGN) option are not supported.  This has two major differences
+from normal command line argument parsing: array assignment is possible,
+and scalar values after tt(=) are not split further into words even if
+expanded (regardless of the setting of the tt(KSH_TYPESET) option; this
+option is obsolete).  Here is an example:
 
 example(# Reserved word parsing
 typeset svar=$(echo one word) avar=(several words))
 
-The above creates a scalar parameter tt(svar) with the value `tt(one
-word)' and an array parameter tt(avar) with a value containing two
-entries, `tt(several)' and `tt(words)'.  On the other hand:
+The above creates a scalar parameter tt(svar) and an array
+parameter tt(var) as if the assignments had been
+
+example(svar="one word"
+avar=(several words))
+
+On the other hand:
 
 example(# Normal builtin interface
-cmd=typeset
-$cmd svar=$(echo two words))
+builtin typeset svar=$(echo two words))
 
-The above creates a scalar tt(svar) contain the value tt(two) and
-another scalar parameter tt(words) with no value.  An array value in
-this case would either cause an error or be treated as an obscure set of
-glob qualifiers.
+The tt(builtin) keyword causes the above to use the standard builtin
+interface to tt(typeset) in which argument parsing is perfomed in the same
+way as for other commands.  This example creates a scalar tt(svar)
+containing the value tt(two) and another scalar parameter tt(words) with
+no value.  An array value in this case would either cause an error or be
+treated as an obscure set of glob qualifiers.
 
 Arbitrary arguments are allowed if they take the form of assignments
 after command line expansion; however, these only perform scalar
@@ -1794,6 +1798,11 @@ a set of three normal command line arguments to tt(typeset) after
 expansion.  Hence it is not possible to assign to multiple arrays by
 this means.
 
+Note that each interface to any of the commands my be disabled
+separately.  For example, `tt(disable -r typeset)' disables the reserved
+word interface to tt(typeset), exposing the builtin interface, while
+`tt(disable typeset)' disables the builtin.
+
 If the shell option tt(TYPESET_SILENT) is not set, for each remaining
 var(name) that refers to a parameter that is already set, the name and
 value of the parameter are printed in the form of an assignment.
@@ -1870,7 +1879,7 @@ the current state, readonly specials (whose values cannot be
 changed) are not shown and assignments to arrays are shown before
 the tt(typeset) rendering the array readonly.
 )
-item(tt(-T) [ var(scalar)[tt(=)var(value)] var(array)[tt(=)LPAR()var(value...)RPAR()] [ var(sep) ] ])(
+item(tt(-T) [ var(scalar)[tt(=)var(value)] var(array)[tt(=)LPAR()var(value)...RPAR()] [ var(sep) ] ])(
 This flag has a different meaning when used with tt(-f); see below.
 Otherwise the tt(-T) option requires zero, two, or three arguments to be
 present.  With no arguments, the list of parameters created in this
diff --git a/README b/README
index 0b985fb7d..745ee6fce 100644
--- a/README
+++ b/README
@@ -44,8 +44,8 @@ interface, exposing the builtin interface:
   disable -r declare export float integer local readonly typeset
 
 This is also necessary in the unusual eventuality that the builtins are
-to be replaced by shell functions, since reserved words take precedence
-over functions.
+to be overridden by shell functions, since reserved words take
+precedence over functions.
 
 Incompatibilites between 5.0.7 and 5.0.8
 ----------------------------------------