The xmh program provides a graphical user interface to the
MH Message Handling System. To actually do things with your mail, it makes
calls to the MH package. Electronic mail messages may be composed, sent,
received, replied to, forwarded, sorted, and stored in folders. xmh provides
extensive mechanism for customization of the user interface.

This option specifies an alternate collection of mail folders in which
to process mail. The directory is specified as an absolute pathname. The
default mail path is the value of the Path component in the MH profile,
which is determined by the MH environment variable and defaults to $HOME/.mh_profile.
$HOME/Mail will be used as the path if the MH Path is not given in the
profile.

-initial folder

This option specifies an alternate folder which
may receive new mail and is initially opened by xmh. The default initial
folder is ``inbox''.

-flag

This option will cause xmh to change the appearance
of appropriate folder buttons and to request the window manager to change
the appearance of the xmh icon when new mail has arrived. By default, xmh
will change the appearance of the ``inbox'' folder button when new mail is
waiting. The application-specific resource checkNewMail can be used to turn
off this notification, and the -flag option will still override it.

These
three options have corresponding application-specific resources, MailPath,
InitialFolder, and MailWaitingFlag, which can be specified in a resource
file.

xmh
requires that the user is already set up to use MH, version 6. To do so,
see if there is a file called .mh_profile in your home directory. If it
exists, check to see if it contains a line that starts with ``Current-Folder''.
If it does, you've been using version 4 or earlier of MH; to convert to
version 6, you must remove that line. (Failure to do so causes spurious
output to stderr, which can hang xmh depending on your setup.)

If you do
not already have a .mh_profile, you can create one (and everything else
you need) by typing ``inc'' to the shell. You should do this before using xmh
to incorporate new mail.

Much of the user interface of xmh is configured in the Xmh application
class defaults file; if this file was not installed properly a warning
message will appear when xmh is used. xmh is backwards compatible with
the R4 application class defaults file.

The default value of the SendBreakWidth
resource has changed since R4.

xmh uses the X Toolkit Intrinsics
and the Athena Widget Set. Many of the features described below (scrollbars,
buttonboxes, etc.) are actually part of the Athena Widget Set, and are described
here only for completeness. For more information, see the Athena Widget
Set documentation.

Some parts of the main window will have a
vertical area on the left containing a grey bar. This area is a scrollbar.
They are used whenever the data in a window takes up more space than can
be displayed. The grey bar indicates what portion of your data is visible.
Thus, if the entire length of the area is grey, then you are looking at
all your data. If only the first half is grey, then you are looking at the
top half of your data. The message viewing area will have a horizontal
scrollbar if the text of the message is wider than the viewing area.

You
can use the pointer in the scrollbar to change what part of the data is
visible. If you click with pointer button 2, the top of the grey area will
move to where the pointer is, and the corresponding portion of data will
be displayed. If you hold down pointer button 2, you can drag around the
grey area. This makes it easy to get to the top of the data: just press
with button 2, drag off the top of the scrollbar, and release.

If you click
with button 1, then the data to the right of the pointer will scroll to
the top of the window. If you click with pointer button 3, then the data
at the top of the window will scroll down to where the pointer is.

Any area containing many words or short phrases, each
enclosed in a rectangular or rounded boundary, is called a buttonbox.
Each rectangle or rounded area is actually a button that you can press
by moving the pointer onto it and pressing pointer button 1. If a given
buttonbox has more buttons in it than can fit, it will be displayed with
a scrollbar, so you can always scroll to the button you want.

Some buttons
have pull-down menus. Pressing the pointer button while the pointer is over
one of these buttons will pull down a menu. Continuing to hold the button
down while moving the pointer over the menu, called dragging the pointer,
will highlight each selectable item on the menu as the pointer passes
over it. To select an item in the menu, release the pointer button while
the item is highlighted.

If you're
not satisfied with the sizes of the various areas of the main window, they
can easily be changed. Near the right edge of the border between each region
is a black box, called a grip. Simply point to that grip with the pointer,
press a pointer button, drag up or down, and release. Exactly what happens
depends on which pointer button you press.

If you drag with the pointer
button 2, then only that border will move. This mode is simplest to understand,
but is the least useful.

If you drag with pointer button 1, then you are
adjusting the size of the window above. xmh will attempt to compensate
by adjusting some window below it.

If you drag with pointer button 3, then
you are adjusting the size of the window below. xmh will attempt to compensate
by adjusting some window above it.

All windows have a minimum and maximum
size; you will never be allowed to move a border past the point where it
would make a window have an invalid size.

This section
will define the concepts of the selected folder, current folder, selected
message(s), current message, selected sequence, and current sequence.
Each xmh command is introduced.

