mh-e: Adding Attachments
9.6 Adding Attachments
======================
MH-E has the capability to create multimedia messages. It uses the MIME
(Multipurpose Internet Mail Extensions) protocol(1) The MIME protocol
allows you to incorporate images, sound, video, binary files, and even
commands that fetch a file with ‘ftp’ when your recipient reads the
message!
If you were to create a multimedia message with plain MH commands,
you would insert ‘mhbuild’ or ‘mhn’ directives (henceforth called
“MH-style directives” into your draft and use the ‘mhbuild’ command in
nmh or ‘mhn’ command in MH and GNU mailutils to expand them. MH-E works
in much the same way, although it provides a handful of commands
prefixed with ‘C-c C-m’ to insert the directives so you don’t need to
remember the syntax of them. Remember: you can always add MH-style
directives by hand(2).
In addition to MH-style directives, MH-E also supports MML (MIME Meta
Language) tags(3). The option ‘mh-compose-insertion’ can be used to
choose between them. By default, this option is set to ‘MML’ if it is
supported since it provides a lot more functionality. This option can
also be set to ‘MH’ if MH-style directives are preferred.
The MH-E MIME commands require a “media type” for each body part or
attachment. For example, a PDF document is of type ‘application/pdf’
and an HTML document is of type ‘text/html’. Some commands fill in the
media type for you, whereas others require you to enter one.
In the cases where MH-E can do so, it will determine the media type
automatically. It uses the ‘file’ command to do this. Failing that,
the Emacs function ‘mailcap-mime-types’ is used to provide a list from
which to choose. This function usually reads the file
‘/etc/mime.types’.
Whether the media type is chosen automatically, or you choose it from
a list, use the type that seems to match best the file that you are
including. In the case of binaries, the media type
‘application/x-executable’ can be useful. If you can’t find an
appropriate media type, use ‘text/plain’ for text messages and
‘application/octet-stream’ for everything else.
You are also sometimes asked for a “content description”. This is
simply an optional brief phrase, in your own words, that describes the
object. If you don’t care to enter a content description, just press
return and none will be included; however, a reader may skip over
multimedia fields unless the content description is compelling.
You can also create your own MIME body parts. In the following
example, I describe how you can create and edit a ‘text/enriched’ body
part to liven up your plain text messages with boldface, underlining,
and italics. I include an Emacs function which inserts enriched text
tags.
(defvar enriched-text-types '(("b" . "bold") ("i" . "italic")
("u" . "underline")
("s" . "smaller") ("B" . "bigger")
("f" . "fixed")
("c" . "center"))
"Alist of (final-character . tag) choices for add-enriched-text.
Additional types can be found in RFC 1563.")
(defun add-enriched-text (begin end)
"Add enriched text tags around region.
The tag used comes from the list enriched-text-types and is
specified by the last keystroke of the command. When called from Lisp,
arguments are BEGIN and END."
(interactive "r")
;; Set type to the tag indicated by the last keystroke.
(let ((type (cdr (assoc (char-to-string (logior last-input-char ?`))
enriched-text-types))))
(save-restriction ; restores state from narrow-to-region
(narrow-to-region begin end) ; narrow view to region
(goto-char (point-min)) ; move to beginning of text
(insert "<" type ">") ; insert beginning tag
(goto-char (point-max)) ; move to end of text
(insert "</" type ">")))) ; insert terminating tag
Emacs function for entering enriched text
To use the function ‘add-enriched-text’, first add it to ‘~/.emacs’
and create key bindings for it (Composing).
Then, in your plain text message, set the mark with ‘C-@’ or
‘C-<SPC>’, type in the text to be highlighted, and type ‘C-c t b’. This
adds ‘<bold>’ where you set the mark and adds ‘</bold>’ at the location
of your cursor, giving you something like: ‘You should be
<bold>very</bold>’.
Before sending this message, use ‘C-c C-m C-m’ (‘mh-mml-to-mime’)(4)
to add MIME header fields. Then replace ‘text/plain’ with
‘text/enriched’ in the ‘Content-Type:’ header field.
You may also be interested in investigating ‘sgml-mode’.
Including Files
---------------
Binaries, images, sound, and video can be inserted in your message with
the command ‘C-c C-m C-i’ (‘mh-compose-insertion’). 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.
Forwarding Multimedia Messages
------------------------------
Mail may be forwarded with MIME using the command ‘C-c C-m C-f’
(‘mh-compose-forward’). You are prompted for a content description, the
name of the folder in which the messages to forward are located, and a
range of messages, which defaults to the current message in that folder.
Ranges.
Including an FTP Reference
--------------------------
You can have your message initiate an ‘ftp’ transfer when the recipient
reads the message. To do this, use the command ‘C-c C-m C-g’
(‘mh-mh-compose-anon-ftp’). You are prompted for the remote host and
filename, the media type, and the content description.
Including tar Files
-------------------
If the remote file is a compressed tar file, you can use ‘C-c C-m C-t’
(‘mh-mh-compose-external-compressed-tar’). Then, in addition to
retrieving the file via anonymous _ftp_ as per the command ‘C-c C-m C-g’
(‘mh-mh-compose-anon-ftp’), the file will also be uncompressed and
untarred. You are prompted for the remote host and filename and the
content description.
Including Other External Files
------------------------------
The command ‘C-c C-m C-x’ (‘mh-mh-compose-external-type’) is a general
utility for referencing external files. In fact, all of the other
commands that insert tags 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.
Previewing Multimedia Messages
------------------------------
When you are finished editing a MIME message, it might look like this:
3 t08/24 root received fax files on Wed Aug 24 11:00:
4+t08/24 To:wohler Test<<This is a test message to get the
--:%% {+inbox} 4 msgs (1-4) Bot L4 (MH-Folder Show)---------------
To: wohler
cc:
Subject: Test of MIME
--------
Here is the SETI@Home logo:
<#part type="image/x-xpm" filename="~/lib/images/setiathome.xpm"
disposition=inline description="SETI@home logo">
<#/part>
--:** {draft} All L8 (MH-Letter)----------------------------------
MH-E MIME draft
Typically, you send a message with attachments just like any other
message (Sending Message).
However, you may take a sneak preview of the MIME encoding if you
wish by running the command ‘C-c C-m C-m’ (‘mh-mml-to-mime’). The
following screen shows the MIME encoding specified by the tags. You can
see why mail user agents are usually built to hide these details from
the user.
To: wohler
cc:
Subject: Test of MIME
X-Mailer: MH-E 8.1; nmh 1.1; GNU Emacs 23.1
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="=-=-="
--------
--=-=-=
Here is the SETI@Home logo:
--=-=-=
Content-Type: image/x-xpm
Content-Disposition: inline; filename=setiathome.xpm
Content-Transfer-Encoding: base64
Content-Description: SETI@home logo
LyogWFBNICovCnN0YXRpYyBjaGFyICogc2V0aWF0aG9tZV94cG1bXSA9IHsKIjQ1IDQ1IDc2N
--:-- {draft} Top L1 (MH-Letter)----------------------------------
MH-E MIME draft ready to send
This action can be undone by running ‘C-_’ (‘undo’).
If you’re using MH-style directives, use ‘C-c C-e’ (‘mh-mh-to-mime’)
instead of ‘C-c C-m C-m’. This runs the command ‘mhbuild’ (‘mhn’) on
the message which expands the tags(5). This action can be undone by
running ‘C-c C-m C-u’ (‘mh-mh-to-mime-undo’), which works by reverting
to a backup file. You are prompted to confirm this action, but you can
avoid the confirmation by adding an argument (for example, ‘C-u C-c C-m
C-u’).
If you wish to pass additional arguments to ‘mhbuild’ (‘mhn’) to
affect how it builds your message, use the option ‘mh-mh-to-mime-args’.
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. The command ‘C-c
C-e’ only consults this option when given a prefix argument (as in ‘C-u
C-c C-e’).
The hook ‘mh-mh-to-mime-hook’ is called after the message has been
formatted by ‘C-c C-e’.
---------- Footnotes ----------
(1) MIME is defined in RFC 2045
(http://www.rfc-editor.org/rfc/rfc2045.txt).
(2) See the section Sending MIME Mail
(http://rand-mh.sourceforge.net/book/mh/usimim.html#SeMIMa) in the MH
book.
(3) Composing with MML (emacs-mime)Composing.
(4) Use ‘C-c C-e’ (‘mh-mh-to-mime’) if you’re using MH-style
directives.
(5) See the section Sending MIME Mail
(http://rand-mh.sourceforge.net/book/mh/usimim.html#SeMIMa) in the MH
book.