; * 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 63f419f133 are
reverted or improved.
This commit is contained in:
Phil Sainty
parent
5444f607a6
commit
bda9abb680
1 changed files with 31 additions and 23 deletions
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue