On 2024-05-22 23:52, Eli Zaretskii wrote:
>> Date: Wed, 22 May 2024 21:19:05 -0700
>> From: Jared Finder <jared@finder.org>
>> Cc: juri@linkov.net, 68765@debbugs.gnu.org, philipk@posteo.net,
>>  monnier@iro.umontreal.ca
>> 
>> +@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

I don't think that fits in with the existing convention.  The convention 
appears to be "use mode, Capital Case Name" for specific modes and 
"mode, lower case" for concepts.  There's 76 other examples of "@cindex 
mode," in the Emacs manual already, the majority of which follow that 
convention.

The only examples I could find not following the convention are: "mode, 
archive", "mode, tar", "mode, display-fill-column-indicator".

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

Makes sense.  Will do.

>> +  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?

I will try to redescribe it.  I have a typo in the existing description. 
  Change "all windows" to "each window".  The idea is that each window 
gets its own tool bar *inside the window*, specifically on the window's 
tab line.  Ideally I think I would just show a picture (see attached 
image), but I see very few pictures in any of the Emacs manuals and none 
of them show up in the HTML output at 
https://www.gnu.org/software/emacs/manual/, only in the PDF.

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

Will do.

   -- MJF