Re: emacs-29 acd462b0306: ; Improve the use-package manual

[John Yates]

I am responding solely to this thread's subject, not to any
recent detailed points.

I have employed a use-package since my most recent emacs
bankruptcy five or so years back.  Early on I struggled
to come up with an appropriate ordering of keywords.
Clearly many are purely declarative.  But some result
in declarations and/or executable code.

Hence this use-package comment in my .init file:

;; Order insensitive metadata (neither introduces nor references any
symbols, nor executes any code):
;; :disabled         - turn off a troublesome or currently unused package
;; :straight         -
;; :pin              - pin the package to an archive
;; :ensure           - causes package(s) to be installed automatically
if not already present on your system
;; :defer            - suppress non-auto-deferred loading if you know
that another package will load this one
;; :demand           - prevent automatic deferred loading
;; :no-require       - inhibit loading package at compile time (e.g.
just need eval-after-load functionality)
;; :requires         - suppress if feature(s) not available at time of
use-package decl (= :if (featurep 'foo))
;; :load             - :load keyword overrides :no-require
;; :after            - delay loading until (:all PKG...) (default) or
(:any PKG...) are loaded
;; :catch            - override use-package-expand-minimally
;; :blackout         -
;; :diminish         - support for diminish.el (if installed).
;; :delight          - support for delight.el (if installed)
;;
;; Order sensitive (may introduce, reference or modify symbols, and/or
may execute code):
;; :load-path        - append to load-path before loading; relative
paths are expanded within user-emacs-directory
;; :defines          - introduce dummy variable declarations solely
for the sake of the byte-compiler
;; :functions        - introduce dummy function declarations solely
for the sake of the byte-compiler
;; :preface          - definition to silence byte-compiler and to be
used in :if tests
;; :if :when :unless - predicate initialization and loading
;; :custom           - custom-set or set-default each variable
definition; does not modify custom-file
;; :custom-face      - customize-set-faces each face definition; does
not modify custom-file
;; :general          - is this correct?
;; :bind(*)          - ( ( <global-key> . <command> )... :map
<package-local-map> ( <local-key> . <command> )... )
;;                     * = overriding all minor mode bindings
;; :bind-keymap(*)   - ( <package-prefix-key> . <map-in-package> )
;;                     * = overriding all minor mode bindings
;; :interpreter      - extend interpreter-mode-alist; use cons if
package name does not end with -mode
;; :mode             - extend auto-mode-alist; use cons if package
name does not end with -mode
;; :magic            - extend magic-mode-alist; use cons if package
name does not end with -mode
;; :magic-fallback   - extend magic-fallback-mode-alist; use cons if
package name does not end with -mode
;; :hook             - see
https://github.com/jwiegley/use-package/blob/master/README.md#hooks
;; :commands         - creates autoloads and defers loading of the
module until commands are used
;; :init             - code executed unconditionally before package is
loaded (and even when not loaded)
;; :config           - execute code after a package is loaded (perhaps
lazily); could even be a use-package form
;; :hydra            -

Since, at least in my theory, the keywords in the first
grouping are order-insensitive, I list them in the order
that I choose to have them appear in my use-package forms.

I am sure that my  comment includes errors.  Thus I would
love to see something similar but more authoritative in
the new manual.

/john