* 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.

9 files changed, 386 insertions, 228 deletions

diff --git a/lisp/mh-e/ChangeLog b/lisp/mh-e/ChangeLog
index dce4b1def32..613fcc49cd4 100644
--- a/lisp/mh-e/ChangeLog
+++ b/lisp/mh-e/ChangeLog
@@ -1,3 +1,66 @@
+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-kill-folder-suppress-prompt-hooks): Rename
+	from mh-kill-folder-suppress-prompt-hook since it is an abnormal
+	hook. Use "Hook run by `function'..." instead of "Invoked...".
+	Sync docstrings with manual.
+	(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-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): Use "Hook run by `function'..." instead
+	of "Invoked...". Sync docstrings with manual.
+
+	* 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.
diff --git a/lisp/mh-e/mh-alias.el b/lisp/mh-e/mh-alias.el
index f82a0ea24dc..1fbcdea0b18 100644
--- a/lisp/mh-e/mh-alias.el
+++ b/lisp/mh-e/mh-alias.el
@@ -183,14 +183,14 @@ Exclude all aliases already in `mh-alias-alist' from `ali'"
 (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.
-
-The value of `mh-alias-reloaded-hook' is a list of functions to be called,
-with no arguments, after the aliases have been loaded."
+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.
+
+This function runs `mh-alias-reloaded-hook' after the aliases have been
+loaded."
   (interactive)
   (save-excursion
     (message "Loading MH aliases...")
diff --git a/lisp/mh-e/mh-comp.el b/lisp/mh-e/mh-comp.el
index 47999fbbeff..a28fa3e9e9e 100644
--- a/lisp/mh-e/mh-comp.el
+++ b/lisp/mh-e/mh-comp.el
@@ -335,15 +335,18 @@ See also `mh-send'."
 (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 @@ work better in MH-Letter mode (see `mh-letter-mode')."
 
 ;;;###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 @@ the draft."
 ;;;###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 @@ there."
 ;;;###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*\".
 
-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.
+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 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 @@ You can control how the message to which you are replying is yanked
 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)
diff --git a/lisp/mh-e/mh-customize.el b/lisp/mh-e/mh-customize.el
index 0e22e38a742..779a25cf03c 100644
--- a/lisp/mh-e/mh-customize.el
+++ b/lisp/mh-e/mh-customize.el
@@ -850,7 +850,10 @@ to enter your own verb."
 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 @@ that you can read the mail you write!"
 (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.
+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.
+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 @@ never displayed.
 
 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 @@ This button runs `mh-previous-undeleted-msg'")
 
 ;;; 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 @@ sending, add the `ispell-message' function."
   :group 'mh-letter)
 
 (defcustom mh-delete-msg-hook nil
-  "Invoked after marking each message for deletion.
+  "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."
+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.
+  "Hook run by \\<mh-letter-mode-map>\\[mh-insert-signature] 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 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.
+(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.
+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."
+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.
+  "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."
+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'.
+  "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."
+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)
diff --git a/lisp/mh-e/mh-e.el b/lisp/mh-e/mh-e.el
index 0c8c3346ecb..e0a8c3a004f 100644
--- a/lisp/mh-e/mh-e.el
+++ b/lisp/mh-e/mh-e.el
@@ -446,45 +446,66 @@ is done highlighting.")
 
 ;;; 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-arrow-marker nil
+  "Marker for arrow display in fringe.")
+
+(defvar mh-delete-list nil
+  "List of message numbers to delete.
+This variable can be used by `mh-before-commands-processed-hook'.")
 
-(defvar mh-delete-list nil)             ;List of msg numbers to delete.
+(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-refile-list nil)             ;List of folder names in mh-seq-list.
+(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-folders-changed nil)         ;For mh-after-commands-processed-hook.
+(defvar mh-next-direction 'forward
+  "Direction to move to next message.")
 
-(defvar mh-next-direction 'forward)     ;Direction to move to next message.
+(defvar mh-view-ops ()
+  "Stack of operations that change the folder view.
+These operations include narrowing or threading.")
 
-(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-folder-view-stack ()
+  "Stack of previous folder views.")
+
+(defvar mh-index-data nil
+  "Info about index search results.")
 
-(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-last-msg-num nil
+  "Number of last msg in buffer.")
 
-(defvar mh-mode-line-annotation nil)    ;Message range displayed in buffer.
+(defvar mh-mode-line-annotation nil
+  "Message range displayed in buffer.")
 
-(defvar mh-sequence-notation-history nil)
-                                        ;Rememeber original notation that
-                                        ;is overwritten by `mh-note-seq'.
+(defvar mh-sequence-notation-history nil
+  "Remember original notation that is overwritten by `mh-note-seq'.")
 
-(defvar mh-colors-available-flag nil)   ;Are colors available?
+(defvar mh-colors-available-flag nil
+  "Non-nil means colors are available.")
 
 
 
@@ -550,11 +571,16 @@ deleted. Use \\[mh-next-undeleted-msg] to force subsequent \\[mh-delete-msg]
 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 @@ interactive use."
     (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 @@ Use the command \\[mh-show] to show the message normally again."
     (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 @@ refiled.
 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 @@ interactively."
 
 (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 @@ option which is \"tick\" by default. The message at the cursor is used for
 
 ;;; 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 @@ arguments, after the message has been refiled."
           (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 @@ Called by functions like `mh-sort-folder', so also invalidate show buffer."
 
 (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 @@ After all cammands are processed, the functions in
       (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 @@ After all cammands are processed, the functions in
 (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)))
diff --git a/lisp/mh-e/mh-funcs.el b/lisp/mh-e/mh-funcs.el
index 813d8a07b6c..ee8e757e728 100644
--- a/lisp/mh-e/mh-funcs.el
+++ b/lisp/mh-e/mh-funcs.el
@@ -106,15 +106,18 @@ interactive use."
 
 ;;;###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)
diff --git a/lisp/mh-e/mh-mime.el b/lisp/mh-e/mh-mime.el
index bb2fc2b8f50..e8b4b2dd2c0 100644
--- a/lisp/mh-e/mh-mime.el
+++ b/lisp/mh-e/mh-mime.el
@@ -419,6 +419,7 @@ See also \\[mh-mh-to-mime]."
 ;;;###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 @@ you can build a consistency check into the message by setting
 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")
diff --git a/lisp/mh-e/mh-pick.el b/lisp/mh-e/mh-pick.el
index a20172ba6f3..5a0a5e6c859 100644
--- a/lisp/mh-e/mh-pick.el
+++ b/lisp/mh-e/mh-pick.el
@@ -203,8 +203,7 @@ Each non-empty field must be matched for a message to be selected.
 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}"
 
diff --git a/lisp/mh-e/mh-utils.el b/lisp/mh-e/mh-utils.el
index e39d141b70b..65e1f2ac9a1 100644
--- a/lisp/mh-e/mh-utils.el
+++ b/lisp/mh-e/mh-utils.el
@@ -566,25 +566,25 @@ about the fontification operation."
             (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 @@ still visible.\n")
 
 (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 @@ The current frame height is taken into consideration."
 
 (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 @@ Returns nil if the field is not in the buffer."
 
 (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)