51511: Documentation for namespaces

ChangeLog

@@ -1,5 +1,7 @@
 2023-03-06  Bart Schaefer  <schaefer@zsh.org>
 
+	* 51511: Doc/Zsh/expn.yo, Doc/Zsh/params.yo: Document namespaces
+
 	* 51510: Src/builtin.c, Src/params.c, Src/utils.c, Src/zsh.h,
 	Test/K02parameter.ztst: parameters with a leading namespace are
 	skipped in output of "set" and "typeset", add tests for ksh-like

Doc/Zsh/expn.yo

@@ -604,6 +604,16 @@ and other operators, such as `tt(${PREFIX:-"/usr/local"})'.  Parameter
 expansions can also be nested.  These topics will be introduced below.
 The full rules are complicated and are noted at the end.
 
+cindex(namespace)
+Parameter expansions may optionally include a em(namespace) prefix in
+the format `tt(.)var(identifier)tt(.)' This currently has no special
+meaning to the shell, but provides a convenient means of grouping
+related parameters.  Expansions using a namespace em(must) include
+braces (tt({) and tt(})) as shown in the descriptions below, and
+only one namespace prefix is allowed.  Note that, for support of
+possible future features, the first `tt(.)' is optional, but omitting
+it is discouraged.
+
 In the expansions discussed below that require a pattern, the form of
 the pattern is the same as that used for filename generation;
 see noderef(Filename Generation).  Note that these patterns, along with
@@ -616,6 +626,8 @@ substitution on the expansion of parameter tt($i).
 
 In the following descriptions, `var(word)' refers to a single word
 substituted on the command line, not necessarily a space delimited word.
+The reference to `var(name)' in each description presumes any optional
+namespace prefix.
 
 startitem()
 item(tt(${)var(name)tt(}))(

Doc/Zsh/params.yo

@@ -52,6 +52,20 @@ cindex(assignment)
 ifzman()
 indent(var(name)tt(=)var(value))
 
+cindex(namespace)
+The var(name) in an assignment may optionally include a em(namespace)
+prefix:
+ifzman()
+indent(tt(.)var(namespace)tt(.)var(parameter)tt(=)var(value))
+
+Namespaces have no special meaning to the shell except that parameters
+with a `tt(.)' prefix are not listed by the `tt(set)' builtin, nor
+shown by the `tt(typeset)' builtin unless explicitly named or the
+`tt(-m)' option is used.  They provide a convenient way to group
+related variables.  Note that, for support of possible future features,
+the first `tt(.)' is optional, but omitting it is discouraged.  Unlike
+ksh, a namespace need not be declared before it is referenced.
+
 In scalar assignment, var(value) is expanded as a single string, in
 which the elements of arrays are joined together; filename expansion is
 not performed unless the option tt(GLOB_ASSIGN) is set.
@@ -70,7 +84,8 @@ change its type to integer or float, and with tt(GLOB_ASSIGN) assigning a
 pattern to a variable may change its type to an array.
 
 To reference the value of a parameter, write `tt($)var(name)' or
-`tt(${)var(name)tt(})'.  See
+`tt(${)var(name)tt(})'.  The latter form is required when var(name)
+includes a namespace prefix.  See
 ifzman(em(Parameter Expansion) in zmanref(zshexpn))\
 ifnzman(noderef(Parameter Expansion))
 for complete details.  That section also explains the effect