Attempt to document aliasing more fully

[Bart Schaefer <schaefer@xxxxxxxxxxxxxxxx>]

So here is what I have (see diff below).  This describes the situation
prior to workers/34641.  To keep 34641, we'd just have to add another
itemiz() calling out command separators as a separate class of "word",
though I still think that if included, those should (a) still exclude
newline and (b) require "alias -g".

Either way I rather suspect that POSIX_ALIASES should prohibit more
than just the reserved words, e.g., I doubt that parameter references
and quoted strings are meant to be allowed in aliases by POSIX.  That
should get fixed, along with the bug(s) mentioned in 34668 and 34682.


diff --git a/Doc/Zsh/grammar.yo b/Doc/Zsh/grammar.yo
index 63d90df..ee44841 100644
--- a/Doc/Zsh/grammar.yo
+++ b/Doc/Zsh/grammar.yo
@@ -532,12 +532,12 @@ characters up to a newline to be ignored.
 texinode(Aliasing)(Quoting)(Comments)(Shell Grammar)
 sect(Aliasing)
 cindex(aliasing)
-Every token in the shell input is checked to see if there
+Every eligible em(word) in the shell input is checked to see if there
 is an alias defined for it.
 If so, it is replaced by the text of the alias if it is in command
 position (if it could be the first word of a simple command),
 or if the alias is global.
-If the text ends with a space, the next word in the shell input
+If the replacement text ends with a space, the next word in the shell input
 is treated as though it were in command position for purposes of alias
 expansion.
 findex(alias, use of)
@@ -545,6 +545,22 @@ cindex(aliases, global)
 An alias is defined using the tt(alias) builtin; global aliases
 may be defined using the tt(-g) option to that builtin.
 
+A em(word) is defined as:
+
+startitemize()
+itemiz(Any plain string or glob pattern)
+itemiz(Any quoted string, using any quoting method (note that the quotes
+must be part of the alias definition for this to be eligible))
+itemiz(Any parameter reference or command substitution)
+itemiz(Any series of the foregoing, concatenated without whitespace or
+other tokens between them)
+itemiz(Any reserved word (tt(case), tt(do), tt(else), etc.))
+enditemize()
+
+Reserved words are not eligible for aliasing when tt(POSIX_ALIASES) set.
+The 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