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

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

[Richard Stallman]

Has anyone fixed this?

------- Start of forwarded message -------
From: "Drew Adams" <drew.adams@oracle.com>
To: "Emacs-Pretest-Bug" <emacs-pretest-bug@gnu.org>
Date: Sun, 19 Feb 2006 17:06:18 -0800
MIME-Version: 1.0
Content-Type: text/plain;
	charset="iso-8859-1"
In-Reply-To: <MEEKKIABFKKDFJMPIOEBAEEHCPAA.drew.adams@oracle.com>
Subject: RE: Customize doc strings and tag strings do not respect \\<...>
	and \\[...]

I should add that the same problem exists for :tag strings.

- --------

    emacs -q
    
    (defcustom foo nil
      "*Behavior of `\\<my-map>\\[my-cmd]' when foobaz is in the wind."
      :type 'boolean)
    
    Then, `C-h v foo' shows the doc string correctly as, say, "Behavior of
    `M-a' when foobaz is in the wind."  However, when you click the
    Customize link and get to the Customize buffer, the key bindings are
    not substituted in the doc string. You see this:
    
    Behavior of `\<my-map>\[my-cmd]' when foobaz is in the wind.
    
    Note that one level of backslash is removed.
    
    In GNU Emacs 22.0.50.1 (i386-mingw-nt5.1.2600)
     of 2005-06-26 on NONIQPC
    X server distributor `Microsoft Corp.', version 5.1.2600
    configured using `configure --with-gcc (3.3) --cflags 
    -I../../jpeg-6b-3/include -I../../libpng-1.2.8/include 
    -I../../tiff-3.6.1-2/include -I../../xpm-nox-4.2.0/include 
    -I../../zlib-1.2.2/include'


_______________________________________________
emacs-pretest-bug mailing list
emacs-pretest-bug@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-pretest-bug
------- End of forwarded message -------

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

[Chong Yidong]

>     emacs -q
>     
>     (defcustom foo nil
>       "*Behavior of `\\<my-map>\\[my-cmd]' when foobaz is in the wind."
>       :type 'boolean)
>     
>     Then, `C-h v foo' shows the doc string correctly as, say, "Behavior of
>     `M-a' when foobaz is in the wind."  However, when you click the
>     Customize link and get to the Customize buffer, the key bindings are
>     not substituted in the doc string. You see this:
>     
>     Behavior of `\<my-map>\[my-cmd]' when foobaz is in the wind.
>     
>     Note that one level of backslash is removed.

I can't reproduce this.  For example,

  M-x customize-option RET Info-enable-edit

displays the "\\<Info-mode-map>\\[Info-edit]" tag fine.

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

[Drew Adams]

    >     (defcustom foo nil
    >       "*Behavior of `\\<my-map>\\[my-cmd]' when ...."
    >       :type 'boolean)
    >
    >     when you get to the Customize buffer you see this:
    >     Behavior of `\<my-map>\[my-cmd]' when....
    >     Note that one level of backslash is removed.

    I can't reproduce this.  For example,

      M-x customize-option RET Info-enable-edit

    displays the "\\<Info-mode-map>\\[Info-edit]" tag fine.

1. I believe I must have been mistaken about the doc string. But the problem
definitely exists for :tag. Try this:

(defcustom bar nil "OK" :type 'boolean
  :tag "`\\<minibuffer-local-map>\\[next-history-element]'.")

and this:

(defcustom titi 'tata "OK" :type
 '(choice
   (const :tag "`\\<minibuffer-local-map>\\[next-history-element]'."
          tata)))

I see in Customize what I reported initially:
\<minibuffer-local-map>\[next-history-element] (one level of \ removed).


2. BTW, if I eval the defcustom I sent originally (quoted above), without
defining `my-map', then I get this in Customize, with a warning message
spliced into the middle of the key description:

 Behavior of ` Hide Rest
 Uses keymap "my-map", which is not currently defined.
 M-x my-cmd' when foobaz is in the wind.
 Parent groups: Nil

This appears to be another bug.

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

[Andreas Schwab]

"Drew Adams" <drew.adams@oracle.com> writes:

> 1. I believe I must have been mistaken about the doc string. But the problem
> definitely exists for :tag. Try this:
>
> (defcustom bar nil "OK" :type 'boolean
>   :tag "`\\<minibuffer-local-map>\\[next-history-element]'.")
>
> and this:
>
> (defcustom titi 'tata "OK" :type
>  '(choice
>    (const :tag "`\\<minibuffer-local-map>\\[next-history-element]'."
>           tata)))
>
> I see in Customize what I reported initially:
> \<minibuffer-local-map>\[next-history-element] (one level of \ removed).

Why do you think this is a bug?  The tag contains exactly this text.

