12 Summaries

Typing h (vm-summarize) causes VM to display a summary of contents of the current folder. The information in the summary is automatically updated as changes are made to the current folder. An arrow ‘->’ appears to the left of the line summarizing the current message. The variable vm-auto-center-summary controls whether VM will keep the summary arrow vertically centered within the summary window. A value of t causes VM to always keep the arrow centered. A value of nil (the default) means VM will never bother centering the arrow. A value that is not nil and not t causes VM to center the arrow only if the summary window is not the only existing window. You can change what the summary arrow looks like by setting vm-summary-arrow to a string depicting the new arrow. You should set this variable before VM creates the summary buffer.

You can have a summary generated automatically at VM startup by setting the variable vm-startup-with-summary non-nil. See Starting Up.

All VM commands are available in the summary buffer just as they are in the folder buffer itself. If you set vm-follow-summary-cursor non-nil, VM will select the message under the cursor in the summary window before executing commands that operate on the current message. Note that this occurs only when executing a command from the summary buffer window.

A non-nil value of vm-gargle-uucp means to use a crufty regular expression that does surprisingly well at beautifying UUCP addresses that are substituted for ‘%f’ and ‘%t’ as part of summary and attribution formats.

12.1 Summary Format

The variable vm-summary-format controls the format of each message’s summary. Its value should be a string. This string should contain printf-like “%” conversion specifiers which substitute information about the message into the final summary.

Recognized specifiers are:

a

attribute indicators (always four characters wide)
The first char is ‘D’, ‘N’, ‘U’ or ‘ ’ for deleted, new, unread and read messages respectively.
The second char is ‘F’, ‘W’ or ‘ ’ for filed (saved) or written messages.
The third char is ‘R’, ‘Z’ or ‘ ’ for messages replied to, and forwarded messages.
The fourth char is ‘E’ if the message has been edited, ‘ ’ otherwise.

A

longer version of attributes indicators (seven characters wide).

The first char is ‘D’, ‘N’, ‘U’ or ‘ ’ for deleted, new, unread and read messages respectively.
The second is ‘r’ or ‘ ’, for message replied to.
The third is ‘z’ or ‘ ’, for messages forwarded.
The fourth is ‘b’ or ‘ ’, for messages redistributed.
The fifth is ‘f’ or ‘ ’, for messages filed.
The sixth is ‘w’ or ‘ ’, for messages written.
The seventh is ‘e’ or ‘ ’, for messages that have been edited.

P

indicator for a message with attachments. The variable vm-summary-attachment-indicator is the inserted string, by default a $.

p

indicator for a postponed message. The variable vm-summary-postponed-indicator is the inserted string, by default a P.

c

number of characters in message (ignoring headers)

S

human readable size of the message

d

numeric day of month message sent

f

author’s address

F

author’s full name (same as f if full name not found)

h

hour:min:sec message sent

H

hour:min message sent

i

message ID

I

thread indentation

l

number of lines in message (ignoring headers)

L

labels (as a comma list)

m

month message sent

M

numeric month message sent (January = 1)

n

message number

s

message subject

t

addresses of the recipients of the message, in a comma-separated list

T

full names of the recipients of the message, in a comma-separated list If a full name cannot be found, the corresponding address is used instead.

U

user defined specifier. The next character in the format string should be a letter. VM will call the function vm-summary-function-<letter> (e.g. vm-summary-function-A for “%UA”) in the folder buffer with the message being summarized bracketed by (point-min) and (point-max). The function will be passed a message struct as an argument. The function should return a string, which VM will insert into the summary as it would for information from any other summary specifier.

w

day of the week message sent

y

year message sent

z

timezone of date when the message was sent

*

‘*’ if the message is marked, ‘ ’ otherwise

(

starts a group, terminated by %). Useful for specifying the field width and precision for the concatenation of group of format specifiers. Example: \"%.35(%I%s%)\" specifies a maximum display width of 35 characters for the concatenation of the thread indentation and the subject.

)

ends a group.

Use “%%” to get a single “%”.

A numeric field width may be specified between the “%” and the specifier; this causes right justification of the substituted string. A negative field width causes left justification. The field width may be followed by a “.” and a number specifying the maximum allowed length of the substituted string. If the string is longer than this value, it is truncated.

