GNU bug report logs - #3936
23.0.96; doc string of called-interactively-p

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 3936 in the body.
You can then email your comments to 3936 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <emacs-pretest-bug <at> gnu.org>
Subject: 23.0.96; doc string of called-interactively-p
Date: Sun, 26 Jul 2009 13:56:22 -0700

Doc string:
 
"Return t if the function using this was called with
`call-interactively'."
 
The function using this? Using what?
This sentence doesn't make sense.
 

In GNU Emacs 23.0.96.1 (i386-mingw-nt5.1.2600)
 of 2009-07-09 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4)'
 

Message #10 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Bastien <bastienguerry <at> googlemail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 3936 <at> debbugs.gnu.org, <emacs-pretest-bug <at> gnu.org>
Subject: Re: bug#3936: 23.0.96; doc string of called-interactively-p
Date: Mon, 27 Jul 2009 10:03:17 +0800

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

> "Return t if the function using this was called with
> `call-interactively'."

I replaced this by :

  Return t if it is in a function called with `call-interactively'.

Thanks,

-- 
 Bastien

Message #20 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Bastien'" <bastienguerry <at> googlemail.com>
Cc: <3936 <at> debbugs.gnu.org>, <emacs-pretest-bug <at> gnu.org>
Subject: RE: bug#3936: 23.0.96; doc string of called-interactively-p
Date: Sun, 26 Jul 2009 23:24:03 -0700

> > "Return t if the function using this was called with
> > `call-interactively'."
> 
> I replaced this by :
> 
>   Return t if it is in a function called with `call-interactively'.

That's just as bad. What's "it"?

I really don't understand what you are trying to say. When does
`called-interactively-p' return t? It should be possible to describe that
condition. What does the code say?

Message #30 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Bastien <bastienguerry <at> googlemail.com>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: <3936 <at> debbugs.gnu.org>, <emacs-pretest-bug <at> gnu.org>
Subject: Re: bug#3936: 23.0.96; doc string of called-interactively-p
Date: Mon, 27 Jul 2009 14:43:36 +0800

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

>> > "Return t if the function using this was called with
>> > `call-interactively'."
>> 
>> I replaced this by :
>> 
>>   Return t if it is in a function called with `call-interactively'.
>
> That's just as bad. 

Thanks. :)

> What's "it"?

Usually "it" in a docstring refers to the function/variable the
docstring is documenting.  At least this is how I understand it.

> I really don't understand what you are trying to say. 

Are you sure?  Even the name of this function is very explicit:
"call-interactively-p", and I bet you know what it does - so it
shouldn't be hard to guess what the docstring is trying to say.

> When does `called-interactively-p' return t?

When the function in which (call-interactively-p) is has been
interactively called with (call-interactively ...)

> It should be possible to describe that
> condition. What does the code say?

Please suggest something better - with this small annoying constraints
that the first line has to be quite short.

-- 
 Bastien

Message #40 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Bastien'" <bastienguerry <at> googlemail.com>
Cc: <3936 <at> debbugs.gnu.org>, <emacs-pretest-bug <at> gnu.org>
Subject: RE: bug#3936: 23.0.96; doc string of called-interactively-p
Date: Mon, 27 Jul 2009 01:18:45 -0700

> > I really don't understand what you are trying to say. 
> 
> Are you sure?  Even the name of this function is very explicit:
> "call-interactively-p", and I bet you know what it does - so it
> shouldn't be hard to guess what the docstring is trying to say.

(`called-interactively-p', not `call-interactively-p'.) And no, I don't know
exactly what it does - its C code is hard for me to follow.

Here is what the doc string of `interactive-p' said, back in Emacs 20-21:

"Return t if function in which this appears was called interactively."

That's a little clearer, though it too speaks of "this". To me, "in which this
appears" is clearer than "using this".

> > When does `called-interactively-p' return t?
> 
> When the function in which (call-interactively-p) is has been
> interactively called with (call-interactively ...)

"_interactively_ called with (call-interactively...)" Is it a joke? How about
just "called using `call-interactively'"?

