bug#58493: [PATCH] * lisp/play/zone.el (zone): Allow selecting a program

bug#58493: [PATCH] * lisp/play/zone.el (zone): Allow selecting a program

[Philip Kaludercic]

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

Tags: patch


By default zone chooses a random program, but it seems to me that it
should be OK to allow choosing a specific effect.


In GNU Emacs 29.0.50 (build 5, x86_64-pc-linux-gnu, GTK+ Version
 3.24.34, cairo version 1.17.6) of 2022-10-13 built on rhea
Repository revision: 0b170c6caeeb669df3cf97c54c43da9cf77e6b42
Repository branch: master
System Description: Fedora Linux 36 (Workstation Edition)

Configured using:
 'configure --with-pgtk --with-imagemagick'


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-lisp-play-zone.el-zone-Allow-selecting-a-program.patch --]
[-- Type: text/patch, Size: 1870 bytes --]

From c122c2a921d0b06d7b49fa8231ab685faeb6169f Mon Sep 17 00:00:00 2001
From: Philip Kaludercic <philipk@posteo.net>
Date: Tue, 11 Oct 2022 12:28:45 +0200
Subject: [PATCH] * lisp/play/zone.el (zone): Allow selecting a program

---
 lisp/play/zone.el | 24 +++++++++++++++++++-----
 1 file changed, 19 insertions(+), 5 deletions(-)

diff --git a/lisp/play/zone.el b/lisp/play/zone.el
index b0ce0194cf..47fdbbec0a 100644
--- a/lisp/play/zone.el
+++ b/lisp/play/zone.el
@@ -103,9 +103,24 @@ zone-call
                  program))))
 
 ;;;###autoload
