manpage clarification/addition.

[Linda Walsh]

Lest some think functions can replace aliases, there's a line in the manpage
that I feel needs amending.  Currently it says:

   "For almost every purpose, aliases are superseded by shell functions."

While true, it may too likely be read by some to mean that aliases have no
useful purpose.  So I'd suggest:

   "For most purposes, aliases are superseded by shell functions, though
aliases are still required in some situations".


-------------------------------------------


For those who would need an example, consider the following
2 example:
---

alias sub=function      # (example 1: I couldn't see how to use a
                                     # function to define a keyword for 
function)
declare -ix Debug_Ops=1   #set to 0/1 to turn off trace of myop
declare -ixr _D_myop=0x01
sub  debug {
   local op="${1:-}"; test "$op" || return 1;
   local dop="_D_$op"
   local vop="${!dop:-0}"
   local res
   ((res=vop&Debug_Ops))    # if bitset, evals as nonzero, so returns 0
}

#   could be a function, but alias is pretty str8forward
alias DebugPop='test -n "$save_ops" && set -$save_ops'

# But DebugPush takes a "param" that includes the debug flag for the 
routine.
# Since the param needs to be "subbed" into the middle
# of the string, an alias, obviously won't work, so first try plain 
function:

sub DebugPush { local save_ops="${-:-}"; debug $1 || set +x; }

sub xxyz {
   DebugPush myop
   echo do some code;    a=1;    b=2;
   DebugPop
}
---
That one won't work -- cuz 'save_ops' which I wanted as a local to xxyz, is
local to DebugPush.

Needed for workaround:
----
unset -f DebugPush   #make sure previous function is undef'd
sub DebugPush_helper { debug $1  && set +x; }
alias DebugPush='local save_ops="${-:-}"; DebugPush_helper'
sub xxyz {
   DebugPush myop
   echo do some code;    a=1;    b=2;
   DebugPop
}
----
Note -- if you run the above, you have to re-define 'sub xxyz', as alias 
subbing
is done at function define time...so it needs to be redefined to use the 
new
definition for DebugPush.
In 2nd example the 'local is in xxyz's context (where it was desired).

The function only "turns off" (could be extended). tracing on some 
functions...
Just wrote it today, so haven't thought through the design that much...just
wanted to turn of some tracing in low level functions...so ... that's 
what got
implemented... ;-)