[elpa] master 5a0cd5c 12/14: Documentation

[Phil]

branch: master
commit 5a0cd5ccb650d7bba1c1ea02cf67b71d7cfa6e9a
Author: Phil Sainty <psainty@orcon.net.nz>
Commit: Phil Sainty <psainty@orcon.net.nz>

    Documentation
    
    This integrates most of the additional information from
    https://www.emacswiki.org/emacs/DelightedModes
---
 delight.el | 150 +++++++++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 116 insertions(+), 34 deletions(-)

diff --git a/delight.el b/delight.el
index d7af68f..52f4192 100644
--- a/delight.el
+++ b/delight.el
@@ -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")
-;;            (rainbow-mode)
-;;            (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")
+;;              (rainbow-mode)
+;;              (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
 ;; starts).
 ;;
-;; 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
-;; library).
+;; 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"))
-;;          :major)
+;;   (delight 'emacs-lisp-mode
+;;            '("Elisp" (lexical-binding ":Lex" ":Dyn"))
+;;            :major)
+;;
+;; 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
+;; cases.
+;;
+;; 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 "..."
+;; varies):
+;;
+;;   (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.
 
 ;;; Code:
-
+
 (eval-when-compile (require 'cl-lib))
 (require 'nadvice)
 
@@ -175,7 +251,7 @@ replacement buffer-local `mode-name' value to use when a 
buffer changes to
 that mode.
 
 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 
nothing."
 
 (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 
`mode-name' when
   ;; All updates completed.
   (setq delight-version delight--latest-version))
 
+
+;; Local Variables:
+;; indent-tabs-mode: nil
+;; ispell-check-comments: exclusive
+;; End:
+
 (provide 'delight)
 ;;; delight.el ends here