[PATCH] timer-list -> list-timers?

[PATCH] timer-list -> list-timers?

[Mark Oteiza]

Hi,

Why was this named timer-list?  While I understand there is a push to
keep everything always in its own "namespace", list-foo is its own
namespace, and is a useful one that collects special listings of
different things around emacs.

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 441fda5d82..af646ce40f 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1885,8 +1885,8 @@ Timers
 cause anything special to happen.
 @end defun
 
-@findex timer-list
-The @code{timer-list} command lists all the currently active timers.
+@findex list-timers
+The @code{list-timers} command lists all the currently active timers.
 There's only one command available in the buffer displayed: @kbd{c}
 (@code{timer-list-cancel}) that will cancel the timer on the line
 under point.
diff --git a/lisp/emacs-lisp/timer-list.el b/lisp/emacs-lisp/timer-list.el
index 44a315f980..69c6741983 100644
--- a/lisp/emacs-lisp/timer-list.el
+++ b/lisp/emacs-lisp/timer-list.el
@@ -25,7 +25,7 @@
 ;;; Code:
 
 ;;;###autoload
-(defun timer-list (&optional _ignore-auto _nonconfirm)
+(defun list-timers (&optional _ignore-auto _nonconfirm)
   "List all timers in a buffer."
   (interactive)
   (pop-to-buffer-same-window (get-buffer-create "*timer-list*"))
@@ -67,7 +67,7 @@ timer-list
   (goto-char (point-min)))
 ;; This command can be destructive if they don't know what they are
 ;; doing.  Kids, don't try this at home!
-;;;###autoload (put 'timer-list 'disabled "Beware: manually canceling timers can ruin your Emacs session.")
+;;;###autoload (put 'list-timers 'disabled "Beware: manually canceling timers can ruin your Emacs session.")
 
 (defvar timer-list-mode-map
   (let ((map (make-sparse-keymap)))
@@ -84,7 +84,7 @@ timer-list-mode
   (setq bidi-paragraph-direction 'left-to-right)
   (setq truncate-lines t)
   (buffer-disable-undo)
-  (setq-local revert-buffer-function 'timer-list)
+  (setq-local revert-buffer-function #'list-timers)
   (setq buffer-read-only t)
   (setq header-line-format
         (format "%4s %10s %8s %s"

Re: [PATCH] timer-list -> list-timers?

[raman]

Mark Oteiza <mvoteiza@udel.edu> writes:

1+ I've stumbled over this more than once in the last few months > Hi,
>
> Why was this named timer-list?  While I understand there is a push to
> keep everything always in its own "namespace", list-foo is its own
> namespace, and is a useful one that collects special listings of
> different things around emacs.
>
> diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
> index 441fda5d82..af646ce40f 100644
> --- a/doc/lispref/os.texi
> +++ b/doc/lispref/os.texi
> @@ -1885,8 +1885,8 @@ Timers
>  cause anything special to happen.
>  @end defun
>  
> -@findex timer-list
> -The @code{timer-list} command lists all the currently active timers.
> +@findex list-timers
> +The @code{list-timers} command lists all the currently active timers.
>  There's only one command available in the buffer displayed: @kbd{c}
>  (@code{timer-list-cancel}) that will cancel the timer on the line
>  under point.
> diff --git a/lisp/emacs-lisp/timer-list.el b/lisp/emacs-lisp/timer-list.el
> index 44a315f980..69c6741983 100644
> --- a/lisp/emacs-lisp/timer-list.el
> +++ b/lisp/emacs-lisp/timer-list.el
> @@ -25,7 +25,7 @@
>  ;;; Code:
>  
>  ;;;###autoload
> -(defun timer-list (&optional _ignore-auto _nonconfirm)
> +(defun list-timers (&optional _ignore-auto _nonconfirm)
>    "List all timers in a buffer."
>    (interactive)
>    (pop-to-buffer-same-window (get-buffer-create "*timer-list*"))
> @@ -67,7 +67,7 @@ timer-list
>    (goto-char (point-min)))
>  ;; This command can be destructive if they don't know what they are
>  ;; doing.  Kids, don't try this at home!
> -;;;###autoload (put 'timer-list 'disabled "Beware: manually canceling timers can ruin your Emacs session.")
> +;;;###autoload (put 'list-timers 'disabled "Beware: manually canceling timers can ruin your Emacs session.")
>  
>  (defvar timer-list-mode-map
>    (let ((map (make-sparse-keymap)))
> @@ -84,7 +84,7 @@ timer-list-mode
>    (setq bidi-paragraph-direction 'left-to-right)
>    (setq truncate-lines t)
>    (buffer-disable-undo)
> -  (setq-local revert-buffer-function 'timer-list)
> +  (setq-local revert-buffer-function #'list-timers)
>    (setq buffer-read-only t)
>    (setq header-line-format
>          (format "%4s %10s %8s %s"
>

-- 

Re: [PATCH] timer-list -> list-timers?

[Eli Zaretskii]

> From: Mark Oteiza <mvoteiza@udel.edu>
> Date: Sat, 16 Sep 2017 11:11:00 -0400
> 
> Why was this named timer-list?

Lars?

> While I understand there is a push to keep everything always in its
> own "namespace", list-foo is its own namespace, and is a useful one
> that collects special listings of different things around emacs.

I'm okay with renaming it, but if we do so, we should also patch NEWS,
which announces this command.  Also, should we have an alias for
timer-list?  Although this command was never released yet, it was
introduced 1.5 years ago, so perhaps it is already used in external
packages, and maybe users are already familiar with it.

Let's wait for a few days in case someone objects, before committing.

Thanks.

Re: [PATCH] timer-list -> list-timers?

[Eli Zaretskii]

> Date: Sat, 16 Sep 2017 19:59:22 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: emacs-devel@gnu.org
> 
> I'm okay with renaming it, but if we do so, we should also patch NEWS,
> which announces this command.

It is also mentioned in Antinews.

Re: [PATCH] timer-list -> list-timers?

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> Why was this named timer-list?
>
> Lars?

I guess I was just adhering to the `<package>-function' naming
convention.  I'm all for renaming it to `list-timers'.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: [PATCH] timer-list -> list-timers?

[Mark Oteiza]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> I guess I was just adhering to the `<package>-function' naming
> convention.  I'm all for renaming it to `list-timers'.

Great.  I'll wait a bit for good measure, then commit (including the
[anti]news mentions)

Re: [PATCH] timer-list -> list-timers?

[John Wiegley]

>>>>> "LI" == Lars Ingebrigtsen <larsi@gnus.org> writes:

LI> I guess I was just adhering to the `<package>-function' naming convention.
LI> I'm all for renaming it to `list-timers'.

+1

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: [PATCH] timer-list -> list-timers?

[Mark Oteiza]

John Wiegley <jwiegley@gmail.com> writes:

>>>>>> "LI" == Lars Ingebrigtsen <larsi@gnus.org> writes:
>
> LI> I guess I was just adhering to the `<package>-function' naming convention.
> LI> I'm all for renaming it to `list-timers'.
>
> +1

Pushed as 965cffd8

Re: [PATCH] timer-list -> list-timers?

[Ted Zlatanov]

On Sat, 16 Sep 2017 20:56:53 +0200 Lars Ingebrigtsen <larsi@gnus.org> wrote: 

LI> I guess I was just adhering to the `<package>-function' naming
LI> convention.  I'm all for renaming it to `list-timers'.

That kind of bugs me about `M-x list-packages' etc. (there's a whole
bunch of them, like `list-holidays' and so on). Is there any rule about
when to make an exception to the `<package>-function' naming convention?
If not, should there be one?

Ted

Re: [PATCH] timer-list -> list-timers?

[Jorge A. Alfaro-Murillo]

Ted Zlatanov writes:

> On Sat, 16 Sep 2017 20:56:53 +0200 Lars Ingebrigtsen 
> <larsi@gnus.org> wrote:  
> 
> LI> I guess I was just adhering to the `<package>-function' 
> naming LI> convention.  I'm all for renaming it to 
> `list-timers'. 
> 
> That kind of bugs me about `M-x list-packages' etc. (there's a 
> whole bunch of them, like `list-holidays' and so on). Is there 
> any rule about when to make an exception to the 
> `<package>-function' naming convention?  If not, should there be 
> one? 

I agree. These functions that don't follow the package naming 
convention are always hard to find. Wouldn't `timer-list-timers', 
`package-list-packages', `holidays-list-holidays', etc be better?
-- 
Jorge.

Re: [PATCH] timer-list -> list-timers?

[Tom Tromey]

>>>>> "Jorge" == Jorge A Alfaro-Murillo <jorge.alfaro-murillo@yale.edu> writes:

Jorge> I agree. These functions that don't follow the package naming
Jorge> convention are always hard to find. Wouldn't `timer-list-timers',
Jorge> `package-list-packages', `holidays-list-holidays', etc be better?

package-list-packages and list-packages are aliases, which
seems like a reasonable thing to do in general.

Tom

Re: [PATCH] timer-list -> list-timers?

[Eli Zaretskii]

> From: jorge.alfaro-murillo@yale.edu (Jorge A. Alfaro-Murillo)
> Date: Wed, 20 Sep 2017 12:17:31 -0400
> 
> Ted Zlatanov writes:
> 
> > That kind of bugs me about `M-x list-packages' etc. (there's a 
> > whole bunch of them, like `list-holidays' and so on). Is there 
> > any rule about when to make an exception to the 
> > `<package>-function' naming convention?  If not, should there be 
> > one? 
> 
> I agree. These functions that don't follow the package naming 
> convention are always hard to find.

Doesn't "M-x apropos" help?

Re: [PATCH] timer-list -> list-timers?

[Jorge A. Alfaro-Murillo]

Eli Zaretskii writes:

>> From: jorge.alfaro-murillo@yale.edu (Jorge A. Alfaro-Murillo) 
>> Date: Wed, 20 Sep 2017 12:17:31 -0400  Ted Zlatanov writes:  
>> > That kind of bugs me about `M-x list-packages' etc. (there's 
>> > a  whole bunch of them, like `list-holidays' and so on). Is 
>> > there  any rule about when to make an exception to the 
>> > `<package>-function' naming convention?  If not, should there 
>> > be  one?  
>>  I agree. These functions that don't follow the package naming 
>> convention are always hard to find. 
> 
> Doesn't "M-x apropos" help?

Sure. But many times one does not know exactly what to look 
for. For example if I am getting familiar with a package I might 
want to see the name of all functions or variables in that 
package. For that I can use describe-function or describe-variable 
with <package>-TAB. Therefore, having at least aliases, as Tom 
suggested, would be useful. 

The `<package>-' naming convention also plays nicely with other 
things like `custom-unlispify-remove-prefixes', for example. And 
it is recommended in (info "(elisp) Coding Conventions").

So, I also have the same question as Ted: when is there a good 
reason to not follow the `<package>-' naming convention?

Best,
-- 
Jorge.

Re: [PATCH] timer-list -> list-timers?

[Mark Oteiza]

jorge.alfaro-murillo@yale.edu (Jorge A. Alfaro-Murillo) writes:

> The `<package>-' naming convention also plays nicely with other things
> like `custom-unlispify-remove-prefixes', for example. And it is
> recommended in (info "(elisp) Coding Conventions").

Commands aren't custom variables.

> So, I also have the same question as Ted: when is there a good reason
> to not follow the `<package>-' naming convention?

One was stated in the OP.

Re: [PATCH] timer-list -> list-timers?

[Ted Zlatanov]

On Sat, 16 Sep 2017 11:11:00 -0400 Mark Oteiza <mvoteiza@udel.edu> wrote: 

MO> While I understand there is a push to keep everything always in its
MO> own "namespace", list-foo is its own namespace, and is a useful one
MO> that collects special listings of different things around emacs.

On Wed, 20 Sep 2017 20:32:45 -0400 Mark Oteiza <mvoteiza@udel.edu> wrote: 

MO> jorge.alfaro-murillo@yale.edu (Jorge A. Alfaro-Murillo) writes:

>> So, I also have the same question as Ted: when is there a good reason
>> to not follow the `<package>-' naming convention?

MO> One was stated in the OP.

I saw it, but it was a bit ambiguous.

A better guideline *might* be "if the *command* PACKAGE-list or
PACKAGE-list-foo is in the core, loaded by default, and accessible
through the menubar; and it brings up a standalone buffer listing
objects with which the user can interact; it should have a
`list-PACKAGE` or `list-foo' alias also loaded by default." This is
less ambiguous. It could even be checked by a style checker. We can
discuss the exact wording but I hope you see what I mean.

Ted

Re: [PATCH] timer-list -> list-timers?

[Jorge A. Alfaro-Murillo]

Mark Oteiza writes:

> jorge.alfaro-murillo@yale.edu (Jorge A. Alfaro-Murillo) writes: 
> 
>> The `<package>-' naming convention also plays nicely with other 
>> things like `custom-unlispify-remove-prefixes', for 
>> example. And it is recommended in (info "(elisp) Coding 
>> Conventions"). 
> 
> Commands aren't custom variables.

I was referring to the part that says: "You should choose a short 
word to distinguish your program from other Lisp programs.  The 
names of all global symbols in your program, that is the names of 
variables, constants, and functions, should begin with that chosen 
prefix."

>> So, I also have the same question as Ted: when is there a good 
>> reason to not follow the `<package>-' naming convention? 
> 
> One was stated in the OP.

Got it, thanks, I didn't know about the list- namespace, and I 
couldn't find anything about in the documentation. Perhaps it 
should be added.

-- 
Jorge.

Re: [PATCH] timer-list -> list-timers?

[Eli Zaretskii]

> From: jorge.alfaro-murillo@yale.edu (Jorge A. Alfaro-Murillo)
> Date: Wed, 20 Sep 2017 18:29:55 -0400
> 
> >>  I agree. These functions that don't follow the package naming 
> >> convention are always hard to find. 
> > 
> > Doesn't "M-x apropos" help?
> 
> Sure. But many times one does not know exactly what to look 
> for.

'apropos' displays a one-line summary which should help you in this
task

> For example if I am getting familiar with a package I might 
> want to see the name of all functions or variables in that 
> package.

list-timers is in its own package.

> For that I can use describe-function or describe-variable with
> <package>-TAB. Therefore, having at least aliases, as Tom suggested,
> would be useful.

Once again, you should use apropos instead.

> So, I also have the same question as Ted: when is there a good 
> reason to not follow the `<package>-' naming convention?

AFAIU, the list-FOO case is one of them.

Re: [PATCH] timer-list -> list-timers?

[Mark Oteiza]

jorge.alfaro-murillo@yale.edu (Jorge A. Alfaro-Murillo) writes:

> Ted Zlatanov writes:
>
>> On Sat, 16 Sep 2017 20:56:53 +0200 Lars Ingebrigtsen
>> <larsi@gnus.org> wrote:  
>>
>> LI> I guess I was just adhering to the `<package>-function' naming
>> LI> convention.  I'm all for renaming it to `list-timers'. 
>>
>> That kind of bugs me about `M-x list-packages' etc. (there's a whole
>> bunch of them, like `list-holidays' and so on). Is there any rule
>> about when to make an exception to the `<package>-function' naming
>> convention?  If not, should there be one? 
>
> I agree. These functions that don't follow the package naming
> convention are always hard to find.

I don't see what's difficult about C-h f list TAB, or apropos.

Re: [PATCH] timer-list -> list-timers?

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > >> That kind of bugs me about `M-x list-packages' etc. (there's a whole
  > >> bunch of them, like `list-holidays' and so on). Is there any rule
  > >> about when to make an exception to the `<package>-function' naming
  > >> convention?  If not, should there be one? 

The convention is that functions in a package (and variables) should
have names which show their relationship to that package.  Usually we
do that by using the package name as a prefix, but that is not the
only way to do it.  It is ok to use the package name (or some form of
it) later on in the name.

So if there is a package called frob that works with things called frobs,
it is natural and ok for it to contain a command 'list-frobs'.

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

RE: [PATCH] timer-list -> list-timers?

[Drew Adams]

> LI> I guess I was just adhering to the `<package>-function' naming
> LI> convention.  I'm all for renaming it to `list-timers'.
> 
> That kind of bugs me about `M-x list-packages' etc. (there's a whole
> bunch of them, like `list-holidays' and so on). Is there any rule about
> when to make an exception to the `<package>-function' naming convention?
> If not, should there be one?

It is a bad idea, in general, to use "list" as a verb in function
etc. names in Emacs Lisp.  Typically, a verb such as "show" or
"display" does the job, with little or no ambiguity.

Re: [PATCH] timer-list -> list-timers?

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > It is a bad idea, in general, to use "list" as a verb in function
  > etc. names in Emacs Lisp.

'list...' is our naming convention for commands to show the list of
whatevers, and we should stick to it for consistency's sake.

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.