1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2025-12-06 06:20:55 -08:00

Improve :delight keyword example in use-package manual

* use-package.texi (Diminish, Delight): Clarify what happens if the
pre-requisite packages are not installed.  Change an example with
performance issues to one without any.

Resolves https://github.com/jwiegley/use-package/issues/835
This commit is contained in:
Stefan Kangas 2022-12-09 06:27:33 +01:00
parent c417fe4df3
commit 5b640f0abd

View file

@ -1243,10 +1243,12 @@ install the corresponding package from @acronym{GNU ELPA}.
@findex :diminish @findex :diminish
When diminish@footnote{The diminish package is installable from When diminish@footnote{The diminish package is installable from
@acronym{GNU ELPA}.} is installed, you can use the @code{:diminish} @acronym{GNU ELPA}.} is installed, you can use the @code{:diminish}
keyword. First, add the following declaration to the beginning of keyword. If diminish is not installed, the @code{:diminish} keyword
your init file. The optional @w{@code{:ensure t}} makes sure the does nothing.
package is installed if it isn't already (@pxref{Installing
packages}). First, add the following declaration to the beginning of your init
file. The optional @w{@code{:ensure t}} makes sure the package is
installed if it isn't already (@pxref{Installing packages}).
@lisp @lisp
(use-package diminish :ensure t) (use-package diminish :ensure t)
@ -1270,7 +1272,9 @@ package name with @samp{-mode} appended at the end:
@findex :delight @findex :delight
When delight@footnote{The @samp{delight} package is installable from When delight@footnote{The @samp{delight} package is installable from
GNU ELPA.} is installed, you can use the @code{:delight} keyword. GNU ELPA.} is installed, you can use the @code{:delight} keyword. If
delight is not installed, the @code{:delight} keyword does nothing.
First, add the following declaration to the beginning of your init First, add the following declaration to the beginning of your init
file. The optional @w{@code{:ensure t}} makes sure the package is file. The optional @w{@code{:ensure t}} makes sure the package is
installed if it isn't already (@pxref{Installing packages}). installed if it isn't already (@pxref{Installing packages}).
@ -1281,25 +1285,41 @@ installed if it isn't already (@pxref{Installing packages}).
The @code{:delight} keyword takes a minor mode symbol, a replacement The @code{:delight} keyword takes a minor mode symbol, a replacement
string, or quoted mode line data (in which case the minor mode symbol string, or quoted mode line data (in which case the minor mode symbol
is guessed to be the package name with @samp{-mode} appended at the is assumed to be the package name with @samp{-mode} appended at the
end), both of these, or several lists of both. @xref{Mode Line end), both of these, or several lists of both. @xref{Mode Line
Data,,, elisp, GNU Emacs Lisp Reference Manual}. If no arguments are Data,,, elisp, GNU Emacs Lisp Reference Manual}. If no arguments are
provided, the default mode name is hidden completely. provided, the default mode name is hidden completely.
@lisp For example, the following hides everything for the @samp{foo-mode}
;; Don't show anything for rainbow-mode. minor mode in the @samp{foo} package:
(use-package rainbow-mode
:delight)
@lisp
(use-package foo
:delight)
@end lisp
If the mode name doesn't match the package name with @samp{-mode}
appended, provide a symbol instead. For example, the following hides
@code{auto-revert-mode} from the mode line:
@lisp
;; Don't show anything for auto-revert-mode, which doesn't match ;; Don't show anything for auto-revert-mode, which doesn't match
;; its package name. ;; its package name.
(use-package autorevert (use-package autorevert
:delight auto-revert-mode) :delight auto-revert-mode)
@end lisp
;; Remove the mode name for projectile-mode, but show the project name. You can also run arbitrary Lisp code. For example, to replace
(use-package projectile @samp{foo-mode} with the value of the current buffer:
:delight '(:eval (concat " " (projectile-project-name))))
@lisp
(use-package foo
:delight '(:eval buffer-file-name))
@end lisp
Here is an example of hiding several built-in minor modes:
@lisp
;; Completely hide visual-line-mode and change auto-fill-mode to " AF". ;; Completely hide visual-line-mode and change auto-fill-mode to " AF".
(use-package emacs (use-package emacs
:delight :delight