Lots of doc fixes and message syntax fixes.

(ispell-command-loop): For X, put point before
the word being considered, and mention C-u M-$ in message.

1 files changed, 55 insertions, 49 deletions

diff --git a/lisp/textmodes/ispell.el b/lisp/textmodes/ispell.el
index 429a097d367..082190f5bc5 100644
--- a/lisp/textmodes/ispell.el
+++ b/lisp/textmodes/ispell.el
@@ -635,16 +635,16 @@ If word not found in dictionary, display possible corrections in a window
 and let user select.
   With a prefix argument (or if CONTINUE is non-nil),
 resume interrupted spell-checking of a buffer or region.
-  If optional argument FOLLOWING is non-nil or if ispell-following-word
+  If optional argument FOLLOWING is non-nil or if `ispell-following-word'
 is non-nil when called interactively, then the following word
-\(rather than preceding\) will be checked when the cursor is not over a word.
-  When the optional argument QUIETLY is non-nil or ispell-quietly is non-nil
+\(rather than preceding\) is checked when the cursor is not over a word.
+  When the optional argument QUIETLY is non-nil or `ispell-quietly' is non-nil
 when called interactively, non-corrective messages are suppressed.
 
-  Word syntax described by ispell-dictionary-alist (which see).
+  Word syntax described by `ispell-dictionary-alist' (which see).
 
 This will check or reload the dictionary.  Use \\[ispell-change-dictionary]
-or \\[ispell-region] to update the ispell process."
+or \\[ispell-region] to update the Ispell process."
   (interactive (list nil nil current-prefix-arg))
   (if continue
       (ispell-continue)
@@ -678,7 +678,7 @@ or \\[ispell-region] to update the ispell process."
           (setq poss (ispell-parse-output (car ispell-filter))))
       (cond ((eq poss t)
              (or quietly
-                 (message "%s is correct." (funcall ispell-format-word word))))
+                 (message "%s is correct" (funcall ispell-format-word word))))
             ((stringp poss)
              (or quietly
                  (message "%s is correct because of root %s"
@@ -718,13 +718,13 @@ or \\[ispell-region] to update the ispell process."
 
 (defun ispell-get-word (following &optional extra-otherchars)
   "Return the word for spell-checking according to ispell syntax.
-  If optional argument FOLLOWING is non-nil or if ispell-following-word
+If optional argument FOLLOWING is non-nil or if `ispell-following-word'
 is non-nil when called interactively, then the following word
-\(rather than preceeding\) will be checked when the cursor is not over a word.
+\(rather than preceeding\) is checked when the cursor is not over a word.
   Optional second argument contains otherchars that can be included in word
 many times.
 
-  Word syntax described by ispell-dictionary-alist (which see)."
+  Word syntax described by `ispell-dictionary-alist' (which see)."
   (let* ((ispell-casechars (ispell-get-casechars))
          (ispell-not-casechars (ispell-get-not-casechars))
          (ispell-otherchars (ispell-get-otherchars))
@@ -781,7 +781,7 @@ many times.
 ;;;###autoload
 (defun ispell-pdict-save (&optional no-query force-save)
   "Check to see if the personal dictionary has been modified.
-  If so, ask if it needs to be saved."
+If so, ask if it needs to be saved."
   (interactive (list ispell-silently-savep t))
   (if (and ispell-pdict-modified-p (listp ispell-pdict-modified-p))
       (setq ispell-pdict-modified-p (car ispell-pdict-modified-p)))
@@ -801,8 +801,8 @@ Returns nil to keep word.
         list for new replacement word (will be rechecked).
           Optional second argument means replace misspelling in
           the rest of the region.
-Global ispell-pdict-modified-p becomes a list where the only value
-indicates whether the dictionary has been modified when option a or i is
+Global `ispell-pdict-modified-p' becomes a list where the only value
+indicates whether the dictionary has been modified when option `a' or `i' is
 used."
   (unwind-protect
   (save-window-excursion
@@ -835,7 +835,7 @@ used."
                   (setq line (1+ line))))
             (insert (car guess) "    ")
             (setq guess (cdr guess)))
