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

From: [email-masked] (GNU bug Tracking System)
Date: Tue, 23 Jul 2024 13:21:02 +0000

Your bug report

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

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
66350: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=66350
GNU Bug Tracking System
Contact [email-masked] with problems

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

Subject: 30.0.50; Description for (use-package emacs ...)
From: Arash Esbati <[email-masked]>
To: [email-masked]
Date: Wed, 04 Oct 2023 23:29:26 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

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/