bug#66350: 30.0.50; Description for (use-package emacs ...)

bug#66350: 30.0.50; Description for (use-package emacs ...)

[Arash Esbati]

Hi all,

use-package.texi contains this example[1]:

  @lisp
  @group
  ;; Completely hide visual-line-mode and change auto-fill-mode to " AF".
  (use-package emacs
    :delight
    (auto-fill-function " AF")
    (visual-line-mode))
  @end group
  @end lisp

The usage of (use-package emacs ...) isn't described anywhere in the
file, though.  There was a discussion about it here[2], but I think it
should be documented in the manual somehow.  I'm not familiar enough
with use-package to make a suggestion, sorry.

Best, Arash

Footnotes:
[1]  https://git.savannah.gnu.org/cgit/emacs.git/tree/doc/misc/use-package.texi#n1539

[2]  https://www.reddit.com/r/emacs/comments/mk9ehd/curious_whats_the_use_of_usepackage_emacs/

bug#66350: 30.0.50; Description for (use-package emacs ...)

[Eli Zaretskii]

> From: Arash Esbati <arash@gnu.org>
> Date: Wed, 04 Oct 2023 23:29:26 +0200
> 
> Hi all,
> 
> use-package.texi contains this example[1]:
> 
>   @lisp
>   @group
>   ;; Completely hide visual-line-mode and change auto-fill-mode to " AF".
>   (use-package emacs
>     :delight
>     (auto-fill-function " AF")
>     (visual-line-mode))
>   @end group
>   @end lisp
> 
> The usage of (use-package emacs ...) isn't described anywhere in the
> file, though.  There was a discussion about it here[2], but I think it
> should be documented in the manual somehow.  I'm not familiar enough
> with use-package to make a suggestion, sorry.
> 
> Best, Arash
> 
> Footnotes:
> [1]  https://git.savannah.gnu.org/cgit/emacs.git/tree/doc/misc/use-package.texi#n1539
> 
> [2]  https://www.reddit.com/r/emacs/comments/mk9ehd/curious_whats_the_use_of_usepackage_emacs/

Adding John, in case he has any thoughts about this.

bug#66350: 30.0.50; Description for (use-package emacs ...)

[John Wiegley]

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

