Re: Generality of defvar

[thibaut . verron]

On 28/07/2022 09:34, Christopher Dimech <dimech@gmx.com> wrote:
> *Sent:* Thursday, July 28, 2022 at 7:06 PM
> *From:* "Thibaut Verron" <thibaut.verron@gmail.com>
> *To:* "Christopher Dimech" <dimech@gmx.com>
> *Cc:* carlmarcos@tutanota.com, "Emanuel Berg" <incal@dataswamp.org>, 
> "help-gnu-emacs" <help-gnu-emacs@gnu.org>
> *Subject:* Re: Generality of defvar
> Le jeu. 28 juil. 2022 à 08:42, Christopher Dimech <dimech@gmx.com 
> <mailto:dimech@gmx.com>> a écrit :
>
>     *Sent:* Thursday, July 28, 2022 at 4:39 AM
>     *From:* "Thibaut Verron" <thibaut.verron@gmail.com
>     <mailto:thibaut.verron@gmail.com>>
>     *To:* "Christopher Dimech" <dimech@gmx.com <mailto:dimech@gmx.com>>
>     *Cc:* carlmarcos@tutanota.com <mailto:carlmarcos@tutanota.com>,
>     "Emanuel Berg" <incal@dataswamp.org <mailto:incal@dataswamp.org>>,
>     "help-gnu-emacs" <help-gnu-emacs@gnu.org
>     <mailto:help-gnu-emacs@gnu.org>>
>     *Subject:* Re: Generality of defvar
>     Le mer. 27 juil. 2022 à 18:29, Christopher Dimech <dimech@gmx.com
>     <mailto:dimech@gmx.com>> a écrit :
>
>
>
>          > Sent: Thursday, July 28, 2022 at 1:47 AM
>          > From: "Thibaut Verron" <thibaut.verron@gmail.com
>         <mailto:thibaut.verron@gmail.com>>
>          > To: carlmarcos@tutanota.com <mailto:carlmarcos@tutanota.com>
>          > Cc: "Emanuel Berg" <incal@dataswamp.org
>         <mailto:incal@dataswamp.org>>, "help-gnu-emacs"
>         <help-gnu-emacs@gnu.org <mailto:help-gnu-emacs@gnu.org>>
>          > Subject: Re: Generality of defvar
>          >
>          > Le mer. 27 juil. 2022 à 15:24, <carlmarcos@tutanota.com
>         <mailto:carlmarcos@tutanota.com>> a écrit :
>          >
>          > >
>          > > Jul 27, 2022, 13:21 by thibaut.verron@gmail.com
>         <mailto:thibaut.verron@gmail.com>:
>          > >
>          > > > Le mer. 27 juil. 2022 à 14:52, carlmarcos--- via Users
>         list for the GNU
>          > > Emacs text editor <> help-gnu-emacs@gnu.org
>         <mailto:help-gnu-emacs@gnu.org>> > a écrit :
>          > > >
>          > > >>
>          > > >>
>          > > >>  Jul 27, 2022, 12:34 by >> incal@dataswamp.org
>         <mailto:incal@dataswamp.org>>> :
>          > > >>
>          > > >>  > carlmarcos--- via Users list for the GNU Emacs text
>         editor wrote:
>          > > >>  >
>          > > >>  >> (defun enable-error-diagnostics ()
>          > > >>  >>  "Enable error diagnostics with backtrace buffer.
>          > > >>  >> One can exit the debugger with the q command."
>          > > >>  >>
>          > > >>  >
>          > > >>  > You can refer to keys in docstrings like this:
>          > > >>  >
>          > > >>  >  \\[forward-word]
>          > > >>  >
>          > > >>  > That way, it isn't hardcoded so if later
>         changed/configured
>          > > >>  > it'll still show the right key.
>          > > >>  >
>          > > >>  How can I figure out what key to use in the docstring
>         for exiting the
>          > > backtrace buffer?
>          > > >>
>          > > >
>          > > > The function bound to 'q' is quit-window. But since this
>         function
>          > > doesn't have a global binding, you need to tell the
>         docstring to use the
>          > > appropriate keymap to look the binding up.
>          > > >
>          > > > Something like
>          > > >
>          > > >   "Enable error diagnostics with backtrace buffer.
>          > > >
>          > > > \\<backtrace-mode-map> (note: this is the part telling
>         emacs where to
>          > > look for the key)
>          > > > One can exit the debugger with the `quit-window' command
>         (bound to
>          > > \\[quit-window])."
>          > > >
>          > > >
>          > > Although quit-window is bound to q, the command
>         \\[quit-window] just
>          > > inserts
>          > > M-x quit-window, rather than q.
>          > >
>          >
>          > Yes, that's precisely because quit-window doesn't have a
>         global binding.
>          > You need to add \\<backtrace-mode-map> somewhere in the
>         docstring to tell
>          > emacs to show bindings for the backtrace buffers, rather than
>         global
>          > bindings.
>          >
>          > Best wishes,
>          > Thibaut
>
>         Sounds good advice, but the result could be
>
>         Uses keymap ‘backtrace-mode-map’, which is not currently defined.
>
>     My bad, it should have been debugger-mode-map.
>     Not quite right yet.
>
> I guess one should also put (require 'debug) at some point along with 
> the function definition?
> Seems more bother than it solves.  Cannot see how users would be able to 
> figure all this complication
> out.

For sure. But it's really a rare situation, and not one that is likely to hit 
first time users: one has to be writing a function with a docstring, and this 
docstring has to involve a key bound in a keymap defined in another file, and 
not loaded by default.

Even for users developing their own packages, usually the keymap will be 
defined in a file loaded at the same time as the function, completely hiding 
this subtlety.

Still, I would almost be tempted to consider this case a bug, and to expect 
that emacs should autoload debug.el to display the relevant information.

Thibaut