For use in customization, action procedures
corresponding to each command are given; these action procedures can be
used to customize the user interface, particularly the keyboard accelerators
and the functionality of the buttons in the optional button box created
by the application resource CommandButtonCount.

A
folder contains a collection of mail messages, or is empty. xmh supports
folders with one level of subfolders.

The selected folder is whichever foldername
appears in the bar above the folder buttons. Note that this is not necessarily
the same folder that is currently being viewed. To change the selected
folder, just press on the desired folder button with pointer button 1;
if that folder has subfolders, select a folder from the pull-down menu.

The
Table of Contents, or toc, lists the messages in the viewed folder. The
title bar above the Table of Contents displays the name of the viewed
folder.

The toc title bar also displays the name of the viewed sequence
of messages within the viewed folder. Every folder has an implicit ``all''
sequence, which contains all the messages in the folder, and initially
the toc title bar will show ``inbox:all''.

Display the data
in the selected folder. Thus, the selected folder also becomes the viewed
folder. The action procedure corresponding to this command is XmhOpenFolder([foldername]).
It takes an optional argument as the name of a folder to select and open;
if no folder is specified, the selected folder is opened. It may be specified
as part of an event translation from a folder menu button or from a folder
menu, or as a binding of a keyboard accelerator to any widget other than
the folder menu buttons or the folder menus.

Open Folder in New Window

Displays
the selected folder in an additional main window. Note, however, that you
cannot reliably display the same folder in more than one window at a time,
although xmh will not prevent you from trying. The corresponding action
is XmhOpenFolderInNewWindow().

Create Folder

Create a new folder. You will
be prompted for a name for the new folder; to enter the name, move the
pointer to the blank box provided and type. Subfolders are created by specifying
the parent folder, a slash, and the subfolder name. For example, to create
a folder named ``xmh'' which is a subfolder of an existing folder named ``clients'',
type ``clients/xmh''. Click on the Okay button when finished, or just type Return;
click on Cancel to cancel this operation. The action corresponding to Create
Folder is XmhCreateFolder().

Delete Folder

Destroy the selected folder.
You will be asked to confirm this action (see CONFIRMATION WINDOWS). Destroying
a folder will also destroy any subfolders of that folder. The corresponding
action is XmhDeleteFolder().

Close Window

Exits xmh, after first confirming
that you won't lose any changes; or, if selected from any additional xmh
window, simply closes that window. The corresponding action is XmhClose().

It is possible
to highlight a set of adjacent messages in the area of the Table of Contents.
To highlight a message, click on it with pointer button 1. To highlight
a range of messages, click on the first one with pointer button 1 and on
the last one with pointer button 3; or press pointer button 1, drag, and
release. To extend a range of selected messages, use pointer button 3.
To highlight all messages in the table of contents, click rapidly three
times with pointer button 1. To cancel any selection in the table of contents,
click rapidly twice.

The selected messages are the same as the highlighted
messages, if any. If no messages are highlighted, then the selected messages
are considered the same as the current message.

