diff lisp/mh-e/mh-mime.el @ 67758:6b063593fdad

Follow Emacs coding conventions. Use default setting of emacs-lisp-docstring-fill-column which is 65.

--- a/lisp/mh-e/mh-mime.el	Fri Dec 23 05:40:21 2005 +0000
+++ b/lisp/mh-e/mh-mime.el	Fri Dec 23 07:40:40 2005 +0000
@@ -55,12 +55,15 @@
 ;;;###mh-autoload
 (defun mh-compose-insertion (&optional inline)
   "Add tag to include a file such as an image or sound.
-You are prompted for the filename containing the object, the media type if it
-cannot be determined automatically, and a content description. If you're using
-MH-style directives, you will also be prompted for additional attributes.
 
-The option `mh-compose-insertion' controls what type of tags are inserted.
-Optional argument INLINE means make it an inline attachment."
+You are prompted for the filename containing the object, the
+media type if it cannot be determined automatically, and a
+content description. If you're using MH-style directives, you
+will also be prompted for additional attributes.
+
+The option `mh-compose-insertion' controls what type of tags are
+inserted. Optional argument INLINE means make it an inline
+attachment."
   (interactive "P")
   (if (equal mh-compose-insertion 'mml)
       (if inline
@@ -71,8 +74,10 @@
 ;;;###mh-autoload
 (defun mh-compose-forward (&optional description folder messages)
   "Add tag to forward a message.
-You are prompted for a content DESCRIPTION, the name of the FOLDER in which
-the messages to forward are located, and the MESSAGES' numbers.
+
+You are prompted for a content DESCRIPTION, the name of the
+FOLDER in which the messages to forward are located, and the
+MESSAGES' numbers.
 
 The option `mh-compose-insertion' controls what type of tags are inserted."
   (interactive (let*
@@ -117,9 +122,9 @@
 
 (defvar mh-mh-to-mime-args nil
   "Extra arguments for \\[mh-mh-to-mime] to pass to the \"mhbuild\" command.
-The arguments are passed to \"mhbuild\" if \\[mh-mh-to-mime] is given a prefix
-argument. Normally default arguments to \"mhbuild\" are specified in the MH
-profile.")
+The arguments are passed to \"mhbuild\" if \\[mh-mh-to-mime] is
+given a prefix argument. Normally default arguments to
+\"mhbuild\" are specified in the MH profile.")
 
 (defvar mh-media-type-regexp
   (concat (regexp-opt '("text" "image" "audio" "video" "application"
@@ -151,12 +156,14 @@
     ("text/plain" "\.vcf" "text/x-vcard"))
   "Substitutions to make for Content-Type returned from file command.
 The first element is the Content-Type returned by the file command.
-The second element is a regexp matching the file name, usually the extension.
+The second element is a regexp matching the file name, usually the
+extension.
 The third element is the Content-Type to replace with.")
 
 (defun mh-file-mime-type-substitute (content-type filename)
   "Return possibly changed CONTENT-TYPE on the FILENAME.
-Substitutions are made from the `mh-file-mime-type-substitutions' variable."
+Substitutions are made from the `mh-file-mime-type-substitutions'
+variable."
   (let ((subst mh-file-mime-type-substitutions)
         (type) (match) (answer content-type)
         (case-fold-search t))
@@ -225,9 +232,10 @@
 
 (defun mh-minibuffer-read-type (filename &optional default)
   "Return the content type associated with the given FILENAME.
-If the \"file\" command exists and recognizes the given file, then its value
-is returned\; otherwise, the user is prompted for a type (see
-`mailcap-mime-types' and for Emacs 20, `mh-mime-content-types').
+If the \"file\" command exists and recognizes the given file,
+then its value is returned\; otherwise, the user is prompted for
+a type (see `mailcap-mime-types' and for Emacs 20,
+`mh-mime-content-types').
 Optional argument DEFAULT is returned if a type isn't entered."
   (mailcap-parse-mimetypes)
   (let* ((default (or default
@@ -272,9 +280,10 @@
 ;;;###mh-autoload
 (defun mh-mh-attach-file (filename type description attributes)
   "Add a tag to insert a MIME message part from a file.
-You are prompted for the FILENAME containing the object, the media TYPE if it
-cannot be determined automatically, and a content DESCRIPTION. In addition,
-you are also prompted for additional ATTRIBUTES.
+You are prompted for the FILENAME containing the object, the
+media TYPE if it cannot be determined automatically, and a
+content DESCRIPTION. In addition, you are also prompted for
+additional ATTRIBUTES.
 
 See also \\[mh-mh-to-mime]."
   (interactive (let ((filename (mml-minibuffer-read-file "Attach file: ")))
@@ -291,9 +300,9 @@
 (defun mh-mh-compose-type (filename type
                                      &optional description attributes comment)
   "Insert an MH-style directive to insert a file.
-The file specified by FILENAME is encoded as TYPE. An optional DESCRIPTION is
-used as the Content-Description field, optional set of ATTRIBUTES and an
-optional COMMENT can also be included."
+The file specified by FILENAME is encoded as TYPE. An optional
+DESCRIPTION is used as the Content-Description field, optional
+set of ATTRIBUTES and an optional COMMENT can also be included."
   (beginning-of-line)
   (insert "#" type)
   (and attributes
@@ -309,8 +318,8 @@
 ;;;###mh-autoload
 (defun mh-mh-compose-anon-ftp (host filename type description)
   "Add tag to include anonymous ftp reference to a file.
-You can even have your message initiate an \"ftp\" transfer when the
-recipient reads the message. You are prompted for the remote
+You can even have your message initiate an \"ftp\" transfer when
+the recipient reads the message. You are prompted for the remote
 HOST and FILENAME, the media TYPE, and the content DESCRIPTION.
 
 See also \\[mh-mh-to-mime]."
@@ -325,10 +334,10 @@
 ;;;###mh-autoload
 (defun mh-mh-compose-external-compressed-tar (host filename description)
   "Add tag to include anonymous ftp reference to a compressed tar file.
-In addition to retrieving the file via anonymous \"ftp\" as per the
-\\[mh-mh-compose-anon-ftp] command, the file will also be uncompressed and
-untarred. You are prompted for the remote HOST and FILENAME and the content
-DESCRIPTION.
+In addition to retrieving the file via anonymous \"ftp\" as per
+the \\[mh-mh-compose-anon-ftp] command, the file will also be
+uncompressed and untarred. You are prompted for the remote HOST
+and FILENAME and the content DESCRIPTION.
 
 See also \\[mh-mh-to-mime]."
   (interactive (list
@@ -347,11 +356,12 @@
                                                 attributes parameters
                                                 comment)
   "Add tag to refer to a remote file.
-This command is a general utility for referencing external files. In fact, all
-of the other commands that insert directives to access external files call
-this command. You are prompted for the ACCESS-TYPE, remote HOST and FILENAME,
-and content TYPE. If you provide a prefix argument, you are also prompted for
-a content DESCRIPTION, ATTRIBUTES, PARAMETERS, and a COMMENT.
+This command is a general utility for referencing external files.
+In fact, all of the other commands that insert directives to
+access external files call this command. You are prompted for the
+ACCESS-TYPE, remote HOST and FILENAME, and content TYPE. If you
+provide a prefix argument, you are also prompted for a content
+DESCRIPTION, ATTRIBUTES, PARAMETERS, and a COMMENT.
 
 See also \\[mh-mh-to-mime]."
   (interactive (list
@@ -386,8 +396,9 @@
 ;;;###mh-autoload
 (defun mh-mh-forward-message (&optional description folder messages)
   "Add tag to forward a message.
-You are prompted for a content DESCRIPTION, the name of the FOLDER in which
-the messages to forward are located, and the MESSAGES' numbers.
+You are prompted for a content DESCRIPTION, the name of the
+FOLDER in which the messages to forward are located, and the
+MESSAGES' numbers.
 
 See also \\[mh-mh-to-mime]."
   (interactive (list
@@ -420,22 +431,24 @@
 (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.
+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.
 
-If you wish to pass additional arguments to \"mhbuild\" (\"mhn\") to affect
-how it builds your message, use the `mh-mh-to-mime-args' option. For example,
-you can build a consistency check into the message by setting
-`mh-mh-to-mime-args' to \"-check\". The recipient of your message can then run
-\"mhbuild -check\" on the message--\"mhbuild\" (\"mhn\") will complain if the
-message has been corrupted on the way. This command only consults this option
-when given a prefix argument EXTRA-ARGS.
+If you wish to pass additional arguments to \"mhbuild\" (\"mhn\") to
+affect how it builds your message, use the `mh-mh-to-mime-args'
+option. For example, you can build a consistency check into the
+message by setting `mh-mh-to-mime-args' to \"-check\". The recipient
+of your message can then run \"mhbuild -check\" on the
+message--\"mhbuild\" (\"mhn\") will complain if the message has been
+corrupted on the way. This command only consults this option when
+given a prefix argument EXTRA-ARGS.
 
 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]."
+The effects of this command can be undone by running
+\\[mh-mh-to-mime-undo]."
   (interactive "*P")
   (mh-mh-quote-unescaped-sharp)
   (save-buffer)
@@ -457,9 +470,9 @@
 
 (defun mh-mh-quote-unescaped-sharp ()
   "Quote `#' characters that haven't been quoted for \"mhbuild\".
-If the `#' character is present in the first column, but it isn't part of a
-MH-style directive then \"mhbuild\" gives an error. This function will quote
-all such characters."
+If the `#' character is present in the first column, but it isn't
+part of a MH-style directive then \"mhbuild\" gives an error.
+This function will quote all such characters."
   (save-excursion
     (goto-char (point-min))
     (while (re-search-forward "^#" nil t)
@@ -471,7 +484,8 @@
 ;;;###mh-autoload
 (defun mh-mh-to-mime-undo (noconfirm)
   "Undo effects of \\[mh-mh-to-mime].
-Optional non-nil argument NOCONFIRM means don't ask for confirmation."
+Optional non-nil argument NOCONFIRM means don't ask for
+confirmation."
   (interactive "*P")
   (if (null buffer-file-name)
       (error "Buffer does not seem to be associated with any file"))
@@ -499,8 +513,8 @@
 ;;;###mh-autoload
 (defun mh-mh-directive-present-p (&optional begin end)
   "Check if the text between BEGIN and END might be a MH-style directive.
-The optional argument BEGIN defaults to the beginning of the buffer, while END
-defaults to the the end of the buffer."
+The optional argument BEGIN defaults to the beginning of the
+buffer, while END defaults to the the end of the buffer."
   (unless begin (setq begin (point-min)))
   (unless end (setq end (point-max)))
   (save-excursion
@@ -525,9 +539,10 @@
 ;;;###mh-autoload
 (defun mh-mml-to-mime ()
   "Compose MIME message from MML tags.
-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.
+
+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.
 
 This action can be undone by running \\[undo]."
   (interactive)
@@ -548,8 +563,9 @@
 ;;;###mh-autoload
 (defun mh-mml-forward-message (description folder message)
   "Forward a message as attachment.
-The function will prompt the user for a DESCRIPTION, a FOLDER and MESSAGE
-number."
+
+The function will prompt the user for a DESCRIPTION, a FOLDER and
+MESSAGE number."
   (let ((msg (if (and (equal message "") (numberp mh-sent-from-msg))
                  mh-sent-from-msg
                (car (read-from-string message)))))
@@ -582,9 +598,10 @@
 ;;;###mh-autoload
 (defun mh-mml-attach-file (&optional disposition)
   "Add a tag to insert a MIME message part from a file.
-You are prompted for the filename containing the object, the media type if it
-cannot be determined automatically, a content description and the DISPOSITION
-of the attachment.
+
+You are prompted for the filename containing the object, the
+media type if it cannot be determined automatically, a content
+description and the DISPOSITION of the attachment.
 
 This is basically `mml-attach-file' from Gnus, modified such that a prefix
 argument yields an `inline' disposition and Content-Type is determined
@@ -601,6 +618,7 @@
 
 (defun mh-secure-message (method mode &optional identity)
   "Add tag to encrypt or sign message.
+
 METHOD should be one of: \"pgpmime\", \"pgp\", \"smime\".
 MODE should be one of: \"sign\", \"encrypt\", \"signencrypt\", \"none\".
 IDENTITY is optionally the default-user-id to use."
@@ -635,30 +653,33 @@
 ;;;###mh-autoload
 (defun mh-mml-secure-message-sign (method)
   "Add tag to sign the message.
-A proper multipart message is created for you when you send the message. Use
-the \\[mh-mml-unsecure-message] command to remove this tag. Use a prefix
-argument METHOD to be prompted for one of the possible security methods
-\(see `mh-mml-method-default')."
+
+A proper multipart message is created for you when you send the
+message. Use the \\[mh-mml-unsecure-message] command to remove
+this tag. Use a prefix argument METHOD to be prompted for one of
+the possible security methods \(see `mh-mml-method-default')."
   (interactive (list (mh-mml-query-cryptographic-method)))
   (mh-secure-message method "sign" mh-identity-pgg-default-user-id))
 
 ;;;###mh-autoload
 (defun mh-mml-secure-message-encrypt (method)
   "Add tag to encrypt the message.
-A proper multipart message is created for you when you send the message. Use
-the \\[mh-mml-unsecure-message] command to remove this tag. Use a prefix
-argument METHOD to be prompted for one of the possible security methods
-\(see `mh-mml-method-default')."
+
+A proper multipart message is created for you when you send the
+message. Use the \\[mh-mml-unsecure-message] command to remove
+this tag. Use a prefix argument METHOD to be prompted for one of
+the possible security methods \(see `mh-mml-method-default')."
   (interactive (list (mh-mml-query-cryptographic-method)))
   (mh-secure-message method "encrypt" mh-identity-pgg-default-user-id))
 
 ;;;###mh-autoload
 (defun mh-mml-secure-message-signencrypt (method)
   "Add tag to encrypt and sign the message.
-A proper multipart message is created for you when you send the message. Use
-the \\[mh-mml-unsecure-message] command to remove this tag. Use a prefix
-argument METHOD to be prompted for one of the possible security methods
-\(see `mh-mml-method-default')."
+
+A proper multipart message is created for you when you send the
+message. Use the \\[mh-mml-unsecure-message] command to remove
+this tag. Use a prefix argument METHOD to be prompted for one of
+the possible security methods \(see `mh-mml-method-default')."
   (interactive (list (mh-mml-query-cryptographic-method)))
   (mh-secure-message method "signencrypt" mh-identity-pgg-default-user-id))
 
@@ -695,10 +716,11 @@
 
 (defun mh-handle-set-external-undisplayer (folder handle function)
   "Replacement for `mm-handle-set-external-undisplayer'.
-This is only called in recent versions of Gnus. The MIME handles are stored
-in data structures corresponding to MH-E folder buffer FOLDER instead of in
-Gnus (as in the original). The MIME part, HANDLE is associated with the
-undisplayer FUNCTION."
+
+This is only called in recent versions of Gnus. The MIME handles
+are stored in data structures corresponding to MH-E folder buffer
+FOLDER instead of in Gnus (as in the original). The MIME part,
+HANDLE is associated with the undisplayer FUNCTION."
   (if (mm-keep-viewer-alive-p handle)
       (let ((new-handle (copy-sequence handle)))
         (mm-handle-set-undisplayer new-handle function)
@@ -716,7 +738,8 @@
 ;;;###mh-autoload
 (defun mh-add-missing-mime-version-header ()
   "Some mail programs don't put a MIME-Version header.
-I have seen this only in spam, so maybe we shouldn't fix this ;-)"
+I have seen this only in spam, so maybe we shouldn't fix
+this ;-)"
   (save-excursion
     (goto-char (point-min))
     (re-search-forward "\n\n" nil t)
@@ -729,7 +752,8 @@
 
 (defun mh-small-show-buffer-p ()
   "Check if show buffer is small.
-This is used to decide if smileys and graphical emphasis will be displayed."
+This is used to decide if smileys and graphical emphasis will be
+displayed."
   (let ((max nil))
     (when (and (boundp 'font-lock-maximum-size) font-lock-maximum-size)
       (cond ((numberp font-lock-maximum-size)
@@ -803,12 +827,13 @@
 (defun mh-mime-save-parts (prompt)
   "Save attachments.
 
-You can save all of the attachments at once with this command. The attachments
-are saved in the directory specified by the option
-`mh-mime-save-parts-default-directory' unless you use a prefix argument PROMPT
-in which case you are prompted for the directory. These directories may be
-superseded by MH profile components, since this function calls on
-\"mhstore\" (\"mhn\") to do the work."
+You can save all of the attachments at once with this command.
+The attachments are saved in the directory specified by the
+option `mh-mime-save-parts-default-directory' unless you use a
+prefix argument PROMPT in which case you are prompted for the
+directory. These directories may be superseded by MH profile
+components, since this function calls on \"mhstore\" (\"mhn\") to
+do the work."
   (interactive "P")
   (let ((msg (if (eq major-mode 'mh-show-mode)
                  (mh-show-buffer-message-number)
@@ -900,9 +925,9 @@
 ;;;###mh-autoload
 (defun mh-mime-display (&optional pre-dissected-handles)
   "Display (and possibly decode) MIME handles.
-Optional argument, PRE-DISSECTED-HANDLES is a list of MIME handles. If
-present they are displayed otherwise the buffer is parsed and then
-displayed."
+Optional argument, PRE-DISSECTED-HANDLES is a list of MIME
+handles. If present they are displayed otherwise the buffer is
+parsed and then displayed."
   (let ((handles ())
         (folder mh-show-folder-buffer)
         (raw-message-data (buffer-string)))
@@ -974,8 +999,8 @@
 
 (defun mh-mime-maybe-display-alternatives (alternatives)
   "Show buttons for ALTERNATIVES.
-If `mh-mime-display-alternatives-flag' is non-nil then display buttons for
-alternative parts that are usually suppressed."
+If `mh-mime-display-alternatives-flag' is non-nil then display
+buttons for alternative parts that are usually suppressed."
   (when (and mh-display-buttons-for-alternatives-flag alternatives)
     (insert "\n----------------------------------------------------\n")
     (insert "Alternatives:\n")
@@ -990,9 +1015,9 @@
 
 (defun mh-mime-part-index (handle)
   "Generate the button number for MIME part, HANDLE.
-Notice that a hash table is used to display the same number when buttons need
-to be displayed multiple times (for instance when nested messages are
-opened)."
+Notice that a hash table is used to display the same number when
+buttons need to be displayed multiple times (for instance when
+nested messages are opened)."
   (or (gethash handle (mh-mime-part-index-hash (mh-buffer-data)))
       (setf (gethash handle (mh-mime-part-index-hash (mh-buffer-data)))
             (incf (mh-mime-parts-count (mh-buffer-data))))))
@@ -1075,8 +1100,8 @@
 
 (defun mh-signature-highlight (&optional handle)
   "Highlight message signature in HANDLE.
-The optional argument, HANDLE is a MIME handle if the function is being used
-to highlight the signature in a MIME part."
+The optional argument, HANDLE is a MIME handle if the function is
+being used to highlight the signature in a MIME part."
   (let ((regexp
          (cond ((not handle) "^-- $")
                ((not (and (equal (mm-handle-media-supertype handle) "text")
@@ -1101,8 +1126,8 @@
 
 (defun mh-insert-mime-button (handle index displayed)
   "Insert MIME button for HANDLE.
-INDEX is the part number that will be DISPLAYED. It is also used by commands
-like \"K v\" which operate on individual MIME parts."
+INDEX is the part number that will be DISPLAYED. It is also used
+by commands like \"K v\" which operate on individual MIME parts."
   ;; The button could be displayed by a previous decode. In that case
   ;; undisplay it if we need a hidden button.
   (when (and (mm-handle-displayed-p handle) (not displayed))
@@ -1214,8 +1239,8 @@
 (defun mh-press-button ()
   "View contents of button.
 
-This command is a toggle so if you use it again on the same attachment, the
-attachment is hidden."
+This command is a toggle so if you use it again on the same
+attachment, the attachment is hidden."
   (interactive)
   (let ((mm-inline-media-tests mh-mm-inline-media-tests)
         (data (get-text-property (point) 'mh-data))
@@ -1233,9 +1258,10 @@
 ;;;###mh-autoload
 (defun mh-push-button (event)
   "Click MIME button for EVENT.
-If the MIME part is visible then it is removed. Otherwise the part is
-displayed. This function is called when the mouse is used to click the MIME
-button."
+
+If the MIME part is visible then it is removed. Otherwise the
+part is displayed. This function is called when the mouse is used
+to click the MIME button."
   (interactive "e")
   (mh-do-at-event-location event
     (let ((folder mh-show-folder-buffer)
@@ -1289,21 +1315,24 @@
 (defun mh-display-with-external-viewer (part-index)
   "View attachment externally.
 
-If Emacs does not know how to view an attachment, you could save it into a
-file and then run some program to open it. It is easier, however, to launch
-the program directly from MH-E with this command. While you'll most likely use
-this to view spreadsheets and documents, it is also useful to use your browser
-to view HTML attachments with higher fidelity than what Emacs can provide.
+If Emacs does not know how to view an attachment, you could save
+it into a file and then run some program to open it. It is
+easier, however, to launch the program directly from MH-E with
+this command. While you'll most likely use this to view
+spreadsheets and documents, it is also useful to use your browser
+to view HTML attachments with higher fidelity than what Emacs can
+provide.
 
-This command displays the attachment associated with the button under the
-cursor. If the cursor is not located over a button, then the cursor first
-moves to the next button, wrapping to the beginning of the message if
-necessary. You can provide a numeric prefix argument PART-INDEX to view the
-attachment labeled with that number.
+This command displays the attachment associated with the button
+under the cursor. If the cursor is not located over a button,
+then the cursor first moves to the next button, wrapping to the
+beginning of the message if necessary. You can provide a numeric
+prefix argument PART-INDEX to view the attachment labeled with
+that number.
 
-This command tries to provide a reasonable default for the viewer by calling
-the Emacs function `mailcap-mime-info'. This function usually reads the file
-\"/etc/mailcap\"."
+This command tries to provide a reasonable default for the viewer
+by calling the Emacs function `mailcap-mime-info'. This function
+usually reads the file \"/etc/mailcap\"."
   (interactive "P")
   (when (consp part-index) (setq part-index (car part-index)))
   (mh-folder-mime-action
@@ -1458,8 +1487,8 @@
 
 (defun mh-mm-inline-message (handle)
   "Display message, HANDLE.
-The function decodes the message and displays it. It avoids decoding the same
-message multiple times."
+The function decodes the message and displays it. It avoids
+decoding the same message multiple times."
   (let ((b (point))
         (clean-message-header mh-clean-message-header-flag)
         (invisible-headers mh-invisible-header-fields-compiled)