> 2. BTW, if I eval the defcustom I sent originally (quoted above), without
> defining `my-map', then I get this in Customize, with a warning message
> spliced into the middle of the key description:
>
>  Behavior of ` Hide Rest
>  Uses keymap "my-map", which is not currently defined.
>  M-x my-cmd' when foobaz is in the wind.
>  Parent groups: Nil
>
> This appears to be another bug.

No.  This is the correct rendition of \<my-map> when my-map is not
defined.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
PGP key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[Drew Adams]

    > (defcustom titi 'tata "OK" :type
    >  '(choice
    >    (const :tag "`\\<minibuffer-local-map>\\[next-history-element]'."
    >           tata)))
    > I see in Customize what I reported initially:
    > \<minibuffer-local-map>\[next-history-element] (one level of
    > \ removed).

    Why do you think this is a bug?  The tag contains exactly this text.

What are you saying?

The point (the bug) is that the tag text should implicitly have
`substitute-command-keys' applied to it. I made that clear in my initial
report. A :tag string should be treated, in this respect, the same way a doc
string is treated.

Use case: You have a choice between two values for an option. Each controls
the behavior of `next-history-element' in a different way. You want to be
able to use `\\<minibuffer-local-map>\\[next-history-element]' in the :tag's
to refer to the command binding. You don't want to hard-code the binding in
the :tag string.

    > 2. BTW, if I eval the defcustom I sent originally (quoted
    > above), without
    > defining `my-map', then I get this in Customize, with a
    > warning message
    > spliced into the middle of the key description:
    >
    >  Behavior of ` Hide Rest
    >  Uses keymap "my-map", which is not currently defined.
    >  M-x my-cmd' when foobaz is in the wind.
    >  Parent groups: Nil
    >
    > This appears to be another bug.

    No.  This is the correct rendition of \<my-map> when my-map is not
    defined.

If one defines "correct rendition" by whatever the program does currently,
then of course there can be no bug. "Circulez, il n'y a rien a voir!"

Does that "rendition" look correct to you? Splicing in the error message in
place of the \\<...>?  With a button ("Hide Rest") inside the string `...'
along with the message?  Do you think this is the best way to present such a
message? Not to mention that (presumably) part of the message is missing
(just what is it that "uses keymap..."?).

I cannot believe that someone would look at that Custom buffer and say that
there is no bug, that this is what we should present to users. The UI should
not compound the problem of an undefined map by making a mess of things. It
is not the user's fault that the map is undefined; the UI should aid the
user as best it can, not throw up at him.

These might not be earth-shaking bugs, but that is no reason to close them
cavalierly, with an attitude that the program does what it does. Put them on
the back burner if you don't think they are important or don't want to work
on them, but please don't take the attitude that whatever is is right.

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

[Andreas Schwab]

"Drew Adams" <drew.adams@oracle.com> writes:

>     > (defcustom titi 'tata "OK" :type
>     >  '(choice
>     >    (const :tag "`\\<minibuffer-local-map>\\[next-history-element]'."
>     >           tata)))
>     > I see in Customize what I reported initially:
>     > \<minibuffer-local-map>\[next-history-element] (one level of
>     > \ removed).
>
>     Why do you think this is a bug?  The tag contains exactly this text.
>
> What are you saying?
>
> The point (the bug) is that the tag text should implicitly have
> `substitute-command-keys' applied to it.

The connection between doc strings and widget tags is not immediately
apparent, but of course this could be added as a new feature.  But note
that this would change the rendition of existing :tag strings since
certain construct in the text would have to be quoted now.  Current only
doc strings are filtered through substitute-command-keys (via
documentation-property).

>     No.  This is the correct rendition of \<my-map> when my-map is not
>     defined.
>
> If one defines "correct rendition" by whatever the program does currently,
> then of course there can be no bug. "Circulez, il n'y a rien a voir!"

That's how substitute-command-keys has always been working, and it is not
a useless feature.  It helps to interpret subsequent renditions of \[...]
(the commands might be bound in a different key map that is current at
this point).

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
PGP key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[Andreas Schwab]

"Drew Adams" <drew.adams@oracle.com> writes:

> Use case: You have a choice between two values for an option. Each controls
> the behavior of `next-history-element' in a different way. You want to be
> able to use `\\<minibuffer-local-map>\\[next-history-element]' in the :tag's
> to refer to the command binding. You don't want to hard-code the binding in
> the :tag string.

You can create your own format handler that handles a new % format that
does the substitute-command-keys on the :tag text.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
PGP key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[Drew Adams]

    > The point (the bug) is that the tag text should implicitly have
    > `substitute-command-keys' applied to it.

    The connection between doc strings and widget tags is not immediately
    apparent, but of course this could be added as a new feature.

