[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: emacs-29 acd462b0306: ; Improve the use-package manual
From: |
John Yates |
Subject: |
Re: emacs-29 acd462b0306: ; Improve the use-package manual |
Date: |
Sun, 11 Dec 2022 15:04:32 -0500 |
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
Re: emacs-29 acd462b0306: ; Improve the use-package manual, Stefan Monnier, 2022/12/10
Re: emacs-29 acd462b0306: ; Improve the use-package manual, Stefan Kangas, 2022/12/10