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

["Juanma Barranquero" <lekktu@gmail.com>]

On 2/16/07, Richard Stallman <rms@gnu.org> wrote:

> What did I say that about?

The case where "Blah blah \\<some-map>\\[some-command] more blah blah"
turns into

 Blah blah
 Uses keymap "some-map", which is not currently defined.
 more blah blah

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

Because I agree with you that if you load a package, and a docstring
from that package contains the above problem, it is a bug in the
package; but this problem often happens for autoloaded functions,
where not having the relevant mode-map at hand while consulting  a
docstring is quite normal. If you think that's an error in the package
(as opposed to an error in `describe-function', `describe-variable',
etc.), that would mean making sure that no autoloaded function ever
references a mode-map with \\<mode-map>

> 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."?

Yes.

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

`checkdoc-minor-mode' is autoloaded, so it's a case like the ones I
talk above. Either we make it not reference the mode-map, or we
implement something like the "prominent notice" scheme I'm suggesting.

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

Great.

             Juanma