Who is to say whether the current design includes this, so that the
implementation is bugged, or the design does not include this, so that this
represents a new feature? I can't speak for the designers, but as a user, it
seems pretty obvious to me that this is the way :tag strings should work.
When I see that they don't, I report it as a bug, but the designers are free
to say "That's the way it is supposed to work", to which I would reply,
"Please change the design to add this useful feature."

    But note that this would change the rendition of existing :tag strings
since
    certain construct in the text would have to be quoted now.

What constructs are those? How would they have to be quoted? I'm not aware
of ever having to quote anything in a doc string? Just what is the
limitation that `substitute-command-keys' imposes? What is an example of an
existing :tag string that would be negatively impacted?

If a programmer wanted the behavior we get currently, then s?he would be out
of luck. I don't know of a way to "quote" things to protect against
`substitute-command-keys', however.

    Current only
    doc strings are filtered through substitute-command-keys (via
    documentation-property).

    >     No.  This is the correct rendition of \<my-map> when my-map is not
    >     defined.
    >
    > If one defines "correct rendition" by whatever the program
    does currently,
    > then of course there can be no bug. "Circulez, il n'y a rien a voir!"

    That's how substitute-command-keys has always been working, and
    it is not a useless feature.

I didn't say anything to the contrary. That feature is useful, as is, for
`substitute-command-keys'. But raw `substitute-command-keys' with that
feature is not appropriate for this context.

The point is that this is not just `substitute-command-keys'; it is use of
that function in a particular context. You are arguing that the
implementation does what it does. I am saying that the implementation
doesn't do the right thing - it's not enough to just use
`substitute-command-keys' with no thought to the context. An error message
like this should be handled more gracefully for the user.

    It helps to interpret subsequent renditions of \[...]
    (the commands might be bound in a different key map that is current at
    this point).

I have nothing against the reporting of the warning. The point is that when
a function passes up an indication of an error condition to its caller, it
is up to the calling function to DTRT with that info, not necessarily just
dump it to the screen. In this case, it would be enough to 1) insert the
original text (so that the error message becomes intelligible, instead of
appearing to be missing a part), 2) insert the error message _after_ the
buttons and original text. IOW, if the garbling of the message and original
text and splicing around the button were fixed, things would be fine.

Admittedly, this is a minor, cosmetic bug. The bug originally reported (need
to apply `substitute-command-keys' to :tag text) is more important, as it
affects fairly important functionality (IMO).

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

[Andreas Schwab]

"Drew Adams" <drew.adams@oracle.com> writes:

> What constructs are those? How would they have to be quoted?

Read the doc string of substitute-command-keys.

> An error message like this should be handled more gracefully for the
> user.

It's not an error message.  It is not an error to use \<...> or \{...} in
a doc string when the referenced keymap may be undefined (think of
autoloading).

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
PGP key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[Richard Stallman]

	>  Behavior of ` Hide Rest
	>  Uses keymap "my-map", which is not currently defined.
	>  M-x my-cmd' when foobaz is in the wind.
	>  Parent groups: Nil

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.

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.

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

[Richard Stallman]

    The connection between doc strings and widget tags is not immediately
    apparent, but of course this could be added as a new feature.  But note
    that this would change the rendition of existing :tag strings since
    certain construct in the text would have to be quoted now.

Theoretically that is true, but I would expect those cases never occur
in practice.  Would you like to look and see if there is even one such
case in Emacs?

I think that we should do substitute-command-keys on tag strings,
that that is obviously right, and not doing it is obviously wrong.

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

[Andreas Schwab]

Richard Stallman <rms@gnu.org> writes:

> Theoretically that is true, but I would expect those cases never occur
> in practice.  Would you like to look and see if there is even one such
> case in Emacs?

Currently there is none.

> I think that we should do substitute-command-keys on tag strings,
> that that is obviously right, and not doing it is obviously wrong.

I'd rather introduce a new format character that is like %t but filters
through substitute-command-keys.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
PGP key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[Richard Stallman]

    > I think that we should do substitute-command-keys on tag strings,
    > that that is obviously right, and not doing it is obviously wrong.

    I'd rather introduce a new format character that is like %t but filters
    through substitute-command-keys.

That is ok with me.

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

[Kevin Rodgers]

Drew Adams wrote:
 >     > (defcustom titi 'tata "OK" :type
 >     >  '(choice
 >     >    (const :tag 
"`\\<minibuffer-local-map>\\[next-history-element]'."
 >     >           tata)))
 >     > I see in Customize what I reported initially:
 >     > \<minibuffer-local-map>\[next-history-element] (one level of
 >     > \ removed).
 >
 >     Why do you think this is a bug?  The tag contains exactly this text.
 >
 > What are you saying?
 >
 > The point (the bug) is that the tag text should implicitly have
 > `substitute-command-keys' applied to it. I made that clear in my initial
 > report. A :tag string should be treated, in this respect, the same 
way a doc
 > string is treated.

That is an interesting idea.  But there's nothing in the Emacs Lisp or
Widget manuals to suggest that the current implementation is broken.

 > Use case: You have a choice between two values for an option. Each 
controls
 > the behavior of `next-history-element' in a different way. You want to be
 > able to use `\\<minibuffer-local-map>\\[next-history-element]' in the 
:tag's
 > to refer to the command binding. You don't want to hard-code the 
binding in
 > the :tag string.

`(choice
   (const :tag ,(substitute-command-keys
                 "`\\<minibuffer-local-map>\\[next-history-element]'.")
          tata)))

