+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
;;;###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: ")
(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."
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
"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.
(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)
(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."
(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
'(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))
(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))
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)
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))
(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)))))
;;;###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."
;;;###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)
(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
(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:
(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
(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
;;;###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.
;;;###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.
;;; 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').
;;;###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)
;;;###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))
;;;###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.
;;;###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
HCoop / bpt / emacs.git / commitdiff