master bda9abb 1/2: ; * lisp/so-long.el: Documentation

[Phil Sainty]

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

    ; * lisp/so-long.el: Documentation
    
    Clarify things which are only relevant to 'global-so-long-mode', and
    not when the 'so-long' command, or one of its actions, is invoked
    directly.
    
    Use the new "customization group" hyperlink syntax.
    
    Only quote 'so-long' as a symbol when it specifically refers to the
    command (or will otherwise generate a hyperlink which is appropriate
    to the context).  When referring to the library more generally, leave
    it unquoted.
    
    Changes from commit 63f419f1339cbd0a7d1e64586854a4f01b3f80d1 are
    reverted or improved.
---
 lisp/so-long.el | 54 +++++++++++++++++++++++++++++++-----------------------
 1 file changed, 31 insertions(+), 23 deletions(-)

diff --git a/lisp/so-long.el b/lisp/so-long.el
index 0cc6e88..800a68e 100644
--- a/lisp/so-long.el
+++ b/lisp/so-long.el
@@ -447,7 +447,7 @@
 ;; 0.7.5 - Documentation.
 ;;       - Added sgml-mode and nxml-mode to `so-long-target-modes'.
 ;; 0.7.4 - Refactored the handling of `whitespace-mode'.
-;; 0.7.3 - Added customize group `so-long' with user options.
+;; 0.7.3 - Added customization group `so-long' with user options.
 ;;       - Added `so-long-original-values' to generalise the storage and
 ;;         restoration of values from the original mode upon `so-long-revert'.
 ;;       - Added `so-long-revert-hook'.
@@ -491,7 +491,7 @@
   ;; considered internal-use only (with `global-so-long-mode' the interface
   ;; for enabling or disabling the automated behaviour).  FIXME: Establish a
   ;; way to support the original use-case, or rename to `so-long--enabled'.
-  "Internal use.  Non-nil when any `so-long' functionality has been used.")
+  "Internal use.  Non-nil when any so-long functionality has been used.")
 
 (defvar-local so-long--active nil ; internal use
   "Non-nil when `so-long' mitigations are in effect.")
@@ -568,7 +568,7 @@ See `so-long-detected-long-line-p' for details."
 
 (defcustom so-long-target-modes
   '(prog-mode css-mode sgml-mode nxml-mode fundamental-mode)
-  "`so-long' affects only these modes and their derivatives.
+  "`global-so-long-mode' affects only these modes and their derivatives.
 
 Our primary use-case is minified programming code, so `prog-mode' covers
 most cases, but there are some exceptions to this.
@@ -615,7 +615,9 @@ the mentioned options might interfere with some intended 
processing."
 (defcustom so-long-predicate (if (fboundp 'buffer-line-statistics)
                                  'so-long-statistics-excessive-p
                                'so-long-detected-long-line-p)
-  "Function, called after `set-auto-mode' to decide whether action is needed.
+  "Function called after `set-auto-mode' to decide whether action is needed.
+
+This affects the behaviour of `global-so-long-mode'.
 
 Only called if the major mode is a member of `so-long-target-modes'.
 
@@ -750,6 +752,8 @@ If ACTION-ARG is provided, it is used in place of 
`so-long-action'."
 (defcustom so-long-file-local-mode-function 'so-long-mode-downgrade
   "Function to call during `set-auto-mode' when a file-local mode is set.
 
+This affects the behaviour of `global-so-long-mode'.
+
 The specified function will be called with a single argument, being the
 file-local mode which was established.
 
@@ -761,8 +765,8 @@ place of `so-long-mode' -- therefore respecting the 
file-local mode value, yet
 still overriding minor modes and variables (as if `so-long-action' had been set
 to `so-long-minor-mode').
 
-The value `so-long-inhibit' means that `so-long' will not take any action at 
all
-for this file.
+The value `so-long-inhibit' means that `global-so-long-mode' will not take any
+action at all for this file.
 
 If nil, then do not treat files with file-local modes any differently to other
 files.
@@ -1090,7 +1094,7 @@ This command calls `so-long' with the selected action as 
an argument.")
 
 ;;;###autoload
 (defun so-long-commentary ()
-  "View the `so-long' documentation in `outline-mode'."
+  "View the so-long library's documentation in `outline-mode'."
   (interactive)
   (let ((buf "*So Long: Commentary*"))
     (when (buffer-live-p (get-buffer buf))
@@ -1130,7 +1134,7 @@ This command calls `so-long' with the selected action as 
an argument.")
 
 ;;;###autoload
 (defun so-long-customize ()
-  "Open the `so-long' customize group."
+  "Open the customization group `so-long'."
   (interactive)
   (customize-group 'so-long))
 
@@ -1375,7 +1379,8 @@ values), despite potential performance issues, type 
\\[so-long-revert].
 
 Use \\[so-long-commentary] for more information.
 
-Use \\[so-long-customize] to configure the behaviour."
+Use \\[so-long-customize] to open the customization group `so-long' to
+configure the behaviour."
   ;; Housekeeping.  `so-long-mode' might be invoked directly rather than via
   ;; `so-long', so replicate the necessary behaviours.  We could use this same
   ;; test in `so-long-after-change-major-mode' to run `so-long-hook', but 
that's
@@ -1583,7 +1588,7 @@ because we do not want to downgrade the major mode in 
that scenario."
             so-long-revert-function 'turn-off-so-long-minor-mode))))
 
 (defun so-long-inhibit (&optional _mode)
-  "Prevent `so-long' from having any effect at all.
+  "Prevent `global-so-long-mode' from having any effect.
 
 This is a `so-long-file-local-mode-function' option."
   (setq so-long--inhibited t))
@@ -1642,12 +1647,13 @@ function defined by `so-long-file-local-mode-function'."
                                    "-mode"))
                    modes))))
 
-    ;; `so-long' now processes the resulting mode list.  If any modes were
-    ;; listed, we assume that one of them is a major mode.  It's possible that
-    ;; this isn't true, but the buffer would remain in fundamental-mode if that
-    ;; were the case, so it is very unlikely.  For the purposes of passing a
-    ;; value to `so-long-handle-file-local-mode' we assume the major mode was
-    ;; the first mode specified (in which case it is the last in the list).
+    ;; Now process the resulting mode list for `so-long--set-auto-mode'.
+    ;; If any modes were listed, we assume that one of them is a major mode.
+    ;; It's possible that this isn't true, but the buffer would remain in
+    ;; fundamental-mode if that were the case, so it is very unlikely.
+    ;; For the purposes of passing a value to `so-long-handle-file-local-mode'
+    ;; we assume the major mode was the first mode specified (in which case it
+    ;; is the last in the list).
     (when modes
       (so-long-handle-file-local-mode (car (last modes))))))
 
@@ -1661,7 +1667,7 @@ function defined by `so-long-file-local-mode-function'."
   ;; (advice-add 'hack-local-variables :around #'so-long--hack-local-variables)
   ;;
   ;; See also "Files with a file-local 'mode'" in the Commentary.
-  "Ensure that `so-long' defers to file-local mode declarations if necessary.
+  "Enable `global-so-long-mode' to defer to file-local mode declarations.
 
 If a file-local mode is detected, then we call the function defined by
 `so-long-file-local-mode-function'.
@@ -1685,7 +1691,8 @@ File-local header comments are currently an exception, 
and are processed by
   ;; (advice-add 'set-auto-mode :around #'so-long--set-auto-mode)
   "Maybe call `so-long' for files with very long lines.
 
-This advice acts after `set-auto-mode' has set the buffer's major mode.
+This advice acts after `set-auto-mode' has set the buffer's major mode, if
+`global-so-long-mode' is enabled.
 
 We can't act before this point, because some major modes must be exempt
 \(binary file modes, for example).  Instead, we act only when the selected
@@ -1848,14 +1855,14 @@ invoked."
 
 ;;;###autoload
 (defun so-long-enable ()
-  "Enable the `so-long' library's functionality.
+  "Enable the so-long library's functionality.
 
 Equivalent to calling (global-so-long-mode 1)"
   (interactive)
   (global-so-long-mode 1))
 
 (defun so-long-disable ()
-  "Disable the `so-long' library's functionality.
+  "Disable the so-long library's functionality.
 
 Equivalent to calling (global-so-long-mode 0)"
   (interactive)
@@ -1880,7 +1887,8 @@ When such files are detected by `so-long-predicate', we 
invoke the selected
 
 Use \\[so-long-commentary] for more information.
 
-Use \\[so-long-customize] to configure the behaviour."
+Use \\[so-long-customize] to open the customization group `so-long' to
+configure the behaviour."
   :global t
   :group 'so-long
   (if global-so-long-mode
@@ -2065,13 +2073,13 @@ If it appears in `%s', you should remove it."
 ;; M-x ispell-buffer (using aspell).
 
 ; LocalWords:  LocalWords british ispell aspell hunspell emacs elisp el init 
dir
-; LocalWords:  customize customized customizing Customization globalized 
amongst
+; LocalWords:  customize customized customizing customization Customization 
prog
 ; LocalWords:  initialized profiler boolean minified pre redisplay config 
keymap
 ; LocalWords:  noerror selectable mapc sgml nxml hl flydiff defs arg Phil 
Sainty
 ; LocalWords:  defadvice nadvice whitespace ie bos eos eobp origmode un Un setq
 ; LocalWords:  docstring auf Wiedersehen longlines alist autoload Refactored 
Inc
 ; LocalWords:  MERCHANTABILITY RET REGEXP VAR ELPA WS mitigations EmacsWiki 
eval
-; LocalWords:  rx filename filenames js defun bidi bpa prog FIXME
+; LocalWords:  rx filename filenames js defun bidi bpa FIXME globalized amongst
 
 ;; So long, farewell, auf Wiedersehen, goodbye
 ;; You have to go, this code is minified