[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] master 5a0cd5c 12/14: Documentation
[elpa] master 5a0cd5c 12/14: Documentation
Sat, 11 Jul 2020 00:57:56 -0400 (EDT)
Author: Phil Sainty <firstname.lastname@example.org>
Commit: Phil Sainty <email@example.com>
This integrates most of the additional information from
delight.el | 150 +++++++++++++++++++++++++++++++++++++++++++++++--------------
1 file changed, 116 insertions(+), 34 deletions(-)
diff --git a/delight.el b/delight.el
index d7af68f..52f4192 100644
@@ -32,16 +32,19 @@
;; Example usage:
-;; (require 'delight)
+;; ;; Delighting a single mode at a time:
+;; (require 'delight)
+;; (delight 'abbrev-mode " Abv" "abbrev")
+;; (delight 'rainbow-mode)
-;; (delight 'abbrev-mode " Abv" "abbrev")
-;; (delight '((abbrev-mode " Abv" "abbrev")
-;; (smart-tab-mode " \\t" "smart-tab")
-;; (eldoc-mode nil "eldoc")
-;; (overwrite-mode " Ov" t)
-;; (emacs-lisp-mode "Elisp" :major)))
+;; ;; Delighting multiple modes together:
+;; (require 'delight)
+;; (delight '((abbrev-mode " Abv" "abbrev")
+;; (smart-tab-mode " \\t" "smart-tab")
+;; (eldoc-mode nil "eldoc")
+;; (overwrite-mode " Ov" t)
+;; (emacs-lisp-mode "Elisp" :major)))
;; The first argument is the mode symbol.
@@ -50,7 +53,7 @@
;; The third argument is either the keyword :major for major modes or,
;; for minor modes, the library which defines the mode. This is passed
-;; to ‘eval-after-load’ and so should be either the name (as a string)
+;; to `eval-after-load' and so should be either the name (as a string)
;; of the library file which defines the mode, or the feature (symbol)
;; provided by that library. If this argument is nil, the mode symbol
;; will be passed as the feature. If this argument is either t or 'emacs
@@ -58,38 +61,111 @@
;; with standard minor modes that are pre-loaded by default when Emacs
-;; To determine which library defines a mode, use e.g.: C-h f
-;; eldoc-mode RET. The name of the library is displayed in the first
-;; paragraph, with an “.el” suffix (in this example it displays
-;; “eldoc.el”, and therefore we could use the value “eldoc” for the
+;; In the above example, `rainbow-mode' is the symbol for both the minor
+;; mode and the feature which provides it, and its lighter text will be
+;; hidden from the mode line.
+;; To determine which library defines a mode, use e.g.: C-h f eldoc-mode.
+;; The name of the library is displayed in the first paragraph, with an
+;; ".el" suffix (in this example it displays "eldoc.el", and therefore we
+;; could use the value "eldoc" for the library).
+;; If you simply cannot figure out which library to specify, an
+;; alternative approach is to evaluate (delight 'something-mode nil t)
+;; once you know for sure that the mode has already been loaded, perhaps
+;; by using the mode hook for that mode.
-;; Important note:
+;; If all else fails, it's worth looking at C-h v minor-mode-alist
+;; (after enabling the minor mode in question). There are rare cases
+;; where the entry in `minor-mode-alist' has a different symbol to the
+;; minor mode with which it is associated, and in these situations you
+;; will need to specify the name in the alist, rather than the name of
+;; the mode itself. Known examples (and how to delight them) are:
-;; Although strings are common, any mode-line construct is permitted
-;; as the value (for both minor and major modes); so before you
-;; override a value you should check the existing one, as you may
-;; want to replicate any structural elements in your replacement
-;; if it turns out not to be a simple string.
+;; `auto-fill-mode': (delight 'auto-fill-function " AF" t)
+;; `server-mode': (delight 'server-buffer-clients " SV" 'server)
+;; * Important notes:
+;; Although strings are common, any mode line construct is permitted as
+;; the value (for both minor and major modes); so before you override a
+;; value you should check the existing one, as you may want to replicate
+;; any structural elements in your replacement if it turns out not to be
+;; a simple string.
;; For major modes, M-: mode-name
;; For minor modes, M-: (cadr (assq 'MODE minor-mode-alist))
;; for the minor MODE in question.
-;; Conversely, you may incorporate additional mode-line constructs in
+;; Conversely, you may incorporate additional mode line constructs in
;; your replacement values, if you so wish. e.g.:
-;; (delight 'emacs-lisp-mode
-;; '("Elisp" (lexical-binding ":Lex" ":Dyn"))
+;; (delight 'emacs-lisp-mode
+;; '("Elisp" (lexical-binding ":Lex" ":Dyn"))
+;; See `mode-line-format' for information about mode line constructs, and
+;; M-: (info "(elisp) Mode Line Format") for further details.
+;; Settings for minor modes are held in a global variable and tend to take
+;; immediate effect upon calling ‘delight’. Major mode names are held in
+;; buffer-local variables, however, so changes to these will not take
+;; effect in a given buffer unless the major mode is called again, or the
+;; buffer is reverted. Calling M-x normal-mode is sufficient in most
+;; Also bear in mind that some modes may dynamically update these values
+;; themselves (for instance dired-mode updates mode-name if you change the
+;; sorting criteria) in which cases this library may prove inadequate.
+;; Some modes also implement direct support for customizing these values;
+;; so if delight is not sufficient for a particular mode, be sure to check
+;; whether the library in question provides its own way of doing this.
+;; * Conflict with `c-mode' and related major modes:
+;; Major modes based on cc-mode.el (including ‘c-mode’, ‘c++-mode’, and
+;; derivatives such as ‘php-mode’) cannot be delighted, due to Emacs bug
+;; #2034: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=2034
-;; See `mode-line-format' for information about mode-line constructs,
-;; and M-: (info "(elisp) Mode Line Format") for further details.
+;; cc-mode.el assumes that ‘mode-name’ is always a string (which was true
+;; in Emacs 22 and earlier), while delight.el makes use of the fact that
+;; ‘mode-name’ can (since Emacs 23) contain any mode line construct. The
+;; two are therefore incompatible.
-;; Also bear in mind that some modes may dynamically update these
-;; values themselves (for instance dired-mode updates mode-name if
-;; you change the sorting criteria) in which cases this library may
-;; prove inadequate.
+;; The symptom of this conflict is the following error (where the "..."
+;; (wrong-type-argument stringp (delight-mode-name-inhibit ...))
+;; The conflicting function is ‘c-update-modeline’ which adds the various
+;; suffix characters documented at M-: (info "(ccmode) Minor Modes").
+;; (E.g. In the mode line of a ‘c-mode’ buffer, the name C might be
+;; changed to "C/*l" or similar, depending on the minor modes.)
+;; If you are willing (or indeed wishing) to eliminate those suffixes
+;; entirely for all relevant major modes, then you can work around this
+;; conflict between the two libraries by disabling ‘c-update-modeline’
+;; entirely, like so:
+;; (advice-add 'c-update-modeline :override #'ignore)
+;; * Integration with mode line replacement libraries:
+;; Libraries which replace the standard mode line are liable to conflict
+;; with delight's treatment of major modes, as such libraries invariably
+;; need to call `format-mode-line', which otherwise happens only in
+;; circumstances in which delight wishes to show the original mode-name.
+;; These libraries (or custom advice) can prevent this by let-binding
+;; `delight-mode-name-inhibit' to nil around calls to `format-mode-line'
+;; which will ensure that the delighted `mode-name' is displayed.
+;; * Configuration via use-package:
+;; The popular `use-package' macro supports delight.el so you can also
+;; delight modes as part of your package configurations. See its README
+;; file for details.
;;; Change Log:
@@ -119,7 +195,7 @@
;; - Initial release.
(eval-when-compile (require 'cl-lib))
@@ -175,7 +251,7 @@ replacement buffer-local `mode-name' value to use when a
buffer changes to
In both cases VALUE is commonly a string, but may in fact contain any valid
-mode-line construct. For details see the `mode-line-format' variable, and
+mode line construct. For details see the `mode-line-format' variable, and
Info node `(elisp) Mode Line Format'.
The FILE argument is passed through to `eval-after-load'. If FILE is nil then
@@ -243,7 +319,7 @@ If the delighted VALUE is not a string and not nil, we do
(defun delight-major-mode ()
"Delight the 'pretty name' of the current buffer's major mode
-when displayed in the mode-line.
+when displayed in the mode line.
When `mode-name' is displayed in other contexts (such as in the
`describe-mode' help buffer), its original value will be used,
@@ -374,5 +450,11 @@ Delighted major modes should exhibit their original
;; All updates completed.
(setq delight-version delight--latest-version))
+;; Local Variables:
+;; indent-tabs-mode: nil
+;; ispell-check-comments: exclusive
;;; delight.el ends here
- [elpa] master e3bd4c2 01/14: * delight.el: Fix copyright, (continued)
- [elpa] master e3bd4c2 01/14: * delight.el: Fix copyright, Phil, 2020/07/11
- [elpa] master 8ec8a5b 05/14: Use cl-lib, nadvice, and lexical-binding, Phil, 2020/07/11
- [elpa] master 6d4a5aa 06/14: Use double-spaced sentence formatting, Phil, 2020/07/11
- [elpa] master 17cce66 04/14: Re-format the Change Log, Phil, 2020/07/11
- [elpa] master a763ec1 07/14: Rename `delight--inhibit' to `delight-mode-name-inhibit', Phil, 2020/07/11
- [elpa] master da63492 08/14: Rename `delighted-modes' to `delight-delighted-modes', Phil, 2020/07/11
- [elpa] master 088aae0 09/14: Support live updates from earlier versions, Phil, 2020/07/11
- [elpa] master 26dab6b 10/14: Support `unload-feature', Phil, 2020/07/11
- [elpa] master 989eed2 11/14: Add to after-change-major-mode-hook at load time, Phil, 2020/07/11
- [elpa] master 2a774d1 14/14: Merge commit '5a0cd5ccb650d7bba1c1ea02cf67b71d7cfa6e9a' from delight, Phil, 2020/07/11
- [elpa] master 5a0cd5c 12/14: Documentation,
- [elpa] master a1b7e94 13/14: * externals-list: Use https for "delight" subtree URL, Phil, 2020/07/11