3 Reading Messages

Once a message has been selected, VM will show it to you. By default, presentation is done in two stages: previewing and paging.

3.1 Previewing

Previewing means showing you a small portion of a message and allowing you to decide whether you want to read it. Typing SPC exposes the body of the message, and from there you can repeatedly type SPC to page through the message.

By default, the sender, recipient, subject and date headers are shown when previewing; the rest of the message is hidden. This behavior may be altered by changing the settings of three variables: vm-visible-headers, vm-invisible-header-regexp and vm-preview-lines.

If the value of vm-preview-lines is a number, it tells VM how many lines of the text of the message should be visible. The default value of this variable is 0. If vm-preview-lines is nil, then previewing is not done at all; when a message is first presented it is immediately exposed in its entirety and is flagged as read. If vm-preview-lines is t, the message body is displayed fully but the message is not flagged as read until you type SPC.

The value of vm-visible-headers should be a list of regular expressions matching the beginnings of headers that should be made visible when a message is presented. The regexps should be listed in the preferred presentation order of the headers they match.

If non-nil, the variable vm-invisible-header-regexp specifies what headers should not be displayed. Its value should be a string containing a regular expression that matches all headers you do not want to see. Setting this variable non-nil implies that you want to see all headers not matched by it; therefore the value of vm-visible-headers is only used to determine the order of the visible headers in this case. Headers not matched by vm-invisible-header-regexp or vm-visible-headers are displayed last.

If you change the value of either vm-visible-headers or vm-invisible-header-regexp in the middle of a VM session the effects will not be immediate. You will need to use the command vm-discard-cached-data on each message (bound to j by default) to force VM to rearrange the message headers. A good way to do this is to mark all the messages in the folder and apply vm-discard-cached-data to the marked messages See Marking Messages.

Another variable of interest is vm-highlighted-header-regexp. The value of this variable should be a single regular expression that matches the beginnings of any header that should be presented in inverse video when previewing. For example, a value of ‘"^From\\|^Subject"’ causes the From and Subject headers to be highlighted. Highlighted headers will be displayed using the face specified by vm-highlighted-header-face, which defaults to ’bold.

By default, VM will not preview messages that are flagged as read. To have VM preview all messages, set the value of vm-preview-read-messages to t.

Typing t (vm-expose-hidden-headers) makes VM toggle between exposing and hiding headers that would ordinarily be hidden.

3.2 Paging

Typing SPC during a message preview exposes the body of the message. If the message was new or previously unread, it will be flagged “read”. At this point you can use SPC to scroll forward, and DEL to scroll backward a windowful of text at a time. A prefix argument n applied to these commands causes VM to scroll forward or backward n lines. Typing space at the end of a message moves you to the next message. If the value of vm-auto-next-message is nil, SPC will not move to the next message; you must type n explicitly.

If the value of vm-honor-page-delimiters is non-nil, VM will recognize and honor page delimiters. This means that when you scroll through a document, VM will display text only up to the next page delimiter. Text after the delimiter will be hidden until you type another SPC, at which point the text preceding the delimiter will become hidden. The Emacs variable page-delimiter determines what VM will consider to be a page delimiter.

You can “unread” a message (so to speak) by typing U (vm-unread-message, also called vm-mark-message-unread). The current message will be marked unread. Conversely, you can mark an unread message as read by typing . (vm-mark-message-read).

As you read messages, you might want to flag important messages so that you can come back to them later. You can do so by typing ! (vm-toggle-flag-message). You can also turn off the flag on a flagged message by typing ! again. In the Summary display, the flagged messages are highlighted using the vm-summary-high-priority-face. (See predefined summary faces.)

Sometimes you will receive messages that contain lines that are too long to fit on your screen without wrapping. Setting vm-word-wrap-paragraphs to t will cause VM to use the longlines.el library by Grossjohann, Schroeder and Yidong to carry out word wrapping. You must have this library installed somewhere on your load-path. Another way to deal with the problem is to use the visual-line-mode in Emacs 23. You can activate it automatically for viewing messages by adding the function turn-on-visual-line-mode to the vm-presentation-mode-hook.

If you are unable to use either of these solutions, then you can use Emacs’s paragraph filling facility. If you set vm-fill-paragraphs-containing-long-lines to a positive numeric value N, VM will call fill-paragraph on all paragraphs that contain lines spanning N columns or more. You can also set this variable to the symbol window-width, in which case the width of the current window is used the limiting width beyond which paragraph filling is invoked. As with other things that VM does for presentation purposes, this does not change the message contents. VM copies the message contents to a “presentation” buffer before altering them. The fill column that VM uses is controlled by vm-paragraph-fill-column. Unlike the Emacs variable fill-column, this variable is not buffer-local by default.

3.3 Reading MIME Messages

MIME is a set of extensions to the standard Internet message format that allows reliable transmission of arbitrary data including images, audio and video, as well as ordinary text in different languages. By default, VM will recognize MIME encoded messages and display them as specified by the various MIME standards specifications. This can be turned off by setting the variable vm-display-using-mime to nil and VM will then display MIME messages as plain text messages.

At its most basic MIME is a set of transfer encodings used to ensure error free transport, and a set of content types. VM understands the two standard MIME transport encodings, Quoted-Printable and BASE64, and will decode messages that use them as necessary. VM also will try to recognize and decode messages using the UNIX “uuencode” encoding system. While this is not an official MIME transfer encoding and never will be, enough old mailers still use it that it is worthwhile to attempt to decode it. VM has Emacs-Lisp based Quoted-Printable and BASE64 encoders and decoders, but you can have VM use external programs to perform these tasks and the process will almost certainly be faster. The variables vm-mime-qp-decoder-program, vm-mime-qp-decoder-switches, vm-mime-qp-encoder-program, vm-mime-qp-encoder-switches, vm-mime-base64-decoder-switches, vm-mime-base64-encoder-switches, vm-mime-base64-decoder-program, vm-mime-base64-encoder-program, tell VM which programs to use and what command line switches to pass to them. There are C programs at VM’s distribution sites on the Internet to handle BASE64 and Quoted-Printable. VM does not have a built-in “uuencode” decoder, so vm-mime-uuencode-decoder-program must be set non-nil for VM to decode uuencoded MIME objects.

Viewing MIME messages

By default VM will display as many content types as possible within Emacs. Images and audio are also supported if support for images and audio has been compiled in. Types that cannot be displayed internally within Emacs can be converted to a type that can, or be displayed using an external viewer.

The first step in displaying a MIME message is decoding it to determine what object types it contains. The variable vm-auto-decode-mime-messages controls when this happens. A value of t means VM should decode the message as soon as the message body is exposed, or during previewing if vm-mime-decode-for-preview is also set non-nil. A nil value means wait until decoding is explicitly requested. Type D (vm-decode-mime-message) to manually initiate MIME decoding.

When VM does not display a MIME object immediately, it displays a MIME button or tag line in its place that describes the object and what you have to do to display it. The value of vm-mime-button-format-alist determines the format of the text in those buttons.

After decoding you will see either the decoded MIME objects or button lines that must be activated to attempt display of the MIME object.

The variable vm-mime-auto-displayed-content-types specifies the types that are displayed immediately. Its value should be a list of MIME content types that should be displayed immediately after decoding. Other types will be displayed as a button that you must activate to display the object. The variable vm-mime-auto-displayed-content-type-exceptions can be used to specify any exceptions to the types listed in vm-mime-auto-displayed-content-types.

The MIME objects in messages come with a header called Content-Disposition, which specifies whether the MIME object should be displayed as part of the message display (the “inline” disposition) or whether it should be displayed as a button that should be invoked to view the object (the attachment disposition). However, not all mail clients do a good job of adding this header. It is not uncommon to find mail clients that declare all MIME objects to be “inline” and others that declare all MIME objects to be “attachment”. The variable vm-mime-honor-content-disposition can be customized to tell VM whether it should follow the suggestions in the Content-Disposition headers. A value of t means that they should be always honored and a value of nil means that they should be ignored. It can also be set to the symbol internal-only, which means that the Content-Disposition suggestions should be honored for only the internally displayable types. (See Internal display of MIME attachments.)

The commands [ and ] (vm-previous-button) and vm-next-button, respectively) can be used move to particular buttons within the message presentation.

Operating on MIME attachments

