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.