Re: Is the description of set -- missing in man bash or at least difficult to find?

[Greg Wooledge]

On Thu, Dec 22, 2011 at 12:09:38PM -0600, Peng Yu wrote:
> As a reasonable search strategy to search for how to set $@ is to
> search for '$@' in man bash.

There is a "Special Parameters" section.  All of the parameters are listed
there without their leading $ prefix.  For example, the documentation for
$@ is found in the section marked with an @ under Special Parameters.

I submitted a patch to try to get the sections to be labeled with $@
(etc.) so that people could find them, but the patch was not accepted.

> Search for 'set --' returns nothing.

There is nothing special about -- with respect to the set command.  The
special option -- to ANY COMMAND (except echo) means "there are no
more options".  Everything after that is a non-option argument.  (In
the case of set, non-option arguments become the new positional
parameters.)

It is traditional to use   set -- foo bar baz   to set the positional
parameters, just in case the first argument happens to begin with a -.
In this example, it could just as well be written   set foo bar baz
and that would have precisely the same effect.  You only need the --
when you have an expansion in the first argument, as in   set -- "${a[@]}"

> As others pointed out LDP/abs is a more readable document, the
> following link is a much better document on helping me to find how to
> set "$@".

... I don't get it.  You clearly already KNOW how to set the positional
parameters, because you mentioned "set --" previously.  You said you
were searching for set --, which means you KNEW about it, and were just
looking for some details.

You can't say that you are searching for set -- and then, in the same
email, say that you don't know how to set the positional parameters.
One of these things must be a lie.

If you are serious about trying to improve the documentation, then submit
a patch.  Maybe you'll have more success than I did.

If you just want to get into a fight about the documentation, please go
somewhere else.

Of course the "ABS" is a more readable document, flawed as it is, because
it's trying to TEACH you how to write bash scripts.  The bash manual is
not trying to teach you how to write scripts.  It is a REFERENCE manual.
Please understand the difference between a tutorial and a reference manual.