Re: Documentation issue

[Eli Barzilay]

On Thu, Oct 26, 2017 at 2:02 PM, Chet Ramey <chet.ramey@case.edu> wrote:
>
> It's more of a general statement about arrays, though it appears in
> the paragraph that discusses unset, so it's in the man page section on
> arrays.  You have to be careful about putting the same information in
> too many different places -- the man page is big enough already.

I'm very aware of man page bloat and the fact that the bash page is very
long as is.  But (a) I think that the builtin section for each command
is the more important place for such things; and (b) what I'm suggesting
is just a short reminder sentence about the need for quoting unsets for
array elements.

To make it more concrete, I think that the following change will be
good:

1. Drop the current "Care must be taken ... the entire array." two
   sentences and replace them with some "See the unset builtin
   description below".

2. Add those two sentences to the unset builtin section, as a new
   paragraph.

3. Tweak it slightly to explicitly encourage quoting:

       Care must be taken to avoid unwanted side effects caused by
       pathname expansion, (i.e., prefer unset "name[subscript]" to
       avoid such problems).  unset name, where name is an array, or
       unset name[subscript], where subscript is * or @, removes the
       entire array.

Note that there are two very small additions to the overall text:

1. A "see also" reference (to ensure that people don't miss it from
   either place).

2. The parenthetical comment.

-- 
                   ((x=>x(x))(x=>x(x)))                  Eli Barzilay:
                   http://barzilay.org/                  Maze is Life!