bug#68600: 30.0.50; Bad mode hook docstring when mode-line constructs are present in the mode-name

bug#68600: 30.0.50; Bad mode hook docstring when mode-line constructs are present in the mode-name

[Phil Sainty]

If we define a major mode with mode-line constructs in its mode-name
(in this example using a copy of the constructs from `emacs-lisp-mode'):

  ;; Force hook docstring re-generation:
  (put 'example-lisp-mode-hook 'variable-documentation nil)

  (define-derived-mode example-lisp-mode lisp-data-mode
    `("Example"
      (lexical-binding (:propertize "/l"
                        help-echo "Using lexical-binding mode")
                       (:propertize "/d"
                        help-echo "Using old dynamic scoping mode\n\
  mouse-1: Enable lexical-binding mode"
                face warning
                mouse-face mode-line-highlight
                        local-map ,elisp--dynlex-modeline-map)))
    "Example mode.")

Then, unles we have previously defined the mode hook variable with a
custom docstring (which seems to be the workaround in the meantime),
C-h v example-lisp-mode-hook says:

Hook run after entering `(Example (lexical-binding (:propertize /l 
help-echo Using lexical-binding mode) (:propertize /d help-echo Using 
old dynamic scoping mode
mouse-1: Enable lexical-binding mode face warning mouse-face 
mode-line-highlight local-map ,elisp--dynlex-modeline-map))) mode.

Instead of: "Hook run after entering Example mode."

I figure `format-mode-line' needs to be called on the `mode-name' when
generating the docstring for the mode hook (which possibly means making
these docstrings dynamic?)


-Phil



In GNU Emacs 30.0.50 (build 2, x86_64-pc-linux-gnu, X toolkit, cairo
  version 1.16.0, Xaw scroll bars) of 2024-01-09 built on phil-lp
Repository revision: 774c8ec74c98d69d56b2511a613145f2b69fb2eb
Repository branch: master
Windowing system distributor 'The X.Org Foundation', version 
11.0.12101004
System Description: Ubuntu 22.04.3 LTS

Configured using:
  'configure --prefix=/home/phil/emacs/trunk/usr/local
  --without-native-compilation --with-x-toolkit=lucid --without-sound
  '--program-transform-name=s/^ctags$/ctags_emacs/''

Configured features:
CAIRO DBUS FREETYPE GIF GLIB GMP GNUTLS GPM GSETTINGS HARFBUZZ JPEG JSON
LCMS2 LIBSELINUX LIBXML2 MODULES NOTIFY INOTIFY PDUMPER PNG RSVG SECCOMP
SQLITE3 THREADS TIFF TOOLKIT_SCROLL_BARS TREE_SITTER WEBP X11 XDBE XIM
XPM LUCID ZLIB

Important settings:
   value of $LC_MONETARY: en_NZ.UTF-8
   value of $LC_NUMERIC: en_NZ.UTF-8
   value of $LC_TIME: en_NZ.UTF-8
   value of $LANG: en_GB.UTF-8
   value of $XMODIFIERS: @im=ibus
   locale-coding-system: utf-8

Major mode: Lisp Interaction

Minor modes in effect:
   hi-lock-mode: t
   elisp-slime-nav-mode: t
   hl-sexp-mode: t
   lexbind-mode: t
   idle-highlight-mode: t
   minibuffer-line-mode: t
   global-edit-server-edit-mode: t
   savehist-mode: t
   magit-wip-initial-backup-mode: t
   magit-wip-before-change-mode: t
   magit-wip-after-apply-mode: t
   magit-wip-after-save-mode: t
   magit-wip-mode: t
   global-git-commit-mode: t
   magit-auto-revert-mode: t
   server-mode: t
   my-contextual-help-mode: t
   global-so-long-mode: t
   display-battery-mode: t
   my-visible-bell-mode: t
   cua-mode: t
   global-display-fill-column-indicator-mode: t
   display-fill-column-indicator-mode: t
   minibuffer-depth-indicate-mode: t
   which-key-mode: t
   windmove-mode: t
   winner-mode: t
   global-subword-mode: t
   subword-mode: t
   global-hl-line-mode: t
   hl-line-mode: t
   display-time-mode: t
   keep-buffers-mode: t
   fic-mode: t
   my-keys-local-minor-mode: t
   auto-compile-on-load-mode: t
   auto-compile-on-save-mode: t
   url-handler-mode: t
   tooltip-mode: t
   global-eldoc-mode: t
   eldoc-mode: t
   show-paren-mode: t
   electric-indent-mode: t
   mouse-wheel-mode: t
   menu-bar-mode: t
   file-name-shadow-mode: t
   global-font-lock-mode: t
   font-lock-mode: t
   minibuffer-regexp-mode: t
   line-number-mode: t
   transient-mark-mode: t
   auto-composition-mode: t
   auto-encryption-mode: t
   auto-compression-mode: t

