[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: address@hidden: RE: Customize doc strings and tagstrings do not resp
From: |
Juanma Barranquero |
Subject: |
Re: address@hidden: RE: Customize doc strings and tagstrings do not respect \\<...> and \\[...]] |
Date: |
Thu, 15 Feb 2007 12:44:13 +0100 |
[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
- Re: address@hidden: RE: Customize doc strings and tagstrings do not respect \\<...> and \\[...]],
Juanma Barranquero <=