From 5972fddfa16f18014afb30b05105fd04e9f81f48 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)

(cherry picked from commit c7609464f701775088184bbfc61907cd9276437c)
---
 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 @@ on Emacs start.  @xref{Installing packages}, for details.
 * 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 @@ registers autoloads, such as @code{:bind} or @code{:hook}
 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.39.2