Load-path shadows:
/home/phil/.emacs.d.sandboxes/trunk/HOME/.emacs.d/el-get/scratch/el-get 
hides 
/home/phil/.emacs.d.sandboxes/trunk/HOME/.emacs.d/el-get/el-get/el-get
/home/phil/.emacs.d.sandboxes/trunk/HOME/.emacs.d/el-get/delight/delight 
hides 
/home/phil/.emacs.d.sandboxes/trunk/HOME/.emacs.d/elpa/delight-1.7/delight
/home/phil/.emacs.d.sandboxes/trunk/HOME/.emacs.d/lisp/python hides 
/home/phil/emacs/trunk/usr/local/share/emacs/30.0.50/lisp/progmodes/python

Features:
(shadow sort ecomplete mail-extr emacsbug whitespace debug backtrace
ibuf-ext face-remap ibuffer ibuffer-loaddefs hippie-exp misearch
multi-isearch shortdoc comp-common autoinsert goto-addr find-func
cl-print help-fns hi-lock elisp-slime-nav etags fileloop generator xref
project hl-sexp lexbind-mode idle-highlight-mode tramp-sh warnings
docker-tramp tramp-cache time-stamp tramp trampver tramp-integration
files-x tramp-message tramp-compat xdg parse-time iso8601 tramp-loaddefs
tabify minibuffer-line edit-server my-org my-projects my-session
savehist desktop frameset my-theme zenburn-theme my-mail pcase autoloads
my-libraries sudo my-version-control magit-wip magit-log which-func
imenu magit-diff smerge-mode diff git-commit rx log-edit message
sendmail yank-media puny rfc822 mml mml-sec epa epg rfc6068 epg-config
gnus-util text-property-search time-date mm-decode mm-bodies mm-encode
mail-parse rfc2231 rfc2047 rfc2045 mm-util ietf-drums mail-prsvr
mailabbrev mail-utils gmm-utils mailheader pcvs-util add-log magit-core
magit-autorevert autorevert filenotify magit-margin magit-transient
magit-process with-editor shell pcomplete comint ansi-osc server
ansi-color magit-mode transient edmacro kmacro format-spec magit-git
magit-section magit-utils crm dash my-text my-programming my-python
so-long my-whitespace ws-trim my-rectangles my-utilities
browse-kill-ring my-configuration cus-edit pp cus-load wid-edit
dired-details dired-x highlight-parentheses battery delight delsel
cua-base ffap display-fill-column-indicator mb-depth which-key framemove
windmove winner ring cap-words superword subword hl-line time
my-externals .loaddefs windcycle transpose-frame simple-wiki derived
sdcv-mode noutline outline icons sauron rainbow-mode notify dbus xml
multiple-cursors mc-separate-operations rectangular-region-mode
mc-mark-pop mc-mark-more thingatpt mc-cycle-cursors mc-edit-lines
multiple-cursors-core rect mo-git-blame keep-buffers iedit fic-mode
dtrt-indent browse-at-remote vc-git diff-mode easy-mmode vc-dispatcher s
el-get cl-extra help-mode autoload loaddefs-gen radix-tree lisp-mnt cl
dired dired-loaddefs jka-compr my-local my-keybindings auto-compile
packed compat-autoloads etags-select-autoloads info
project-local-variables-autoloads advice wtf-autoloads package
browse-url url url-proxy url-privacy url-expand url-methods url-history
url-cookie generate-lisp-file url-domsuf url-util mailcap url-handlers
url-parse auth-source cl-seq eieio eieio-core cl-macs password-cache
json subr-x map byte-opt gv bytecomp byte-compile url-vars cl-loaddefs
cl-lib rmc iso-transl tooltip cconv eldoc paren electric uniquify
ediff-hook vc-hooks lisp-float-type elisp-mode mwheel term/x-win x-win
term/common-win x-dnd touch-screen tool-bar dnd fontset image regexp-opt
fringe tabulated-list replace newcomment text-mode lisp-mode prog-mode
register page tab-bar menu-bar rfn-eshadow isearch easymenu timer select
scroll-bar mouse jit-lock font-lock syntax font-core term/tty-colors
frame minibuffer nadvice seq simple cl-generic indonesian philippine
cham georgian utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao
korean japanese eucjp-ms cp51932 hebrew greek romanian slovak czech
european ethiopic indian cyrillic chinese composite emoji-zwj charscript
charprop case-table epa-hook jka-cmpr-hook help abbrev obarray oclosure
cl-preloaded button loaddefs theme-loaddefs faces cus-face macroexp
files window text-properties overlay sha1 md5 base64 format env
code-pages mule custom widget keymap hashtable-print-readable backquote
threads dbusbind inotify lcms2 dynamic-setting system-font-setting
font-render-setting cairo x-toolkit x multi-tty move-toolbar
make-network-process emacs)