>> (use-package emacs

> Adding John, in case he has any thoughts about this.

The ‘(use-package emacs …)‘ declaration has no special meaning. It just takes
advantage of the fact that ‘(featurep 'emacs)‘ is always true, so in a way
it’s just for consistency’s sake, and doesn’t actually do anything special.

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

bug#66350: 30.0.50; Description for (use-package emacs ...)

[Arash Esbati]

John Wiegley <johnw@gnu.org> writes:

> The ‘(use-package emacs …)‘ declaration has no special meaning. It just takes
> advantage of the fact that ‘(featurep 'emacs)‘ is always true, so in a way
> it’s just for consistency’s sake, and doesn’t actually do anything special.

Thanks for your response.  I wonder which use-package keywords don't
make sense in that form?  The way I see it things like :defer, :init et
al. are useless since we're talking about Emacs with all preloaded
libraries, right?

Best, Arash

bug#66350: 30.0.50; Description for (use-package emacs ...)

[Arash Esbati]

John Wiegley <johnw@gnu.org> writes:

>>>>>> Eli Zaretskii <eliz@gnu.org> writes:
>
>>> (use-package emacs
>
>> Adding John, in case he has any thoughts about this.
>
> The ‘(use-package emacs …)‘ declaration has no special meaning. It just takes
> advantage of the fact that ‘(featurep 'emacs)‘ is always true, so in a way
> it’s just for consistency’s sake, and doesn’t actually do anything special.

Thanks.  In order to close this report, I suggest to add the following
to the manual:

--8<---------------cut here---------------start------------->8---
diff --git a/doc/misc/use-package.texi b/doc/misc/use-package.texi
index c2b6404b68b..e0a156eb373 100644
--- a/doc/misc/use-package.texi
+++ b/doc/misc/use-package.texi
@@ -181,7 +181,7 @@ Getting Started
 immediately.  In most cases, this is not necessary or desirable, as
 that will slow down Emacs startup.  Instead, you should try to set
 things up so that packages are only loaded when they are actually
-needed (a.k.a. ``autoloading'').  If you have installed a package from
+needed (a.k.a.@: ``autoloading'').  If you have installed a package from
 @acronym{GNU} @acronym{ELPA} that provides it's own autoloads, it is often
 enough to say:

@@ -225,6 +225,21 @@ Getting Started
 that you can use.  Where possible, it is a good idea to copy them, and
 use that as a starting point.

+You can also configure variables defined in Emacs C sources or preloaded
+with Emacs with the no-op @samp{emacs} package:
+
+@lisp
+@group
+(use-package emacs
+  :init
+  (setq custom-file "~/.emacs.d/emacs-custom.el")
+  (load custom-file)
+  (setq frame-title-format "%b")
+  :custom
+  (use-short-answers t))
+@end group
+@end lisp
+
 That should be enough to get you started!

 @c ----------------------------------------------------------------------------
--8<---------------cut here---------------end--------------->8---

If the question is too trivial, we can close it as wontfix.

Best, Arash

bug#66350: 30.0.50; Description for (use-package emacs ...)

[Stefan Kangas]

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

Version: 30.1

Arash Esbati <arash@gnu.org> writes:

> Thanks.  In order to close this report, I suggest to add the following
> to the manual:
>
> --8<---------------cut here---------------start------------->8---
> diff --git a/doc/misc/use-package.texi b/doc/misc/use-package.texi
> index c2b6404b68b..e0a156eb373 100644
> --- a/doc/misc/use-package.texi
> +++ b/doc/misc/use-package.texi
> @@ -181,7 +181,7 @@ Getting Started
>  immediately.  In most cases, this is not necessary or desirable, as
>  that will slow down Emacs startup.  Instead, you should try to set
>  things up so that packages are only loaded when they are actually
> -needed (a.k.a. ``autoloading'').  If you have installed a package from
> +needed (a.k.a.@: ``autoloading'').  If you have installed a package from
>  @acronym{GNU} @acronym{ELPA} that provides it's own autoloads, it is often
>  enough to say:
>
> @@ -225,6 +225,21 @@ Getting Started
>  that you can use.  Where possible, it is a good idea to copy them, and
>  use that as a starting point.
>
> +You can also configure variables defined in Emacs C sources or preloaded
> +with Emacs with the no-op @samp{emacs} package:
> +
> +@lisp
> +@group
> +(use-package emacs
> +  :init
> +  (setq custom-file "~/.emacs.d/emacs-custom.el")
> +  (load custom-file)
> +  (setq frame-title-format "%b")
> +  :custom
> +  (use-short-answers t))
> +@end group
> +@end lisp
> +
>  That should be enough to get you started!
>
>  @c ----------------------------------------------------------------------------
> --8<---------------cut here---------------end--------------->8---
>
> If the question is too trivial, we can close it as wontfix.

I've installed the attached patch on emacs-30 (commit c7609464f70),
adding a new node describing this all.  Thanks for proposing a text, it
was a useful starting point.

Please let me know if you spot any mistakes or anything that could be
improved in what I wrote.  Meanwhile, I'm closing this bug report.

[-- Attachment #2: 0001-Document-use-package-emacs-declarations.patch --]
[-- Type: text/x-patch, Size: 2208 bytes --]

From d7ff9734103504e9840c8e0056d48924e41da216 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Tue, 23 Jul 2024 15:12:01 +0200
Subject: [PATCH] Document (use-package 'emacs) declarations

* doc/misc/use-package.texi (The @code{emacs} package): New
node.  (Bug#66350)
---
 doc/misc/use-package.texi | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/doc/misc/use-package.texi b/doc/misc/use-package.texi
index c4b8209be70..309315db23d 100644
--- a/doc/misc/use-package.texi
+++ b/doc/misc/use-package.texi
@@ -252,6 +252,7 @@ Loading Packages
 * Forcing loading::             Loading packages immediately.
 * Conditional loading::         Loading packages conditionally.
 * Loading sequentially::        Loading packages in sequence.
+* The @code{emacs} package::    Customizing built-in variables.
 * Load dependencies::           Don't load without dependencies.
 * Manual installation::         Loading manually installed packages.
 @end menu
@@ -567,6 +568,34 @@ Loading sequentially
 it is possible that your package will never be loaded if you do not
 add @code{:demand t} to those declarations.
 
+@node The @code{emacs} package
+@section Customizing built-in variables
+@cindex customizing built-in variables
+
+Some users want to put all their customizations in use-package
+declarations, even for variables, hooks, and options that are always
+available, without loading any package.@footnote{In other words, they
+are either preloaded in Emacs or defined in Emacs' C sources.}
+
+For that purpose, you can use the no-op @samp{emacs} package:
+
+@lisp
+@group
+(use-package emacs
+  :init
+  (setq custom-file "~/.emacs.d/emacs-custom.el")
+  (load custom-file)
+  (setq frame-title-format "%b")
+  :custom
+  (use-short-answers t))
+@end group
+@end lisp
+
+This declaration takes advantage of the fact that @w{@code{(featurep
+'emacs)}} always returns true, and has no special meaning beyond that.
+It simply provides a way to organize your customizations, without
+loading anything.
+
 @node Load dependencies
 @section Prevent loading if dependencies are missing
 @cindex prevent loading package if dependencies are missing
-- 
2.45.2

bug#66350: 30.0.50; Description for (use-package emacs ...)

[Arash Esbati]

Stefan Kangas <stefankangas@gmail.com> writes:

> I've installed the attached patch on emacs-30 (commit c7609464f70),
> adding a new node describing this all.  Thanks for proposing a text, it
> was a useful starting point.
>
> Please let me know if you spot any mistakes or anything that could be
> improved in what I wrote.  Meanwhile, I'm closing this bug report.

Many thanks for picking this up; your patch LGTM.  One other change in
my proposal was this around line 184:

-needed (a.k.a. ``autoloading'').  If you have installed a package from
+needed (a.k.a.@: ``autoloading'').  If you have installed a package from

We can also ignore this if use-package manual isn't distributed as .pdf,
I think.

Best, Arash

bug#66350: 30.0.50; Description for (use-package emacs ...)

[Eli Zaretskii]

> From: Arash Esbati <arash@gnu.org>
> Cc: John Wiegley <johnw@gnu.org>,  Eli Zaretskii <eliz@gnu.org>,
>   66350-done@debbugs.gnu.org
> Date: Tue, 23 Jul 2024 19:37:09 +0200
> 
> Stefan Kangas <stefankangas@gmail.com> writes:
> 
> > I've installed the attached patch on emacs-30 (commit c7609464f70),
> > adding a new node describing this all.  Thanks for proposing a text, it
> > was a useful starting point.
> >
> > Please let me know if you spot any mistakes or anything that could be
> > improved in what I wrote.  Meanwhile, I'm closing this bug report.
> 
> Many thanks for picking this up; your patch LGTM.  One other change in
> my proposal was this around line 184:
> 
> -needed (a.k.a. ``autoloading'').  If you have installed a package from
> +needed (a.k.a.@: ``autoloading'').  If you have installed a package from
> 
> We can also ignore this if use-package manual isn't distributed as .pdf,
> I think.

Users should be able to generate a good-looking PDF from every manual
we ship.  So I think that part of the change should also be installed.

bug#66350: 30.0.50; Description for (use-package emacs ...)

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> One other change in my proposal was this around line 184:
>>
>> -needed (a.k.a. ``autoloading'').  If you have installed a package from
>> +needed (a.k.a.@: ``autoloading'').  If you have installed a package from
>>
>> We can also ignore this if use-package manual isn't distributed as .pdf,
>> I think.
>
> Users should be able to generate a good-looking PDF from every manual
> we ship.  So I think that part of the change should also be installed.

Thanks, I removed the acronym as redundant on emacs-30.
See commit 05629d3af0a.