-(defun zone ()
-  "Zone out, completely."
-  (interactive)
+(defun zone (&optional pgm)
+  "Zone out, completely.
+The optional argument PGM should be an element of `zone-programs'
+or nil to have a random element chosen.  When invoked
+interactively with a prefix argument, the user is prompted for a
+program."
+  (interactive
+   (and current-prefix-arg
+        (let ((choice (completing-read
+                       "Program: "
+                       (mapcar
+                        (lambda (prog)
+                          (substring (symbol-name prog) 9))
+                        zone-programs)
+                       nil t)))
+          (list (intern (concat "zone-pgm-" choice))))))
+  (unless pgm
+    (setq pgm (aref zone-programs (random (length zone-programs)))))
   (save-window-excursion
     (let ((f (selected-frame))
           (outbuf (get-buffer-create "*zone*"))
@@ -125,8 +140,7 @@ zone
       (set-window-start (selected-window) (point-min))
       (set-window-point (selected-window) wp)
       (sit-for 0 500)
-      (let ((pgm (elt zone-programs (random (length zone-programs))))
-            (ct (and f (frame-parameter f 'cursor-type)))
+      (let ((ct (and f (frame-parameter f 'cursor-type)))
             (show-trailing-whitespace nil)
             restore)
         (when ct
-- 
2.37.3

bug#58493: [PATCH] * lisp/play/zone.el (zone): Allow selecting a program

[Stefan Kangas]

Philip Kaludercic <philipk@posteo.net> writes:

> By default zone chooses a random program, but it seems to me that it
> should be OK to allow choosing a specific effect.

LGTM (but I didn't test it).

bug#58493: [PATCH] * lisp/play/zone.el (zone): Allow selecting a program

[Eli Zaretskii]

> From: Philip Kaludercic <philipk@posteo.net>
> Date: Thu, 13 Oct 2022 13:37:12 +0000
> 
> +(defun zone (&optional pgm)
> +  "Zone out, completely.
> +The optional argument PGM should be an element of `zone-programs'
> +or nil to have a random element chosen.  When invoked
> +interactively with a prefix argument, the user is prompted for a
> +program."                             ^^^^^^^^^^^^^^^^^^^^^^^^^^

Passive tense alert!

bug#58493: [PATCH] * lisp/play/zone.el (zone): Allow selecting a program

[Philip Kaludercic]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Philip Kaludercic <philipk@posteo.net>
>> Date: Thu, 13 Oct 2022 13:37:12 +0000
>> 
>> +(defun zone (&optional pgm)
>> +  "Zone out, completely.
>> +The optional argument PGM should be an element of `zone-programs'
>> +or nil to have a random element chosen.  When invoked
>> +interactively with a prefix argument, the user is prompted for a
>> +program."                             ^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> Passive tense alert!

"... the command prompts the user for a program?"

bug#58493: [PATCH] * lisp/play/zone.el (zone): Allow selecting a program

[Eli Zaretskii]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: 58493@debbugs.gnu.org
> Date: Thu, 13 Oct 2022 17:14:54 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Philip Kaludercic <philipk@posteo.net>
> >> Date: Thu, 13 Oct 2022 13:37:12 +0000
> >> 
> >> +(defun zone (&optional pgm)
> >> +  "Zone out, completely.
> >> +The optional argument PGM should be an element of `zone-programs'
> >> +or nil to have a random element chosen.  When invoked
> >> +interactively with a prefix argument, the user is prompted for a
> >> +program."                             ^^^^^^^^^^^^^^^^^^^^^^^^^^
> >
> > Passive tense alert!
> 
> "... the command prompts the user for a program?"

Possible.  Or just "... prompt for the program to use."

bug#58493: [PATCH] * lisp/play/zone.el (zone): Allow selecting a program

[Philip Kaludercic]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Philip Kaludercic <philipk@posteo.net>
>> Cc: 58493@debbugs.gnu.org
>> Date: Thu, 13 Oct 2022 17:14:54 +0000
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> >> From: Philip Kaludercic <philipk@posteo.net>
>> >> Date: Thu, 13 Oct 2022 13:37:12 +0000
>> >> 
>> >> +(defun zone (&optional pgm)
>> >> +  "Zone out, completely.
>> >> +The optional argument PGM should be an element of `zone-programs'
>> >> +or nil to have a random element chosen.  When invoked
>> >> +interactively with a prefix argument, the user is prompted for a
>> >> +program."                             ^^^^^^^^^^^^^^^^^^^^^^^^^^
>> >
>> > Passive tense alert!
>> 
>> "... the command prompts the user for a program?"
>
> Possible.  Or just "... prompt for the program to use."

As always your suggestion is preferable.  Thanks!

bug#58493: [PATCH] * lisp/play/zone.el (zone): Allow selecting a program

[Stefan Kangas]

Philip Kaludercic <philipk@posteo.net> writes:

> Eli Zaretskii <eliz@gnu.org> writes:
>
>>> From: Philip Kaludercic <philipk@posteo.net>
>>> Date: Thu, 13 Oct 2022 13:37:12 +0000
>>>
>>> +(defun zone (&optional pgm)
>>> +  "Zone out, completely.
>>> +The optional argument PGM should be an element of `zone-programs'
>>> +or nil to have a random element chosen.  When invoked
>>> +interactively with a prefix argument, the user is prompted for a
>>> +program."                             ^^^^^^^^^^^^^^^^^^^^^^^^^^
>>
>> Passive tense alert!
>
> "... the command prompts the user for a program?"

I think we use the style

    "With a \\[universal-argument] prefix argument, prompt for a program."

I would personally put the interactive part first, and then say
explicitly:

    "When called from Lisp, ..."

This is a command, first and foremost, after all.

bug#58493: [PATCH] * lisp/play/zone.el (zone): Allow selecting a program

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Fri, 14 Oct 2022 11:22:00 +0200
> Cc: 58493@debbugs.gnu.org
> 
> > "... the command prompts the user for a program?"
> 
> I think we use the style
> 
>     "With a \\[universal-argument] prefix argument, prompt for a program."

No, we rarely if at all mention universal-argument explicitly in doc
strings.  The assumption is that the reader knows well enough how to
invoke commands with a prefix argument.

> I would personally put the interactive part first, and then say
> explicitly:
> 
>     "When called from Lisp, ..."
> 
> This is a command, first and foremost, after all.

That's a matter of personal preferences.  We have both styles in our
doc strings, and both are okay, from my POV.

bug#58493: [PATCH] * lisp/play/zone.el (zone): Allow selecting a program

[Philip Kaludercic]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Stefan Kangas <stefankangas@gmail.com>
>> Date: Fri, 14 Oct 2022 11:22:00 +0200
>> Cc: 58493@debbugs.gnu.org
>> 
>> > "... the command prompts the user for a program?"
>> 
>> I think we use the style
>> 
>>     "With a \\[universal-argument] prefix argument, prompt for a program."
>
> No, we rarely if at all mention universal-argument explicitly in doc
> strings.  The assumption is that the reader knows well enough how to
> invoke commands with a prefix argument.

FWIW it wouldn't be bad to do so.  When I first got into Emacs I was
using it for maybe 1 or 1 1/2 years before I understood what prefix
arguments are.  Really improved my experience when I found out :)

>> I would personally put the interactive part first, and then say
>> explicitly:
>> 
>>     "When called from Lisp, ..."
>> 
>> This is a command, first and foremost, after all.
>
> That's a matter of personal preferences.  We have both styles in our
> doc strings, and both are okay, from my POV.

I agree with Stefan that in this case mentioning the interactive case
first is more intuitive.

bug#58493: [PATCH] * lisp/play/zone.el (zone): Allow selecting a program

[Philip Kaludercic]

Philip Kaludercic <philipk@posteo.net> writes:

> Tags: patch
>
>
> By default zone chooses a random program, but it seems to me that it
> should be OK to allow choosing a specific effect.
>
>
> In GNU Emacs 29.0.50 (build 5, x86_64-pc-linux-gnu, GTK+ Version
>  3.24.34, cairo version 1.17.6) of 2022-10-13 built on rhea
> Repository revision: 0b170c6caeeb669df3cf97c54c43da9cf77e6b42
> Repository branch: master
> System Description: Fedora Linux 36 (Workstation Edition)
>
> Configured using:
>  'configure --with-pgtk --with-imagemagick'

The patch has been applies, so I'll close the report.