If you save copies of all your outbound messages in a folder and later visit that folder, the ‘%F’ format specifier will normally display your own name. If you would rather see the recipient addresses in this case, set the variable vm-summary-uninteresting-senders. This variable’s value, if non-nil, should be a regular expression that matches addresses that you don’t consider interesting enough to appear in the summary. When such senders would be displayed by the ‘%F’ or ‘%f’ summary format specifiers VM will substitute the value of vm-summary-uninteresting-senders-arrow (default "To: ") followed by what would be shown by the ‘%T’ and ‘%t’ specifiers respectively.

The summary format need not be one line per message but it must end with a newline, otherwise the message pointer will not be displayed correctly in the summary window.

Summary lines are precomputed and cached in the folder buffer. If you change the vm-summary-format, you need to force the cache to be updated. You can do this by the commandvm-fix-my-summary.

Every folder can have its own summary format. The format is written into the folder and saved on the disk. When you visit the folder again, you can reuse the saved summary format. Set the variable vm-restore-saved-summary-format to t to achieve this effect.

12.2 Threaded Summaries

When message threading is enabled (see Threading), you will find that the Summary buffer has all related messages are grouped together and the subject titles are indented to show hierarchical relationships. Parent messages are displayed before their children and children are indented by a default two spaces to the right. The amount of indentation per level is controlled by the variable vm-summary-thread-indent-level. The default is two spaces. The variable vm-summary-maximum-thread-indentation says how many levels should be displayed via indentation. The default is 20.

If you want VM to always display summaries using threads, you should set the default value of the variable vm-summary-show-threads non-nil in your VM init file. Example:

(setq-default vm-summary-show-threads t)

Do not use setq, as this will only set the value of the variable in a single buffer. Once you’ve started VM you should not change the value of this variable. Rather you should use C-t to control the thread display. See Threading.

Manual control of thread indentation

When you deal with long discussions in mailing lists or newsgroups, you would find that threads get very deep and their indentation in the Summary window is not entirely helpful. You can temporarily promote the subthreads to higher level so that you can view the threading relationships more clearly.

The command < (vm-promote-subthread) temporarily decreases the indentation of the current message and its subthread by one step. You can give the command a numeric prefix argument N asking it to decreasing indentation by N steps. Giving 0 as the prefix argument has a special meaning. It says that the current message should not be indented at all, effectively making it appear as the root message of a thread.

The command > (M-x vm-demote-subthread) does the opposite. It increases the indentation of the current message and its subthread. You can specify the level of increased indentation as the prefix argument. Giving 0 as the prefix argument has the special meaning of asking VM to return the message to its standard indentation as determined by its thread level.

Both of these commands alter the thread indentation for the current session only. The next time you visit the folder, the threads will be displayed using the standard indentation.

12.3 Thread Folding

A new feature in VM version 8.2 is that of “folding” message threads in the summary window. This feature allows you to collapse all the messages in a thread into a single line of the summary window, so that you can see a more compact summary of the folder.

Thread folding is enabled by setting the variable vm-summary-enable-thread-folding to a non-nil value. The summary window then has a folding indicator in the first column: with - for threads that are expanded and + for threads that are collapsed. The command T (vm-toggle-thread) allows you to expand a collapsed thread or collapse an expanded thread. The commands vm-expand-thread and vm-collapse-thread implement the more specific versions of the function.

When threads are folded, not all messages in the threads are hidden. New messages that are yet unread continue to be visible. Which messages remain visible in folded threads is controlled by the variable vm-summary-visible, whose value must be a list of VM selectors in the same format as those in vm-virtual-folder-alist. See Virtual Folders.

The variable vm-summary-thread-folding-on-motion allows a more automatic expansion/collapsing of threads. If the variable is set to a non-nil value, then the usual motion commands N and P (vm-next-message-no-skip and vm-previous-message-no-skip) cause the threads to be expanded or collapsed as needed when you move into or out of threads.

The variable vm-summary-show-thread-count allows a more elaborate display of the thread information in the summary window. If it is set to non-nil then the message number field of the summary line includes a count of the messages in its thread, in the format N+C where N is the message number and C is the message count in the thread. This takes up 3 extra columns in the summary lines. Set the variable to nil to obtain the more standard format of the summary.

When thread folding is enabled, the Summary window starts out with all the threads folded. You can expand all the threads in the folder using the command E (vm-expand-all-threads). The command C (vm-collapse-all-threads) does the reverse.

12.4 Thread Operations

