* mh-comp.el (mh-forward): Went over all uses of the word "RANGE" in

the docstrings and made usage consistent. Generally speaking,
"messages in range" and "range of messages" is redundant and just
"range" can be used in most circumstances. Also ensured that
mh-interactive-range was mentioned in all interactive functions that
use a range which describes the range argument for both users and
programmers.

* mh-e.el (mh-delete-msg-no-motion, mh-refile-msg)
(mh-refile-or-write-again, mh-rescan-folder, mh-undo)
(mh-visit-folder, mh-scan-folder, mh-regenerate-headers)
(mh-notate-user-sequences, mh-delete-msg-from-seq, mh-catchup): Ditto.

* mh-funcs.el (mh-copy-msg, mh-pack-folder, mh-pack-folder-1): Ditto.

* mh-junk.el (mh-junk-blacklist, mh-junk-whitelist): Ditto.

* mh-print.el (mh-ps-print-range, mh-ps-print-msg)
(mh-ps-print-msg-file, mh-print-msg): Ditto.

* mh-seq.el (mh-put-msg-in-seq, mh-range-to-msg-list)
(mh-narrow-to-range, mh-toggle-tick): Ditto.

7 files changed, 149 insertions, 65 deletions

diff --git a/lisp/mh-e/ChangeLog b/lisp/mh-e/ChangeLog
index 746157e6e51..780b5cd067e 100644
--- a/lisp/mh-e/ChangeLog
+++ b/lisp/mh-e/ChangeLog
@@ -1,3 +1,30 @@
+2005-12-04  Bill Wohler  <wohler@newt.com>
+
+        * mh-comp.el (mh-forward): Went over all uses of the word "RANGE"
+        in the docstrings and made usage consistent. Generally speaking,
+        "messages in range" and "range of messages" is redundant and just
+        "range" can be used in most circumstances. Also ensured that
+        mh-interactive-range was mentioned in all interactive functions
+        that use a range which describes the range argument for both
+        users and programmers.
+
+        * mh-e.el (mh-delete-msg-no-motion, mh-refile-msg)
+        (mh-refile-or-write-again, mh-rescan-folder, mh-undo)
+        (mh-visit-folder, mh-scan-folder, mh-regenerate-headers)
+        (mh-notate-user-sequences, mh-delete-msg-from-seq, mh-catchup):
+        Ditto.
+
+        * mh-funcs.el (mh-copy-msg, mh-pack-folder, mh-pack-folder-1):
+        Ditto.
+
+        * mh-junk.el (mh-junk-blacklist, mh-junk-whitelist): Ditto.
+
+        * mh-print.el (mh-ps-print-range, mh-ps-print-msg)
+        (mh-ps-print-msg-file, mh-print-msg): Ditto.
+
+        * mh-seq.el (mh-put-msg-in-seq, mh-range-to-msg-list)
+        (mh-narrow-to-range, mh-toggle-tick): Ditto.
+
 2005-12-01  Bill Wohler  <wohler@newt.com>
 
         Rewrote Reading Mail chapter in manual which affected mh-show
diff --git a/lisp/mh-e/mh-comp.el b/lisp/mh-e/mh-comp.el
index d8d8b48d74d..4a812d6822c 100644
--- a/lisp/mh-e/mh-comp.el
+++ b/lisp/mh-e/mh-comp.el
@@ -327,18 +327,15 @@ See also `mh-send'."
 
 ;;;###mh-autoload
 (defun mh-forward (to cc &optional range)
-  "Forward message(s).
+  "Forward message.
 
 You are prompted for the TO and CC recipients. You are given a draft to edit
 that looks like it would if you had run the MH command \"forw\". You are given
 a chance to add some text.
 
-You can forward several messages by using a RANGE. All of the messages in the
-range are inserted into your draft. Check the documentation of
+You can forward several messages by using a RANGE. Check the documentation of
 `mh-interactive-range' to see how RANGE is read in interactive use.
 
