Mercurial > emacs

--- a/lisp/mh-e/ChangeLog	Fri Dec 23 04:57:28 2005 +0000
+++ b/lisp/mh-e/ChangeLog	Fri Dec 23 05:38:54 2005 +0000
@@ -1,3 +1,62 @@
+2005-12-22  Bill Wohler  <wohler@newt.com>
+
+	* mh-alias.el (mh-alias-reload): Sync docstrings with manual.
+
+	* mh-comp.el (mh-letter-mode): Use 60 column width.
+	(mh-forward, mh-insert-signature, mh-send-letter): Sync docstrings
+	with manual.
+	(mh-yank-cur-msg): Mention that mh-ins-buf-prefix isn't used if
+	you have added a mail-citation-hook and neither are used if you
+	use one of the supercite flavors of mh-yank-behavior. Sync
+	docstrings with manual.
+
+	* mh-customize.el (mh-ins-buf-prefix, mh-yank-behavior): Mention
+	that mh-ins-buf-prefix isn't used if you have added a
+	mail-citation-hook and neither are used if you use one of the
+	supercite flavors of mh-yank-behavior. Sync docstrings with
+	manual.
+	(mail-citation-hook): Delete. Use one in sendmail.el.
+	(mh-signature-file-name, mh-after-commands-processed-hook)
+	(mh-alias-reloaded-hook, mh-before-commands-processed-hook)
+	(mh-before-quit-hook, mh-before-send-letter-hook)
+	(mh-delete-msg-hook, mh-find-path-hook, mh-folder-mode-hook)
+	(mh-forward-hook, mh-inc-folder-hook, mh-insert-signature-hook)
+	(mh-kill-folder-suppress-prompt-hooks, mh-letter-mode-hook)
+	(mh-mh-to-mime-hook, mh-pick-mode-hook, mh-quit-hook)
+	(mh-refile-msg-hook, mh-show-hook, mh-show-mode-hook)
+	(mh-unseen-updated-hook): Sync docstrings with manual. Use "Hook
+	run by `function'..." instead of "Invoked...".
+
+	* mh-e.el (mh-last-destination, mh-last-destination-folder)
+	(mh-last-destination-write, mh-folder-mode-map, mh-arrow-marker)
+	(mh-delete-list, mh-refile-list, mh-folders-changed)
+	(mh-next-direction, mh-view-ops, mh-folder-view-stack)
+	(mh-index-data, mh-first-msg-num, mh-last-msg-num)
+	(mh-mode-line-annotation, mh-sequence-notation-history)
+	(mh-colors-available-flag): Move comment into docstring.
+	(mh-delete-msg, mh-execute-commands, mh-inc-folder, mh-quit,
+	mh-process-commands): Sync docstrings with manual.
+	(mh-refile-msg): Small doc edit.
+	(mh-delete-a-msg, mh-refile-a-msg): Sync docstrings with manual.
+	Rename msg argument to message.
+
+	* mh-funcs.el (mh-kill-folder): Sync docstrings with manual.
+
+	* mh-e.el (mh-update-unseen): No longer say "The value of
+	`foo-hook' is a list of functions to be called, with no arguments,
+	...," but rather just "The hook foo-hook is called...".
+
+	* mh-mime.el (mh-mh-to-mime): Ditto
+
+	* mh-pick.el (mh-pick-mode): Ditto.
+
+	* mh-utils.el (mh-showing-mode): Use uppercase for argument in
+	docstring.
+	(mh-seq-list, mh-seen-list, mh-showing-with-headers): Move comment
+	into docstring.
+	(mh-show-mode, mh-show-msg, mh-find-path): Sync docstrings with
+	manual.
+
 2005-12-19  Stephen Gildea

 	* mh-customize.el (mh-after-commands-processed-hook): New variable.
