scratch/so-long-updates 0c61fe0 1/6: ; Documentation and spelling

[Phil]

branch: scratch/so-long-updates
commit 0c61fe05a7bf220f9d28d3b5497803fbb09a1ce2
Author: Phil Sainty <address@hidden>
Commit: Phil Sainty <address@hidden>

    ; Documentation and spelling
    
    * lisp/so-long.el: Documentation fixes.  For the purposes of
    consistency, this reverts some of the changes made in commit
    41ba8231ef072571e1a6feabc15d113e5cf57556, including one which
    had introduced inconsistent spelling.
    
    ispell configuration and LocalWords have been added such that
    `ispell-buffer' should find no misspellings for this library.
    
    * test/lisp/so-long-tests/spelling-tests.el (so-long-spelling):
    New test to check the spelling using `ispell-buffer'.
---
 lisp/so-long.el                           | 43 ++++++++++++++++++-------
 test/lisp/so-long-tests/spelling-tests.el | 53 +++++++++++++++++++++++++++++++
 2 files changed, 84 insertions(+), 12 deletions(-)

diff --git a/lisp/so-long.el b/lisp/so-long.el
index e2467e4..202a71b 100644
--- a/lisp/so-long.el
+++ b/lisp/so-long.el
@@ -325,7 +325,7 @@
 
 ;; * Caveats
 ;; ---------