Memory information:
((conses 16 452119 295599) (symbols 48 24552 0)
  (strings 32 84489 6031) (string-bytes 1 3339539) (vectors 16 46546)
  (vector-slots 8 1200262 242797) (floats 8 268 207)
  (intervals 56 47487 619) (buffers 984 21))

bug#68600: 30.0.50; Bad mode hook docstring when mode-line constructs are present in the mode-name

[Eli Zaretskii]

> Date: Sat, 20 Jan 2024 18:15:51 +1300
> From: Phil Sainty <psainty@orcon.net.nz>
> 
> If we define a major mode with mode-line constructs in its mode-name
> (in this example using a copy of the constructs from `emacs-lisp-mode'):
> 
>   ;; Force hook docstring re-generation:
>   (put 'example-lisp-mode-hook 'variable-documentation nil)
> 
>   (define-derived-mode example-lisp-mode lisp-data-mode
>     `("Example"
>       (lexical-binding (:propertize "/l"
>                         help-echo "Using lexical-binding mode")
>                        (:propertize "/d"
>                         help-echo "Using old dynamic scoping mode\n\
>   mouse-1: Enable lexical-binding mode"
>                 face warning
>                 mouse-face mode-line-highlight
>                         local-map ,elisp--dynlex-modeline-map)))
>     "Example mode.")
> 
> Then, unles we have previously defined the mode hook variable with a
> custom docstring (which seems to be the workaround in the meantime),
> C-h v example-lisp-mode-hook says:
> 
> Hook run after entering `(Example (lexical-binding (:propertize /l 
> help-echo Using lexical-binding mode) (:propertize /d help-echo Using 
> old dynamic scoping mode
> mouse-1: Enable lexical-binding mode face warning mouse-face 
> mode-line-highlight local-map ,elisp--dynlex-modeline-map))) mode.
> 
> Instead of: "Hook run after entering Example mode."
> 
> I figure `format-mode-line' needs to be called on the `mode-name' when
> generating the docstring for the mode hook (which possibly means making
> these docstrings dynamic?)

I'd very much prefer not to call format-mode-line in these cases.
It's a very blunt instrument, and its results are sometimes
unexpected, especially when there are arbitrary advanced elements in
mode-line-format.

If we cannot find a better way to solve this, I'd prefer documenting
the current workaround, and otherwise leaving the code unchanged.

Adding Stefan, in case he has some comments or ideas to suggest.

Thanks.

bug#68600: 30.0.50; Bad mode hook docstring when mode-line constructs are present in the mode-name

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

