diff lisp/mh-e/mh-e.el @ 67313:2ae99b10dd40

* 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.

--- a/lisp/mh-e/mh-e.el	Sun Dec 04 21:00:59 2005 +0000
+++ b/lisp/mh-e/mh-e.el	Sun Dec 04 22:34:49 2005 +0000
@@ -552,11 +552,10 @@
   (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 @@
    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 @@
   "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 @@
   (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 @@
     (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 @@
     (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.
 
-If RANGE is nil (the default if it is omitted when called non-interactively),
-then all messages in FOLDER are displayed.
+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.
 
-If an index buffer is being created then INDEX-DATA is used to initialize the
-index buffer specific data structures.
+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.
 
-A prefix argument will cause a prompt for the RANGE of messages
-regardless of the size of the `mh-large-folder' variable."
+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.
+
+Do not call this function from outside MH-E; use \\[mh-rmail] instead.
+
+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 @@
                  '(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 @@
   (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 @@
     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 @@
 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 @@
         (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)))))