bug#68765: 30.0.50; Adding window-tool-bar package.

[Eli Zaretskii]

> Date: Sun, 26 May 2024 09:20:56 -0700
> From: Jared Finder <jared@finder.org>
> Cc: juri@linkov.net, 68765@debbugs.gnu.org, philipk@posteo.net,
>  monnier@iro.umontreal.ca
> 
> >> +@findex global-window-tool-bar-mode
> >> +  The command @code{global-window-tool-bar-mode} toggles the display 
> >> of
> >> +a tool bar at the top of each window.  When enabled, multiple windows
> >> +can display their own tool bar simultaneously.  To conserve space, a
> >> +window tool bar is only shown if the tool bar for that window's 
> >> current
> >> +buffer is different from the global (default) tool bar.  The most 
> >> common
> >> +way a buffer has a different tool bar is due to its major mode, so 
> >> you
> >> +can think of the window tool bar as showing a major mode's tool bar 
> >> if
> >> +it exists.
> > 
> > So, let me understand what happens under this global mode.  By
> > default, the frame's tool bar changes according to the major mode of
> > the buffer shown in the frame's selected window.  As a very frequent
> > example, entering the minibuffer from a buffer whose mode is, say,
> > Dired or Rmail or Info, changes the tool bar.  When that happens, some
> > windows which previously didn't display their tool bar because it was
> > identical to the frame's tool bar will now display their tool bars.
> > Right?  And when you exit the minibuffer, those window-specific tool
> > bars will again disappear, right?  Wouldn't that cause annoying
> > flickering of the display?  (I know that setting
> > tool-bar-always-show-default non-nil can prevent that, but I'm asking
> > about the default behavior.)
> 
> No, this is not the behavior.  The window tool bar displays that 
> buffer's binding of <tool-bar>.  The window tool bar is displayed in the 
> tab line of each window and doesn't pay attention to what the current 
> buffer or window is.

But this means that the following text:

>>                                                  To conserve space,
>> a window tool bar is only shown if the tool bar for that window's
>> current buffer is different from the global (default) tool bar

is at least inaccurate.  Specifically, if the frame's global tool bar
changes as result of some command, the identity of the tool bars of
windows to that of the frame is not re-examined.  So if some window
decided that its tool bar is not to be displayed, it will remain
undisplayed until that window shows a different buffer or its buffer
changes its major mode.  Is that correct?  If not, why not?

Or maybe I don't understand well enough what you mean by "The window
tool bar is displayed in the tab line of each window and doesn't pay
attention to what the current buffer or window is."  You are using
here terminology that is confusing: there's no "current window" in
Emacs, only the "selected window", and it is unclear whether by
"current buffer" you mean the global current buffer (the one returned
by the function current-buffer) or the buffer shown in a window (since
you also say "the window's current buffer", another term that we do
not use).

> > Btw, what exactly is the meaning of "the tool bar of the window is
> > different from the global tool bar"?  How are tool bars compared?  For
> > example, a button on the tool bar can have the :visible attribute,
> > which will cause the icon not to appear under some conditions -- will
> > a tool bar with that icon on display be considered "different" from a
> > tool bar where the icon is not shown due to :visible conditions?
> 
> It's specifically using the following test:
> 
> (eq tool-bar-map
>      (default-value 'tool-bar-map))

So a frame's tool bar can completely change its look due to :visible,
and Emacs will still consider it "equal" to the tool bar of some
window where those :visible conditions yield a completely different
look?  Does that make sense?

I'm beginning to think that the feature whereby we don't display the
window's tool bar under some conditions "to conserve space" is more
confusing and hard to document than is useful, and perhaps we should
simply show the window's tool bar unconditionally?

> > I wonder whether it's a good idea to tell that tab line works "the
> > same as mode line", since the purpose is very different, and the
> > default value of tab-line-format is very different from the default of
> > mode-line-format.  At the very least I think we should tell that
> > tab-line-format should cause the tab line appear as a row of buttons,
> > clicking on which should change the buffer shown in the window.
> 
> Perhaps there's some sort of convention we can describe that talks about 
> the difference between header-line-format and tab-line-format?  I'd like 
> to copy back any changes to header-line-format which I based this text 
> off of.
> 
> It seems to me that really the only difference is conventional.  I'm 
> thinking something along the lines of "header line is usually modified 
> by major modes to add additional info (examples: EWW, Info) and the tab 
> line is usually modified by minor modes to add IDE-styled buttons 
> (examples: tab line mode, window tool bar mode)".
> 
> Does that sound right to you?

It doesn't address my concerns.  My concerns are that the purpose of
tab-line and window's tool bar is conceptually very different from
that of the mode line and the header line.  Technically, they are all
controlled by a FOO-format variable that has the same rules and
syntax, but that's an implementation detail.  For example, it would
make no sense at all to use something similar to the default
mode-line-format for the tab-line or the window tool bar, would it?

So what I would like us to say in the manual is that the value of
window-tool-bar-format and of tab-line-format should produce what is
expected from these lines: a row of tabs for tab-line and a row of
icons for the tool bar.  The reader should understand that having a
tab-line-format whose value is "%b %f", for example, makes no sense,
although it will work.  (In general, most or all %-elements of mode
line and header line make no sense in tab-line and tool bar.  It is
hardly an accident that tab-line-format's value is just (:eval FUNC),
in stark contrast to the value of mode-line-format and
header-line-format in modes in which it is non-nil.)

Did I succeed to explain my concerns?