-          (insert "\nUse option \"i\" if this is a correct composition from the derivative root.\n")
+          (insert "\nUse option `i' if this is a correct composition from the derivative root\n")
           (setq line (+ line (if choices 3 2)))))
     (while (and choices
                 (< (if (> (+ 7 (current-column) (length (car choices))
@@ -915,11 +915,19 @@ used."
              ((or (= char ??) (= char help-char) (= char ?\C-h))
               (ispell-help)
               t)
-             ;; quit or quit and stay at this point.
-             ((or (= char ?x) (= char ?X)) ; quit.
+             ;; Quit and move point back.
+             ((= char ?x)
               (ispell-pdict-save ispell-silently-savep)
-              (message "exited ispell")
-              (setq ispell-quit (if (= char ?X) (point) t))
+              (message "Exited spell-checking")
+              (setq ispell-quit t)
+              nil)
+             ;; Quit and preserve point.
+             ((= char ?X)
+              (ispell-pdict-save ispell-silently-savep)
+              (message
+               (substitute-command-keys
+                "Spell-checking suspended; use C-u \\[ispell-word] to resume"))
+              (setq ispell-quit (max (point-min) (- (point) (length word))))
               nil)
              ((= char ?q)
               (if (y-or-n-p "Really quit ignoring changes? ")
@@ -996,7 +1004,7 @@ used."
 
 ;;;###autoload
 (defun ispell-help ()
-  "This gives a list of the options available when a misspelling is encountered.
+  "Display a list of the options available when a misspelling is encountered.
 
 Selections are:
 
@@ -1050,11 +1058,11 @@ DIGIT: Replace the word with a digit offered in the *Choices* buffer.
 
 (defun lookup-words (word &optional lookup-dict)
   "Look up word in word-list dictionary.
-A '*' is used for wild cards.  If no wild cards, 'look' is used if it exists.
- Otherwise the variable ispell-grep-command contains the command used to
+A `*' is serves as a wild card.  If no wild cards, `look' is used if it exists.
+ Otherwise the variable `ispell-grep-command' contains the command used to
  search for the words (usually egrep).
-Optional second argument contains the dictionary to use, the default is
- ispell-alternate-dictionary."
+Optional second argument contains the dictionary to use; the default is
+ `ispell-alternate-dictionary'."
   ;; We don't use the filter for this function, rather the result is written
   ;; into a buffer.  Hence there is no need to save the filter values.
   (if (null lookup-dict)
@@ -1146,10 +1154,9 @@ Optional second argument contains the dictionary to use, the default is
 ;;; This function destroys the mark location if it is in the word being
 ;;; highlighted.
 (defun highlight-spelling-error-generic (start end &optional highlight)
-  "Highlight the word from START to END by deleting and reinserting it
-while toggling the variable \"inverse-video\".  When the optional
-third arg HIGHLIGHT is set, the word is highlighted otherwise it is
-displayed normally."
+  "Highlight the word from START to END with a kludge using `inverse-video'.
+When the optional third arg HIGHLIGHT is set, the word is highlighted;
+otherwise it is displayed normally."
   (let ((modified (buffer-modified-p))  ; don't allow this fn to modify buffer
         (buffer-read-only nil)          ; Allow highlighting read-only buffers.
         (text (buffer-substring start end)) ; Save highlight region
@@ -1167,8 +1174,8 @@ displayed normally."
 
 
 (defun highlight-spelling-error-lucid (start end &optional highlight)
-  "Highlight the word from START to END using isearch-highlight.  When
-the optional third arg HIGHLIGHT is set, the word is highlighted
+  "Highlight the word from START to END using `isearch-highlight'.
+When the optional third arg HIGHLIGHT is set, the word is highlighted
 otherwise it is displayed normally."
   (if highlight
       (isearch-highlight start end)
@@ -1178,9 +1185,9 @@ otherwise it is displayed normally."
 
 
 (defun highlight-spelling-error-overlay (start end &optional highlight)
-  "Highlight the word from START to END using overlays.  When the
-optional third arg HIGHLIGHT is set, the word is highlighted otherwise
-it is displayed normally.
+  "Highlight the word from START to END using overlays.
+When the optional third arg HIGHLIGHT is set, the word is highlighted
+otherwise it is displayed normally.
   The variable ispell-highlight-face selects the face that will be used
 for highlighting."
   (if highlight
@@ -1201,10 +1208,9 @@ for highlighting."
 
 
 (defun ispell-overlay-window (height)
-  "Create a (usually small) window covering the top HEIGHT lines of the
-current window.  Ensure that the line above point is still visible but
-otherwise avoid scrolling the current window.  Should leave the old
-window selected."
+  "Create a window covering the top HEIGHT lines of the current window.
+Ensure that the line above point is still visible but otherwise avoid
+scrolling the current window.  Leave the old window selected."
   (save-excursion
     (let ((oldot (save-excursion (forward-line -1) (point)))
           (top (save-excursion (move-to-window-line height) (point))))
@@ -1218,14 +1224,14 @@ window selected."
 
 ;;; Should we add a compound word match return value?
 (defun ispell-parse-output (output)
-  "Parse the OUTPUT string of 'ispell' and return:
+  "Parse the OUTPUT string of `ispell' and return:
 1: T for an exact match.
 2: A string containing the root word for a match via suffix removal.
 3: A list of possible correct spellings of the format:
-   '(\"original-word\" offset miss-list guess-list)
-   original-word is a string of the possibly misspelled word.
-   offset is an integer giving the line offset of the word.
-   miss-list and guess-list are possibly null lists of guesses and misses."
+   '(\"ORIGINAL-WORD\" OFFSET MISS-LIST GUESS-LIST)
+   ORIGINAL-WORD is a string of the possibly misspelled word.
+   OFFSET is an integer giving the line offset of the word.
+   MISS-LIST and GUESS-LIST are possibly null lists of guesses and misses."
   (cond
    ((string= output "") t)              ; for startup with pipes...
    ((string= output "*") t)             ; exact match
@@ -1299,7 +1305,7 @@ window selected."
 
 
 (defun ispell-init-process ()
-  "Check status of 'ispell' process and start if necessary."
+  "Check status of Ispell process and start if necessary."
   (if (and ispell-process
            (eq (process-status ispell-process) 'run)
            ;; If we're using a personal dictionary, assure
@@ -1309,7 +1315,7 @@ window selected."
       (setq ispell-filter nil ispell-filter-continue nil)
     ;; may need to restart to select new personal dictionary.
     (ispell-kill-ispell t)
-    (message "Starting new ispell process...")
+    (message "Starting new Ispell process...")
     (sit-for 0)
     (check-ispell-version)
     (setq ispell-process
@@ -1372,7 +1378,7 @@ With NO-ERROR, just return non-nil if there was no ispell running."
           (error "There is no ispell process running!"))
     (kill-process ispell-process)
     (setq ispell-process nil)
-    (message "Killed ispell process.")
+    (message "Ispell process killed")
     nil))
 
 
@@ -1407,7 +1413,7 @@ With prefix argument, set the default directory."
                    (setq ispell-local-dictionary dict)))
            (error "Illegal dictionary: %s" dict))
          (ispell-kill-ispell t)
-         (message "(Next %sispell command will use %s dictionary)"
+         (message "(Next %sIspell command will use %s dictionary)"
                   (cond ((equal ispell-local-dictionary ispell-dictionary)
                          "")
                         (arg "global ")
@@ -1428,7 +1434,7 @@ With prefix argument, set the default directory."
   (ispell-accept-buffer-local-defs)     ; set up dictionary, local words, etc.
   (unwind-protect
   (save-excursion
-  (message "Spelling %s..."
+  (message "Spell checking %s..."
            (if (and (= reg-start (point-min)) (= reg-end (point-max)))
                (buffer-name) "region"))
   (sit-for 0)
@@ -1486,7 +1492,7 @@ With prefix argument, set the default directory."
                 (progn
                   (ispell-pdict-save ispell-silently-savep)
                   (ding)
-                  (message "Open tib reference.   Set ispell-skip-tib to nil to avoid this error.")
+                  (message "Open tib reference--set `ispell-skip-tib' to nil to avoid this error")
                   (setq ispell-quit (- (point) 2)))) ; leave dot at error loc.
           ;; tib ref starts later on line.  Check spelling before tib.
           (let ((limit (- (point) 2)))
@@ -1533,7 +1539,7 @@ With prefix argument, set the default directory."
                                        (search-forward (car poss) word-end t)
                                        (point)))
                         ;; This usually occurs due to filter pipe problems
-                        (error "***ispell misalignment: word \"%s\" point %d; please retry."
+                        (error "Ispell misalignment: word `%s' point %d; please retry"
                                (car poss) word-start))
                     (unwind-protect
                     (progn
@@ -1597,7 +1603,7 @@ With prefix argument, set the default directory."
                               offset-change (+ offset-change change)
                               end (+ end change)))))
                     (if (not ispell-quit)
-                        (message "continuing spelling check..."))
+                        (message "Continuing spelling check..."))
                     (sit-for 0)))
               (setq ispell-filter (cdr ispell-filter))))) ; finished with line
       (goto-char end)))))
@@ -1622,7 +1628,7 @@ With prefix argument, set the default directory."
     (set-marker ispell-region-end nil)
     ;; Only save if successful exit.
     (ispell-pdict-save ispell-silently-savep)
-    (message "Spell done."))))
+    (message "Spell-checking done"))))