-;; The variables affecting the automated behavior of this library (such as
+;; The variables affecting the automated behaviour of this library (such as
 ;; `so-long-action') can be used as file- or dir-local values in Emacs 26+, but
 ;; not in previous versions of Emacs.  This is on account of improvements made
 ;; to `normal-mode' in 26.1, which altered the execution order with respect to
@@ -654,7 +654,7 @@ an example."
 ;; `provided-mode-derived-p' was added in 26.1
 (unless (fboundp 'provided-mode-derived-p)
   (defun provided-mode-derived-p (mode &rest modes)
-    "Return non-nil if MODE is derived from one of MODES.
+    "Non-nil if MODE is derived from one of MODES.
 Uses the `derived-mode-parent' property of the symbol to trace backwards.
 If you just want to check `major-mode', use `derived-mode-p'."
     (while (and (not (memq mode modes))
@@ -707,7 +707,7 @@ was established."
   "List of buffer-local minor modes to explicitly disable.
 
 The ones which were originally enabled in the buffer are disabled by calling
-them with the numeric argument 0.  Unknown modes, and modes which were were not
+them with the numeric argument 0.  Unknown modes, and modes which were not
 enabled, are ignored.
 
 This happens after any globalized minor modes have acted, so that buffer-local
@@ -742,8 +742,8 @@ If `so-long-revert' is subsequently invoked, then the 
variables are restored
 to their original states.
 
 The combination of `line-move-visual' (enabled) and `truncate-lines' (disabled)
-is important for avoiding performance hits when moving vertically between
-excessively long lines, as otherwise the full length of the line may need to be
+is important for maximising responsiveness when moving vertically within an
+extremely long line, as otherwise the full length of the line may need to be
 scanned to find the next position."
   :type '(alist :key-type (variable :tag "Variable")
                 :value-type (sexp :tag "Value"))
@@ -1174,11 +1174,11 @@ enabled, and `so-long-predicate' has detected that the 
file contains long lines.
 Many Emacs modes struggle with buffers which contain excessively long lines,
 and may consequently cause unacceptable performance issues.
 
-This is commonly on account of 'minified' code (i.e. code has been compacted
-into the smallest file size possible, which often entails removing newlines
-should they not be strictly necessary).  These kinds of files are typically
-not intended to be edited, so not providing the usual editing mode in these
-cases will rarely be an issue.
+This is commonly on account of 'minified' code (i.e. code that has been
+compacted into the smallest file size possible, which often entails removing
+newlines should they not be strictly necessary).  These kinds of files are
+typically not intended to be edited, so not providing the usual editing mode
+in these cases will rarely be an issue.
 
 This major mode disables any active minor modes listed in `so-long-minor-modes'
 for the current buffer, and buffer-local values are assigned to variables in
@@ -1189,7 +1189,7 @@ values), despite potential performance issues, type 
\\[so-long-revert].
 
 Use \\[so-long-commentary] for more information.
 
-Use \\[so-long-customize] to configure the behavior."
+Use \\[so-long-customize] 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
@@ -1344,7 +1344,7 @@ This is the `so-long-revert-function' for `so-long-mode'."
 
 A buffer-local 'downgrade' from `so-long-mode' to `so-long-minor-mode'.
 
-When `so-long-function' is set to `so-long-mode', then we change it to to
+When `so-long-function' is set to `so-long-mode', then we change it to
 `turn-on-so-long-minor-mode' instead -- retaining the file-local major
 mode, but still doing everything else that `so-long-mode' would have done.
 `so-long-revert-function' is likewise updated.
@@ -1695,14 +1695,33 @@ or call the function `global-so-long-mode'.")
   (global-so-long-mode 0)
   nil)
 
+
 (provide 'so-long)
 
 ;; Local Variables:
 ;; emacs-lisp-docstring-fill-column: 80
 ;; fill-column: 80
 ;; indent-tabs-mode: nil
+;; ispell-check-comments: exclusive
+;; ispell-local-dictionary: "british"
 ;; End:
 
+;; This library uses (the author's preference of) British English, contrary to
+;; the preference for American English in Emacs.  This is partly due to its
+;; origins (and continued availability in GNU ELPA) as a third-party library;
+;; and partly because it is extensively documented, and using an unfamiliar
+;; dialect would be an annoyance.  I hope the benefits of the library will
+;; outweigh any discontent you may experience regarding the spelling (or that
+;; you find the spelling to be an agreeable bonus).
+
+; LocalWords:  LocalWords ispell customize customized customizing Customization
+; LocalWords:  globalized initialized profiler redisplay boolean minified pre 
el
+; LocalWords:  noerror selectable setq mapc sgml nxml hl flydiff defs rx bos 
eos
+; LocalWords:  defadvice nadvice EmacsWiki WS ie arg origmode Un cXXXr init 
eobp
+; LocalWords:  docstring british auf wiedersehen longlines eval dir keymap 
alist
+; LocalWords:  elisp autoload Sainty MERCHANTABILITY whitespace emacs RET 
config
+; LocalWords:  amongst mitigations ELPA init
+
 ;; So long, farewell, auf wiedersehen, goodbye
 ;; You have to go, this code is minified
 ;; Goodbye!
diff --git a/test/lisp/so-long-tests/spelling-tests.el 
b/test/lisp/so-long-tests/spelling-tests.el
new file mode 100644
index 0000000..a4a35c0
--- /dev/null
+++ b/test/lisp/so-long-tests/spelling-tests.el
@@ -0,0 +1,53 @@
+;;; spelling-tests.el --- Test suite for so-long.el  -*- lexical-binding: t; 
-*-
+
+;; Copyright (C) 2019 Free Software Foundation, Inc.
+
+;; Author: Phil Sainty <address@hidden>
+;; Keywords: convenience
+
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; GNU Emacs is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
+
+;;; Code:
+
+(require 'ert)
+(require 'ispell)
+(require 'cl-lib)
+
+(when (and (executable-find "ispell")
+           (member "british" (ispell-valid-dictionary-list)))
+  (ert-deftest so-long-spelling ()
+    "Check the spelling in the source code."
+    :tags '(:unstable) ;; It works for me, but I'm not sure about others.
+    ;; There could be different "british" dictionaries yielding different
+    ;; results, for instance.
+    (let ((process-environment process-environment)
+          (tmpdir (make-temp-file "so-long." :dir ".ispell")))
+      (when (file-directory-p tmpdir)
+        (let ((find-spelling-mistake
+               (progn
+                 (push (format "HOME=%s" tmpdir) process-environment)
+                 (find-library "so-long")
+                 (cl-letf (((symbol-function 'ispell-command-loop)
+                            (lambda (_miss _guess word _start _end)
+                              (message "Unrecognised word: %s." word)
+                              (throw 'mistake t))))
+                   (catch 'mistake
+                     (ispell-buffer)
+                     nil)))))
+          (delete-directory tmpdir)
+          (should (not find-spelling-mistake)))))))
+
+;;; spelling-tests.el ends here