The current message is
indicated by a `+' next to the message number. It usually corresponds to
the message currently being viewed. Upon opening a new folder, for example,
the current message will be different from the viewed message. When a message
is viewed, the title bar above the view will identify the message.

The Table of Contents command menu contains commands
which operate on the open, or viewed, folder.

Incorporate New Mail

Add
any new mail received to viewed folder, and set the current message to
be the first new message. This command is selectable in the menu and will
execute only if the viewed folder is allowed to receive new mail. By default,
only ``inbox'' is allowed to incorporate new mail. The corresponding action
is XmhIncorporateNewMail().

Commit Changes

Execute all deletions, moves,
and copies that have been marked in this folder. The corresponding action
is XmhCommitChanges().

Pack Folder

Renumber the messages in this folder
so they start with 1 and increment by 1. The corresponding action is XmhPackFolder().

Sort Folder

Sort the messages in this folder in chronological order. (As
a side effect, this may also pack the folder.) The corresponding action
is XmhSortFolder().

Rescan Folder

Rebuild the list of messages. This can
be used whenever you suspect that xmh's idea of what messages you have
is wrong. (In particular, this is necessary if you change things using
straight MH commands without using xmh.) The corresponding action is XmhForceRescan().

The Message command menu contains commands which operate
on the selected message(s), or if there are no selected messages, the current
message.

Compose Message

Composes a new message. A new window will be brought
up for composition; a description of it is given in the COMPOSITION WINDOWS
section below. This command does not affect the current message. The corresponding
action is XmhComposeMessage().

View Next Message

View the first selected
message. If no messages are highlighted, view the current message. If current
message is already being viewed, view the first unmarked message after
the current message. The corresponding action is XmhViewNextMessage().

View
Previous

View the last selected message. If no messages are highlighted,
view the current message. If current message is already being viewed, view
the first unmarked message before the current message. The corresponding
action is XmhViewPrevious().

Delete

Mark the selected messages for deletion.
If no messages are highlighted, mark the current message for deletion
and automatically display the next unmarked message. The corresponding
action is XmhMarkDelete().

Move

Mark the selected messages to be moved into
the currently selected folder. (If the selected folder is the same as the
viewed folder, this command will just beep.) If no messages are highlighted,
mark the current message to be moved and display the next unmarked message.
The corresponding action is XmhMarkMove().

Copy as Link

Mark the selected
messages to be copied into the selected folder. (If the selected folder
is the same as the viewed folder, this command will just beep.) If no messages
are highlighted, mark the current message to be copied. Note that messages
are actually linked, not copied; editing a message copied by xmh will
affect all copies of the message. The corresponding action is XmhMarkCopy().

Unmark

Remove any of the above three marks from the selected messages,
or the current message, if none are highlighted. The corresponding action
is XmhUnmark().

View in New

Create a new window containing only a view of
the first selected message, or the current message, if none are highlighted.
The corresponding action is XmhViewInNewWindow().

Reply

Create a composition
window in reply to the first selected message, or the current message,
if none are highlighted. The corresponding action is XmhReply().

Forward

Create a composition window whose body is initialized to contain an encapsulation
of of the selected messages, or the current message if none are highlighted.
The corresponding action is XmhForward().

Use as Composition

Create a composition
window whose body is initialized to be the contents of the first selected
message, or the current message if none are selected. Any changes you make
in the composition will be saved in a new message in the ``drafts'' folder,
and will not change the original message. However, there is an exception
to this rule. If the message to be used as composition was selected from
the ``drafts'' folder, (see BUGS), the changes will be reflected in the original
message (see COMPOSITION WINDOWS). The action procedure corresponding to
this command is XmhUseAsComposition().

Print

Print the selected messages,
or the current message if none are selected. xmh normally prints by invoking
the enscript(1)
command, but this can be customized with the xmh application-specific
resource PrintCommand. The corresponding action is XmhPrint().

The Sequence command menu contains commands pertaining to message
sequences (See MESSAGE-SEQUENCES), and a list of the message-sequences defined
for the currently viewed folder. The selected message-sequence is indicated
by a check mark in its entry in the margin of the menu. To change the selected
message-sequence, select a new message-sequence from the sequence menu.

Pick Messages

Define a new message-sequence. The corresponding action
is XmhPickMessages().

The following menu entries will be sensitive only
if the current folder has any message-sequences other than the ``all'' message-sequence.

Open Sequence

Change the viewed sequence to be the same as the selected
sequence. The corresponding action is XmhOpenSequence().

Add to Sequence

Add the selected messages to the selected sequence. The corresponding action
is XmhAddToSequence().

Remove from Sequence

Remove the selected messages
from the selected sequence. The corresponding action is XmhRemoveFromSequence().

Delete Sequence

Remove the selected sequence entirely. The messages themselves
are not affected; they simply are no longer grouped together to define
a message-sequence. The corresponding action is XmhDeleteSequence().

Commands in the View menu and in the buttonboxes of view windows
(which result from the Message menu command View In New) correspond in
functionality to commands of the same name in the Message menu, but they
operate on the viewed message rather than the selected messages or current
message.

Close Window

When the viewed message is in a separate view window,
this command will close the view, after confirming the status of any unsaved
edits. The corresponding action procedure is XmhCloseView().

Reply

Create
a composition window in reply to the viewed message. The related action
procedure is XmhViewReply().

Forward

Create a composition window whose body
is initialized contain an encapsulation of the viewed message. The corresponding
action is XmhViewForward().

Use As Composition

Create a composition window
whose body is initialized to be the contents of the viewed message. Any
changes made in the composition window will be saved in a new message in
the ``drafts'' folder, and will not change the original message. An exception:
if the viewed message was selected from the ``drafts'' folder, (see BUGS) the
original message is edited. The action procedure corresponding to this command
is XmhViewUseAsComposition().

Edit Message

This command enables the direct
editing of the viewed message. The action procedure is XmhEditView().

Save
Message

This command is insensitive until the message has been edited;
when activated, edits will be saved to the original message in the view.
The corresponding action is XmhSaveView().

Print

Print the viewed message.
xmh prints by invoking the enscript(1)
command, but this can be customized
with the application-specific resource PrintCommand. The corresponding action
procedure is XmhPrintView().

Delete

Marks the viewed message for deletion.
The corresponding action procedure is XmhViewMarkDelete().

When selected, a check mark appears
in the margin of this menu entry. Read in Reverse will switch the meaning
of the next and previous messages, and will increment to the current message
marker in the opposite direction. This is useful if you want to read your
messages in the order of most recent first. The option acts as a toggle;
select it from the menu a second time to undo the effect. The check mark
appears when the option is selected.

Composition windows
are created by selecting Compose Message from the Message command menu,
or by selecting Reply or Forward or Use as Composition from the Message
or View command menu. These are used to compose mail messages. Aside from
the normal text editing functions, there are six command buttons associated
with composition windows:

Close Window

Close this composition window. If
changes have been made since the most recent Save or Send, you will be
asked to confirm losing them. The corresponding action is XmhCloseView().

Send

Send this composition. The corresponding action is XmhSend().

New Headers

Replace the current composition with an empty message. If changes have
been made since the most recent Send or Save, you will be asked to confirm
losing them. The corresponding action is XmhResetCompose().

Compose Message

Bring up another new composition window. The corresponding action is XmhComposeMessage().

Save Message

Save this composition in your drafts folder. Then you can
safely close the composition. At some future date, you can continue working
on the composition by opening the drafts folder, selecting the message,
and using the ``Use as Composition'' command. The corresponding action is
XmhSave().

Insert

Insert a related message into the composition. If the
composition window was created with a ``Reply'' command, the related message
is the message being replied to, otherwise no related message is defined
and this button is insensitive. The message may be filtered before being
inserted; see ReplyInsertFilter under APPLICATION RESOURCES for more information.
The corresponding action is XmhInsert().

Accelerators are shortcuts.
They allow you to invoke commands without using the menus, either from
the keyboard or by using the pointer.

xmh defines pointer accelerators for
common actions: To select and view a message with a single click, use pointer
button 2 on the message's entry in the table of contents. To select and
open a folder or a sequence in a single action, make the folder or sequence
selection with pointer button 2.

To mark the highlighted messages, or current
message if none have been highlighted, to be moved to a folder in a single
action, use pointer button 3 to select the target folder and simultaneously
mark the messages. Similarly, selecting a sequence with pointer button 3
will add the highlighted or current message(s) to that sequence. In both
of these operations, the selected folder or sequence and the viewed folder
or sequence are not changed.

xmh defines the following keyboard accelerators
over the surface of the main window, except in the view area while editing
a message:

All of the text editing commands are actually defined
by the Text widget in the Athena Widget Set. The commands may be bound to
different keys than the defaults described below through the X Toolkit
Intrinsics key re-binding mechanisms. See the X Toolkit Intrinsics and the
Athena Widget Set documentation for more details.

Whenever you are asked
to enter any text, you will be using a standard text editing interface.
Various control and meta keystroke combinations are bound to a somewhat
Emacs-like set of commands. In addition, the pointer buttons may be used
to select a portion of text or to move the insertion point in the text.
Pressing pointer button 1 causes the insertion point to move to the pointer.
Double-clicking button 1 selects a word, triple-clicking selects a line,
quadruple-clicking selects a paragraph, and clicking rapidly five times
selects everything. Any selection may be extended in either direction by
using pointer button 3.

In the following, a line refers to one displayed
row of characters in the window. A paragraph refers to the text between
carriage returns. Text within a paragraph is broken into lines for display
based on the current width of the window. When a message is sent, text is
broken into lines based upon the values of the SendBreakWidth and SendWidth
application-specific resources.

Whenever you press a button that may cause you
to lose some work or is otherwise dangerous, a popup dialog box will appear
asking you to confirm the action. This window will contain an ``Abort'' or
``No'' button and a ``Confirm'' or ``Yes'' button. Pressing the ``No'' button cancels the
operation, and pressing the ``Yes'' will proceed with the operation.

When xmh
is run under a Release 6 session manager it will prompt the user for confirmation
during a checkpoint operation. The dialog box asks whether any current
changes should be committed (saved) during the checkpoint. Responding ``Yes''
will have the same effect as pressing the ``Commit Changes'' or ``Save Message''
buttons in the respective folder and view windows. Responding ``No'' will cause
the checkpoint to continue successfully to completion without actually
saving any pending changes. If the session manager disallows user interaction
during the checkpoint a ``Yes'' response is assumed; i.e. all changes will be
committed during the checkpoint.

Some dialog boxes contain messages from
MH. Occasionally when the message is more than one line long, not all of
the text will be visible. Clicking on the message field will cause the
dialog box to resize so that you can read the entire message.

An
MH message sequence is just a set of messages associated with some name.
They are local to a particular folder; two different folders can have sequences
with the same name. The sequence named ``all'' is predefined in every folder;
it consists of the set of all messages in that folder. As many as nine
sequences may be defined for each folder, including the predefined ``all''
sequence. (The sequence ``cur'' is also usually defined for every folder; it
consists of only the current message. xmh hides ``cur'' from the user, instead
placing a ``+'' by the current message. Also, xmh does not support MH's``unseen''
sequence, so that one is also hidden from the user.)

The message sequences
for a folder (including one for ``all'') are displayed in the ``Sequence'' menu,
below the sequence commands. The table of contents (also known as the ``toc'')
is at any one time displaying one message sequence. This is called the
``viewed sequence'', and its name will be displayed in the toc title bar after
the folder name. Also, at any time one of the sequences in the menu will
have a check mark next to it. This is called the ``selected sequence''. Note
that the viewed sequence and the selected sequence are not necessarily
the same. (This all pretty much corresponds to the way folders work.)

The
Open Sequence, Add to Sequence, Remove from Sequence, and Delete Sequence
commands are active only if the viewed folder contains message-sequences
other than ``all'' sequence.

Note that none of the above actually affect whether
a message is in the folder. Remember that a sequence is a set of messages
within the folder; the above operations just affect what messages are in
that set.

To create a new sequence, select the ``Pick'' menu entry. A new window
will appear, with lots of places to enter text. Basically, you can describe
the sequence's initial set of messages based on characteristics of the message.
Thus, you can define a sequence to be all the messages that were from
a particular person, or with a particular subject, and so on. You can also
connect things up with boolean operators, so you can select all things
from ``weissman'' with a subject containing ``xmh''.

The layout should be fairly
obvious. The simplest cases are the easiest: just point to the proper field
and type. If you enter in more than one field, it will only select messages
which match all non-empty fields.

The more complicated cases arise when
you want things that match one field or another one, but not necessarily
both. That's what all the ``or'' buttons are for. If you want all things with
subjects that include ``xmh'' or ``xterm'', just press the ``or'' button next to the
``Subject:'' field. Another box will appear where you can enter another subject.

If you want all things either from ``weissman'' or with subject ``xmh'', but not
necessarily both, select the ``-Or-'' button. This will essentially double the
size of the form. You can then enter ``weissman'' in a from: box on the top
half, and ``xmh'' in a subject: box on the lower part.

If you select the ``Skip''
button, then only those messages that don't match the fields on that row
are included.

Finally, in the bottom part of the window will appear several
more boxes. One is the name of the sequence you're defining. (It defaults
to the name of the selected sequence when ``Pick'' was pressed, or to ``temp''
if ``all'' was the selected sequence.) Another box defines which sequence to
look through for potential members of this sequence; it defaults to the
viewed sequence when ``Pick'' was pressed.

Two more boxes define a date range;
only messages within that date range will be considered. These dates must
be entered in RFC 822-style format: each date is of the form ``dd mmm yy hh:mm:ss
zzz'', where dd is a one or two digit day of the month, mmm is the three-letter
abbreviation for a month, and yy is a year. The remaining fields are optional:
hh, mm, and ss specify a time of day, and zzz selects a time zone. Note
that if the time is left out, it defaults to midnight; thus if you select
a range of ``7 nov 86'' - ``8 nov 86'', you will only get messages from the 7th,
as all messages on the 8th will have arrived after midnight.

``Date field''
specifies which field in the header to look at for this date range; it
defaults to ``Date''. If the sequence you're defining already exists, you can
optionally merge the old set with the new; that's what the ``Yes'' and ``No'' buttons
are all about. Finally, you can ``OK'' the whole thing, or ``Cancel'' it.

In general,
most people will rarely use these features. However, it's nice to occasionally
use ``Pick'' to find some messages, look through them, and then hit ``Delete
Sequence'' to put things back in their original state.

In
order to specify resources, it is useful to know the hierarchy of widgets
which compose xmh. In the notation below, indentation indicates hierarchical
structure. The widget class name is given first, followed by the widget
instance name. The application class name is Xmh.

The hierarchy of the main
toc and view window is identical for additional toc and view windows, except
that a TopLevelShell widget is inserted in the hierarchy between the application
shell and the Paned widget.

The application class name is Xmh. Application-specific
resources are listed below by name. Application-specific resource class names
always begin with an upper case character, but unless noted, are otherwise
identical to the instance names given below.

Any of these options may also
be specified on the command line by using the X Toolkit Intrinsics resource
specification mechanism. Thus, to run xmh showing all message headers,
% xmh -xrm '*HideBoringHeaders:off'

If TocGeometry, ViewGeometry, CompGeometry,
or PickGeometry are not specified, then the value of Geometry is used instead.
If the resulting height is not specified (e.g., "", "=500", "+0-0"), then
the default height of windows is calculated from fonts and line counts.
If the width is not specified (e.g., "", "=x300", "-0+0"), then half of the
display width is used. If unspecified, the height of a pick window defaults
to half the height of the display.

The following resources are defined:

banner

A short string that is the default label of the folder, Table of
Contents, and view. The default shows the program name, vendor, and release.

blockEventsOnBusy

Whether to disallow user input and show a busy cursor
while xmh is busy processing a command. If false, the user can `mouse ahead'
and type ahead; if true, user input is discarded when processing lengthy
mh commands. The default is true.

