zsh-workers/7636

2 files changed, 32 insertions, 12 deletions

diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index 2f1f37258..0a1f917d4 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -440,7 +440,7 @@ added by explicit specification.  If has no effect if used with tt(-f).
 )
 alias(history)(fc -l)
 findex(integer)
-item(tt(integer) [ {tt(PLUS())|tt(-)}tt(glrtux) ] [ var(name)[tt(=)var(value)] ... ])(
+item(tt(integer) [ {tt(PLUS())|tt(-)}tt(ghlrtux) ] [ var(name)[tt(=)var(value)] ... ])(
 Equivalent to tt(typeset -i), except that options irrelevant to
 integers are not permitted.
 )
@@ -533,7 +533,7 @@ sitem([var(mm)tt(:)]var(ss))(minutes and seconds)
 endsitem()
 )
 findex(local)
-item(tt(local) [ {tt(PLUS())|tt(-)}tt(ALRUZailrtu) [var(n)]] [ var(name)[tt(=)var(value)] ] ...)(
+item(tt(local) [ {tt(PLUS())|tt(-)}tt(ALRUZahilrtu) [var(n)]] [ var(name)[tt(=)var(value)] ] ...)(
 Same as tt(typeset), except that the options tt(-g), tt(-x) and
 tt(-f) are not permitted.
 )
@@ -922,7 +922,7 @@ Equivalent to tt(whence -v).
 findex(typeset)
 cindex(parameters, setting)
 cindex(parameters, declaring)
-xitem(tt(typeset) [ {tt(PLUS())|tt(-)}tt(ALRUZafgilrtuxm) [var(n)]] [ \
+xitem(tt(typeset) [ {tt(PLUS())|tt(-)}tt(ALRUZafghilrtuxm) [var(n)]] [ \
 var(name)[tt(=)var(value)] ... ])
 item(tt(typeset) -T [ {tt(PLUS()|tt(-))}tt(LRUZrux) ] \
   var(SCALAR)[tt(=)var(value)] var(array))(
@@ -1038,6 +1038,24 @@ suppressed when the function is loaded.  The tt(fpath) parameter
 will be searched to find the function definition when the function
 is first referenced; see noderef(Functions).
 )
+item(tt(-h))(
+Hide: only useful for special parameters (those marked `<S>' in the table in
+ifzman(zmanref(zshparams))\
+ifnzman(noderef(Parameters))\
+), and for local parameters with the same name as a special parameter,
+though harmless for others.  A special parameter with this attribute will
+not retain its special effect when made local.  Thus after `tt(typeset -h
+PATH)', a function containing `tt(typeset PATH)' will create an ordinary
+local parameter without the usual behaviour of tt(PATH).  Alternatively,
+the local parameter may itself be given this attribute; hence inside a
+function `tt(typeset -h PATH)' creates an ordinary local parameter and the
+special tt(PATH) parameter is not altered in any way.  It is also possible
+to create a local parameter using `tt(typeset +h )var(special)', where the
+local copy of var(special) will retain its special properties regardless of
+having the tt(-h) attribute.  Global special parameters loaded from shell
+modules (currently those in tt(mapfile) and tt(parameter)) are
+automatically given the tt(-h) attribute to avoid name clashes.
+)
 item(tt(-i))(
 Use an internal integer representation.  If var(n) is nonzero it
 defines the output arithmetic base, otherwise it is determined by the
diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo
index 65c8e7599..3b7857471 100644
--- a/Doc/Zsh/params.yo
+++ b/Doc/Zsh/params.yo
@@ -203,15 +203,17 @@ tt(unset) can be used to delete a parameter while it is still in scope;
 any outer parameter of the same name remains hidden.
 
 Special parameters may also be made local; they retain their special
-attributes.  This may have unexpected effects.  Firstly, there is no
-default value, so if there is no assigment at the point the variable is
-made local, it will be set to an empty value (or zero in the case of
-integers).  Secondly, special parameters which are made local will not be
-exported (as with other parameters), so that the global value of the
-parameter remains present in the environment if it is already there.  This
-should be particularly noted in the case of tt(PATH): the shell will use
-the local version of tt(PATH) for finding programmes, but programmes using
-the shell's environment will inherit the global version.  The following:
+attributes unless either the existing or the newly-created parameter
+has the tt(-h) (hide) attribute.  This may have unexpected effects.
+Firstly, there is no default value, so if there is no assigment at the
+point the variable is made local, it will be set to an empty value (or zero
+in the case of integers).  Secondly, special parameters which are made
+local will not be exported (as with other parameters), so that the global
+value of the parameter remains present in the environment if it is already
+there.  This should be particularly noted in the case of tt(PATH): the
+shell will use the local version of tt(PATH) for finding programmes, but
+programmes using the shell's environment will inherit the global version.
+The following:
 
 example(typeset PATH=/new/directory:$PATH)