Re: [drew.adams@oracle.com: RE: Customize doc strings and tagstrings do not respect \\<...> and \\[...]]

[Richard Stallman <rms@gnu.org>]

I don't remember any of the previous discussion after the lapse of a
whole year.

    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.

What did I say that about?

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

Not particularly, but how does that relate?

    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.

Is this the sort of output about which I said, "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."?

If so, I think that is true.  If the mode produces this output,
it's a bug, and because it is visible it will get fixed.

    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.

That seems like a good solution too, since it will also make the bug
visible.