[Emacs-commit] emacs/lisp/mh-e mh-seq.el mh-print.el mh-junk.e...

[Bill Wohler]

CVSROOT:        /cvsroot/emacs
Module name:    emacs
Branch:         
Changes by:     Bill Wohler <address@hidden>    05/12/04 22:34:50

Modified files:
        lisp/mh-e      : mh-seq.el mh-print.el mh-junk.el mh-funcs.el 
                         mh-e.el mh-comp.el ChangeLog 

Log message:
        * 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.

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/emacs/emacs/lisp/mh-e/mh-seq.el.diff?tr1=1.13&tr2=1.14&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/emacs/emacs/lisp/mh-e/mh-print.el.diff?tr1=1.11&tr2=1.12&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/emacs/emacs/lisp/mh-e/mh-junk.el.diff?tr1=1.11&tr2=1.12&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/emacs/emacs/lisp/mh-e/mh-funcs.el.diff?tr1=1.14&tr2=1.15&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/emacs/emacs/lisp/mh-e/mh-e.el.diff?tr1=1.34&tr2=1.35&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/emacs/emacs/lisp/mh-e/mh-comp.el.diff?tr1=1.23&tr2=1.24&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/emacs/emacs/lisp/mh-e/ChangeLog.diff?tr1=1.67&tr2=1.68&r1=text&r2=text

Patches:
Index: emacs/lisp/mh-e/ChangeLog
diff -u emacs/lisp/mh-e/ChangeLog:1.67 emacs/lisp/mh-e/ChangeLog:1.68
--- emacs/lisp/mh-e/ChangeLog:1.67      Fri Dec  2 05:54:33 2005
+++ emacs/lisp/mh-e/ChangeLog   Sun Dec  4 22:34:49 2005
@@ -1,3 +1,30 @@
+2005-12-04  Bill Wohler  <address@hidden>
+
+       * 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  <address@hidden>
 
        Rewrote Reading Mail chapter in manual which affected mh-show
Index: emacs/lisp/mh-e/mh-comp.el
diff -u emacs/lisp/mh-e/mh-comp.el:1.23 emacs/lisp/mh-e/mh-comp.el:1.24
--- emacs/lisp/mh-e/mh-comp.el:1.23     Fri Dec  2 05:54:33 2005
+++ emacs/lisp/mh-e/mh-comp.el  Sun Dec  4 22:34:49 2005
@@ -327,17 +327,14 @@
 
 ;;;###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'."
Index: emacs/lisp/mh-e/mh-e.el
diff -u emacs/lisp/mh-e/mh-e.el:1.34 emacs/lisp/mh-e/mh-e.el:1.35
--- emacs/lisp/mh-e/mh-e.el:1.34        Fri Dec  2 05:54:33 2005
+++ emacs/lisp/mh-e/mh-e.el     Sun Dec  4 22:34:49 2005
@@ -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.
+
+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 @@
                  '(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)))))
Index: emacs/lisp/mh-e/mh-funcs.el
diff -u emacs/lisp/mh-e/mh-funcs.el:1.14 emacs/lisp/mh-e/mh-funcs.el:1.15
--- emacs/lisp/mh-e/mh-funcs.el:1.14    Fri Dec  2 05:54:33 2005
+++ emacs/lisp/mh-e/mh-funcs.el Sun Dec  4 22:34:49 2005
@@ -79,7 +79,14 @@
 
 ;;;###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 @@
 
 ;;;###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 @@
 
 (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
Index: emacs/lisp/mh-e/mh-junk.el
diff -u emacs/lisp/mh-e/mh-junk.el:1.11 emacs/lisp/mh-e/mh-junk.el:1.12
--- emacs/lisp/mh-e/mh-junk.el:1.11     Fri Dec  2 04:54:06 2005
+++ emacs/lisp/mh-e/mh-junk.el  Sun Dec  4 22:34:49 2005
@@ -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 @@
 (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
Index: emacs/lisp/mh-e/mh-print.el
diff -u emacs/lisp/mh-e/mh-print.el:1.11 emacs/lisp/mh-e/mh-print.el:1.12
--- emacs/lisp/mh-e/mh-print.el:1.11    Fri Dec  2 05:54:33 2005
+++ emacs/lisp/mh-e/mh-print.el Sun Dec  4 22:34:49 2005
@@ -88,7 +88,8 @@
           (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 @@
 
 ;;;###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 @@
 
 ;;;###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 @@
 ;;; 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').
Index: emacs/lisp/mh-e/mh-seq.el
diff -u emacs/lisp/mh-e/mh-seq.el:1.13 emacs/lisp/mh-e/mh-seq.el:1.14
--- emacs/lisp/mh-e/mh-seq.el:1.13      Thu Nov  3 19:59:38 2005
+++ emacs/lisp/mh-e/mh-seq.el   Sun Dec  4 22:34:49 2005
@@ -273,10 +273,16 @@
 
 ;;;###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 @@
 ;;;###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 @@
 
 ;;;###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 @@
 
 ;;;###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