Re: address@hidden: RE: Customize doc strings and tagstrings do not respect \\<...> and \\[...]]

[Juanma Barranquero]

[From a thread almost a year ago about where Drew and Andreas
discussed (among other things) the behavior of
`substitute-command-keys' when it finds a keymap not currently
defined.]

Richard said:

> This could be the most useful behavior, since it provides a warning
> that the keymap is not defined at the place where you expected it to
> be.  Any clueful user will realize it means the mode has a bug
> and will report it, and then things will be fixed so they really work.

Do you consider using \\<some-mode-map> in the docstring of an
autoloaded function a bug in the mode?

> By contrast, if it did something else quieter, such as ignore the
> specification of the nonexistent map, it would give a result that is
> not what it ought to be but not so obviously wrong.  A user would have
> to be really on his toes to notice and report the bug.

True in theory, but the current behavior can be confusing for a
newbie. Witness checkdoc-minor-mode's docstring:

 Toggle Checkdoc minor mode, a mode for checking Lisp doc strings.
 With prefix arg, turn Checkdoc minor mode on iff arg is positive.

 In Checkdoc minor mode, the usual bindings for `eval-defun' which is
 bound to
 Uses keymap "checkdoc-minor-mode-map", which is not currently defined.
 M-x checkdoc-eval-defun and `checkdoc-eval-current-buffer' are
overridden to include
 checking of documentation strings.


 Uses keymap "checkdoc-minor-mode-map", which is not currently defined.

So, at least in the case of the output of `describe-function',
`describe-variable', etc. a better answer IMHO would be to detect
these cases, silently ignore them at the point where they happen, and
add a prominent notice somewhere (preferibly at the top):

 NOTE: This documentation references the keymap "checkdoc-minor-mode-map",
 which is not currently defined.  You can load the package `checkdoc'
 to fix the problem.

 Toggle Checkdoc minor mode, a mode for checking Lisp doc strings.
 With prefix arg, turn Checkdoc minor mode on iff arg is positive.

 In Checkdoc minor mode, the usual bindings for `eval-defun' which is
 bound to M-x checkdoc-eval-defun and `checkdoc-eval-current-buffer'
are overridden to include
 checking of documentation strings.

(The exact wording is irrelevant.)

This probably requires adding args to `substitute-command-keys', or
perhaps a new function, so I'm not suggesting any change right now, of
course.

            Juanma