Subject: bug#22000: Patch addressing the menu-bar frame-resize interaction

From: Vivek Dasmohapatra <[email-masked]>
Date: Thu, 18 Oct 2018 18:26:34 +0100 (BST)

>> +(defcustom menu-bar-scrollbar-mode nil
>> +      "Specify how GTK menu bars deal with the frame being too narrow to hold them.\n
>> +Valid values are:
>> +  `always'        - the menu bar always has a scrollbar
>> +  `automatic'     - a scrollbar is added when required
>> +  `forced-resize' - no scrollbar, the frame is forced to resize to accommodate
>> +                    the menu bar.
>> +   nil (or any other value) - the menu bar is truncated\n
>> +Note that prior to GTK 3.16 truncation is not possible and the default
>> +is equivalent to 'forced-resize.\n
>
> Do you really need these explicit \n newlines?

I wouldn't say need but I find they make the documentation more readable, 
per item 3 in (elisp)Top > Tips > Documentation tips … D.6 Tips for…

> More generally, shouldn't this mode have "gtk" somewhere in the name?
> Or, if we hope to implement it for other toolkits at some future date,
> the doc string should not say "GTK menu bars", it should say "menu
> bars" and then have a note that this currently has effect only with
> GTK menus.

I prefer the second option, I will adjust the docstrings accordingly.

>> +(defun menu-bar-showhide-menu-bar-scrollbar-mode-customize-nil ()
>> +  "Truncate the menu bar to fit the frame."
>> +  (interactive)
>> +  (customize-set-variable 'menu-bar-scrollbar-mode 'default))
>
> I think doc strings of these functions are too laconic for interactive
> functions.

AIUI they are interactive purely because that is a requirement for the
way they are used by the menu infrastructure, not because they are
intended to be used as commands with M-x or similar by the user.

The other …-customize-… shim commands in that file are similarly laconically
documented. However if the objection still stands, I will add more verbose
docstrings.

I will make the other changes suggested (to which I have not responded
individually here).