When you have thread-folding enabled, you can execute VM operations such as saving and deleting messages on entire threads. To obtain this functionality, set the variable vm-enable-thread-operations to a non-nil value in your vm-init-file. Setting it to ‘t’ enables thread operations unconditionally. Setting it to the symbol ‘ask’ allows a confirmation dialog before a thread operation is invoked. You can use the command vm-toggle-thread-operations in a running VM session to enable or disable thread operations.

As an example, doing an s (vm-save-message) operation on an ordinary message saves just the single message. However, if thread operations are enabled and you invoke s on the root message of a collapsed thread, then the entire thread is saved. The same effect can be obtained using message marking. See Marking Messages. The following sequence of key strokes can achieve the effect of saving an entire thread:

MuMTMNsMu

However, the thread-operation is simpler and more convenient.

All operations that can be sensibly invoked on multiple messages extend to thread operations in this way. They include deleting, undeleting, marking, unmarking, forwarding, saving/deleting attachments etc. Replying to messages cannot be invoked as a thread operation, to prevent the accidental sending of replies to unintended recipients.

The thread operations can give rise to surprising behavior. Even though it appears that an operation was invoked on a single message, it actually applies to all the messages in a thread. So, care and practice are warranted before you enable thread operations unconditionally. A safer option is to set ‘vm-enable-thread-operations’ to ‘ask’. In that case, VM asks for confirmation every time an operation is applicable to all the messages in a collapsed thread. You can override the confirmation dialog by giving a prefix argument ‘C-u’ to your operation.

12.5 Summary Faces

By default, the summary of a folder is shown in a black-and-white window with plain text. This is suitable for terminal mode Emacs users. The variable vm-summary-highlight-face, which is set to the standard Emacs bold face by default, is used to highlight the currently selected message. You can set the variable to any other face, or to nil if you wan to turn off highlighting.

You can turn on more elaborate faces support, suitable for color graphics terminals, by setting the variable vm-summary-enable-faces to t in your vm-init-file. You can also run M-x vm-summary-faces-mode in the middle of a VM session to turn on summary faces. Then VM decorates the summary lines with different faces based on the attributes of the message. See Faces in the GNU Emacs Manual, for basic information on faces. The predefined faces used to highlight the summary window are listed below. It is possible for you to change the definitions of these faces in your vm-init-file as well as to define new faces of your own.

The variable vm-summary-faces-alist defines a list of condition-action pairs for decorating the summary with faces. It has the following form:

( ((SELECTOR [ARG ...])    vm-summary-FACE)
  ... )

The first element of each pair is a VM selector in the same format as used for vm-virtual-folder-alist. See Virtual Folders. The second element is a face name of the form vm-summary-FACE where FACE is one of the face types listed below. The first condition satisfied by the message wins, and the face listed there is used to decorate its summary line.

The faces vm-summary-selected, vm-summary-collapsed and vm-summary-expanded are special. They are added to the face specified by vm-summary-faces-alist instead of replacing it. This allows VM to add highlighting for the selected message and the collapsed/expanded thread roots, without scrubbing the natural face determined by the message attributes.

The variable vm-mouse-track-summary controls whether summary entries are highlighted when the mouse pointer passes over them. The highlighting is done using the standard Emacs highlight face.

Hiding summary lines

The command vm-summary-faces-hide allows you to hide the summary lines of messages with a particular face type. By default, it hides messages with the deleted face type. By invoking it with a prefix argument, you can specify other face types that you might like to hide. (Note that deleted face type does not necessarily mean deleted messages. Whatever messages satisfy the condition associated with the vm-summary-deleted-face in vm-summary-faces-alist will be hidden.)

Predefined summary faces

• vm-summary-high-priority: Messages that are flagged or have other priority headers.
• vm-summary-low-priority: Messages that might be of low priority, by user-defined criteria.
• vm-summary-deleted: Deleted messages.
• vm-summary-new: New messages that have arrived during the session.
• vm-summary-unread: Messages that have not been read.
• vm-summary-marked: Messages currently marked.
• vm-summary-replied: Messages for which a reply has been sent.
• vm-summary-saved: Messages saved to a folder on disk. (Subsumes the earlier categories filed and written.)
• vm-summary-forwarded: Messages forwarded to other recipients. (Subsumes the earlier category redistributed.)
• vm-summary-edited: Messages edited after receipt.
• vm-summary-outgoing: Messages sent by you.
• vm-summary-default: Messages not matching any of the above criteria.
• vm-summary-collapsed: Root messages of threads that are collapsed.
• vm-summary-expanded: Root messages of threads that are expanded.
• vm-summary-selected: Message that is currently selected.