--- a/lisp/mh-e/mh-alias.el	Fri Dec 23 04:57:28 2005 +0000
+++ b/lisp/mh-e/mh-alias.el	Fri Dec 23 05:38:54 2005 +0000
@@ -183,14 +183,14 @@
 (defun mh-alias-reload ()
   "Reload MH aliases.

-Since aliases are updated frequently, MH-E will reload aliases automatically
-whenever an alias lookup occurs if an alias source (a file listed in your
-`Aliasfile:' profile component and your password file if variable
-`mh-alias-local-users' is non-nil) has changed. However, you can reload your
-aliases manually by calling this command directly.
+Since aliases are updated frequently, MH-E reloads aliases automatically
+whenever an alias lookup occurs if an alias source has changed. Sources
+include files listed in your `Aliasfile:' profile component and your password
+file if option `mh-alias-local-users' is turned on. However, you can reload
+your aliases manually by calling this command directly.

-The value of `mh-alias-reloaded-hook' is a list of functions to be called,
-with no arguments, after the aliases have been loaded."
+This function runs `mh-alias-reloaded-hook' after the aliases have been
+loaded."
   (interactive)
   (save-excursion
     (message "Loading MH aliases...")
--- a/lisp/mh-e/mh-comp.el	Fri Dec 23 04:57:28 2005 +0000
+++ b/lisp/mh-e/mh-comp.el	Fri Dec 23 05:38:54 2005 +0000
@@ -335,15 +335,18 @@
 (defun mh-forward (to cc &optional range)
   "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 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 can then add some text.

-You can forward several messages by using a RANGE. Check the documentation of
+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
 `mh-interactive-range' to see how RANGE is read in interactive use.

-See also `mh-compose-forward-as-mime-flag', `mh-forward-subject-format',
-and `mh-send'."
+The hook `mh-forward-hook' is called on the draft.
+
+See also `mh-compose-forward-as-mime-flag',
+`mh-forward-subject-format', and `mh-send'."
   (interactive (list (mh-interactive-read-address "To: ")
                      (mh-interactive-read-address "Cc: ")
                      (mh-interactive-range "Forward")))
@@ -933,18 +936,19 @@

 ;;;###autoload
 (define-derived-mode mh-letter-mode text-mode "MH-Letter"
-  "Mode for composing letters in MH-E.\\<mh-letter-mode-map>
+  "Mode for composing letters in MH-E\\<mh-letter-mode-map>.

-When you have finished composing, type \\[mh-send-letter] to send the message
-using the MH mail handling system.
+When you have finished composing, type \\[mh-send-letter] to send the
+message using the MH mail handling system.

-There are two types of tags used by MH-E when composing MIME messages: MML and
-MH. The option `mh-compose-insertion' controls what type of tags are inserted
-by MH-E commands. These tags can be converted to MIME body parts by running
-\\[mh-mh-to-mime] for MH-style directives or \\[mh-mml-to-mime] for MML tags.
+There are two types of tags used by MH-E when composing MIME messages:
+MML and MH. The option `mh-compose-insertion' controls what type of
+tags are inserted by MH-E commands. These tags can be converted to
+MIME body parts by running \\[mh-mh-to-mime] for MH-style directives
+or \\[mh-mml-to-mime] for MML tags.

-Options that control this mode can be changed with \\[customize-group];
-specify the \"mh-compose\" group.
+Options that control this mode can be changed with
+\\[customize-group]; specify the \"mh-compose\" group.

 When a message is composed, the hooks `text-mode-hook' and
 `mh-letter-mode-hook' are run.
@@ -1143,21 +1147,24 @@
 ;;;###mh-autoload
 (defun mh-insert-signature (&optional file)
   "Insert signature in message.
+
 This command inserts your signature at the current cursor location.

 By default, the text of your signature is taken from the file
-\"~/.signature\". You can read from other sources by changing the option
-`mh-signature-file-name' or passing in a signature FILE.
+\"~/.signature\". You can read from other sources by changing the
+option `mh-signature-file-name'.

-A signature separator (\"-- \") will be added if the signature block does not
-contain one and `mh-signature-separator-flag' is on.
+A signature separator (\"-- \") will be added if the signature block
+does not contain one and `mh-signature-separator-flag' is on.

-The value of `mh-insert-signature-hook' is a list of functions to be
-called, with no arguments, after the signature is inserted. These functions
-may access the actual name of the file or the function used to insert the
-signature with `mh-signature-file-name'.
+The hook `mh-insert-signature-hook' is run after the signature is
+inserted. Hook functions may access the actual name of the file or the
+function used to insert the signature with `mh-signature-file-name'.

-The signature can also be inserted using Identities (see `mh-identity-list')"
+The signature can also be inserted using Identities (see
+`mh-identity-list').
+
+In a program, you can pass in a signature FILE."
   (interactive)
   (save-excursion
     (insert "\n")
@@ -1424,16 +1431,18 @@
 ;;;###mh-autoload
 (defun mh-send-letter (&optional arg)
   "Save draft and send message.
-When you are all through editing a message, you send it with this command. You
-can give an argument ARG to monitor the first stage of the delivery\; this
-output can be found in a buffer called \"*MH-E Mail Delivery*\".
+
+When you are all through editing a message, you send it with this
+command. You can give a prefix argument ARG to monitor the first stage
+of the delivery\; this output can be found in a buffer called \"*MH-E
+Mail Delivery*\".

-The value of `mh-before-send-letter-hook' is a list of functions to be called
-at the beginning of this command. For example, if you want to check your
-spelling in your message before sending, add the `ispell-message' function.
+The hook `mh-before-send-letter-hook' is run at the beginning of the
+this command. For example, if you want to check your spelling in your
+message before sending, add the `ispell-message' function.

-In case the MH \"send\" program is installed under a different name, use
-`mh-send-prog' to tell MH-E the name."
+In case the MH \"send\" program is installed under a different name,
+use `mh-send-prog' to tell MH-E the name."
   (interactive "P")
   (run-hooks 'mh-before-send-letter-hook)
   (if (and (mh-insert-auto-fields t)
@@ -1567,7 +1576,14 @@
 into your reply using `mh-yank-behavior'.

 If this isn't enough, you can gain full control over the appearance of the
-included text by setting `mail-citation-hook' to a function that modifies it."
+included text by setting `mail-citation-hook' to a function that modifies it.
+For example, if you set this hook to `trivial-cite' (which is NOT part of
+Emacs), set `mh-yank-behavior' to \"Body and Header\" (see URL
+`http://shasta.cs.uiuc.edu/~lrclause/tc.html').
+
+Note that if `mail-citation-hook' is set, `mh-ins-buf-prefix' is not inserted.
+If the option `mh-yank-behavior' is set to one of the supercite flavors, the
+hook `mail-citation-hook' is ignored and `mh-ins-buf-prefix' is not inserted."
   (interactive)
   (if (and mh-sent-from-folder
            (save-excursion (set-buffer mh-sent-from-folder) mh-show-buffer)
--- a/lisp/mh-e/mh-customize.el	Fri Dec 23 04:57:28 2005 +0000
+++ b/lisp/mh-e/mh-customize.el	Fri Dec 23 05:38:54 2005 +0000
@@ -850,7 +850,10 @@
 The prefix \"> \" is the default setting of this option. I suggest that you
 not modify this option since it is used by many mailers and news readers:
 messages are far easier to read if several included messages have all been
-indented by the same string."
+indented by the same string.
+
+This prefix is not inserted if you use one of the supercite flavors of
+`mh-yank-behavior' or you have added a `mail-citation-hook'."
   :type 'string
   :group 'mh-letter)

@@ -890,21 +893,22 @@
 (defcustom mh-signature-file-name "~/.signature"
   "*Source of user's signature.

-By default, the text of your signature is taken from the file \"~/.signature\".
-You can read from other files by changing this option. This file may contain a
-vCard in which case an attachment is added with the vCard.
-
-This option may also be a symbol, in which case that function is called. You
-may not want a signature separator to be added for you; instead you may want
-to insert one yourself. Options that you may find useful to do this include
-`mh-signature-separator' (when inserting a signature separator) and
-`mh-signature-separator-regexp' (for finding said separator). The function
-`mh-signature-separator-p', which reports t if the buffer contains a
-separator, may be useful as well.
+By default, the text of your signature is taken from the file
+\"~/.signature\". You can read from other sources by changing this
+option. This file may contain a vCard in which case an attachment is
+added with the vCard.
+
+This option may also be a symbol, in which case that function is
+called. You may not want a signature separator to be added for you;
+instead you may want to insert one yourself. Options that you may find
+useful to do this include `mh-signature-separator' (when inserting a
+signature separator) and `mh-signature-separator-regexp' (for finding
+said separator). The function `mh-signature-separator-p', which
+reports t if the buffer contains a separator, may be useful as well.

 The signature is inserted into your message with the command
-\\<mh-letter-mode-map>\\[mh-insert-signature] or with the `mh-identity-list'
-option."
+\\<mh-letter-mode-map>\\[mh-insert-signature] or with the
+`mh-identity-list' option."
   :type 'file
   :group 'mh-letter)

@@ -972,7 +976,10 @@

 If the show buffer has a region, the `mh-yank-behavior' option is ignored
 unless its value is one of Attribution variants in which case the attribution
-is added to the yanked region."
+is added to the yanked region.
+
+If this option is set to one of the supercite flavors, the hook
+`mail-citation-hook' is ignored and `mh-ins-buf-prefix' is not inserted."
   :type '(choice (const :tag "Body and Header" t)
                  (const :tag "Body" body)
                  (const :tag "Below Point" nil)
@@ -2227,39 +2234,48 @@

 ;;; Hooks (:group 'mh-hooks + group where hook described)

-(defcustom mail-citation-hook nil
-  "*Hook for modifying a citation just inserted in the mail buffer.
-You can gain full control over the appearance of the included text by setting
-this hook to a function that modifies it. This hook is ignored if the option
-`mh-yank-behavior' is set to one of the supercite flavors. Otherwise, this
-option controls how much of the message is passed to the hook. The function
-can find the citation between point and mark and it should leave point and
-mark around the modified citation text for the next hook function. The
-standard prefix `mh-ins-buf-prefix' is not added if this hook is set.
-
-For example, if you use the hook function trivial-cite (which is NOT part of
-Emacs), set `mh-yank-behavior' to \"Body and Header\" (see URL
-`http://shasta.cs.uiuc.edu/~lrclause/tc.html')."
+(defcustom mh-after-commands-processed-hook nil
+  "Hook run by \\<mh-folder-mode-map>\\[mh-execute-commands] after performing outstanding requests.
+
+Variables that are useful in this hook include `mh-folders-changed',
+which lists which folders were affected by deletes and refiles. This
+list will always include the current folder, which is also available
+in `mh-current-folder'."
   :type 'hook
-  :options '(trivial-cite)
   :group 'mh-hooks
-  :group 'mh-letter)
+  :group 'mh-folder)

 (defcustom mh-alias-reloaded-hook nil
-  "Invoked by `mh-alias-reload' after reloading aliases."
+  "Hook run by `mh-alias-reload' after loading aliases."
   :type 'hook
   :group 'mh-hooks
   :group 'mh-alias)

+(defcustom mh-before-commands-processed-hook nil
+  "Hook run by \\<mh-folder-mode-map>\\[mh-execute-commands] before performing outstanding requests.
+
+Variables that are useful in this hook include `mh-delete-list' and
+`mh-refile-list' which can be used to see which changes will be made
+to the current folder, `mh-current-folder'."
+  :type 'hook
+  :group 'mh-hooks
+  :group 'mh-folder)
+
 (defcustom mh-before-quit-hook nil
-  "Invoked by \\<mh-folder-mode-map>`\\[mh-quit]' before quitting MH-E.
+  "Hook run by \\<mh-folder-mode-map>\\[mh-quit] before quitting MH-E.
+
+This hook is called before the quit occurs, so you might use it to
+perform any MH-E operations; you could perform some query and abort
+the quit or call `mh-execute-commands', for example.
+
 See also `mh-quit-hook'."
   :type 'hook
   :group 'mh-hooks
   :group 'mh-folder)

 (defcustom mh-before-send-letter-hook nil
-  "Invoked at the beginning of the \\<mh-letter-mode-map>\\[mh-send-letter] command.
+  "Hook run at the beginning of the \\<mh-letter-mode-map>\\[mh-send-letter] command.
+
 For example, if you want to check your spelling in your message before
 sending, add the `ispell-message' function."
   :type 'hook
@@ -2268,135 +2284,137 @@
   :group 'mh-letter)

 (defcustom mh-delete-msg-hook nil
-  "Invoked after marking each message for deletion.
-
-For example, a past maintainer of MH-E used this once when he kept statistics
-on his mail usage."
+  "Hook run by \\<mh-letter-mode-map>\\[mh-delete-msg] after marking each message for deletion.
+
+For example, a past maintainer of MH-E used this once when he kept
+statistics on his mail usage."
   :type 'hook
   :group 'mh-hooks
   :group 'mh-show)

-(defcustom mh-mh-to-mime-hook nil
-  "Invoked on the formatted letter by \\<mh-letter-mode-map>\\[mh-mh-to-mime]."
-  :type 'hook
-  :group 'mh-hooks
-  :group 'mh-letter)
-
 (defcustom mh-find-path-hook nil
-  "Invoked by `mh-find-path' after reading the user's MH profile."
+  "Hook run by `mh-find-path' after reading the user's MH profile.
+
+This hook can be used the change the value of the variables that
+`mh-find-path' sets if you need to run with different values between
+MH and MH-E."
   :type 'hook
   :group 'mh-hooks
   :group 'mh-e)

 (defcustom mh-folder-mode-hook nil
-  "Invoked in `mh-folder-mode' on a new folder."
-  :type 'hook
-  :group 'mh-hooks
-  :group 'mh-folder)
-
-(defcustom mh-before-commands-processed-hook nil
-  "Invoked before the folder actions (such as moves and deletes) are performed.
-Variables that are useful in this hook include `mh-delete-list' and
-`mh-refile-list' which can be used to see which changes will be made to
-current folder, `mh-current-folder'."
+  "Hook run by `mh-folder-mode' when visiting a new folder."
   :type 'hook
   :group 'mh-hooks
   :group 'mh-folder)

-(defcustom mh-after-commands-processed-hook nil
-  "Invoked after the folder actions (such as moves and deletes) are performed.
-Variables that are useful in this hook include `mh-folders-changed',
-which lists which folders were affected by deletes and refiles.  This
-list will always include the current folder, which is also available
-in `mh-current-folder'."
-  :type 'hook
-  :group 'mh-hooks)
-
 (defcustom mh-forward-hook nil
-  "Invoked on the forwarded letter by \\<mh-folder-mode-map>\\[mh-forward]."
+  "Hook run by `mh-forward' on a forwarded letter."
   :type 'hook
   :group 'mh-hooks
   :group 'mh-sending-mail)

 (defcustom mh-inc-folder-hook nil
-  "Invoked by \\<mh-folder-mode-map>`\\[mh-inc-folder]' after incorporating mail into a folder."
+  "Hook run by \\<mh-folder-mode-map>\\[mh-inc-folder] after incorporating mail into a folder."
   :type 'hook
   :group 'mh-hooks
   :group 'mh-inc)

 (defcustom mh-insert-signature-hook nil
-  "Invoked after signature has been inserted.
-
-These functions may access the actual name of the file or the function used to
-insert the signature with `mh-signature-file-name'."
+  "Hook run by \\<mh-letter-mode-map>\\[mh-insert-signature] after signature has been inserted.
+
+Hook functions may access the actual name of the file or the function
+used to insert the signature with `mh-signature-file-name'."
   :type 'hook
   :group 'mh-hooks
   :group 'mh-letter)

-(defcustom mh-kill-folder-suppress-prompt-hook '(mh-index-p)
-  "Invoked at the beginning of the  \\<mh-folder-mode-map>`\\[mh-kill-folder]' command.
-This hook is a list of functions to be called, with no arguments, which should
-return a value of non-nil if you should not be asked if you're sure that you
-want to remove the folder. This is useful for folders that are easily
-regenerated.
-
-The default value of `mh-index-p' suppresses the prompt on folders generated
-by an index search.
-
-WARNING: Use this hook with care. If there is a bug in your hook which returns
-t on +inbox and you hit \\<mh-folder-mode-map>`\\[mh-kill-folder]' by accident
-in the +inbox buffer, you will not be happy."
+(defcustom mh-kill-folder-suppress-prompt-hooks '(mh-index-p)
+  "Abnormal hook run at the beginning of \\<mh-folder-mode-map>\\[mh-kill-folder].
+
+The hook functions are called with no arguments and should return a
+non-nil value to suppress the normal prompt when you remove a folder.
+This is useful for folders that are easily regenerated.
+
+The default value of `mh-index-p' suppresses the prompt on folders
+generated by an index search.
+
+WARNING: Use this hook with care. If there is a bug in your hook which
+returns t on \"+inbox\" and you hit \\[mh-kill-folder] by accident in
+the \"+inbox\" folder, you will not be happy."
   :type 'hook
   :group 'mh-hooks
   :group 'mh-folder)

 (defcustom mh-letter-mode-hook nil
-  "Invoked by `mh-letter-mode' on a new letter."
+  "Hook run by `mh-letter-mode' on a new letter.
+
+This hook allows you to do some processing before editing a letter.
+For example, you may wish to modify the header after \"repl\" has done
+its work, or you may have a complicated \"components\" file and need
+to tell MH-E where the cursor should go."
   :type 'hook
   :group 'mh-hooks
   :group 'mh-sending-mail)

+(defcustom mh-mh-to-mime-hook nil
+  "Hook run on the formatted letter by \\<mh-letter-mode-map>\\[mh-mh-to-mime]."
+  :type 'hook
+  :group 'mh-hooks
+  :group 'mh-letter)
+
 (defcustom mh-pick-mode-hook nil
-  "Invoked upon entry to `mh-pick-mode'."
+  "Hook run upon entry to `mh-pick-mode'\\<mh-folder-mode-map>.
+
+If you find that you do the same thing over and over when editing the
+search template, you may wish to bind some shortcuts to keys. This can
+be done with this hook which is called when \\[mh-search-folder] is
+run on a new pattern."
   :type 'hook
   :group 'mh-hooks
   :group 'mh-index)

 (defcustom mh-quit-hook nil
-  "Invoked after \\<mh-folder-mode-map>`\\[mh-quit]' quits MH-E.
+  "Hook run by \\<mh-folder-mode-map>\\[mh-quit] after quitting MH-E.
+
+This hook is not run in an MH-E context, so you might use it to modify
+the window setup.
+
 See also `mh-before-quit-hook'."
   :type 'hook
   :group 'mh-hooks
   :group 'mh-folder)

 (defcustom mh-refile-msg-hook nil
-  "Invoked after marking each message for refiling."
+  "Hook run by \\<mh-folder-mode-map>\\[mh-refile-msg] after marking each message for refiling."
   :type 'hook
   :group 'mh-hooks
   :group 'mh-folder)

 (defcustom mh-show-hook nil
-  "Invoked after \\<mh-folder-mode-map>\\[mh-show] shows a message.
-
-It is the last thing called after messages are displayed. It's used to affect
-the behavior of MH-E in general or when `mh-show-mode-hook' is too early."
+  "Hook run after \\<mh-folder-mode-map>\\[mh-show] shows a message.
+
+It is the last thing called after messages are displayed. It's used to
+affect the behavior of MH-E in general or when `mh-show-mode-hook' is
+too early."
   :type 'hook
   :group 'mh-hooks
   :group 'mh-show)

 (defcustom mh-show-mode-hook nil
-  "Invoked upon entry to `mh-show-mode'.
-
-This hook is called early on in the process of the message display. It is
-usually used to perform some action on the message's content."
+  "Hook run upon entry to `mh-show-mode'.
+
+This hook is called early on in the process of the message display. It
+is usually used to perform some action on the message's content."
   :type 'hook
   :group 'mh-hooks
   :group 'mh-show)

 (defcustom mh-unseen-updated-hook nil
-  "Invoked after the unseen sequence has been updated.
-The variable `mh-seen-list' can be used to obtain the list of messages which
-will be removed from the unseen sequence."
+  "Hook run after the unseen sequence has been updated.
+
+The variable `mh-seen-list' can be used by this hook to obtain the
+list of messages which were removed from the unseen sequence."
   :type 'hook
   :group 'mh-hooks
   :group 'mh-sequences)
--- a/lisp/mh-e/mh-e.el	Fri Dec 23 04:57:28 2005 +0000
+++ b/lisp/mh-e/mh-e.el	Fri Dec 23 05:38:54 2005 +0000
@@ -446,45 +446,66 @@

 ;;; Internal variables:

-(defvar mh-last-destination nil)        ;Destination of last refile or write
-                                        ;command.
-(defvar mh-last-destination-folder nil) ;Destination of last refile command.
-(defvar mh-last-destination-write nil)  ;Destination of last write command.
+(defvar mh-last-destination nil
+  "Destination of last refile or write command.")
+
+(defvar mh-last-destination-folder nil
+  "Destination of last refile command.")
+
+(defvar mh-last-destination-write nil
+  "Destination of last write command.")

 (defvar mh-folder-mode-map (make-keymap)
   "Keymap for MH folders.")

-(defvar mh-arrow-marker nil)            ;Marker for arrow display in fringe.
-
-(defvar mh-delete-list nil)             ;List of msg numbers to delete.
+(defvar mh-arrow-marker nil
+  "Marker for arrow display in fringe.")

-(defvar mh-refile-list nil)             ;List of folder names in mh-seq-list.
+(defvar mh-delete-list nil
+  "List of message numbers to delete.
+This variable can be used by `mh-before-commands-processed-hook'.")

-(defvar mh-folders-changed nil)         ;For mh-after-commands-processed-hook.
+(defvar mh-refile-list nil
+  "List of folder names in `mh-seq-list'.
+This variable can be used by `mh-before-commands-processed-hook'.")

-(defvar mh-next-direction 'forward)     ;Direction to move to next message.
+(defvar mh-folders-changed nil
+  "Lists which folders were affected by deletes and refiles.
+This list will always include the current folder `mh-current-folder'.
+This variable can be used by `mh-before-commands-processed-hook'.")
+
+(defvar mh-next-direction 'forward
+  "Direction to move to next message.")

-(defvar mh-view-ops ())                 ;Stack of ops that change the folder
-                                        ;view (such as narrowing or threading).
-(defvar mh-folder-view-stack ())        ;Stack of previous folder views.
+(defvar mh-view-ops ()
+  "Stack of operations that change the folder view.
+These operations include narrowing or threading.")

-(defvar mh-index-data nil)              ;Info about index search results
+(defvar mh-folder-view-stack ()
+  "Stack of previous folder views.")
+
+(defvar mh-index-data nil
+  "Info about index search results.")
+
 (defvar mh-index-previous-search nil)
 (defvar mh-index-msg-checksum-map nil)
 (defvar mh-index-checksum-origin-map nil)
 (defvar mh-index-sequence-search-flag nil)

-(defvar mh-first-msg-num nil)           ;Number of first msg in buffer.
+(defvar mh-first-msg-num nil
+  "Number of first message in buffer.")

-(defvar mh-last-msg-num nil)            ;Number of last msg in buffer.
-
-(defvar mh-mode-line-annotation nil)    ;Message range displayed in buffer.
+(defvar mh-last-msg-num nil
+  "Number of last msg in buffer.")

-(defvar mh-sequence-notation-history nil)
-                                        ;Rememeber original notation that
-                                        ;is overwritten by `mh-note-seq'.
+(defvar mh-mode-line-annotation nil
+  "Message range displayed in buffer.")

-(defvar mh-colors-available-flag nil)   ;Are colors available?
+(defvar mh-sequence-notation-history nil
+  "Remember original notation that is overwritten by `mh-note-seq'.")
+
+(defvar mh-colors-available-flag nil
+  "Non-nil means colors are available.")


@@ -550,11 +571,16 @@
 commands to move forward to the next undeleted message after deleting the
 message under the cursor.

+The hook `mh-delete-msg-hook' is called after you mark a message for deletion.
+For example, a past maintainer of MH-E used this once when he kept statistics
+on his mail usage.
+
 Check the documentation of `mh-interactive-range' to see how RANGE is read in
 interactive use."
   (interactive (list (mh-interactive-range "Delete")))
   (mh-delete-msg-no-motion range)
-  (if (looking-at mh-scan-deleted-msg-regexp) (mh-next-msg)))
+  (if (looking-at mh-scan-deleted-msg-regexp)
+      (mh-next-msg)))

 (defun mh-delete-msg-no-motion (range)
   "Delete RANGE, don't move to next message.
@@ -569,7 +595,18 @@
     (mh-delete-a-msg nil)))

 (defun mh-execute-commands ()
-  "Process outstanding delete and refile requests."
+  "Process outstanding delete and refile requests\\<mh-folder-mode-map>.
+
+If you've marked messages to be deleted or refiled and you want to go ahead
+and delete or refile the messages, use this command. Many MH-E commands that
+may affect the numbering of the messages (such as \\[mh-rescan-folder] or
+\\[mh-pack-folder]) will ask if you want to process refiles or deletes first
+and then either run this command for you or undo the pending refiles and
+deletes, which are lost.
+
+This function runs `mh-before-commands-processed-hook' before the commands are
+processed and `mh-after-commands-processed-hook' after the commands are
+processed."
   (interactive)
   (if mh-folder-view-stack (mh-widen t))
   (mh-process-commands mh-current-folder)
@@ -603,13 +640,18 @@
     (setq mh-showing-with-headers t)))

 (defun mh-inc-folder (&optional maildrop-name folder)
-  "Inc(orporate)s new mail into the Inbox folder.
-Optional argument MAILDROP-NAME specifies an alternate maildrop from the
-default. The optional argument FOLDER specifies where to incorporate mail
-instead of the default named by `mh-inbox'.
-The value of `mh-inc-folder-hook' is a list of functions to be called, with no
-arguments, after incorporating new mail.
-Do not call this function from outside MH-E; use \\[mh-rmail] instead."
+  "Incorporate new mail into a folder.
+
+You can incorporate mail from any file into the current folder by
+specifying a prefix argument; you'll be prompted for the name of the
+file to use as well as the destination folder
+
+The hook `mh-inc-folder-hook' is run after incorporating new mail. Do
+not call this function from outside MH-E; use \\[mh-rmail] instead.
+
+In a program optional argument MAILDROP-NAME specifies an alternate
+maildrop from the default. The optional argument FOLDER specifies
+where to incorporate mail instead of the default named by `mh-inbox'."
   (interactive (list (if current-prefix-arg
                          (expand-file-name
                           (read-file-name "inc mail from file: "
@@ -760,8 +802,9 @@
 Check the documentation of `mh-interactive-range' to see how RANGE is read in
 interactive use.

-If DONT-UPDATE-LAST-DESTINATION-FLAG is non-nil, then the variables
-`mh-last-destination' and `mh-last-destination-folder' are not updated."
+In a program, the variables `mh-last-destination' and
+`mh-last-destination-folder' are not updated if
+DONT-UPDATE-LAST-DESTINATION-FLAG is non-nil."
   (interactive (list (mh-interactive-range "Refile")
                      (intern (mh-prompt-for-refile-folder))))
   (unless dont-update-last-destination-flag
@@ -796,13 +839,19 @@

 (defun mh-quit ()
   "Quit the current MH-E folder.
-Restore the previous window configuration, if one exists.
-The value of `mh-before-quit-hook' is a list of functions to be called, with
-no arguments, immediately upon entry to this function.
-The value of `mh-quit-hook' is a list of functions to be called, with no
-arguments, upon exit of this function.
-MH-E working buffers (whose name begins with \" *mh-\" or \"*MH-E \") are
-killed."
+
+When you want to quit using MH-E and go back to editing, you can use this
+command. This buries the buffers of the current MH-E folder and restores the
+buffers that were present when you first ran \\[mh-rmail]. It also removes any
+MH-E working buffers whose name begins with \" *mh-\" or \"*MH-E \". You can
+later restore your MH-E session by selecting the \"+inbox\" buffer or by
+running \\[mh-rmail] again.
+
+The two hooks `mh-before-quit-hook' and `mh-quit-hook' are called by this
+function. The former one is called before the quit occurs, so you might use it
+to perform any MH-E operations; you could perform some query and abort the
+quit or call `mh-execute-commands', for example. The latter is not run in an
+MH-E context, so you might use it to modify the window setup."
   (interactive)
   (run-hooks 'mh-before-quit-hook)
   (let ((show-buffer (get-buffer mh-show-buffer)))
@@ -1368,44 +1417,45 @@

 ;;; Support routines.

-(defun mh-delete-a-msg (msg)
-  "Delete the MSG.
-If MSG is nil then the message at point is deleted.
+(defun mh-delete-a-msg (message)
+  "Delete MESSAGE.
+If MESSAGE is nil then the message at point is deleted.

-The value of `mh-delete-msg-hook' is a list of functions to be called, with no
-arguments, after the message has been deleted."
+The hook `mh-delete-msg-hook' is called after you mark a message for deletion.
+For example, a past maintainer of MH-E used this once when he kept statistics
+on his mail usage."
   (save-excursion
-    (if (numberp msg)
-        (mh-goto-msg msg nil t)
+    (if (numberp message)
+        (mh-goto-msg message nil t)
       (beginning-of-line)
-      (setq msg (mh-get-msg-num t)))
+      (setq message (mh-get-msg-num t)))
     (if (looking-at mh-scan-refiled-msg-regexp)
-        (error "Message %d is refiled.  Undo refile before deleting" msg))
+        (error "Message %d is refiled.  Undo refile before deleting" message))
     (if (looking-at mh-scan-deleted-msg-regexp)
         nil
       (mh-set-folder-modified-p t)
-      (setq mh-delete-list (cons msg mh-delete-list))
+      (setq mh-delete-list (cons message mh-delete-list))
       (mh-notate nil mh-note-deleted mh-cmd-note)
       (run-hooks 'mh-delete-msg-hook))))

-(defun mh-refile-a-msg (msg folder)
-  "Refile MSG in FOLDER.
-If MSG is nil then the message at point is refiled.
+(defun mh-refile-a-msg (message folder)
+  "Refile MESSAGE in FOLDER.
+If MESSAGE is nil then the message at point is refiled.

 Folder is a symbol, not a string.
-The value of `mh-refile-msg-hook' is a list of functions to be called, with no
-arguments, after the message has been refiled."
+The hook `mh-refile-msg-hook' is called after a message is marked to be
+refiled."
   (save-excursion
-    (if (numberp msg)
-        (mh-goto-msg msg nil t)
+    (if (numberp message)
+        (mh-goto-msg message nil t)
       (beginning-of-line)
-      (setq msg (mh-get-msg-num t)))
+      (setq message (mh-get-msg-num t)))
     (cond ((looking-at mh-scan-deleted-msg-regexp)
-           (error "Message %d is deleted.  Undo delete before moving" msg))
+           (error "Message %d is deleted.  Undo delete before moving" message))
           ((looking-at mh-scan-refiled-msg-regexp)
            (if (y-or-n-p
                 (format "Message %d already refiled.  Copy to %s as well? "
-                        msg folder))
+                        message folder))
                (mh-exec-cmd "refile" (mh-get-msg-num t) "-link"
                             "-src" mh-current-folder
                             (symbol-name folder))
@@ -1413,9 +1463,9 @@
           (t
            (mh-set-folder-modified-p t)
            (cond ((null (assoc folder mh-refile-list))
-                  (push (list folder msg) mh-refile-list))
-                 ((not (member msg (cdr (assoc folder mh-refile-list))))
-                  (push msg (cdr (assoc folder mh-refile-list)))))
+                  (push (list folder message) mh-refile-list))
+                 ((not (member message (cdr (assoc folder mh-refile-list))))
+                  (push message (cdr (assoc folder mh-refile-list)))))
            (mh-notate nil mh-note-refiled mh-cmd-note)
            (run-hooks 'mh-refile-msg-hook)))))

@@ -2151,10 +2201,10 @@

 (defun mh-process-commands (folder)
   "Process outstanding commands for FOLDER.
-The value of `mh-before-commands-processed-hook' is a list of functions
-to be called, with no arguments, before the commands are processed.
-After all cammands are processed, the functions in
-`mh-after-commands-processed-hook' are called with no arguments."
+
+This function runs `mh-before-commands-processed-hook' before the commands are
+processed and `mh-after-commands-processed-hook' after the commands are
+processed."
   (message "Processing deletes and refiles for %s..." folder)
   (set-buffer folder)
   (with-mh-folder-updating (nil)
@@ -2238,7 +2288,7 @@
       (mh-remove-all-notation)
       (mh-notate-user-sequences)

-      ;; Run the after hook -- now folders-changed is valid,
+      ;; Run the after hook -- now folders-changed is valid,
       ;; but not the lists of specific messages.
       (let ((mh-folders-changed folders-changed))
         (run-hooks 'mh-after-commands-processed-hook)))
@@ -2248,8 +2298,8 @@
 (defun mh-update-unseen ()
   "Synchronize the unseen sequence with MH.
 Return non-nil iff the MH folder was set.
-The value of `mh-unseen-updated-hook' is a list of functions to be called,
-with no arguments, after the unseen sequence is updated."
+The hook `mh-unseen-updated-hook' is called after the unseen sequence
+is updated."
   (if mh-seen-list
       (let* ((unseen-seq (mh-find-seq mh-unseen-seq))
              (unseen-msgs (mh-seq-msgs unseen-seq)))
--- a/lisp/mh-e/mh-funcs.el	Fri Dec 23 04:57:28 2005 +0000
+++ b/lisp/mh-e/mh-funcs.el	Fri Dec 23 05:38:54 2005 +0000
@@ -106,15 +106,18 @@

 ;;;###mh-autoload
 (defun mh-kill-folder ()
-  "Remove the current folder and all included messages.
-Removes all of the messages (files) within the specified current folder,
-and then removes the folder (directory) itself.
-The value of `mh-kill-folder-suppress-prompt-hook' is a list of functions to
-be called, with no arguments, which should return a value of non-nil if
-verification is not desired."
+  "Remove folder.
+
+Remove all of the messages (files) within the current folder, and then
+remove the folder (directory) itself.
+
+Run the abnormal hook `mh-kill-folder-suppress-prompt-hooks'. The hook
+functions are called with no arguments and should return a non-nil
+value to suppress the normal prompt when you remove a folder. This is
+useful for folders that are easily regenerated."
   (interactive)
   (if (or (run-hook-with-args-until-success
-           'mh-kill-folder-suppress-prompt-hook)
+           'mh-kill-folder-suppress-prompt-hooks)
           (yes-or-no-p (format "Remove folder %s (and all included messages)? "
                                mh-current-folder)))
       (let ((folder mh-current-folder)
--- a/lisp/mh-e/mh-mime.el	Fri Dec 23 04:57:28 2005 +0000
+++ b/lisp/mh-e/mh-mime.el	Fri Dec 23 05:38:54 2005 +0000
@@ -419,6 +419,7 @@
 ;;;###mh-autoload
 (defun mh-mh-to-mime (&optional extra-args)
   "Compose MIME message from MH-style directives.
+
 Typically, you send a message with attachments just like any other message.
 However, you may take a sneak preview of the MIME encoding if you wish by
 running this command.
@@ -431,8 +432,8 @@
 message has been corrupted on the way. This command only consults this option
 when given a prefix argument EXTRA-ARGS.

-The value of `mh-mh-to-mime-hook' is a list of functions to be called after
-the message has been formatted.
+The hook `mh-mh-to-mime-hook' is called after the message has been
+formatted.

 The effects of this command can be undone by running \\[mh-mh-to-mime-undo]."
   (interactive "*P")
--- a/lisp/mh-e/mh-pick.el	Fri Dec 23 04:57:28 2005 +0000
+++ b/lisp/mh-e/mh-pick.el	Fri Dec 23 05:38:54 2005 +0000
@@ -203,8 +203,7 @@
 To effect a logical \"or\", use \\[mh-search-folder] multiple times.
 When you have finished, type  \\[mh-pick-do-search]  to do the search.

-The value of `mh-pick-mode-hook' is a list of functions to be called,
-with no arguments, upon entry to this mode.
+The hook `mh-pick-mode-hook' is called upon entry to this mode.

 \\{mh-pick-mode-map}"
--- a/lisp/mh-e/mh-utils.el	Fri Dec 23 04:57:28 2005 +0000
+++ b/lisp/mh-e/mh-utils.el	Fri Dec 23 05:38:54 2005 +0000
@@ -566,25 +566,25 @@
             (cons modeline-buffer-id-left-extent "XEmacs%N:"))
           (cons modeline-buffer-id-right-extent " %17b")))))

-;; This holds a documentation string used by describe-mode.
 (defun mh-showing-mode (&optional arg)
   "Change whether messages should be displayed.
-With arg, display messages iff ARG is positive."
+
+With ARG, display messages iff ARG is positive."
   (setq mh-showing-mode
         (if (null arg)
             (not mh-showing-mode)
           (> (prefix-numeric-value arg) 0))))

-;; The sequences of this folder.  An alist of (seq . msgs).
-(defvar mh-seq-list nil)
+(defvar mh-seq-list nil
+  "Alist of this folder's sequences.
+Elements have the form (SEQUENCE . MESSAGES).")

-;; List of displayed messages to be removed from the Unseen sequence.
-(defvar mh-seen-list nil)
+(defvar mh-seen-list nil
+  "List of displayed messages to be removed from the \"Unseen\" sequence.")

-;; If non-nil, show buffer contains message with all headers.
-;; If nil, show buffer contains message processed normally.
-;; Showing message with headers or normally.
-(defvar mh-showing-with-headers nil)
+(defvar mh-showing-with-headers nil
+  "If non-nil, MH-Show buffer contains message with all header fields.
+If nil, MH-Show buffer contains message processed normally.")


@@ -1108,8 +1108,9 @@

 (define-derived-mode mh-show-mode text-mode "MH-Show"
   "Major mode for showing messages in MH-E.\\<mh-show-mode-map>
-The value of `mh-show-mode-hook' is a list of functions to
-be called, with no arguments, upon entry to this mode.
+
+The hook `mh-show-mode-hook' is called upon entry to this mode.
+
 See also `mh-folder-mode'.

 \\{mh-show-mode-map}"
@@ -1610,8 +1611,9 @@

 (defun mh-show-msg (msg)
   "Show MSG.
-The value of `mh-show-hook' is a list of functions to be called, with no
-arguments, after the message has been displayed."
+
+The hook `mh-show-hook' is called after the message has been
+displayed."
   (if (not msg)
       (setq msg (mh-get-msg-num t)))
   (mh-showing-mode t)
@@ -1904,10 +1906,16 @@

 (defun mh-find-path ()
   "Set variables from user's MH profile.
-Set `mh-user-path', `mh-draft-folder', `mh-unseen-seq', `mh-previous-seq',
-`mh-inbox' from user's MH profile.
-The value of `mh-find-path-hook' is a list of functions to be called, with no
-arguments, after these variable have been set."
+
+This function sets `mh-user-path' from your \"Path:\" MH profile
+component (but defaults to \"Mail\" if one isn't present),
+`mh-draft-folder' from \"Draft-Folder:\", `mh-unseen-seq' from
+\"Unseen-Sequence:\", `mh-previous-seq' from \"Previous-Sequence:\",
+and `mh-inbox' from \"Inbox:\" (defaults to \"+inbox\").
+
+The hook `mh-find-path-hook' is run after these variables have been
+set. This hook can be used the change the value of these variables if
+you need to run with different values between MH and MH-E."
   (mh-variants)
   (unless mh-find-path-run
     (setq mh-find-path-run t)