Commit 2be362c2 authored by Bill Wohler's avatar Bill Wohler
Browse files

* 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.
parent 7b18d88f
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
......
......@@ -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: ")
......
......@@ -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)))))
......
......@@ -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
......
......@@ -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
......
......@@ -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').
......
......@@ -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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment