bug#44748: [PATCH] New section on package initialization; document quickstart

bug#44748: [PATCH] New section on package initialization; document quickstart

[Stefan Kangas]

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

Severity: wishlist

Please find attached a patch to add a new section on package
initialization to the user manual, and to document package-quickstart.

Thoughts?

[-- Attachment #2: 0001-New-section-on-package-initialization-document-quick.patch --]
[-- Type: text/x-diff, Size: 2827 bytes --]

From 11d1d9845fc8d6850a9b342c2a7f92de56aa3623 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Fri, 20 Nov 2020 01:55:08 +0100
Subject: [PATCH] New section on package initialization; document quickstart

* doc/emacs/package.texi (Package Initialization): Add new section
including information previously under "Package Installation".
Document package-quickstart.
(Packages): Update menu.
---
 doc/emacs/package.texi | 25 +++++++++++++++++++------
 1 file changed, 19 insertions(+), 6 deletions(-)

diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi
index 4981dd50c7..3e9be39475 100644
--- a/doc/emacs/package.texi
+++ b/doc/emacs/package.texi
@@ -48,6 +48,7 @@ Packages
 * Package Menu::         Buffer for viewing and managing packages.
 * Package Statuses::     Which statuses a package can have.
 * Package Installation:: Options for package installation.
+* Package Initialization:: How packages are initialized.
 * Package Files::        Where packages are installed.
 @end menu
 
@@ -409,12 +410,15 @@ Package Installation
 wide-ranging effects on the Emacs session.  For such information,
 consult the package's help buffer.
 
-  After a package is installed, it is automatically made available by
-Emacs in all subsequent sessions.  This happens at startup, before
-processing the init file but after processing the early init file
-(@pxref{Early Init File}).  As an exception, Emacs does not make
-packages available at startup if invoked with the @samp{-q} or
-@samp{--no-init-file} options (@pxref{Initial Options}).
+@node Package Initialization
+@section Package Initialization
+
+Installed packages are automatically made available by Emacs in all
+subsequent sessions.  This happens at startup, before processing the
+init file but after processing the early init file (@pxref{Early Init
+File}).  As an exception, Emacs does not make packages available at
+startup if invoked with the @samp{-q} or @samp{--no-init-file} options
+(@pxref{Initial Options}).
 
 @vindex package-enable-at-startup
   To keep Emacs from automatically making packages available at
@@ -423,6 +427,15 @@ Package Installation
 is read before loading the regular init file.  Currently this variable
 cannot be set via Customize.
 
+@findex package-quickstart-refresh
+@vindex package-quickstart
+  If you have many packages installed, you can improve startup times
+by setting the user option @code{package-quickstart} to @code{t}.
+This requires you to manually run the command
+@code{package-quickstart-refresh} when the activations need to be
+changed, such as when you change the value of
+@code{package-load-list}.
+
 @findex package-activate-all
   If you have set @code{package-enable-at-startup} to @code{nil}, you
 can still make packages available either during or after startup.  To
-- 
2.29.2

bug#44748: [PATCH] New section on package initialization; document quickstart

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Thu, 19 Nov 2020 17:00:18 -0800
> Cc: monnier@iro.umontreal.ca
> 
> Please find attached a patch to add a new section on package
> initialization to the user manual, and to document package-quickstart.
> 
> Thoughts?

Does adding 2 short paragraphs justify yet another node?  The original
text is 125 lines long, not too long IMO.

> diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi
> index 4981dd50c7..3e9be39475 100644
> --- a/doc/emacs/package.texi
> +++ b/doc/emacs/package.texi
> @@ -48,6 +48,7 @@ Packages
>  * Package Menu::         Buffer for viewing and managing packages.
>  * Package Statuses::     Which statuses a package can have.
>  * Package Installation:: Options for package installation.
> +* Package Initialization:: How packages are initialized.
>  * Package Files::        Where packages are installed.
>  @end menu

When you add nodes, you need to update the detailed menu in emacs.texi
as well.

> +@findex package-quickstart-refresh
> +@vindex package-quickstart
> +  If you have many packages installed, you can improve startup times
> +by setting the user option @code{package-quickstart} to @code{t}.
> +This requires you to manually run the command
> +@code{package-quickstart-refresh} when the activations need to be
> +changed, such as when you change the value of
> +@code{package-load-list}.

This text doesn't explain what the quick start does.  Perhaps saying
what will happen if the user forgets to manually run that command
(error messages? signs of incorrect behavior?) would suffice.
Otherwise this text sounds like some black magic, and that is not a
good thing for a user manual.

Thanks.

bug#44748: [PATCH] New section on package initialization; document quickstart

[Lars Ingebrigtsen]

Documenting package-quickstart seems like a good idea, so I've partially
applied Stefan's patch.  But I agree with Eli that we don't need a new
section here, so I removed that bit, and I expanded a bit upon what
package-quickstart does.

Feel free to edit further if it's still unclear.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no