25018: Omari Norman: completion for awk, join, sort

Doc/Zsh/builtins.yo

@@ -98,6 +98,10 @@ If the tt(-L) flag is present, then print each
 alias in a manner suitable for putting in a startup script.  The exit
 status is nonzero if a var(name) (with no var(value)) is given for
 which no alias has been defined.
+
+For more on aliases, include common problems,
+ifzman(see the section ALIASING in zmanref(zshmisc))\
+ifnzman(noderef(Aliasing)).
 )
 findex(autoload)
 cindex(functions, autoloading)

Doc/Zsh/grammar.yo

@@ -479,6 +479,19 @@ if an alias is defined for the word tt(foo), alias expansion
 may be avoided by quoting part of the word, e.g. tt(\foo).
 But there is nothing to prevent an alias being defined
 for tt(\foo) as well.
+
+There is a commonly encountered problem with aliases
+illustrated by the following code:
+
+example(alias echobar='echo bar'; echobar)
+
+This prints a message that the command tt(echobar) could not be found.
+This happens because aliases are expanded when the code is read in;
+the entire line is read in one go, so that when tt(echobar) is executed it
+is too late to expand the newly defined alias.  This is often
+a problem in shell scripts, functions, and code executed with `tt(source)'
+or `tt(.)'.  Consequently, use of functions rather than aliases is
+recommended in non-interactive code.
 texinode(Quoting)()(Aliasing)(Shell Grammar)
 sect(Quoting)
 cindex(quoting)