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

From: Eli Zaretskii <[email-masked]>
Date: Thu, 23 May 2024 09:52:51 +0300

> Date: Wed, 22 May 2024 21:19:05 -0700
> From: Jared Finder <[email-masked]>
> Cc: [email-masked], [email-masked], [email-masked],
>  [email-masked]
> 
> +@node Window Tool Bar
> +@cindex mode, Window Tool Bar

Index entries should preferably use only lower-case letters, to avoid
problems with sorting index entries in different locales.

In addition, I would rephrase the above index entry to say just

  @cindex window tool bar

> +@findex global-window-tool-bar-mode
> +@vindex global-window-tool-bar-mode

This will create two identical index entries (since we produce a
single Index from all the index entries).  So leave just one of the
two.

> +  The command @code{global-window-tool-bar-mode} toggles the display of
> +a tool bar at the top of all windows.  (You can also customize the
> +variable @code{global-window-tool-bar-mode}.)  To conserve space, a
> +window tool bar is only shown if the tool bar for a 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.

This paragraph left me puzzled.  By default, the frame-global tool bar
follows the major mode of the selected buffer's window.  This is not
going to change even under global-window-tool-bar-mode, is it?  If so,
when will the window-specific tool bar be displayed -- only in
non-selected windows whose buffers have a major mode different from
that of the selected-window's buffer?  If so, this should be
explicitly explained in the manual, I think.

Also, does this mean the window-specific tool bar will appear and
disappear depending on which window is selected?  Wouldn't that cause
annoying "flickering" of display?

> +@findex window-tool-bar-mode
> +If you want to toggle the display of a tool bar in just a single window,
> +run the command @code{window-tool-bar-mode}.  This is also useful to put
> +in a hook.  For example if you want the window tool bar to appear for
> +all buffers that do not represent files and have a custom tool bar, you
> +could add the following code to your init file (@pxref{Init File}):

Are these window tool bars also limited to windows whose buffers'
major mode is different from the selected window?  In any case, this
aspect, whether identical to global-window-tool-bar-mode or different
from it, should be explicitly documented.

Last, but not least: please mention the bug number in the commit log
message.

Thanks.