-- 
Kevin Rodgers

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

[Drew Adams]

     > The point (the bug) is that the tag text should implicitly have
     > `substitute-command-keys' applied to it. I made that clear
     > in my initial report. A :tag string should be treated, in this
     > respect, the same way a doc string is treated.

    That is an interesting idea.  But there's nothing in the Emacs Lisp or
    Widget manuals to suggest that the current implementation is broken.

Right. The manuals are silent on this, AFAICT. Call it a new feature request
if you like.

    `(choice
       (const :tag ,(substitute-command-keys
                     "`\\<minibuffer-local-map>\\[next-history-element]'.")
              tata)))

Sure, that's OK too. But why not have it done implicitly?

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

[Per Abrahamsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> Right. The manuals are silent on this, AFAICT. Call it a new feature request
> if you like.
>
>     `(choice
>        (const :tag ,(substitute-command-keys
>                      "`\\<minibuffer-local-map>\\[next-history-element]'.")
>               tata)))
>
> Sure, that's OK too. But why not have it done implicitly?

Would you like 'message' to do an implicit substitute-command-keys as
well?

It is not a rhetorical question.

It doesn't seem intuitive to me that the value of :tag should be
considered a documentation string.

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

[Drew Adams]

    > Sure, that's OK too. But why not have it done implicitly?

    Would you like 'message' to do an implicit substitute-command-keys as
    well?

No.

    It is not a rhetorical question.

It's a good question.

    It doesn't seem intuitive to me that the value of :tag should be
    considered a documentation string.

Fair enough. It seemed natural to me, but I see your point. I guess I was
thinking of :tag strings the way I think of doc strings, since the role is
somewhat similar. Doc strings are generally not evaluated, however, so there
is no choice wrt them: substitute-command-keys must be built-in.

One difference between :tag and `message' is that you have to jump through a
few extra hoops to use substitute-command-keys with :tag (backquoting etc.).
Granted, that is only a minor difference.

I guess I'd say that things are OK as is. Perhaps we should just make sure
that the doc says that :tag values are evaluated (I imagine it does already
say that).

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

[Richard Stallman]

	It doesn't seem intuitive to me that the value of :tag should be
	considered a documentation string.

Didn't someone define a different keyword which is like :tag
but goes through substitute-command-keys?

Re: [drew.adams@oracle.com: 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

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

[Richard Stallman]

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.

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

[Juanma Barranquero]

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

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

[Richard Stallman]

    `checkdoc-minor-mode' is autoloaded, so it's a case like the ones I
    talk above.

Why does it matter whether `checkdoc-minor-mode' is autoloaded?

Oh, now I see why: because Emacs knows the doc string initially,
even though the command has ever been run.

This leads me to reconsider part of my previous conclusion.  It is
useful for modes to show their keymaps, and it is useful to autoload
modes.  Would be rather inconvenient to insist on preloading all files
that define modes that show their keymaps.

Therefore, the case of an autoload mode's doc string that refers to
the not-yet-loaded keymap is legitimate, so it ought to produce
nice-looking output.  So now I agree a change is called for -- similar
to the one you proposed, but with slightly different details.

I think a good solution would be to make \\<some-mode-map> generate
something friendly but clear, such as a note at the end rather than at
the beginning, saying that the keymap couldn't be displayed because
it isn't loaded yet.

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

[Juanma Barranquero]

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

> Oh, now I see why: because Emacs knows the doc string initially,
> even though the command has ever been run.

Yes.

> Therefore, the case of an autoload mode's doc string that refers to
> the not-yet-loaded keymap is legitimate, so it ought to produce
> nice-looking output.

Agreed. In fact, cases like `checkdoc-minor-mode' were what prompted
me to comment in this thread.

> I think a good solution would be to make \\<some-mode-map> generate
> something friendly but clear, such as a note at the end rather than at
> the beginning, saying that the keymap couldn't be displayed because
> it isn't loaded yet.

Fine by me.

             Juanma