Re: Question about the return value of 'local'

[Dan Douglas]

On Friday, December 14, 2012 08:37:02 AM Francis Moreau wrote:
> On Thu, Dec 13, 2012 at 3:19 PM, Chet Ramey <chet.ramey@case.edu> wrote:
> > On 12/13/12 3:56 AM, Francis Moreau wrote:
> >
> >> I see thanks.
> >>
> >> Somehow I thought that help(1) would have given nothing more nothing
> >> less than what was described in the manual.
> >
> > `help' is a quick reference -- a handy shortcut.  The authoritative
> > documentation is still the manual page and texinfo document.
> 
> Then maybe an option should be added to 'local' to display the full
> description that one can get from the manual, or maybe change the
> behaviour of '-m' switch ?
> 
> Thanks.

The best you could do (realistically) is manually keep the man document in 
sync with the help text for every individual builtin. Generating help output 
automatically would require completely changing the way builtin options are 
processed, because there aren't just arrays of options that could be mapped to 
descriptions. Bash loops over a condition for all available options for each 
argument. There are also a couple intentionally undocumented options (like 
declare -c), and some which can vary by how bash was built (like echo). Also 
the man document has all the formatting in it and can't be automatically 
generated from individual builtin help text easily, or vice versa.

Zsh is way bigger than Bash and has no help system at all (unless I missed it 
in the dozen or so manpages...). Ksh has an unbelievably stupid way of 
accessing the help, though it tends to be even more comprehensive than the 
manpage. The options are automatically generated and the descriptions 
hardcoded to a central builtins.c file. (user-defined types are self-
documenting).

Most shell manuals follow about the same overall format and obviously borrow 
from one another. Some paragraphs are word-for-word identical between Bash and 
multiple other manuals. Best bet is to learn to navigate it quickly.

-- 
Dan Douglas