>> If we define a major mode with mode-line constructs in its mode-name
>> (in this example using a copy of the constructs from `emacs-lisp-mode'):
>> 
>>   ;; Force hook docstring re-generation:
>>   (put 'example-lisp-mode-hook 'variable-documentation nil)
>> 
>>   (define-derived-mode example-lisp-mode lisp-data-mode
>>     `("Example"
>>       (lexical-binding (:propertize "/l"
>>                         help-echo "Using lexical-binding mode")
>>                        (:propertize "/d"
>>                         help-echo "Using old dynamic scoping mode\n\
>>   mouse-1: Enable lexical-binding mode"
>>                 face warning
>>                 mouse-face mode-line-highlight
>>                         local-map ,elisp--dynlex-modeline-map)))
>>     "Example mode.")
>> 
>> Then, unles we have previously defined the mode hook variable with a
>> custom docstring (which seems to be the workaround in the meantime),
>> C-h v example-lisp-mode-hook says:
>> 
>> Hook run after entering `(Example (lexical-binding (:propertize /l 
>> help-echo Using lexical-binding mode) (:propertize /d help-echo Using 
>> old dynamic scoping mode
>> mouse-1: Enable lexical-binding mode face warning mouse-face 
>> mode-line-highlight local-map ,elisp--dynlex-modeline-map))) mode.
>> 
>> Instead of: "Hook run after entering Example mode."

Duh, indeed.

>> I figure `format-mode-line' needs to be called on the `mode-name' when
>> generating the docstring for the mode hook (which possibly means making
>> these docstrings dynamic?)

I don't think we want to make it dynamic, no.
But indeed with `format-mode-line` the docstring would say "Exemple/l" or
"Exemple/d" whereas we'd probably prefer it to say just "Exemple".
The patch below solves the problem in a different way.

> I'd very much prefer not to call format-mode-line in these cases.
> It's a very blunt instrument, and its results are sometimes
> unexpected, especially when there are arbitrary advanced elements in
> mode-line-format.

I don't think we need to avoid `format-mode-line` like the plague, but
indeed it will tend to give subpar results here (being too specific
while the docstring should say what the var does in general).


        Stefan


diff --git a/lisp/emacs-lisp/derived.el b/lisp/emacs-lisp/derived.el
index 5c224362708..f48774f7ad8 100644
--- a/lisp/emacs-lisp/derived.el
+++ b/lisp/emacs-lisp/derived.el
@@ -211,10 +211,10 @@ define-derived-mode
        (defvar ,hook nil)
        (unless (get ',hook 'variable-documentation)
          (put ',hook 'variable-documentation
-              ,(format "Hook run after entering %s mode.
+              ,(format "Hook run after entering `%S'.
 No problems result if this variable is not bound.
 `add-hook' automatically binds it.  (This is true for all hook variables.)"
-                       name)))
+                       child)))
        (unless (boundp ',map)
 	 (put ',map 'definition-name ',child))
        (with-no-warnings (defvar ,map (make-sparse-keymap)))

bug#68600: 30.0.50; Bad mode hook docstring when mode-line constructs are present in the mode-name

[Phil Sainty]

On 2024-01-21 04:47, Stefan Monnier wrote:
> The patch below solves the problem in a different way.

For my example, it gives us a cross-linked
"Hook run after entering ‘example-lisp-mode’."

I think that's a good solution.


-Phil

bug#68600: 30.0.50; Bad mode hook docstring when mode-line constructs are present in the mode-name

[Phil Sainty]

> "Hook run after entering ‘example-lisp-mode’."

This is also consistent with the minor mode hook docstring code,
which is doing this:

          (put ',hook 'variable-documentation
               ,(format "Hook run after entering or leaving `%s'.
No problems result if this variable is not bound.
`add-hook' automatically binds it.  (This is true for all hook 
variables.)"
                        modefun))


The sole difference being %S vs %s -- I figure that should be
consistent one way or the other?

bug#68600: 30.0.50; Bad mode hook docstring when mode-line constructs are present in the mode-name

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

>> "Hook run after entering ‘example-lisp-mode’."
> This is also consistent with the minor mode hook docstring code,

Thanks, pushed, closing.

> The sole difference being %S vs %s -- I figure that should be
> consistent one way or the other?

%s is for use to include the contents of a string.  In the current case
we're including a symbol.  For symbols %s and %S behave identically,
tho, so it doesn't matter very much.  I do think %S is the better option
(e.g. it will make it clear if/when the arg is a string rather than
a symbol, for example, since it will put "..." around the contents), but
it's not important enough to go and change the `easy-mmode.el` code.


        Stefan