bug#16052: 24.3.50; `set-frame-parameter` broken for `tool-bar-lines`

[Drew Adams <drew.adams@oracle.com>]

> > M-x tool-bar-mode ; turn it on
> > M-x pp-eval-expression RET (frame-parameters)
> >
> > In frame *Pp Eval Output* search for `tool-bar-lines' => 2
> > (wrong).

> > M-x pp-eval-expression RET
> >     (set-frame-parameter nil 'tool-bar-lines 1)
> > M-x pp-eval-expression RET (frame-parameters)
> >
> > In frame *Pp Eval Output* search for `tool-bar-lines' => 2
> > (wrong).

> Before using terms like "wrong" in bug reports please consult the
> Elisp manual:
> 
>     On each frame, the frame parameter `tool-bar-lines' controls
>     how many lines' worth of height to reserve for the tool bar.

That does not contradict my expectation.  Is there some nuanced
interpretation of "reserved" that I need to guess here, such that
perhaps "reserving" that much height does not actually give the
tool bar area that much height?

And actually, node (elisp) `Layout Parameters' says that it is "the
number of lines to USE for the tool bar."  Not just reserved but
used.

Furthermore, it says explicitly that "The default is 1 if Tool Bar
mode is enabled, and 0 otherwise."  That pretty much describes the
intended default behavior, and it coincides with my uninformed
expectation.

> What you see is either 0 when `tool-bar-mode' is turned off or 2
> which probably comes from the actual toolbar pixel height divided
> by the frame's default line height.

What it really comes from should be *specified* in the manual.

IOW, what is the default number?  Otherwise, it is pretty reasonable
to assume (as I did) that the default is one.  Whether reasonable or
not, users should not need to guess the default behavior for the
on state.

And see above.  The manual in fact DOES say what the default is,
and it is not 2.  Is the manual wrong here or is the implementation
bugged in this regard?

> Explicitly setting the `tool-bar-lines' parameter has no effect
> when `auto-resize-tool-bars' is non-nil (which it is with emacs -Q).

Thanks for that explanation of what the implementation does.
However, that too is unlikely to be guessed by users.  And the doc
does not say that at all, AFAICT.  It says only that the tool bar
gets resized automatically.

All of the info regarding `tool-bar-lines' should be either
documented in the same place or clearly interconnected using cross
references.

Layout parameter `tool-bar-lines' is documented primarily in node
`Layout Parameters' - that it the reference doc for it.  At the
very least there needs to be a cross reference from there to node
`Tool Bar' (and vice versa).

And preferably it would be explicitly mentioned at `Layout
Parameters' what the effect is of `auto-resize-tool-bars' on
`tool-bar-lines' (the latter is ignored if the former is non-nil,
i.e., it is IGNORED by DEFAULT).

So if the behavior is as it is intended to be, then the doc is
inadequate.  It does not describe the behavior.  And what it does
suggest (i.e., by default, setting `tool-bar-lines' would do just
what the `tool-bar-lines' doc says: change the number of tool bar
lines) is something quite different from the actual behavior.