busyCursor

The name of the symbol used
to represent the position of the pointer, displayed if blockEventsOnBusy
is true, when xmh is processing a time-consuming command. The default is
"watch".

busyPointerColor

The foreground color of the busy cursor. Default
is XtDefaultForeground.

checkFrequency

How often to check for new mail,
make checkpoints, and rescan the Table of Contents, in minutes. If checkNewMail
is true, xmh checks to see if you have new mail each interval. If makeCheckpoints
is true, checkpoints are made every fifth interval. Also every fifth interval,
the Table of Contents is checked for inconsistencies with the file system,
and rescanned if out of date. To prevent all of these checks from occurring,
set CheckFrequency to 0. The default is 1. This resource is retained for
backward compatibility with user resource files; see also checkpointInterval,
mailInterval, and rescanInterval.

checkNewMail

If true, xmh will check at
regular intervals to see if new mail has arrived for any of the top level
folders and any opened subfolders. A visual indication will be given if
new mail is waiting to be incorporated into a top level folder. Default
is true. The interval can be adjusted with mailInterval.

checkpointInterval
(class Interval)

Specifies in minutes how often to make checkpoints of
volatile state, if makeCheckpoints is true. The default is 5 times the value
of checkFrequency.

checkpointNameFormat

Specifies how checkpointed files
are to be named. The value of this resource will be used to compose a file
name by inserting the message number as a string in place of the required
single occurance of `%d'. If the value of the resource is the empty string,
or if no `%d' occurs in the string, or if "%d" is the value of the resource,
the default will be used instead. The default is "%d.CKP". Checkpointing
is done in the folder of origin unless an absolute pathname is given.
xmh does not assist the user in recovering checkpoints, nor does it provide
for removal of the checkpoint files.

