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

[Stefan Monnier]

>> 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)))