GNU bug report logs - #22813
24.5; doc string of `apropos-variable' - mention C-u

Previous Next

Package: emacs;

Reported by: Drew Adams <drew.adams <at> oracle.com>

Date: Fri, 26 Feb 2016 05:18:02 UTC

Severity: minor

Found in version 24.5

Done: Eli Zaretskii <eliz <at> gnu.org>

Bug is archived. No further changes may be made.

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

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

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to bug-gnu-emacs <at> gnu.org:
bug#22813; Package emacs. (Fri, 26 Feb 2016 05:18:02 GMT) Full text and rfc822 format available.

Acknowledgement sent to Drew Adams <drew.adams <at> oracle.com>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs <at> gnu.org. (Fri, 26 Feb 2016 05:18:02 GMT) Full text and rfc822 format available.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.5; doc string of `apropos-variable' - mention C-u
Date: Thu, 25 Feb 2016 21:17:30 -0800 (PST)
Subject line says it all.  The doc string says something
about Lisp argument DO-NOT-ALL, but it does not speak to an interactive
user, telling her that C-u gives that behavior.



In GNU Emacs 24.5.1 (i686-pc-mingw32)
 of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/usr --host=i686-pc-mingw32'




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#22813; Package emacs. (Fri, 26 Feb 2016 13:17:02 GMT) Full text and rfc822 format available.

Message #8 received at 22813 <at> debbugs.gnu.org (full text, mbox):

From: Kaushal Modi <kaushal.modi <at> gmail.com>
To: 22813 <at> debbugs.gnu.org
Subject: 24.5; doc string of `apropos-variable' - mention C-u
Date: Fri, 26 Feb 2016 08:15:27 -0500
[Message part 1 (text/plain, inline)]
In the emacs-25 branch, I see the doc-string for apropos-variable as:

"Show variables that match PATTERN.
When DO-NOT-ALL is non-nil, show user options only, i.e. behave
like `apropos-user-option'."

How about the below patch:

diff --git a/lisp/apropos.el b/lisp/apropos.el
index 3c1a413..fdd85b4 100644
--- a/lisp/apropos.el
+++ b/lisp/apropos.el
@@ -505,7 +505,7 @@ apropos-user-option
 ;;;###autoload
 (defun apropos-variable (pattern &optional do-not-all)
   "Show variables that match PATTERN.
-When DO-NOT-ALL is non-nil, show user options only, i.e. behave
+With prefix argument DO-NOT-ALL non-nil, show user options only, i.e.
behave
 like `apropos-user-option'."
   (interactive (list (apropos-read-pattern
       (if current-prefix-arg "user option" "variable"))


I simply added the term "prefix argument" (based on the doc-string of
quit-window).

--
Kaushal Modi
[Message part 2 (text/html, inline)]

Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#22813; Package emacs. (Fri, 26 Feb 2016 14:16:02 GMT) Full text and rfc822 format available.

Message #11 received at 22813 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Kaushal Modi <kaushal.modi <at> gmail.com>
Cc: 22813 <at> debbugs.gnu.org
Subject: Re: bug#22813: 24.5; doc string of `apropos-variable' - mention C-u
Date: Fri, 26 Feb 2016 16:14:54 +0200
> From: Kaushal Modi <kaushal.modi <at> gmail.com>
> Date: Fri, 26 Feb 2016 08:15:27 -0500
> 
> --- a/lisp/apropos.el
> +++ b/lisp/apropos.el
> @@ -505,7 +505,7 @@ apropos-user-option
>  ;;;###autoload
>  (defun apropos-variable (pattern &optional do-not-all)
>    "Show variables that match PATTERN.
> -When DO-NOT-ALL is non-nil, show user options only, i.e. behave
> +With prefix argument DO-NOT-ALL non-nil, show user options only, i.e. behave
>  like `apropos-user-option'."

Thanks.

However, this is not the best way of expressing the behavior wrt
prefix arguments.  Here's an example of how we do this elsewhere:

  (defun jump-to-register (register &optional delete)
    "Move point to location stored in a register.
  If the register contains a file name, find that file.
  \(To put a file name in a register, you must use `set-register'.)
  If the register contains a window configuration (one frame) or a frameset
  \(all frames), restore that frame or all frames accordingly.
  First argument is a character, naming the register.
  Optional second arg non-nil (interactively, prefix argument) says to
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  delete any existing frames that the frameset doesn't mention.
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#22813; Package emacs. (Fri, 26 Feb 2016 14:34:01 GMT) Full text and rfc822 format available.

Message #14 received at 22813 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Kaushal Modi <kaushal.modi <at> gmail.com>, 22813 <at> debbugs.gnu.org
Subject: RE: bug#22813: 24.5; doc string of `apropos-variable' - mention C-u
Date: Fri, 26 Feb 2016 06:33:20 -0800 (PST)
> How about the below patch:
> 
> -When DO-NOT-ALL is non-nil, show user options only, i.e. behave
> +With prefix argument DO-NOT-ALL non-nil, show user options only,

Conventionally we address doc strings for commands to an interactive user.

We say something like "With a prefix argument...", not mentioning it by
name as a parameter.  We may also (at the end) say something like
"When called from Lisp, DO-NOT-ALL..."  IOW, the interactive user
gets a coherent description that does not involve Lisp parameters
s?he need not bother with.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#22813; Package emacs. (Fri, 26 Feb 2016 14:41:02 GMT) Full text and rfc822 format available.

Message #17 received at 22813 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Kaushal Modi <kaushal.modi <at> gmail.com>, 22813 <at> debbugs.gnu.org
Subject: RE: bug#22813: 24.5; doc string of `apropos-variable' - mention C-u
Date: Fri, 26 Feb 2016 06:40:14 -0800 (PST)
> Conventionally we address doc strings for commands to an interactive
> user.
> 
> We say something like "With a prefix argument...", not mentioning it
> by
> name as a parameter.  We may also (at the end) say something like
> "When called from Lisp, DO-NOT-ALL..."  IOW, the interactive user
> gets a coherent description that does not involve Lisp parameters
> s?he need not bother with.

Eli's response was better than mine.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#22813; Package emacs. (Fri, 26 Feb 2016 14:54:02 GMT) Full text and rfc822 format available.

Message #20 received at 22813 <at> debbugs.gnu.org (full text, mbox):

From: Kaushal Modi <kaushal.modi <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 22813 <at> debbugs.gnu.org
Subject: Re: bug#22813: 24.5; doc string of `apropos-variable' - mention C-u
Date: Fri, 26 Feb 2016 09:52:34 -0500
[Message part 1 (text/plain, inline)]
I get the point now. How about this:

diff --git a/lisp/apropos.el b/lisp/apropos.el
index 3c1a413..a2bfee9 100644
--- a/lisp/apropos.el
+++ b/lisp/apropos.el
@@ -505,7 +505,8 @@ apropos-user-option
 ;;;###autoload
 (defun apropos-variable (pattern &optional do-not-all)
   "Show variables that match PATTERN.
-When DO-NOT-ALL is non-nil, show user options only, i.e. behave
+With the optional argument DO-NOT-ALL non-nil (or when called
interactively with
+the prefix \\[universal-argument]), show user options only, i.e. behave
 like `apropos-user-option'."
   (interactive (list (apropos-read-pattern
       (if current-prefix-arg "user option" "variable"))
[Message part 2 (text/html, inline)]

Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#22813; Package emacs. (Fri, 26 Feb 2016 15:43:01 GMT) Full text and rfc822 format available.

Message #23 received at 22813 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Kaushal Modi <kaushal.modi <at> gmail.com>
Cc: 22813 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#22813: 24.5; doc string of `apropos-variable' - mention C-u
Date: Fri, 26 Feb 2016 17:41:37 +0200
> From: Kaushal Modi <kaushal.modi <at> gmail.com>
> Date: Fri, 26 Feb 2016 09:52:34 -0500
> Cc: 22813 <at> debbugs.gnu.org
> 
> I get the point now. How about this:
> 
> diff --git a/lisp/apropos.el b/lisp/apropos.el
> index 3c1a413..a2bfee9 100644
> --- a/lisp/apropos.el
> +++ b/lisp/apropos.el
> @@ -505,7 +505,8 @@ apropos-user-option
>  ;;;###autoload
>  (defun apropos-variable (pattern &optional do-not-all)
>    "Show variables that match PATTERN.
> -When DO-NOT-ALL is non-nil, show user options only, i.e. behave
> +With the optional argument DO-NOT-ALL non-nil (or when called interactively with
> +the prefix \\[universal-argument]), show user options only, i.e. behave
>  like `apropos-user-option'."
>    (interactive (list (apropos-read-pattern
>        (if current-prefix-arg "user option" "variable"))

LGTM, thanks.  However, the line you changed is too long now, so
please reformat the doc string to have shorter lines, before you push.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#22813; Package emacs. (Fri, 26 Feb 2016 15:50:02 GMT) Full text and rfc822 format available.

Message #26 received at 22813 <at> debbugs.gnu.org (full text, mbox):

From: Kaushal Modi <kaushal.modi <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 22813 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#22813: 24.5; doc string of `apropos-variable' - mention C-u
Date: Fri, 26 Feb 2016 10:48:43 -0500
[Message part 1 (text/plain, inline)]
Thanks.

Can you commit it? I don't have push rights.

I would like to get commit right for next time :)
For now, here's the reformatted patch:

diff --git a/lisp/apropos.el b/lisp/apropos.el
index 3c1a413..eb145bd 100644
--- a/lisp/apropos.el
+++ b/lisp/apropos.el
@@ -505,8 +505,9 @@ apropos-user-option
 ;;;###autoload
 (defun apropos-variable (pattern &optional do-not-all)
   "Show variables that match PATTERN.
-When DO-NOT-ALL is non-nil, show user options only, i.e. behave
-like `apropos-user-option'."
+With the optional argument DO-NOT-ALL non-nil (or when called
+interactively with the prefix \\[universal-argument]), show user
+options only, i.e. behave like `apropos-user-option'."
   (interactive (list (apropos-read-pattern
       (if current-prefix-arg "user option" "variable"))
                      current-prefix-arg))

PS: I just did M-x fill-region on that doc-string.. I guess that's what
needed to be done.
[Message part 2 (text/html, inline)]

Reply sent to Eli Zaretskii <eliz <at> gnu.org>:
You have taken responsibility. (Fri, 26 Feb 2016 18:34:02 GMT) Full text and rfc822 format available.

Notification sent to Drew Adams <drew.adams <at> oracle.com>:
bug acknowledged by developer. (Fri, 26 Feb 2016 18:34:02 GMT) Full text and rfc822 format available.

Message #31 received at 22813-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Kaushal Modi <kaushal.modi <at> gmail.com>
Cc: 22813-done <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#22813: 24.5; doc string of `apropos-variable' - mention C-u
Date: Fri, 26 Feb 2016 20:33:04 +0200
> From: Kaushal Modi <kaushal.modi <at> gmail.com>
> Date: Fri, 26 Feb 2016 10:48:43 -0500
> Cc: Drew Adams <drew.adams <at> oracle.com>, 22813 <at> debbugs.gnu.org
> 
> 
> Can you commit it? I don't have push rights.

Done.




bug archived. Request was from Debbugs Internal Request <help-debbugs <at> gnu.org> to internal_control <at> debbugs.gnu.org. (Sat, 26 Mar 2016 11:24:03 GMT) Full text and rfc822 format available.

This bug report was last modified 9 years and 144 days ago.

Previous Next


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