To activate a button, either click the middle mouse button over it, or move the cursor to the line and press RET. If you are running under a window system, you can use the right mouse button over a MIME button to display a menu of actions you can take on the MIME object. If you prefer using keyboard commands, you can save the MIME object with $ w, print it with $ p, or pipe it to a shell command with $ |. Use $ s to append an encapsulated message or USENET news article to a folder. If you want to display the object with its characters displayed using Emacs’ default face, use $ RET. To display the object using an external viewer, type $ e.

The MIME attachments can be saved to disk with $ w (vm-mime-reader-map-save-file). They can be deleted at the same time by setting the variable vm-mime-delete-after-saving. In this case, the attachment is deleted and replaced by a MIME part that refers to the saved copy. The variable vm-mime-attachment-save-directory specifies the default directory to save the attachments in. The MIME attachments can also be deleted directly from the message bodies with $ d (vm-delete-mime-object). The variable vm-mime-confirm-delete controls whether a confirmation is asked for.

It is a good idea to use vm-mime-delete-after-saving to delete saved attachments instead of deleting them manually, because with the former approach the message will have a handle to the saved copy, which can be retrieved when desired.

Saving attachments to the file system and deleting them from message bodies has the beneficial effect of reducing the size of VM folders. That leads to a better utilization of the computer resources and usually a faster operation of VM.

The commands vm-save-all-attachments and vm-delete-all-attachments can be used to save or delete all the attachments in a message. An "attachment" in this context is any MIME part that has "attachment" as its content-disposition or simply has a file name. In addition, all MIME parts that have types matching vm-mime-savable-types or vm-mime-deletable-types (but not the corresponding -exceptions) are included.

Internal display of MIME attachments

A value of t for vm-mime-auto-displayed-content-types means that all types should be displayed immediately. A nil value means never display MIME objects immediately; only use buttons. If the value of vm-mime-auto-displayed-content-types is a list, it should be a list of strings, which should all be MIME types or type/subtype pairs. Example:

