diff options
| -rw-r--r-- | lisp/mh-e/ChangeLog | 27 | ||||
| -rw-r--r-- | lisp/mh-e/mh-comp.el | 7 | ||||
| -rw-r--r-- | lisp/mh-e/mh-e.el | 105 | ||||
| -rw-r--r-- | lisp/mh-e/mh-funcs.el | 27 | ||||
| -rw-r--r-- | lisp/mh-e/mh-junk.el | 18 | ||||
| -rw-r--r-- | lisp/mh-e/mh-print.el | 9 | ||||
| -rw-r--r-- | lisp/mh-e/mh-seq.el | 21 |
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 |