Re: [PATCH] Reorder the documentation of typeset flags

[Philippe Altherr <philippe.altherr@xxxxxxxxx>]

Below is an updated version, see the second commit on GitHib to view the additional changes.

Applied, but I have a niggle with this bit:

+A named reference declared with the `tt(-n)' option to any of the
+`tt(typeset)' commands acts as a reference to another parameter, which

"A named reference ... acts as a reference" reads wrong to me,  The
original sentence "A named parameter declared with ..." intentionally
did not introduce the term "named reference" until after "acts as a
reference" had been stated.  (The original term "named parameter" was
differentiating from "positional parameter" in context.)

I have more or less reverted to the original sentence but added the term "named reference".

Noting for reference that the intro needs -H and -h added to to
`typeset {+|-}n ...` too.

I added -H and -h, as well as -u, -p, and +.

Any reason why we don't allow -t for named references? I don't see any incompatibility.

I've not applied this yet because I'm not entirely happy with moving
'-n' into the list of parameters with everything else.  The
introduction to `typeset` looks like this:

typeset [ {+|-}AHUaghlmrtux ] [ {+|-}EFLRZip [ N ] ]
        [ + ] [ NAME[=VALUE] ... ]
typeset {+|-}n [ -g ] [ {+|-}r ] [ NAME[=VALUE] ... ]
typeset -T [ {+|-}Uglrux ] [ {+|-}LRZp [ N ] ]
        [ + | SCALAR[=VALUE] ARRAY[=(VALUE ...)] [ SEP ] ]
typeset -f [ {+|-}TUkmtuz ] [ + ] [ NAME ... ]

I have added a sentence at the beginning to explain that -n, -T, and -f change the set of valid additional flags and their meaning.

This implies that there are four different entities being managed:
"normal" parameters with all their bells and whistles; named
references; tied parameters; and functions.

I agree that there are 4 typeset syntaxes but I don't see 4 different entities. I only see 2: parameters and functions. A named reference is just a special type of parameter, admitely a very special one, more special than for example an integer parameter, but it's still just a parameter. Parameter tying neither introduces a different type of entity. It simply ties a scalar parameter to an array parameter. I rather see tying as an extra layer on top of parameters.

 

Rearranging the
documentation to mix all of the "flags" into one table discards these
distinctions.  (Yes, I acknowledge that '-f' is already "in the wrong
place" from this standpoint.)

Not sure what you mean here. There were two lists of flags, which I have rearranged into 3:

- Control flags: +, -f, -g, -m, -p, -T

- Type attribute flags: -i, -E, -F, -a, -A, -n

- Attribute flags: -l, -u, -L, -R, -Z, -U, -h, -H, -r, -t, -x

- Reorder the documentation of typeset flags

Philippe

diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index b9dd8faa5..f7fe896cf 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -1918,15 +1918,20 @@ cindex(parameters, setting)
 cindex(parameters, declaring)
 redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ @ @ ))ifnztexi(        )))
 xitem(tt(typeset )[ {tt(PLUS())|tt(-)}tt(AHUaghlmrtux) ] \
-[ {tt(PLUS())|tt(-)}tt(EFLRZip) [ var(n) ] ])
-xitem(SPACES()[ tt(+) ] [ var(name)[tt(=)var(value)] ... ])
-xitem(tt(typeset ){tt(PLUS())|tt(-)}tt(n) [ tt(-g) ] \
-[ {tt(PLUS())|tt(-)}tt(r) ] [ var(name)[tt(=)var(value)] ... ])
+[ {tt(PLUS())|tt(-)}tt(EFLRZip) [ var(n) ] ] \
+[ tt(+) ] [ var(name)[tt(=)var(value)] ... ])
+xitem(tt(typeset ){tt(PLUS())|tt(-)}tt(n) [ {tt(PLUS())|tt(-)}tt(Hghru) ] \
+[ {tt(PLUS())|tt(-)}tt(p) [ var(n) ] ] \
+[ tt(+) ] [ var(name)[tt(=)var(value)] ... ])
 xitem(tt(typeset )tt(-T) [ {tt(PLUS())|tt(-)}tt(Uglrux) ] [ {tt(PLUS())|tt(-)}tt(LRZp) [ var(n) ] ])
 xitem(SPACES()[ tt(+) | var(SCALAR)[tt(=)var(value)] var(array)[tt(=LPAR())var(value) ...tt(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.
 
+The type attribute flag tt(-n) and the control flags tt(-T) and tt(-f)
+change the set of valid additional flags as well as the meaning of
+some of them, see below the description of tt(-n), tt(-T) and tt(-f).
+
 Except as noted below for control flags that change the behavior,
 a parameter is created for each var(name) that does not already refer
 to one.  When inside a function, a new parameter is created for every
@@ -2033,37 +2038,6 @@ To initialize a parameter var(param) to a command output and mark it readonly,
 use tt(typeset -r )var(param) or tt(readonly )var(param) after the parameter
 assignment statement.
 
-cindex(named reference)
-cindex(reference, named)
-The flag tt(-n) creates a em(named reference) to another parameter.
-The second parameter need not exist at the time the reference is
-created.  Only the tt(-H), tt(-g), tt(-h), and tt(-r) flags may be used
-in conjunction with tt(-n), having their usual meanings.  The tt(-u)
-flag is special and may be applied to alter the scope of the reference.
-The var(name) so created may not be an array element nor use
-a subscript, but the var(value) assigned may be any valid parameter
-name, but not a subscripted array (or associative array) element nor
-an array slice.  It is an error for a named reference to refer
-to itself, even indirectly through a chain of references.  When tt(-u)
-is applied to a named reference, the parameter identified by var(value)
-is always found in the calling function scope rather than the current
-local scope.  In this case, if there is no such parameter in the calling
-scope, assignments to the named reference may fail, setting tt($?) to 1.
-See sectref(Parameter Expansion)(zshexpn) and
-sectref(Named References)(zshparam) for details of the
-behavior of named references.
-
-Local function scoping rules for `tt(typeset)' do apply with `tt(-n)',
-so a declaration within a function persists only until the end of the
-function unless `tt(-g -n)' is specified, and any local parameter (of
-any type) with the same var(name) supplants a named reference from a
-surrounding scope.
-
-A scalar parameter, including an existing named reference, may be
-converted to a new named reference by `tt(typeset -n )var(name)', so
-the `tt(-p)' option must be included to display the value of a
-specific named reference var(name).
-
 If no attribute flags are given, and either no var(name) arguments are
 present or the flag tt(+m) is used, then each parameter name printed is
 preceded by a list of the attributes of that parameter (tt(array),
@@ -2090,6 +2064,23 @@ names of all autoloadable functions.  If tt(PLUS()) is the only option,
 then type information (array, readonly, etc.) is also printed for each
 parameter, in the same manner as `tt(typeset +m "*")'.
 )
+item(tt(-f))(
+The names refer to functions rather than parameters.  No assignments
+can be made, and the only other valid flags are tt(-t), tt(-T), tt(-k),
+tt(-u), tt(-U) and tt(-z).  The flag tt(-t) turns on execution tracing
+for this function; the flag tt(-T) does the same, but turns off tracing
+for any named (not anonymous) function called from the present one,
+unless that function also
+has the tt(-t) or tt(-T) flag.  The tt(-u) and tt(-U) flags cause the
+function to be marked for autoloading; tt(-U) also causes alias
+expansion to be suppressed when the function is loaded.  See the
+description of the `tt(autoload)' builtin for details.
+
+Note that the builtin tt(functions) provides the same basic capabilities
+as tt(typeset -f) but gives access to a few extra options; tt(autoload)
+gives further additional options for the case tt(typeset -fu) and
+tt(typeset -fU).
+)
 item(tt(-g))(
 The tt(-g) (global) means that any resulting parameter will not be
 restricted to local scope.  Note that this does not necessarily mean that
@@ -2138,7 +2129,7 @@ would cause errors.  However, these parameters are printed when they
 have been made local to the scope where `tt(typeset -p)' is run.
 )
 item(tt(-T) [ var(scalar)[tt(=)var(value)] var(array)[tt(=LPAR())var(value) ...tt(RPAR())] [ var(sep) ] ])(
-This flag has a different meaning when used with tt(-f); see below.
+This flag has a different meaning when used with tt(-f); see above.
 Otherwise the tt(-T) option requires zero, two, or three arguments to be
 present.  With no arguments, the list of parameters created in this
 fashion is shown.  With two or three arguments, the first two are the name
@@ -2172,17 +2163,76 @@ is preserved but no attribute other than export will be preserved.
 )
 enditem()
 
-Attribute flags that transform the final value (tt(-L), tt(-R), tt(-Z),
-tt(-l), tt(-u)) are only applied to the expanded value at the point
-of a parameter expansion expression using `tt($)'.  They are not applied
-when a parameter is retrieved internally by the shell for any purpose. 
-
-The following attribute flags may be specified:
+The following type attribute flags control the internal representation
+of the parameters.  Each parameter can have at most one type attribute.
+Parameters with no type attribute use an internal string representation.
 
 startitem()
+item(tt(-i) [ var(n) ])(
+Use an internal integer representation.  If var(n) is nonzero it
+defines the output arithmetic base, otherwise it is determined by the
+first assignment.  Bases from 2 to 36 inclusive are allowed.
+)
+item(tt(-E) [ var(n) ])(
+Use an internal double-precision floating point representation.  On output
+the variable will be converted to scientific notation.  If var(n) is
+nonzero it defines the number of significant figures to display; the
+default is ten.
+)
+item(tt(-F) [ var(n) ])(
+Use an internal double-precision floating point representation.  On output
+the variable will be converted to fixed-point decimal notation.  If var(n)
+is nonzero it defines the number of digits to display after the decimal
+point; the default is ten.
+)
+item(tt(-a))(
+Create an array parameter.  It may be assigned to in the tt(typeset)
+statement only if the reserved word form of tt(typeset) is enabled
+(as it is by default).  When displaying, both normal and associative
+arrays are shown.
+)
 item(tt(-A))(
-The names refer to associative array parameters; see
-sectref(Array Parameters)(zshparam).
+Create an associative array parameter;
+see sectref(Array Parameters)(zshparam).
+)
+item(tt(-n))(
+cindex(named reference)
+cindex(reference, named)
+Create a em(named reference) to another parameter.
+The referred parameter need not exist at the time the reference is
+created.  Only the tt(-H), tt(-g), tt(-h), and tt(-r) flags may be used
+in conjunction with tt(-n), having their usual meanings.  The tt(-u)
+flag is special and may be applied to alter the scope of the reference.
+The var(name) so created may not be an array element nor use
+a subscript, but the var(value) assigned may be any valid parameter
+name, but not a subscripted array (or associative array) element nor
+an array slice.  It is an error for a named reference to refer
+to itself, even indirectly through a chain of references.  When tt(-u)
+is applied to a named reference, the parameter identified by var(value)
+is always found in the calling function scope rather than the current
+local scope.  In this case, if there is no such parameter in the calling
+scope, assignments to the named reference may fail, setting tt($?) to 1.
+See sectref(Parameter Expansion)(zshexpn) and
+sectref(Named References)(zshparam) for details of the
+behavior of named references.
+)
+enditem()
+
+The following additional attribute flags may be specified.  Attribute
+flags that transform the final value (tt(-l), tt(-u), tt(-L), tt(-R),
+tt(-Z)) are only applied to the expanded value at the point of a
+parameter expansion expression using `tt($)'.  They are not applied
+when a parameter is retrieved internally by the shell for any purpose.
+
+startitem()
+item(tt(-l))(
+Convert the result to lower case whenever the parameter is expanded.
+The value is em(not) converted when assigned.
+)
+item(tt(-u))(
+Convert the result to upper case whenever the parameter is expanded.
+The value is em(not) converted when assigned.
+This flag has different meanings when used with tt(-f) or tt(-n); see above.
 )
 item(tt(-L) [ var(n) ])(
 Left justify and remove leading blanks from the value when the parameter
@@ -2211,17 +2261,6 @@ when the parameter is expanded, the field is left filled with
 blanks or truncated from the end.  May not be combined with the tt(-Z)
 flag.
 )
-item(tt(-U))(
-For arrays (but not for associative arrays), keep only the first
-occurrence of each duplicated value.  This may also be set for tied
-parameters (see tt(-T)) or colon-separated special parameters like
-tt(PATH) or tt(FIGNORE), etc.  Note the flag takes effect on assignment,
-and the type of the variable being assigned to is determinative; for
-variables with shared values it is therefore recommended to set the flag
-for all interfaces, e.g. `tt(typeset -U PATH path)'.
-
-This flag has a different meaning when used with tt(-f); see below.
-)
 item(tt(-Z) [ var(n) ])(
 Specially handled if set along with the tt(-L) flag.
 Otherwise, similar to tt(-R), except that leading zeros are used for
@@ -2230,29 +2269,16 @@ Numeric parameters are specially handled: they are always eligible
 for padding with zeroes, and the zeroes are inserted at an appropriate
 place in the output.
 )
-item(tt(-a))(
-The names refer to array parameters.  An array parameter may be
-created this way, but it may be assigned to in the tt(typeset)
-statement only if the reserved word form of tt(typeset) is enabled
-(as it is by default).  When displaying, both normal and associative
-arrays are shown.
-)
-item(tt(-f))(
-The names refer to functions rather than parameters.  No assignments
-can be made, and the only other valid flags are tt(-t), tt(-T), tt(-k),
-tt(-u), tt(-U) and tt(-z).  The flag tt(-t) turns on execution tracing
-for this function; the flag tt(-T) does the same, but turns off tracing
-for any named (not anonymous) function called from the present one,
-unless that function also
-has the tt(-t) or tt(-T) flag.  The tt(-u) and tt(-U) flags cause the
-function to be marked for autoloading; tt(-U) also causes alias
-expansion to be suppressed when the function is loaded.  See the
-description of the `tt(autoload)' builtin for details.
+item(tt(-U))(
+For arrays (but not for associative arrays), keep only the first
+occurrence of each duplicated value.  This may also be set for tied
+parameters (see tt(-T)) or colon-separated special parameters like
+tt(PATH) or tt(FIGNORE), etc.  Note the flag takes effect on assignment,
+and the type of the variable being assigned to is determinative; for
+variables with shared values it is therefore recommended to set the flag
+for all interfaces, e.g. `tt(typeset -U PATH path)'.
 
-Note that the builtin tt(functions) provides the same basic capabilities
-as tt(typeset -f) but gives access to a few extra options; tt(autoload)
-gives further additional options for the case tt(typeset -fu) and
-tt(typeset -fU).
+This flag has a different meaning when used with tt(-f); see above.
 )
 item(tt(-h))(
 Hide: only useful for special parameters (those marked `<S>' in the table in
@@ -2281,27 +2307,6 @@ default for the parameters in the tt(zsh/parameter) and tt(zsh/mapfile)
 modules.  Note, however, that unlike the tt(-h) flag this is also useful
 for non-special parameters.
 )
-item(tt(-i) [ var(n) ])(
-Use an internal integer representation.  If var(n) is nonzero it
-defines the output arithmetic base, otherwise it is determined by the
-first assignment.  Bases from 2 to 36 inclusive are allowed.
-)
-item(tt(-E) [ var(n) ])(
-Use an internal double-precision floating point representation.  On output
-the variable will be converted to scientific notation.  If var(n) is
-nonzero it defines the number of significant figures to display; the
-default is ten.
-)
-item(tt(-F) [ var(n) ])(
-Use an internal double-precision floating point representation.  On output
-the variable will be converted to fixed-point decimal notation.  If var(n)
-is nonzero it defines the number of digits to display after the decimal
-point; the default is ten.
-)
-item(tt(-l))(
-Convert the result to lower case whenever the parameter is expanded.
-The value is em(not) converted when assigned.
-)
 item(tt(-r))(
 The given var(name)s are marked readonly.  Note that if var(name) is a
 special parameter, the readonly attribute can be turned on, but cannot then
@@ -2328,11 +2333,6 @@ the user's own purposes --- the list of tagged parameters can be queried
 using `tt(typeset -t)'.  Tags have no other use.  Note that the tt(-t)
 flag has a different meaning when used with tt(-f); see above.
 )
-item(tt(-u))(
-Convert the result to upper case whenever the parameter is expanded.
-The value is em(not) converted when assigned.
-This flag has different meanings when used with tt(-f) or tt(-n); see above.
-)
 item(tt(-x))(
 Mark for automatic export to the environment of subsequently
 executed commands.  If the option tt(GLOBAL_EXPORT) is set, this implies
diff --git a/Doc/Zsh/func.yo b/Doc/Zsh/func.yo
index e2db24880..fb38b0c53 100644
--- a/Doc/Zsh/func.yo
+++ b/Doc/Zsh/func.yo
@@ -22,9 +22,12 @@ place of any other parameter having the same name that was assigned or
 declared in an earlier function scope.
 (See sectref(Local Parameters)(zshparam).)
 
-A named reference declared with the `tt(-n)' option to any of the
-`tt(typeset)' commands acts as a reference to another parameter, which
-may be at a different call level than the declaring function.  When
+cindex(named reference)
+cindex(reference, named)
+A parameter declared with the `tt(-n)' option to any of the
+`tt(typeset)' creates a em(named reference); it acts as a reference to
+another parameter, which may be at a different call level than the
+declaring function. When
 the `tt(-u)' option is also given, the referenced parameter is always
 found at a call level above the function where the reference is
 declared, otherwise the reference scope is dynamic.  For this reason,