(setq vm-mime-auto-displayed-content-types '("text" "image/jpeg"))

If a top-level type is listed without a subtype then all subtypes of that type are assumed to be included. The example above says that all text types should be displayed immediately, but only JPEG images should be displayed this way.

The variable vm-mime-auto-displayed-content-type-exceptions should be a list of MIME content types that should not be displayed immediately after decoding. This variable acts as an exception list for vm-mime-auto-displayed-content-types; all types listed there will be auto-displayed except those in the exception list.

(setq vm-mime-auto-displayed-content-type-exceptions '("text/html"))

If “code” has been included in vm-mime-auto-displayed-content-types then the effect of this setting is to allow the auto-display of all text types except for html.

The variable vm-mime-internal-content-types specifies which types should be displayed internally within Emacs. Like vm-mime-auto-displayed-content-types its value should be a list of MIME content types. A value of t means that VM should always display an object internally if possible. VM knows which object types can be displayed internally, so you can specify the types you want without worrying about potential errors. If the value is a list, it should be a list of strings. Example:

(setq vm-mime-internal-content-types '("text" "message" "image/jpeg"))

If a top-level type is listed without a subtype then all subtypes of that type are assumed to be included. Note that multipart types are always handled internally regardless of the setting of this variable.

The variable vm-mime-internal-content-type-exceptions serves as the exception list for vm-mime-internal-content-types. Its value should be a list of types that should not be displayed internally.

The HTML content in text/html MIME parts can be displayed in Emacs using a variety of packages. VM knows about:

You can set the variable vm-mime-text/html-handler to one of these values to use the appropriate package. A value of auto-select causes VM to select the best package available. A value of nil asks VM not to display HTML content internally. The default value is auto-select, allowing VM to give you the best display possible in your environment. If you do not like the results, you may set the variable to a different value or nil.

External display of MIME attachments

For types that you want displayed externally, set the value of vm-mime-external-content-types-alist to specify external viewers for the types. The value of this variable should be an associative list of MIME content types and the external programs used to display them. If VM cannot display a type internally or a type is not listed in vm-mime-internal-content-types VM will try to launch an external program to display that type.

The alist format is a list of lists, each sublist having the form

(TYPE FUNCTION ARG ARG ... )

or

(TYPE PROGRAM ARG ARG ... )

or

(TYPE COMMAND-LINE)

TYPE is a string specifying a MIME type or type/subtype pair. For example “text” or “image/jpeg”. If a top-level type is listed without a subtype, all subtypes of that type are assumed to be included.

In the first form, FUNCTION is a lisp function that is responsible for displaying the attachment in an external application. Any ARGs will be passed to the function as arguments. The octets that compose the object will be written into a temporary file and the name of the file is passed as an additional argument.

In the second form, PROGRAM is a string naming a program to run to display an object. Any ARGs will be passed to the program as arguments. The octets that compose the object will be written into a temporary file and the name of the file can be inserted into an ARG string by writing ‘%f’ in the ARG string. In earlier versions of VM the filename was always added as the last argument; as of VM 6.49 this is only done if ‘%f’ does not appear in any of the ARG strings.

If the COMMAND-LINE form is used, the program and its arguments are specified as a single string and that string is passed to the shell ("sh -c" typically) for execution. Since the command line will be passed to the shell, you can use shell variables and input/output redirection if needed. As with the PROGRAM/ARGS form, the name of the temporary file that contains the MIME object will be appended to the command line if ‘%f’ does not appear in the command line string.

In either the PROGRAM/ARG or COMMAND-LINE forms, all the program and argument strings will have any %-specifiers in them expanded as described in the documentation for the variable vm-mime-button-format-alist. The only difference is that ‘%f’ refers to the temporary file VM creates to store the object to be displayed, not the filename that the sender may have associated with the attachment.

Example:

(setq vm-mime-external-content-types-alist
      '(
         ("text/html"   browse-url-of-file)
         ("image/gif"   "xv")
         ("image/jpeg"  "xv")
         ("video/mpeg"  "mpeg_play")
         ("video"       w32-shell-execute "open")
       )
)

The first matching list element will be used.

No multipart message will ever be sent to an external viewer.

External viewer processes are normally killed when you select a new message in the current folder. If you want viewer processes to not be killed, set vm-mime-delete-viewer-processes to a nil value.

Any type that cannot be displayed internally or externally or converted to a type that can be displayed, will be displayed as a button that allows you to save the body to a file.

As with the internal type list, there is an exception list that you can use to specify types that you do not want displayed externally. When VM is considering whether it should automatically launch an external viewer, it will consult the variable vm-mime-external-content-type-exceptions. If the type to be displayed is listed, VM will not launch a viewer. This allows you to setup viewers for types that ordinarily you would not want VM to display or for types that you normally want to convert to some other type using vm-mime-type-converter-alist. You can still display such a type with an external viewer by using $ e.

When a MIME object is displayed using an external viewer VM must first write the object to a temporary file. The external viewer then opens and displays that file. Some viewers will not open a file unless the filename ends with some extension that it recognizes such as ‘.html’ or ‘.jpg’. You can use the variable vm-mime-attachment-auto-suffix-alist to map MIME types to extensions that your external viewers will recognize. The value of this variable should be a list of type and suffix pairs. The list format is:

((TYPE . SUFFIX) ...)

TYPE is a string specifying a MIME top-level type or a type/subtype pair. If a top-level type is listed without a subtype, all subtypes of that type are matched.

SUFFIX is a string specifying the suffix that should be used for the accompanying type.

Example:

(setq vm-mime-attachment-auto-suffix-alist
      '(
        ("image/jpeg"           .       ".jpg")
        ("image/gif"            .       ".gif")
        ("image/png"            .       ".png")
        ("text"                 .       ".txt")
       )
)

VM will search the list for a matching type. The suffix associated with the first type that matches will be used for the temporary filename.

Displaying inline images in messages

Most versions of Emacs can display images when used on graphical screens. You can verify if the Emacs version is able to do so by calling the function display-images-p. However, Emacs relies on external libraries to create graphical images, which are specified through the variable image-library-alist. Even if Emacs has the ability to display some image type, it cannot display such images unless appropriate libraries are installed and specified to Emacs. You can verify which image types are really available by calling the function image-type-available-p with an image type such as ‘tiff’ or ‘gif’ as the argument.

Assuming that a particular image type, say ‘tiff’ is available, you can include its MIME type in vm-mime-internal-content-types, e.g.,

(add-to-list 'vm-mime-internal-content-types "image/tiff")

You can also add the MIME type to the variable vm-mime-auto-displayed-content-types so that VM will automatically display all images of the type. If the type is not included among the auto-displayed types, then the image is initially shown as a button with a thumbnail image. Clicking on the button with the middle mouse button expands the image to its full size.

Once an image is displayed, you can use the right mouse button to do various image manipulations on it, such as enlarging/reducing it, rotating it etc. To do such operations, VM uses the ‘ImageMagick’ graphics manipulation software. You can install ImageMagick on your system and specify the location of its identify and convert programs to VM via the variables vm-imagemagick-identify-program and vm-imagemagick-convert-program.

By default, VM displays images by slicing them into contiguous horizontal strips and displaying the strips in order. This facilitates vertical scrolling within an image. The variable vm-mime-use-image-strips controls whether VM uses strips for image display. It is ‘t’ by default.

VM also uses the ImageMagick’s convert program to convert between image formats, so that an image that is not displayable in Emacs is converted to another format that is displayable. You can turn off such conversion by setting the variable vm-imagemagick-convert-program to ‘nil’.

MIME type conversion

Types that cannot be displayed internally or externally are checked against an associative list of types that can be converted to other types. If an object can be converted to a type that VM can display, then the conversion is done and the new object is subject to the auto-display rules which determine whether the object is displayed immediately or a button is displayed in its place. The conversion list is stored in the variable vm-mime-type-converter-alist.

The alist format is

( (START-TYPE END-TYPE COMMAND-LINE ) ... )

START-TYPE is a string specifying a MIME type or type/subtype pair. Example ‘"text"’ or ‘"image/jpeg"’. If a top-level type is listed without a subtype, all subtypes of that type are assumed to be included.

END-TYPE must be an exact type/subtype pair. This is the type to which START-TYPE will be converted.

COMMAND-LINE is a string giving a command line to be passed to the shell. The octets that compose the object will be written to the standard input of the shell command.

Example:

(setq vm-mime-type-converter-alist
       '(
         ("image/jpeg"  "image/gif"     "jpeg2gif")
         ("text/html"   "text/plain"    "striptags")
        )
)

The first matching list element will be used.

MIME character sets

For text type messages, MIME also requires that a character set be specified, so that the recipient’s mail reader knows what character glyphs to use to display each character code. To display a message properly VM needs to know how to choose a font for a given character set.

The variable vm-mime-default-face-charsets tells VM what character sets your default face can display. For most American and European users using X Windows, Emacs’ default face displays the ISO-8859-1 and US-ASCII characters, US-ASCII being a subset of ISO-8859-1. Additional character sets can be included if you think that the messages only contain characters that your system can display. For example, messages sent by a Chinese sender might declare the character set to be GB2312 but the message might contain only English characters that you might be able to display and read. Messages sent by Microsoft Windows users might declare the character set to be Windows-1252 or CP1252, but the majority of the characters might be in ISO-8859-1. By including such character sets in vm-mime-default-face-charsets, you might be able to view the majority of the characters even if your system cannot fully handle the character set.

The value of vm-mime-default-face-charsets must be a list of strings specifying the character sets that your default face can display. Example:

(add-to-list 'vm-mime-default-face-charsets "Windows-1251")
(add-to-list 'vm-mime-default-face-charsets "Windows-1252")
(add-to-list 'vm-mime-default-face-charsets "Windows-1257")

Note that for character sets listed in this variable, VM’s MIME decoding is bypassed. So you should not add charsets like "UTF-8" that require additional decoding.

Sometimes a charset that VM cannot display can be converted to a one that VM can display. An example would be a message encoded using UTF-8 but in fact only contains Japanese characters. In that case the message text could probably be converted to iso-2022-jp which VM running on a MULE-enabled Emacs could display.

VM offers a way to do such conversions. The variable vm-mime-charset-converter-alist is an associative list of MIME charsets and programs that can convert between them. If VM cannot display a particular character set, it will scan this list to see if the charset can be converted into a charset that it can display.

The alist format is:

 ( ( START-CHARSET END-CHARSET COMMAND-LINE ) ... )

START-CHARSET is a string specifying a MIME charset. Example ‘"iso-8859-1"’ or ‘"utf-8"’.

END-CHARSET is a string specifying the charset to which START-CHARSET will be converted.

COMMAND-LINE is a string giving a command line to be passed to the shell. The characters in START-CHARSET will be written to the standard input of the shell command and VM expects characters encoded in END-CHARSET to appear at the standard output of the COMMAND-LINE. COMMAND-LINE is passed to the shell, so you can use pipelines, shell variables and redirections.

Example:

(setq vm-mime-charset-converter-alist
      '(
         ("utf-8" "iso-2022-jp" "iconv -f utf-8 -t iso-2022-jp -c")
       )
)

The first matching list element will be used. Be sure to include the -c option so that nonconvertible characters are ignored instead of causing error messages.

The variable vm-mime-charset-font-alist tells VM what font to use to display a character set that cannot be displayed using the default face. The value of this variable should be an assoc list of character sets and fonts that can be used to display them. The format of the list is:

( (CHARSET . FONT) ...)

CHARSET is a string naming a MIME registered character set such as ‘"iso-8859-5"’.

FONT is a string naming a font that can be used to display CHARSET.

An example setup might be:

(setq vm-mime-charset-font-alist
  '(
    ("iso-8859-5" . "-*-*-medium-r-normal-*-16-160-72-72-c-80-iso8859-5")
   )
)

This variable is only useful for character sets whose characters can all be encoded in single 8-bit bytes. Also multiple fonts can only be displayed if you’re running under a window system e.g. X Windows. So this variable will have no effect if you’re running Emacs on a tty.

Note that under FSF Emacs 19 any fonts you use must be the same height as your default font. XEmacs and Emacs 21 do not have this limitation. Under Emacs 20 and beyond, and under any XEmacs version compiled with MULE support, the value of vm-mime-charset-font-alist has no effect. This is because all characters are displayed using fonts discovered by MULE and VM has no control over them.

MIME multipart/alternative

MIME allows a message to be sent with its content encoded in multiple formats, simultaneously, in the same message. Such messages have a content type of multipart/alternative. The idea is that the sender might have different MIME decoding or display capabilities than some of his recipients. For instance, the sender may be able to compose a message using fancy text formatting constructs like tables, italics and equations but some of the recipients may only be able to display plain text. The ‘multipart/alternative’ type message is the solution to this dilemma. Such a message would contain at least two text subparts, one in plain text and the other in the full featured text formatting language that the sender used.

To control how VM displays ‘multipart/alternative’ messages, you must set the variable vm-mime-alternative-show-method. Its value must be a symbol. A value of best tells VM to display the message using the subpart closest in appearance to what the sender used to compose the message. In the example above this would mean displaying the fully featured text subpart, if VM knows how to display that type. VM will display the type either internally or externally. A value of best-internal tells VM to use the closest subpart that it can display internally. External viewers won’t be used in this case. A value of all asks VM to display all the alternatives.

The value can also be a list of the form

  (favorite TYPE ...)

with the first element of the list being the symbol favorite. The remaining elements of the list are strings specifying MIME types. VM will look for each TYPE in turn in the list of alternatives and choose the first matching alternative found that can be displayed. If instead of the symbol favorite, favorite-internal is used then the first TYPE that matches an alternative that can be displayed internally will be chosen.

Messages with multiple alternatives use up extra file space and slow down the operation of vm. If you would like keep the text/plain alternatives but erase the text/html alternatives, you can use the vm-nuke-alternative-text/html command. This operation may not always be safe because the text/html alternative is often the most faithful representation of the sender’s message and it may include attachments that are not replicated in the other alternatives. Please use caution.

Inferring MIME types

Some mailers incorrectly use the generic ‘application/octet-stream’ type when sending files that really have a specific MIME type. For example, a JPEG image might be sent using ‘application/octet-stream’ type instead of ‘image/jpeg’, which would be the correct type. In many cases the filename sent along with the mistyped file (e.g. foo.jpg) suggests the correct type.

If the variable vm-infer-mime-types is set non-nil, VM will attempt to use the filename sent with a MIME attachment to guess an attachment’s type if the attachment is of type ‘application/octet-stream’.

If the variable vm-infer-mime-types-for-text is set non-nil, VM will attempt to use filenames for attachments of type ‘text/plain’ as well.