-The default message is the current message.
-
 See also `mh-compose-forward-as-mime-flag', `mh-forward-subject-format',
 and `mh-send'."
   (interactive (list (mh-interactive-read-address "To: ")
diff --git a/lisp/mh-e/mh-e.el b/lisp/mh-e/mh-e.el
index 86d9bbfcddf..c69c62bd734 100644
--- a/lisp/mh-e/mh-e.el
+++ b/lisp/mh-e/mh-e.el
@@ -552,11 +552,10 @@ interactive use."
   (if (looking-at mh-scan-deleted-msg-regexp) (mh-next-msg)))
 
 (defun mh-delete-msg-no-motion (range)
-  "Delete message, don't move to next message.
+  "Delete RANGE, don't move to next message.
 
-This command marks the message (or messages in RANGE) for deletion but leaves
-the cursor at the current message in case you wish to perform other operations
-on the message.
+This command marks the RANGE for deletion but leaves the cursor at the current
+message in case you wish to perform other operations on the message.
 
 Check the documentation of `mh-interactive-range' to see how RANGE is read in
 interactive use."
@@ -744,14 +743,20 @@ The default folder name is generated by the option
    t))
 
 (defun mh-refile-msg (range folder &optional dont-update-last-destination-flag)
-  "Refile RANGE into FOLDER.
+  "Refile (output) RANGE into FOLDER.
+
+You are prompted for the folder name. Note that this command can also be used
+to create folders. If you specify a folder that does not exist, you will be
+prompted to create it.
+
+The hook `mh-refile-msg-hook' is called after a message is marked to be
+refiled.
 
 Check the documentation of `mh-interactive-range' to see how RANGE is read in
 interactive use.
 
-If optional argument DONT-UPDATE-LAST-DESTINATION-FLAG is non-nil then the
-variables `mh-last-destination' and `mh-last-destination-folder' are not
-updated."
+If DONT-UPDATE-LAST-DESTINATION-FLAG is non-nil, then the variables
+`mh-last-destination' and `mh-last-destination-folder' are not updated."
   (interactive (list (mh-interactive-range "Refile")
                      (intern (mh-prompt-for-refile-folder))))
   (unless dont-update-last-destination-flag
@@ -765,7 +770,7 @@ updated."
   "Repeat last output command.
 
 If you are refiling several messages into the same folder, you can use this
-command to repeat the last refile or write. Or, you can use a range.
+command to repeat the last refile or write. You can use a range.
 
 Check the documentation of `mh-interactive-range' to see how RANGE is read in
 interactive use.
@@ -1054,11 +1059,19 @@ Also removes all content from the folder buffer."
   (let ((buffer-read-only nil)) (erase-buffer)))
 
 (defun mh-rescan-folder (&optional range dont-exec-pending)
-  "Rescan a folder after optionally processing the outstanding commands.
-If optional prefix argument RANGE is provided, prompt for the range of
-messages to display. Otherwise show the entire folder.
-If optional argument DONT-EXEC-PENDING is non-nil then pending deletes and
-refiles aren't carried out."
+  "Rescan folder\\<mh-folder-mode-map>.
+
+This command is useful to grab all messages in your \"+inbox\" after
+processing your new mail for the first time. If you don't want to rescan the
+entire folder, this command will accept a RANGE. Check the documentation of
+`mh-interactive-range' to see how RANGE is read in interactive use.
+
+This command will ask if you want to process refiles or deletes first and then
+either run \\[mh-execute-commands] for you or undo the pending refiles and
+deletes, which are lost.
+
+In a program, the processing of outstanding commands is not performed if
+DONT-EXEC-PENDING is non-nil."
   (interactive (list (if current-prefix-arg
                          (mh-read-range "Rescan" mh-current-folder t nil t
                                         mh-interpret-number-as-range-flag)
@@ -1109,7 +1122,12 @@ can be made with the command \\[mh-refile-or-write-again]."
     (mh-show)))
 
 (defun mh-undo (range)
-  "Undo the pending deletion or refile of the specified RANGE.
+  "Undo pending deletes or refiles in RANGE.
+
+If you've deleted a message or refiled it, but changed your mind, you can
+cancel the action before you've executed it. Use this command to undo a refile
+on or deletion of a single message. You can also undo refiles and deletes for
+messages that are found in a given RANGE.
 
 Check the documentation of `mh-interactive-range' to see how RANGE is read in
 interactive use."
@@ -1254,17 +1272,29 @@ used to avoid problems in corner cases involving folders whose names end with a
     (mh-folder-size-folder folder)))
 
 (defun mh-visit-folder (folder &optional range index-data)
-  "Visit FOLDER and display RANGE of messages.
-Do not call this function from outside MH-E; see \\[mh-rmail] instead.
+  "Visit FOLDER.
+
+When you want to read the messages that you have refiled into folders, use
+this command to visit the folder. You are prompted for the folder name.
+
+The folder buffer will show just unseen messages if there are any; otherwise,
+it will show all the messages in the buffer as long there are fewer than
+`mh-large-folder' messages. If there are more, then you are prompted for a
+range of messages to scan.
+
+You can provide a prefix argument in order to specify a RANGE of messages to
+show when you visit the folder. In this case, regions are not used to specify
+the range and `mh-large-folder' is ignored. Check the documentation of
+`mh-interactive-range' to see how RANGE is read in interactive use.
 
-If RANGE is nil (the default if it is omitted when called non-interactively),
-then all messages in FOLDER are displayed.
+Note that this command can also be used to create folders. If you specify a
+folder that does not exist, you will be prompted to create it.
 
-If an index buffer is being created then INDEX-DATA is used to initialize the
-index buffer specific data structures.
+Do not call this function from outside MH-E; use \\[mh-rmail] instead.
 
-A prefix argument will cause a prompt for the RANGE of messages
-regardless of the size of the `mh-large-folder' variable."
+If, in a program, RANGE is nil (the default), then all messages in FOLDER are
+displayed. If an index buffer is being created then INDEX-DATA is used to
+initialize the index buffer specific data structures."
   (interactive (let ((folder-name (mh-prompt-for-folder "Visit" mh-inbox t)))
                  (list folder-name
                        (mh-read-range "Scan" folder-name t nil
@@ -1762,10 +1792,15 @@ DESKTOP-BUFFER-MISC holds a list of miscellaneous info used by the
                  '(mh-folder-mode . mh-restore-desktop-buffer)))
 
 (defun mh-scan-folder (folder range &optional dont-exec-pending)
-  "Scan the FOLDER over the RANGE.
-If the optional argument DONT-EXEC-PENDING is non-nil then pending deletes and
-refiles aren't carried out.
-Return in the folder's buffer."
+  "Scan FOLDER over RANGE.
+
+After the scan is performed, switch to the buffer associated with FOLDER.
+
+Check the documentation of `mh-interactive-range' to see how RANGE is read in
+interactive use.
+
+The processing of outstanding commands is not performed if DONT-EXEC-PENDING
+is non-nil."
   (when (stringp range)
     (setq range (delete "" (split-string range "[ \t\n]"))))
   (cond ((null (get-buffer folder))
@@ -1804,7 +1839,7 @@ Note that columns in Emacs start with 0."
   (setq mh-cmd-note column))
 
 (defun mh-regenerate-headers (range &optional update)
-  "Scan folder over range RANGE.
+  "Scan folder over RANGE.
 If UPDATE, append the scan lines, otherwise replace."
   (let ((folder mh-current-folder)
         (range (if (and range (atom range)) (list range) range))
@@ -2331,9 +2366,10 @@ Expands ranges into set of individual numbers."
     msgs))
 
 (defun mh-notate-user-sequences (&optional range)
-  "Mark user-defined sequences in the messages specified by RANGE.
-The optional argument RANGE can be a message number, a list of message
-numbers, a sequence, a region in a cons cell. If nil all messages are notated."
+  "Mark user-defined sequences in RANGE.
+
+Check the documentation of `mh-interactive-range' to see how RANGE is read in
+interactive use; if nil all messages are notated."
   (unless range
     (setq range (cons (point-min) (point-max))))
   (let ((seqs mh-seq-list)
@@ -2366,8 +2402,7 @@ numbers, a sequence, a region in a cons cell. If nil all messages are notated."
 Check the documentation of `mh-interactive-range' to see how RANGE is read in
 interactive use.
 
-Optional third arg INTERNAL-FLAG non-nil means do not inform MH of the
-change."
+In a program, non-nil INTERNAL-FLAG means do not inform MH of the change."
   (interactive (list (mh-interactive-range "Delete")
                      (mh-read-seq-default "Delete from" t)
                      nil))
@@ -2393,9 +2428,9 @@ change."
         (apply #'mh-speed-flists t folders-changed)))))
 
 (defun mh-catchup (range)
-  "Delete RANGE from the `mh-unseen-seq' sequence.
+  "Delete RANGE from the \"unseen\" sequence.
 
-Check the document of `mh-interactive-range' to see how RANGE is read in
+Check the documentation of `mh-interactive-range' to see how RANGE is read in
 interactive use."
   (interactive (list (mh-interactive-range "Catchup"
                                            (cons (point-min) (point-max)))))
diff --git a/lisp/mh-e/mh-funcs.el b/lisp/mh-e/mh-funcs.el
index 4f9adbe970b..ca2f7333eb8 100644
--- a/lisp/mh-e/mh-funcs.el
+++ b/lisp/mh-e/mh-funcs.el
@@ -79,7 +79,14 @@ field yourself."
 
 ;;;###mh-autoload
 (defun mh-copy-msg (range folder)
-  "Copy the specified RANGE to another FOLDER without deleting them.
+  "Copy RANGE to FOLDER\\<mh-folder-mode-map>.
+
+If you wish to copy a message to another folder, you can use this command
+\(see the \"-link\" argument to \"refile\"). Like the command
+\\[mh-refile-msg], this command prompts you for the name of the target folder
+and you can specify a range. Note that unlike the command \\[mh-refile-msg],
+the copy takes place immediately. The original copy remains in the current
+folder.
 
 Check the documentation of `mh-interactive-range' to see how RANGE is read in
 interactive use."
@@ -156,10 +163,16 @@ Display the results only if something went wrong."
 
 ;;;###mh-autoload
 (defun mh-pack-folder (range)
-  "Renumber the messages of a folder to be 1..n.
-First, offer to execute any outstanding commands for the current folder. If
-optional prefix argument provided, prompt for the RANGE of messages to display
-after packing. Otherwise, show the entire folder."
+  "Pack folder\\<mh-folder-mode-map>.
+
+This command packs the folder, removing gaps from the numbering sequence. If
+you don't want to rescan the entire folder afterward, this command will accept
+a RANGE. Check the documentation of `mh-interactive-range' to see how RANGE is
+read in interactive use.
+
+This command will ask if you want to process refiles or deletes first and then
+either run \\[mh-execute-commands] for you or undo the pending refiles and
+deletes, which are lost."
   (interactive (list (if current-prefix-arg
                          (mh-read-range "Scan" mh-current-folder t nil t
                                         mh-interpret-number-as-range-flag)
@@ -175,8 +188,8 @@ after packing. Otherwise, show the entire folder."
 
 (defun mh-pack-folder-1 (range)
   "Close and pack the current folder.
-Display the given RANGE of messages after packing. If RANGE is nil, show the
-entire folder."
+
+Display RANGE after packing, or the entire folder if RANGE is nil."
   (mh-process-or-undo-commands mh-current-folder)
   (message "Packing folder...")
   (mh-set-folder-modified-p t)          ; lock folder while packing
diff --git a/lisp/mh-e/mh-junk.el b/lisp/mh-e/mh-junk.el
index 54d21db443a..5cbc7b77b47 100644
--- a/lisp/mh-e/mh-junk.el
+++ b/lisp/mh-e/mh-junk.el
@@ -41,9 +41,12 @@
 (defun mh-junk-blacklist (range)
   "Blacklist RANGE as spam.
 
-This command trains the spam program in use (see the `mh-junk-program' option)
-with the content of the range (see `mh-interactive-range') and then handles
-the message(s) as specified by the `mh-junk-disposition' option.
+This command trains the spam program in use (see the option `mh-junk-program')
+with the content of RANGE and then handles the message(s) as specified by the
+option `mh-junk-disposition'.
+
+Check the documentation of `mh-interactive-range' to see how RANGE is read in
+interactive use.
 
 For more information about using your particular spam fighting program, see:
 
@@ -77,11 +80,12 @@ For more information about using your particular spam fighting program, see:
 (defun mh-junk-whitelist (range)
   "Whitelist RANGE as ham.
 
-This command reclassifies a range of messages (see `mh-interactive-range') as
-ham if it were incorrectly classified as spam. It then refiles the message
-into the `+inbox' folder.
+This command reclassifies the RANGE as ham if it were incorrectly classified
+as spam (see the option `mh-junk-program'). It then refiles the message into
+the \"+inbox\" folder.
 
-The `mh-junk-program' option specifies the spam program in use."
+Check the documentation of `mh-interactive-range' to see how RANGE is read in
+interactive use."
   (interactive (list (mh-interactive-range "Whitelist")))
   (let ((whitelist-func (nth 2 (assoc mh-junk-choice mh-junk-function-alist))))
     (unless whitelist-func
diff --git a/lisp/mh-e/mh-print.el b/lisp/mh-e/mh-print.el
index 8cf91f08d74..cc35926aecc 100644
--- a/lisp/mh-e/mh-print.el
+++ b/lisp/mh-e/mh-print.el
@@ -88,7 +88,8 @@ Sensible choices are the functions `ps-spool-buffer' and
           (kill-buffer buffer)))))
 
 (defun mh-ps-print-range (range file)
-  "Print the messages in RANGE to FILE.
+  "Print RANGE to FILE.
+
 This is the function that actually does the work.
 If FILE is nil, then the messages are spooled to the printer."
   (mh-iterate-on-range msg range
@@ -105,7 +106,7 @@ Pass along the PREFIX-ARG to it."
 
 ;;;###mh-autoload
 (defun mh-ps-print-msg (range)
-  "Print the messages in RANGE\\<mh-folder-mode-map>.
+  "Print RANGE\\<mh-folder-mode-map>.
 
 Check the documentation of `mh-interactive-range' to see how RANGE is read in
 interactive use.
@@ -126,7 +127,7 @@ and \\[mh-ps-print-toggle-faces]."
 
 ;;;###mh-autoload
 (defun mh-ps-print-msg-file (range file)
-  "Print the messages in RANGE to FILE\\<mh-folder-mode-map>.
+  "Print RANGE to FILE\\<mh-folder-mode-map>.
 
 Check the documentation of `mh-interactive-range' to see how RANGE is read in
 interactive use.
@@ -185,7 +186,7 @@ best. You change this setting permanently by customizing the option
 ;;; Old non-PS based printing
 ;;;###mh-autoload
 (defun mh-print-msg (range)
-  "Print the messages in RANGE the old fashioned way\\<mh-folder-mode-map>.
+  "Print RANGE the old fashioned way\\<mh-folder-mode-map>.
 
 The message is formatted with \"mhl\" (see option `mh-mhl-format-file') and
 printed with the \"lpr\" command (see option `mh-lpr-command-format').
diff --git a/lisp/mh-e/mh-seq.el b/lisp/mh-e/mh-seq.el
index 6dbb5f26c07..fcf9c64e266 100644
--- a/lisp/mh-e/mh-seq.el
+++ b/lisp/mh-e/mh-seq.el
@@ -273,10 +273,16 @@ When you want to widen the view to all your messages again, use \\[mh-widen]."
 
 ;;;###mh-autoload
 (defun mh-put-msg-in-seq (range sequence)
-  "Add RANGE to SEQUENCE.
+  "Add RANGE to SEQUENCE\\<mh-folder-mode-map>.
 
-Check the documentation of `mh-interactive-range' to see how RANGE is read in
-interactive use."
+To place a message in a sequence, use this command to do it manually, or use
+the MH command \"pick\" or the MH-E version of \"pick\", \\[mh-search-folder],
+which create a sequence automatically.
+
+Give this command a RANGE and you can add all the messages in a sequence to
+another sequence (for example, \"\\[universal-argument] \\[mh-put-msg-in-seq]
+SourceSequence RET DestSequence RET\"). Check the documentation of
+`mh-interactive-range' to see how RANGE is read in interactive use."
   (interactive (list (mh-interactive-range "Add messages from")
                      (mh-read-seq-default "Add to" nil)))
   (unless (mh-valid-seq-p sequence)
@@ -661,8 +667,9 @@ in order to provide a uniform interface to MH-E functions."
 ;;;###mh-autoload
 (defun mh-range-to-msg-list (range)
   "Return a list of messages for RANGE.
-RANGE can be a message number, a list of message numbers, a sequence, or
-a region in a cons cell."
+
+Check the documentation of `mh-interactive-range' to see how RANGE is read in
+interactive use."
   (let (msg-list)
     (mh-iterate-on-range msg range
       (push msg msg-list))
@@ -915,7 +922,7 @@ The MH command pick is used to do the match."
 
 ;;;###mh-autoload
 (defun mh-narrow-to-range (range)
-  "Limit to messages in RANGE.
+  "Limit to RANGE.
 
 Check the documentation of `mh-interactive-range' to see how RANGE is read in
 interactive use.
@@ -1679,7 +1686,7 @@ start of the region and the second is the point at the end."
 
 ;;;###mh-autoload
 (defun mh-toggle-tick (range)
-  "Toggle tick mark of all messages in RANGE.
+  "Toggle tick mark of RANGE.
 
 This command adds messages to the \"tick\" sequence (which you can customize
 via the option `mh-tick-seq'). This sequence can be viewed later with the