commandButtonCount

The number of command
buttons to create in a button box in between the toc and the view areas
of the main window. xmh will create these buttons with the names button1,
button2 and so on, in a box with the name commandBox. The default is 0.
xmh users can specify labels and actions for the buttons in a private
resource file; see the section ACTIONS AND INTERFACE CUSTOMIZATION.

compGeometry

Initial geometry for windows containing compositions.

cursor

The name of
the symbol used to represent the pointer. Default is ``left_ptr''.

debug

Whether
or not to print information to stderr as xmh runs. Default is false.

draftsFolder

The folder used for message drafts. Default is ``drafts''.

geometry

Default
geometry to use. Default is none.

hideBoringHeaders

If ``on'', then xmh will
attempt to skip uninteresting header lines within messages by scrolling
them off the top of the view. Default is ``on''.

initialFolder

Which folder to
display on startup. May also be set with the command-line option -initial.
Default is ``inbox''.

initialIncFile

The absolute path name of your incoming
mail drop file. In some installations, for example those using the Post
Office Protocol, no file is appropriate. In this case, initialIncFile should
not be specified, or may be specified as the empty string, and inc will
be invoked without a -file argument. By default, this resource has no value.
This resource is ignored if xmh finds an .xmhcheck file; see the section
on multiple mail drops.

mailInterval (class Interval)

Specifies the interval
in minutes at which the mail should be checked, if mailWaitingFlag or checkNewMail
is true. The default is the value of checkFrequency.

mailPath

The full path
prefix for locating your mail folders. May also be set with the command
line option, -path. The default is the Path component in the MH profile,
or ``$HOME/Mail'' if none.

mailWaitingFlag

If true, xmh will attempt to set
an indication in its icon when new mail is waiting to be retrieved. If
mailWaitingFlag is true, then checkNewMail is assumed to be true as well.
The -flag command line option is a quick way to turn on this resource.

makeCheckpoints

If true, xmh will attempt to save checkpoints of volatile edits. The default
is false. The frequency of checkpointing is controlled by the resource
checkpointInterval. For the location of checkpointing, see checkpointNameFormat.

mhPath

What directory in which to find the MH commands. If a command isn't
found in the user's path, then the path specified here is used. Default is
``/usr/local/mh6''.

newMailBitmap (class NewMailBitmap)

The bitmap to show in
the folder button when a folder has new mail. The default is ``black6''.

newMailIconBitmap
(class NewMailBitmap)

The bitmap suggested to the window manager for the
icon when any folder has new mail. The default is ``flagup''.

noMailBitmap (class
NoMailBitmap)

The bitmap to show in the folder button when a folder has
no new mail. The default is ``box6''.

noMailIconBitmap (class NoMailBitmap)

The
bitmap suggested to the window manager for the icon when no folders have
new mail. The default is ``flagdown''.

pickGeometry

Initial geometry for pick
windows.

