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

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

[Drew Adams]

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'

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

[Kaushal Modi]

[-- Attachment #1: Type: text/plain, Size: 878 bytes --]

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

[-- Attachment #2: Type: text/html, Size: 1356 bytes --]

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

[Eli Zaretskii]

> From: Kaushal Modi <kaushal.modi@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.
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

[Drew Adams]

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

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

[Drew Adams]

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

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

[Kaushal Modi]

[-- Attachment #1: Type: text/plain, Size: 661 bytes --]

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"))

[-- Attachment #2: Type: text/html, Size: 1311 bytes --]

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

[Eli Zaretskii]

> From: Kaushal Modi <kaushal.modi@gmail.com>
> Date: Fri, 26 Feb 2016 09:52:34 -0500
> Cc: 22813@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.

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

[Kaushal Modi]

[-- Attachment #1: Type: text/plain, Size: 933 bytes --]

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.

[-- Attachment #2: Type: text/html, Size: 1350 bytes --]

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

[Eli Zaretskii]

> From: Kaushal Modi <kaushal.modi@gmail.com>
> Date: Fri, 26 Feb 2016 10:48:43 -0500
> Cc: Drew Adams <drew.adams@oracle.com>, 22813@debbugs.gnu.org
> 
> 
> Can you commit it? I don't have push rights.

Done.