# HG changeset patch # User Bill Wohler # Date 1135316334 0 # Node ID 7ff92ad9932611f5a93f88301241cc4d4b46df36 # Parent 0cdb122ad4db74972feae8cf1eba9121079b8ba7 * 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. diff -r 0cdb122ad4db -r 7ff92ad99326 lisp/mh-e/ChangeLog --- 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 + + * 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. diff -r 0cdb122ad4db -r 7ff92ad99326 lisp/mh-e/mh-alias.el --- 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...") diff -r 0cdb122ad4db -r 7ff92ad99326 lisp/mh-e/mh-comp.el --- 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.\\ + "Mode for composing letters in MH-E\\. -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) diff -r 0cdb122ad4db -r 7ff92ad99326 lisp/mh-e/mh-customize.el --- 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-insert-signature] or with the `mh-identity-list' -option." +\\\\[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-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-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-quit]' before quitting MH-E. + "Hook run by \\\\[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-send-letter] command. + "Hook run at the beginning of the \\\\[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-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-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-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-inc-folder]' after incorporating mail into a folder." + "Hook run by \\\\[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-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-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-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-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-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'\\. + +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-quit]' quits MH-E. + "Hook run by \\\\[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-refile-msg] after marking each message for refiling." :type 'hook :group 'mh-hooks :group 'mh-folder) (defcustom mh-show-hook nil - "Invoked after \\\\[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-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) diff -r 0cdb122ad4db -r 7ff92ad99326 lisp/mh-e/mh-e.el --- 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\\. + +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))) diff -r 0cdb122ad4db -r 7ff92ad99326 lisp/mh-e/mh-funcs.el --- 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) diff -r 0cdb122ad4db -r 7ff92ad99326 lisp/mh-e/mh-mime.el --- 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") diff -r 0cdb122ad4db -r 7ff92ad99326 lisp/mh-e/mh-pick.el --- 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}" diff -r 0cdb122ad4db -r 7ff92ad99326 lisp/mh-e/mh-utils.el --- 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.\\ -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)