Re: Question about the return value of 'local'

[Bill Gradwohl]

I'm not trying to start a war, but ...

Has anyone entertained the idea of getting rid of the man pages and the
info system? Those are relics of the tty era. We have graphical interfaces
today with capabilities that could enhance providing and then finding
better information.

Wouldn't a browser based html page be more helpful?  Anyone on a non GUI
could use lynx to read the pages, or make man pull up lynx to keep the
command structure the same.

The basic page could be what man is now, more or less, and the ability to
drill down would provide more and more information the deeper you drill.
Code snippets could highlight idiosyncratic behavior at boundary conditions
while other examples demonstrate the main emphasis.

A WIKI set up could allow people to augment the docs with some authority
then editing the content to keep it up to some standard. Greg's site is
excellent, as are several others, and that's the issue. There is no one
authoritative place to go to get the OFFICIAL docs in a modern form. Who
wants to learn how to write and submit man or info docs when the future is
clearly html, especially when neither man nor info has the rendering
capability html has?

If the Linux community as a whole missed one technical release cycle to
instead concentrate on properly documenting what already exists, the effort
would pay off in spades for all future releases.


On Fri, Dec 14, 2012 at 10:15 AM, Dan Douglas <ormaaj@gmail.com> wrote:

> 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
>
>


-- 
Bill Gradwohl