41842: aliasing documentation update

1 files changed, 29 insertions, 9 deletions

diff --git a/Doc/Zsh/grammar.yo b/Doc/Zsh/grammar.yo
index 463ac8831..bd7727298 100644
--- a/Doc/Zsh/grammar.yo
+++ b/Doc/Zsh/grammar.yo
@@ -568,15 +568,6 @@ itemiz(With global aliasing, any command separator, any redirection
 operator, and `tt(LPAR())' or `tt(RPAR())' when not part of a glob pattern)
 enditemize()
 
-It is not presently possible to alias the `tt(LPAR()LPAR())' token that
-introduces arithmetic expressions, because until a full statement has been
-parsed, it cannot be distinguished from two consecutive `tt(LPAR())'
-tokens introducing nested subshells.
-
-When tt(POSIX_ALIASES) is set, only plain unquoted strings are eligible
-for aliasing.  The tt(alias) builtin does not reject ineligible aliases,
-but they are not expanded.
-
 Alias expansion is done on the shell input before any other expansion
 except history expansion.  Therefore, if an alias is defined for the
 word tt(foo), alias expansion may be avoided by quoting part of the
@@ -586,11 +577,40 @@ tt(\foo) as well.  Also, if a separator such as tt(&&) is aliased,
 tt(\&&) turns into the two tokens tt(\&) and tt(&), each of which may
 have been aliased separately.  Similarly for tt(\<<), tt(\>|), etc.
 
+When tt(POSIX_ALIASES) is set, only plain unquoted strings are eligible
+for aliasing.  The tt(alias) builtin does not reject ineligible aliases,
+but they are not expanded.
+
 For use with completion, which would remove an initial backslash followed
 by a character that isn't special, it may be more convenient to quote the
 word by starting with a single quote, i.e. tt('foo); completion will
 automatically add the trailing single quote.
 
+subsect(Alias difficulties)
+
+Although aliases can be used in ways that bend normal shell syntax, not
+every string of non-white-space characters can be used as an alias.
+
+Any set of characters not listed as a word above is not a word, hence no
+attempt is made to expand it as an alias, no matter how it is defined
+(i.e. via the builtin or the special parameter tt(aliases) described in
+ifnzman(noderef(The zsh/parameter Module))\
+ifzman(the section THE ZSH/PARAMETER MODULE in zmanref(zshmodules))).
+However, as noted in the case of tt(POSIX_ALIASES) above, the shell does
+not attempt to deduce whether the string corresponds to a word at the
+time the alias is created.
+
+For example, an expression containing an tt(=) at the start of
+a command line is an assignment and cannot be expanded as an alias;
+a lone tt(=) is not an assignment but can only be set as an alias
+using the parameter, as otherwise the tt(=) is taken part of the
+syntax of the builtin command.
+
+It is not presently possible to alias the `tt(LPAR()LPAR())' token that
+introduces arithmetic expressions, because until a full statement has been
+parsed, it cannot be distinguished from two consecutive `tt(LPAR())'
+tokens introducing nested subshells.
+
 There is a commonly encountered problem with aliases
 illustrated by the following code: