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

[Eli Zaretskii]

> Date: Sat, 25 May 2024 12:54:30 -0700
> From: Jared Finder <jared@finder.org>
> Cc: juri@linkov.net, 68765@debbugs.gnu.org, philipk@posteo.net,
>  monnier@iro.umontreal.ca
> 
> Ok, I tried to fit into the existing convention but not use upper case 
> letters with "@cindex mode, window tool bar".  Let me know if that's not 
> appropriate.

LGTM, thanks.

> That's what I was concerned about.  Please let me know if this updated 
> text is clear enough.
> 
> > I will wait for the next version to see if my questions are now
> > answered or we need to discuss them further.
> 
> New patch attached.  Feedback welcome.

Thanks, some comments below.

> +@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.)

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?

> +@findex window-tool-bar-mode
> +If you want to toggle the display of a window tool bar for only some
> +buffers, run the command @code{window-tool-bar-mode}.

I guess this should say that window-tool-bar-mode should be run in the
buffer(s) where the window tool bar is desired?

> +bar will then only appear at the top of any window displaying that
> +buffer.  This is useful to put in a hook.

"in a mode hook", I suppose?

> +Note that the window tool bar displays in the same space as the tab
> +line, so only one of these can be display at a time unless you customize
> +the value of @code{tab-line-format} in Lisp.  In this case, add
> +@code{(:eval (window-tool-bar-strng))} to @code{tab-line-format}.
                                 ^^^^^
A typo?

> +  A window can have a @dfn{tab line} at the top.  If both the tab line
> +and header line are visible, the tab line appears above the header line.
> +The tab line feature works just like the mode line feature, except that
> +it's controlled by @code{tab-line-format}:
> +
> +@defvar tab-line-format
> +This variable, local in every buffer, specifies how to display the tab
> +line, for windows displaying the buffer.  The format of the value is the
> +same as for @code{mode-line-format} (@pxref{Mode Line Data}).  It is
> +normally @code{nil}, so that ordinary buffers have no tab line.
> +@end defvar

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.

> ++++
> +** New user option 'tool-bar-always-show-default'.
> +This can be set so that the tool bar at the top of a frame does not show
> +buffer local customization of the tool bar.  This is convenient when
> +using the newly added 'global-window-tool-bar-mode'.

This should tell the values of the option and their effect.