From a2229ce10c41147b17ff074ae9c2b545801acb9f Mon Sep 17 00:00:00 2001 From: Peter Stephenson Date: Tue, 23 Jun 2015 10:00:04 +0100 Subject: Further doucmentation improvements after comments from Bart and Oliver --- Doc/Zsh/builtins.yo | 51 ++++++++++++++++++++++++++++++--------------------- README | 4 ++-- 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 ---------------------------------------- -- cgit 1.4.1