GNU bug report logs - #77311
Minor documentation fix (`use-package')

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 77311 in the body.
You can then email your comments to 77311 AT debbugs.gnu.org in the normal way.

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

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

From: Dominik Schrempf <dominik.schrempf <at> gmail.com>
To: "Emacs Bug Tracker" <bug-gnu-emacs <at> gnu.org>
Subject: Minor documentation fix (`use-package')
Date: Thu, 27 Mar 2025 16:01:33 +0100

[Message part 1 (text/plain, inline)]

Hello,

I attach a suggested minor patch of the documentation of `use-package'.

[0001-Fix-minor-issues-in-documentation-of-use-package.patch (text/x-patch, attachment)]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Dominik Schrempf <dominik.schrempf <at> gmail.com>
Cc: 77311 <at> debbugs.gnu.org
Subject: Re: bug#77311: Minor documentation fix (`use-package')
Date: Sat, 29 Mar 2025 13:04:43 +0300

> From: Dominik Schrempf <dominik.schrempf <at> gmail.com>
> Date: Thu, 27 Mar 2025 16:01:33 +0100
> 
> I attach a suggested minor patch of the documentation of `use-package'.

Thanks, see some comments below.

> --- a/lisp/use-package/use-package-core.el
> +++ b/lisp/use-package/use-package-core.el
> @@ -1849,11 +1849,11 @@ Usage:
>  :magic-fallback  Form to be added to `magic-fallback-mode-alist'.
>  :interpreter     Form to be added to `interpreter-mode-alist'.
>  
> -:commands        Define autoloads for commands that will be defined by the
> +:commands        Define autoloads for interactive commands defined by the
>                   package.  This is useful if the package is being lazily
> -                 loaded, and you wish to conditionally call functions in your
> -                 `:init' block that are defined in the package.
> -:autoload        Similar to :commands, but it for no-interactive one.
> +                 loaded, and you wish to conditionally call functions in
> +                 your `:init' block that are defined in the package.
> +:autoload        Similar to `:commands', but used for non-interactive commands.
>  :hook            Specify hook(s) to attach this package to.
>  
>  :bind            Bind keys, and define autoloads for the bound commands.

A command is always interactive.  So saying "interactive commands" is
a kind-of tautology, and "non-interactive commands" is something that
doesn't exist in Emacs.

My suggestion is to leave the description of :commands unchanged, and
modify :autoload to say that its for non-interactive functions.

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

From: Dominik Schrempf <dominik.schrempf <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 77311 <at> debbugs.gnu.org
Subject: Re: bug#77311: Minor documentation fix (`use-package')
Date: Sat, 29 Mar 2025 14:54:39 +0100

[Message part 1 (text/plain, inline)]

Hi,

thanks for your comments.

Please find attached the updated patch. I still changed the tense used
in the documentation of `:commands'.

Best,
Dominik

[0001-Fix-minor-issues-in-documentation-of-use-package.patch (text/x-patch, attachment)]

[Message part 3 (text/plain, inline)]

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

>> From: Dominik Schrempf <dominik.schrempf <at> gmail.com>
>> Date: Thu, 27 Mar 2025 16:01:33 +0100
>>
>> I attach a suggested minor patch of the documentation of `use-package'.
>
> Thanks, see some comments below.
>
>> --- a/lisp/use-package/use-package-core.el
>> +++ b/lisp/use-package/use-package-core.el
>> @@ -1849,11 +1849,11 @@ Usage:
>>  :magic-fallback  Form to be added to `magic-fallback-mode-alist'.
>>  :interpreter     Form to be added to `interpreter-mode-alist'.
>>
>> -:commands        Define autoloads for commands that will be defined by the
>> +:commands        Define autoloads for interactive commands defined by the
>>                   package.  This is useful if the package is being lazily
>> -                 loaded, and you wish to conditionally call functions in your
>> -                 `:init' block that are defined in the package.
>> -:autoload        Similar to :commands, but it for no-interactive one.
>> +                 loaded, and you wish to conditionally call functions in
>> +                 your `:init' block that are defined in the package.
>> +:autoload        Similar to `:commands', but used for non-interactive commands.
>>  :hook            Specify hook(s) to attach this package to.
>>
>>  :bind            Bind keys, and define autoloads for the bound commands.
>
> A command is always interactive.  So saying "interactive commands" is
> a kind-of tautology, and "non-interactive commands" is something that
> doesn't exist in Emacs.
>
> My suggestion is to leave the description of :commands unchanged, and
> modify :autoload to say that its for non-interactive functions.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Dominik Schrempf <dominik.schrempf <at> gmail.com>
Cc: 77311-done <at> debbugs.gnu.org
Subject: Re: bug#77311: Minor documentation fix (`use-package')
Date: Sat, 29 Mar 2025 17:17:43 +0300

> From: Dominik Schrempf <dominik.schrempf <at> gmail.com>
> Cc: 77311 <at> debbugs.gnu.org
> Date: Sat, 29 Mar 2025 14:54:39 +0100
> 
> thanks for your comments.
> 
> Please find attached the updated patch. I still changed the tense used
> in the documentation of `:commands'.

Thanks, installed on the emacs-30 branch, and closing the bug.

Previous Next

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