> > It should be possible to describe that
> > condition. What does the code say?
> 
> Please suggest something better - with this small annoying constraints
> that the first line has to be quite short.

The first line has to be short. The rest doesn't have to be short. See what was
said before for `interactive-p' - it's not too bad.  

In particular, the doc strings of `called-interactively-p' and `interactive-p'
should, together, make clear their difference. They can't both just say that
they test for an interactive call. They need to speak about keyboard macro use
as the difference in behavior.

See also bug #3941, preferably before fixing this doc string. The doc of both of
these functions is a mess in general, IMO.

Message #50 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Bastien <bastienguerry <at> googlemail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 3936 <at> debbugs.gnu.org, emacs-pretest-bug <at> gnu.org
Subject: Re: bug#3936: 23.0.96; doc string of called-interactively-p
Date: Mon, 27 Jul 2009 17:17:32 +0800

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

> In particular, the doc strings of `called-interactively-p' and `interactive-p'
> should, together, make clear their difference. They can't both just say that
> they test for an interactive call. They need to speak about keyboard macro use
> as the difference in behavior.

Please suggest a docstring for both these functions.

If your suggested dosctrings are clearer, we will clearly see it.

By trying to explain in a very wordy fashion what is *not* clear to you,
you're at risk of not being clear yourself.

Thanks,

-- 
 Bastien

Message #60 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Bastien'" <bastienguerry <at> googlemail.com>
Cc: <3936 <at> debbugs.gnu.org>, <emacs-pretest-bug <at> gnu.org>
Subject: RE: bug#3936: 23.0.96; doc string of called-interactively-p
Date: Mon, 27 Jul 2009 09:04:17 -0700

> > In particular, the doc strings of `called-interactively-p' 
> > and `interactive-p' should, together, make clear their
> > difference. They can't both just say that they test for
> > an interactive call. They need to speak about keyboard
> > macro use as the difference in behavior.
> 
> Please suggest a docstring for both these functions.
> If your suggested dosctrings are clearer, we will clearly see it.
> 
> By trying to explain in a very wordy fashion what is *not* 
> clear to you, you're at risk of not being clear yourself.

I think I was clear enough. Fix the Elisp manual first; the doc strings will
follow easily. If you don't understand what I wrote or are unwilling to work on
it, perhaps someone else will.

The doc is not just unclear; it is wrong/bad, as I pointed out specifically.

In addition to the doc problems I listed, there is a non-doc problem: Whoever
came up with the new function (in Emacs 22) `called-interactively-p' did the
wrong thing, IMO.

That function name tells nothing more nor less than the name `interactive-p' -
there is nothing in the names that distinguishes these functions. Might as well
have named the new function `interactive-p-2' (no, it's not a suggestion).

It would have been far better to add an optional argument to `interactive-p'
than to create a new, similarly named function. For example:

(defun interactive-p (&optional k-macro-p)
  "Return t if function in which this appears was called interactively.
If optional arg K-MACRO-P is non-nil, return t when called during
execution of a keyboard macro. If it is nil, return nil in that case.
...[rest of description]"

I vote for deprecating one or the other of these two functions, combining them
by using an optional argument to express the alternative behaviors. That will go
a long way toward clarifying the intended uses.

Message #70 received at 3936 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <emacs-pretest-bug <at> gnu.org>, <3936 <at> debbugs.gnu.org>
Subject: bug#3938: 23.0.96; regression: minibuffer-message interferes with C-u
Date: Sun, 2 Aug 2009 22:14:59 -0700

Taking off the "3938-done" address, I forgot to add back the original
recipients, so this would get to the bug list. So here it is again, with the bug
list added back as recipient.

[It is really a shame that once someone closes a bug you can no longer just
reply to the message; you have to reopen the bug and change the recipients... I
replied, and my reply was recorded as _me_ closing the bug. What a lame UI...
And of course none of that meta-conversation was added to the bug thread, except
for a bit by Stefan, who no doubt thought to add the bug list as recipient.]

Anyway...

-----Original Message-----
From: Drew Adams Sent: Sunday, August 02, 2009 10:07 PM
To: 'Chong Yidong'
Subject: RE: bug#3938: 23.0.96; regression: minibuffer-message interferes with
C-u

> 1. That kind of thing should not be necessary. Something has 
> become overly fragile or things have become overly coupled.
> 
> I'm not "hacking universal-argument this way" or in any way - 
> I don't redefine it. I just use a different binding for `C-u' 
> and a different keymap from `universal-argument-map'. (In the 
> bug report I show that even an exact copy of that map 
> demonstrates the bug, but in my real code I do use a slightly 
> different map.)
> 
> All my code does is change the behavior of `C-u' during 
> completion very slightly, so that the prefix arg is echoed in 
> the minibuffer using `minibuffer-message'. IOW, instead of 
> echoing "FOO" as in the bug report, it shows the prefix arg. 
> In Icicles, you can perform lots of operations during 
> completion, and you can use `C-u' with those operations.
> 
> That's true for vanilla Emacs too, but it's not as often that 
> users use `C-u' when editing minibuffer text. Because `C-u' 
> is used more during completion, Icicles shows the prefix value.
> 
> 
> 2. As I mentioned, the code for `sit-for' has not changed a 
> bit between Emacs 22 and 23 (and my code works in Emacs 
> 22-21-20). Something else must have changed. There should be 
> no need to replace any of the `sit-for' code. This should not 
> be happening. There should be no need for such jumping 
> through hoops and redefining multiple things.
> 
> I appreciate the workaround advice, and I'll look into it as 
> a temporary Emacs 23 workaround. But how about fixing this 
> regression? Interrupting `sit-for' with user input should 
> never cause the full `sit-for' delay to be waited out - 
> something is amiss. `sit-for' is not `sleep-for'.

In case it helps, below is what my code really does, so you can see that I am in
no way changing the code of `universal-argument' etc. In each case, I write and
use my own function and my own keymap. The code is nearly the same as the
original, with the only real change (and the purpose) being to add a minibuffer
message that echoes the prefix arg.

I hope this regression will be fixed. Thanks.

Here you have my complete use of this, so you can better understand. Each
function is identical to the original, except in the minor ways indicated:

;; Use my map for overriding terminal local.
;; Same as the definition of `ensure-overriding-map-is-bound',
;; except for using the different map.
(defun icicle-ensure-overriding-map-is-bound ()
  (unless overriding-map-is-bound
   (setq saved-overriding-map           overriding-terminal-local-map
         overriding-terminal-local-map  icicle-universal-argument-map
         overriding-map-is-bound        t)))

;; Bound to `C-<0-9>', `M-<0-9>', `C-M-<0-9>' in minibuffer.
(defun icicle-digit-argument (arg)
  "`digit-argument', but also echo the prefix arg."
  (interactive "P")
  (let* ((char   (if (integerp last-command-char)
                     last-command-char
                   (get last-command-char 'ascii-character)))
         (digit  (- (logand char ?\177) ?0)))
    (cond ((integerp arg)
           (setq prefix-arg  (+ (* arg 10) (if (< arg 0) (- digit) digit))))
          ((eq arg '-)
           ;; Treat -0 as just -, so that -01 will work.
           (setq prefix-arg  (if (zerop digit) '- (- digit))))
          (t
           (setq prefix-arg  digit))))
  (setq universal-argument-num-events  (length (this-command-keys)))
  (icicle-ensure-overriding-map-is-bound)
  (icicle-msg-maybe-in-minibuffer "prefix %S" prefix-arg))

;; Bound to `M--', `C-M--' in minibuffer.
(defun icicle-negative-argument (arg)
  "`negative-argument', but also echo the prefix arg."
  (interactive "P")
  (cond ((integerp arg) (setq prefix-arg  (- arg)))
        ((eq arg '-) (setq prefix-arg  nil))
        (t (setq prefix-arg  '-)))
  (setq universal-argument-num-events  (length (this-command-keys)))
  (icicle-ensure-overriding-map-is-bound)
  (icicle-msg-maybe-in-minibuffer "prefix %S" prefix-arg))

; Bound to `C-u' in minibuffer.
(defun icicle-universal-argument ()
  "`universal-argument', but also echo the prefix arg."
  (interactive)
  (setq prefix-arg                     (list 4)
        universal-argument-num-events  (length (this-command-keys)))
  (icicle-ensure-overriding-map-is-bound)
  (icicle-msg-maybe-in-minibuffer "prefix %S" prefix-arg))

(defun icicle-universal-argument-more (arg)
  "`universal-argument-more', but also echo the prefix arg."
  (interactive "P")
  (universal-argument-more arg)
  (icicle-msg-maybe-in-minibuffer "prefix %S" prefix-arg))

(defun icicle-universal-argument-other-key (arg)
  "`universal-argument-other-key', but also echo the prefix."
  (interactive "P")
  (universal-argument-other-key arg)
  (icicle-msg-maybe-in-minibuffer "prefix %S" prefix-arg))

(defun icicle-universal-argument-minus (arg)
  "`universal-argument-minus', but also echo the prefix arg."
  (interactive "P")
  (universal-argument-minus arg)
  (icicle-msg-maybe-in-minibuffer "prefix %S" prefix-arg))

(defun icicle-msg-maybe-in-minibuffer (format-string &rest args)
  "Display FORMAT-STRING as a message.
If called with the minibuffer inactive, use `message'.
Otherwise, use `minibuffer-message'."
  (if (active-minibuffer-window)
      (save-selected-window
        (select-window (minibuffer-window))
        (minibuffer-message
         (apply #'format (concat "  [" format-string "]") args)))
    (apply #'message format-string args)))

;; Same code as that defining `universal-argument-map',
;; but with the above corresponding functions substituted.
(defvar icicle-universal-argument-map
  (let ((map  (make-sparse-keymap)))
    (define-key map [t] 'icicle-universal-argument-other-key)
    (define-key map (vector meta-prefix-char t)
                    'icicle-universal-argument-other-key)
    (define-key map [switch-frame] nil)
    (define-key map [?\C-u] 'icicle-universal-argument-more)
    (define-key map [?-] 'icicle-universal-argument-minus)
    (define-key map [?0] 'icicle-digit-argument)
    (define-key map [?1] 'icicle-digit-argument)
    (define-key map [?2] 'icicle-digit-argument)
    (define-key map [?3] 'icicle-digit-argument)
    (define-key map [?4] 'icicle-digit-argument)
    (define-key map [?5] 'icicle-digit-argument)
    (define-key map [?6] 'icicle-digit-argument)
    (define-key map [?7] 'icicle-digit-argument)
    (define-key map [?8] 'icicle-digit-argument)
    (define-key map [?9] 'icicle-digit-argument)
    (define-key map [kp-0] 'icicle-digit-argument)
    (define-key map [kp-1] 'icicle-digit-argument)
    (define-key map [kp-2] 'icicle-digit-argument)
    (define-key map [kp-3] 'icicle-digit-argument)
    (define-key map [kp-4] 'icicle-digit-argument)
    (define-key map [kp-5] 'icicle-digit-argument)
    (define-key map [kp-6] 'icicle-digit-argument)
    (define-key map [kp-7] 'icicle-digit-argument)
    (define-key map [kp-8] 'icicle-digit-argument)
    (define-key map [kp-9] 'icicle-digit-argument)
    (define-key map [kp-subtract] 'icicle-universal-argument-minus)
    map)
  "Keymap used while processing `C-u' during Icicles completion.")

;; Use my `C-u' during completion (only).
(define-key minibuffer-local-completion-map
            (vector 'remap 'universal-argument) 'icicle-universal-argument)

Besides this, I think that your suggested workaround has no chance of solving
the problem. The problem cannot be in `sit-for', since that code has not changed
between Emacs 22 and 23. And this bug is a regression wrt Emacs 22 (and 21,
20...).

Thanks for taking another look.

Message #75 received at 3936-done <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Chong Yidong <cyd <at> stupidchicken.com>
To: 3936-done <at> debbugs.gnu.org
Subject: Re: 23.0.96; doc string of called-interactively-p
Date: Sat, 15 Aug 2009 17:53:07 -0400

I've checked in fixes for the doc strings of interactive-p and
called-interactively-p, which should make them clearer.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.