pointerColor

The foreground color of the pointer. Default is XtDefaultForeground.

prefixWmAndIconName

Whether to prefix the window and icon name with "xmh:
". Default is true.

printCommand

An sh command to execute to print a message.
Note that stdout and stderr must be specifically redirected. If a message
or range of messages is selected for printing, the full file paths of each
message file are appended to the specified print command. The default is
``enscript >/dev/null 2>/dev/null''.

replyInsertFilter

An sh command to be executed
when the Insert button is activated in a composition window. The full path
and filename of the source message is appended to the command before being
passed to sh(1)
. The default filter is cat; i.e. it inserts the entire message
into the composition. Interesting filters are: sed 's/^/> /' or awk -e '{print
" " $0}' or <mh directory>/lib/mhl -form mhl.body.

rescanInterval (class Interval)

How often to check the Table of Contents of currently viewed folders and
of folders with messages currently being viewed, and to update the Table
of Contents if xmh sees inconsistencies with the file system in these folders.
The default is 5 times the value of checkFrequency.

reverseReadOrder

When
true, the next message will be the message prior to the current message
in the table of contents, and the previous message will be the message
after the current message in the table of contents. The default is false.

sendBreakWidth

When a message is sent from xmh, lines longer than this
value will be split into multiple lines, each of which is no longer than
SendWidth. This value may be overridden for a single message by inserting
an additional line in the message header of the form SendBreakWidth: value.
This line will be removed from the header before the message is sent. The
default is 2000 (to allow for sending mail containing source patches).

sendWidth

When a message is sent from xmh, lines longer than SendBreakWidth characters
will be split into multiple lines, each of which is no longer than this
value. This value may be overridden for a single message by inserting an
additional line in the message header of the form SendWidth: value. This
line will be removed from the header before the message is sent. The default
is 72.

showOnInc

Whether to automatically show the current message after
incorporating new mail. Default is true.

skipCopied

Whether to skip over
messages marked for copying when using ``View Next Message'' and ``View Previous
Message''. Default is true.

skipDeleted

Whether to skip over messages marked
for deletion when using ``View Next Message'' and ``View Previous Message''. Default
is true.

skipMoved

Whether to skip over messages marked for moving to other
folders when using ``View Next Message'' and ``View Previous Message''. Default
is true.

stickyMenu

If true, when popup command menus are used, the most
recently selected entry will be under the cursor when the menu pops up.
Default is false. See the file clients/xmh/Xmh.sample for an example of
how to specify resources for popup command menus.

tempDir

Directory for
xmh to store temporary files. For privacy, a user might want to change
this to a private directory. Default is ``/tmp''.

tocGeometry

Initial geometry
for main xmh toc and view windows.

tocPercentage

The percentage of the main
window that is used to display the Table of Contents. Default is 33.

tocWidth

How many characters to generate for each message in a folder's table of
contents. Default is 100. Use less if the geometry of the main xmh window
results in the listing being clipped at the right hand boundary, or if
you plan to use mhl a lot, because it will be faster, and the extra characters
may not be useful.

Users may need to incorporate mail from
multiple spool files or mail drops. If incoming mail is forwarded to the
MH slocal program, it can be sorted as specified by the user into multiple
incoming mail drops. Refer to the MH man page for slocal to learn how to
specify fowarding and the automatic sorting of incoming mail in a .maildelivery
file.

To inform xmh about the various mail drops, create a file in your
home directory called .xmhcheck. In this file, a mapping between existing
folder names and mail drops is created by giving a folder name followed
by the absolute pathname of the mail drop site, with some white space separating
them, one mapping per line. xmh will read this file whether or not resources
are set for notification of new mail arrival, and will allow incorporation
of new mail into any folder with a mail drop. xmh will invoke inc with the
-file argument, and if xmh has been requested to check for new mail, it
will check directly, instead of using msgchk.

An example of .xmhcheck file
format, for the folders ``inbox'' and ``xpert'':

Because xmh provides action procedures
which correspond to command functionality and installs accelerators, users
can customize accelerators and new button functionality in a private resource
file. For examples of specifying customized resources, see the file mit/clients/xmh/Xmh.sample.
To understand the syntax, see the Appendix of the X Toolkit Intrinsics
specification on Translation Table Syntax, and any general explanation
of using and specifying X resources. Unpredictable results can occur if
actions are bound to events or widgets for which they were not designed.

Here's an example of how to bind actions to your own xmh buttons, and how
to redefine the default accelerators so that the Meta key is not required,
in case you don't have access to the sample file mentioned above.

xmh provides action procedures which correspond to entries in the command
menus; these are given in the sections describing menu commmands, not here.
In addition to the actions corresponding to commands in the menus, these
action routines are defined:

XmhPushFolder([foldername, ...])

This action
pushes each of its argument(s) onto a stack of foldernames. If no arguments
are given, the selected folder is pushed onto the stack.

XmhPopFolder()

This action pops one foldername from the stack and sets the selected folder.

XmhPopupFolderMenu()

This action should always be taken when the user selects
a folder button. A folder button represents a folder and zero or more subfolders.
The menu of subfolders is built upon the first reference, by this routine.
If there are no subfolders, this routine will mark the folder as having
no subfolders, and no menu will be built. In that case the menu button
emulates a toggle button. When subfolders exist, the menu will popup, using
the menu button action PopupMenu().

XmhSetCurrentFolder()

This action allows
menu buttons to emulate toggle buttons in the function of selecting a folder.
This action is for menu button widgets only, and sets the selected folder.

XmhLeaveFolderButton()

This action ensures that the menu button behaves
properly when the user moves the pointer out of the menu button window.

XmhPushSequence([sequencename, ...])

This action pushes each of its arguments
onto the stack of sequence names. If no arguments are given, the selected
sequence is pushed onto the stack.

XmhPopSequence()

This action pops one
sequence name from the stack of sequence names, which then becomes the
selected sequence.

XmhPromptOkayAction()

This action is equivalent to pressing
the okay button in the Create Folder popup.

XmhReloadSeqLists()

This action
rescans the contents of the public MH sequences for the currently opened
folder and updates the sequence menu if necessary.

XmhShellCommand( parameter
[, parameter])

At least one parameter must be specified. The parameters
will be concatenated with a space character separator, into a single string,
and the list of selected messsages, or if no messages are selected, the
current message, will be appended to the string of parameters. The string
will be executed as a shell command. The messages are always given as absolute
pathnames. It is an error to cause this action to execute when there are
no selected messages and no current message.

XmhCheckForNewMail()

This action
will check all mail drops known to xmh. If no mail drops have been specified
by the user either through the .xmhcheck file or by the initialIncFile resource,
the MH command msgchk is used to check for new mail, otherwise, xmh checks
directly.

XmhWMProtocols([wm_delete_window] [wm_save_yourself])

This action
is responsible for participation in window manager communication protocols.
It responds to delete window and save yourself messages. The user can cause
xmh to respond to one or both of these protocols, exactly as if the window
manager had made the request, by invoking the action with the appropriate
parameters. The action is insensitive to the case of the string parameters.
If the event received is a ClientMessage event and parameters are present,
at least one of the parameters must correspond to the protocol requested
by the event for the request to be honored by xmh.

The initial text displayed in a composition window is generated by executing
the corresponding MH command; i.e. comp, repl, or forw, and therefore message
components may be customized as specified for those commands. comp is executed
only once per invocation of xmh and the message template is re-used for
every successive new composition.

xmh uses MH commands, including inc, msgchk,
comp, send, repl, forw, refile, rmm, pick, pack, sort, and scan. Some flags
for these commands can be specified in the MH profile; xmh may override
them. The application resource debug can be set to true to see how xmh
uses MH commands.

~/.mh_profile - MH profile,
used if the MH environment variable is not set
~/Mail - directory of folders, used if the MH profile cannot be found
~/.xmhcheck - optional, for multiple mail drops in cooperation with slocal.
/usr/local/mh6 - MH commands, as a last resort, see mhPath.
~/Mail/<folder>/.xmhcache - scan output in each folder
~/Mail/<folder>/.mh_sequences - sequence definitions, in each folder
/tmp - temporary files, see tempDir.

- When the user
closes a window, all windows which are transient for that window should
also be closed by xmh.
- When XmhUseAsComposition and XmhViewUseAsComposition operate on messages
in the DraftsFolder, xmh disallows editing of the composition if the same
message is also being viewed in another window.
- Occasionally after committing changes, the table of contents will appear
to be completely blank when there are actually messages present. When this
happens, refreshing the display, or typing Control-L in the table of contents,
will often cause the correct listing to appear. If this doesn't work, force
a rescan of the folder.
- Should recognize and use the ``unseen'' message-sequence.
- Should determine by itself if the user hasn't used MH before, and offer
to create the .mh_profile, instead of hanging on inc.
- A few commands are missing (rename folder, resend message).
- WM_DELETE_WINDOW protocol doesn't work right when requesting deletion of
the first toc and view, while trying to keep other xmh windows around.
- Doesn't support annotations when replying to messages.
- Doesn't allow folders to be shared without write permission.
- Doesn't recognize private sequences.
- MH will report that the .mh_sequences file is poorly formatted if any sequence
definition in a particular folder contains more than BUFSIZ characters.
xmh tries to capture these messages and display them when they occur,
but it cannot correct the problem.
- Should save a temporary checkpoint file rather than requiring changes
to be committed in the non-shutdown case.