Subject: Re: bug#66350: 30.0.50; Description for (use-package emacs ...)
From: Stefan Kangas <[email-masked]>
To: Arash Esbati <[email-masked]>, John Wiegley <[email-masked]>
Cc: [email-masked], Eli Zaretskii <[email-masked]>
Date: Tue, 23 Jul 2024 06:19:44 -0700
List-Id: <debbugs-submit.debbugs.gnu.org>

Version: 30.1

Arash Esbati <[email-masked]> 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.
From d7ff9734103504e9840c8e0056d48924e41da216 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <[email-masked]>
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