XMAIL(1)

NAME
xmail - X11 visual interface to the mail program

SYNOPSIS
xmail [-toolkitoptions] [-xmailoptions]

DESCRIPTION
xmail is an X11 window based visual interface to the Mail program. It offers functionality similar to the SunView mailtool, but with some enhancements. Users may use mouse button actions in the index window to select a message for further processing (by pressing left mouse button), and automatically read the selected message (by pressing the right mouse button). Folder specification is aided by a selection menu which can walk down through the user's folder directory hierarchy. Message composition and modification is provided by the user's preferred visual editor (vi by default). Editor preference can be specified using the process or Mail environment variable VISUAL. Help is available for any window or command button by pressing the middle mouse button on the window or command button while holding down the Shift key.

OPTIONS
A non-existent or illegal command line option specification will cause display of the usage statement and xmail termination.

-toolkitoptions
    All standard X11 toolkit options are accepted on the command line.

-xmailoptions
    xmail also accepts the following additional options:

    -iconGeometry +XOff+YOff
        provides a command line option for specifying the preferred geometry location for the xmail icon window. This overrides any xmail resource specification for "*iconGeometry: +XOff+YOff".

    -nb tells xmail to not ring the terminal bell when issuing status and error messages. This is equivalent to the xmail resource specification "*bellRing: False".

    -helpfont fontname
        specifies the font to use when displaying help text. This option overrides the xmail resource specification "*helpFont: fontname".

    -n  tells Mail to not initialize from the system default Mail.rc file. This option is actually a Mail program option, which is passed on to it during startup from xmail. The option can also be specified as an xmail resource using the specification "*mailopt_n: True".

    -U  tells Mail to convert internet style addresses into uucp format. This option also is a Mail option, passed on to it during startup. The option can also be specified as an xmail resource using the specification "*mailopt_U: True".

    -f +foldername
        tells Mail to start by processing the specified folder. This is also a Mail program option, passed to it during startup. The option can also be specified as an xmail resource using the specification "*MFileName: +foldername".

    -ls tells xmail to not show the last message of a folder by default. This option is equivalent to setting the xmail resource *Show_Last to False. If disabled, xmail (actually Mail) will display the default (usually first) message of a folder when switching to or re-reading a folder. By default, xmail attempts to read the latest (or last) message of a folder.

USAGE
The xmail shell appearance is similar in layout to mailtool. A title bar decorates the top of the shell, and carries the name and version of the program, as well as information about the current mail folder and its content. Immediately below the title bar, an index window displays header information for the current mail folder. Message selection is indicated by highlight of the number of a particular message. New and unread mail are prefixed with 'N' and 'U' characters. Deleted messages not yet removed from the index list have the letter 'D' preceding the message number. Below the index window, a status window displays status and error messages. The terminal bell is usually rung to draw attention to these messages. The bell can be disabled from the command line or user resource file. The center portion of the shell displays a panel with a selection of commonly used Mail commands. Pressing and then releasing (also known as "clicking") the left mouse button while the cursor is within a particular command button box invokes that Mail command. Each button in the command panel also offers an expanded menu of choices. Pressing the right mouse button presents the user with the expanded menu. Dragging the cursor over one of these selections while still holding the right button down causes the particular selection to highlight. Releasing the right button while a selection is highlighted invokes that particular command action. Keyboard accelerators for these actions are indicated by appropriate entries in the command menus. Users may take advantage of these accelerators by holding down the Shift and/or Control key(s) prior to clicking the left mouse button on the desired command. A grip along the right edge of the command panel allows the user to slide the status window/command panel combination up and down in the xmail shell, to accommodate those times when the user is reviewing a short list of longer than average messages, or a longer list of relatively short messages. Message text is displayed in the bottom window of the xmail shell. Like the index window above, scroll bars provide easy access to any portion of the text. Because the reading of a very large message can take more than a few moments, xmail decides when starting Mail or changing folders that a message longer than 65,000 characters will not be automatically displayed. A modified mailWatch widget (ala xwatch) is used as the xmail icon window. The mailbox flag will be raised and mail shown inside, whenever new mail arrives. In the non-iconic state, the Newmail command button is highlighted to signal new mail arrival. Clicking on the Newmail button will reset the flag and highlighting, and deliver the new mail to your display. Pressing the middle mouse button on any window or command button of the xmail shell while holding down either Shift key will cause help information relating to that window (or button) to be displayed in the text (bottom) window. Releasing the mouse button will cause the help information to disappear. During command execution, the cursor is changed to a watch face to indicate that xmail is busy. Upon completion of the activity, the cursor is restored to its previous value.

ICONIFICATION
xmail establishes access to a dummy mail folder whenever the application is iconified. This is done to prevent potential corruption of a real mail folder, should the user choose to read their mail from another process while xmail is running. Because of this action, iconifying xmail always COMMITS any changes made to the current folder, prior to switching to the dummy folder. The original folder being read by the user will be automatically reinstated as current whenever xmail is again de-iconified. This action will flush any deleted messages from the index headers and renumber the remaining messages in the folder. The last message in the folder will then become the current message displayed (unless xmail was started with the *Show_Last resource option disabled, in which case the first message would be made current). If the "current" folder was the user's system folder, any new mail received since the iconification would be automatically included by the re-access. If some other folder were current (or no folder, due to initial conditions of no mail for the user), de-iconification would not cause the reading of any new mail. Under those circumstances the user must press the Newmail command button to read the new mail (and change to the system mail folder). Iconification is typically promoted by user definable button events which are particular to the window manager in use at the time. The National Semiconductor Corporation logo displayed at the left of the title bar will also make a window manager request to iconify, under X11 Release 4. (Under Release 3, it will simply ring the terminal bell, as R3 did not support client iconification requests.)

SENDING MESSAGES
All send and reply operations invoke the user's preferred editor (as defined by the user's VISUAL environment variable) to create or modify the message prior to delivery. An appropriate xterm window will be created to contain the edit session. The default editor will be vi, if no VISUAL (mailrc or process) environment variable definition exists.

Resources for this edit window must be specified in the user's "/.Xdefaults" file, as opposed to the xmail application default file, because the editor invocation is actually an xterm window, not a widget of xmail. User's may specify resources for this xterm message composition window using the xmail Class identifier followed by the xterm terminal resources identifier "vt100", as in "XMail*vt100.<resource: value>". For example, the author uses the following resource definitions in a ~/.Xdefaults file to control message composition windows.

    XMail*vt100.geometry:           80x27+30+100
    XMail*vt100.font:               fg-22
    XMail*vt100.foreground:         white
    XMail*vt100.background:         blue
    XMail*vt100.mouse:              white
Upon completion of the send/reply editing session, a smaller window will be displayed containing To:, Subject:, Cc:, and Bcc: fields for the current message composition. Help is available for each of these fields by pressing the middle mouse button while holding down either keyboard Shift key. A menu of user defined mail aliases is available for any of the To:, Cc:, or Bcc: windows. Pressing the right mouse button while the cursor is in any of these input fields causes the alias names menu to be displayed. If the user has not defined any mail aliases, the terminal bell will be rung instead, to indicate that no alias names menu is available. Like the File: window used to enter file and mail folder names, the content of the send window popup fields may be modified by the user as needed. Backspace and delete keys remove the previous character, control_W deletes the previous word, and control_U deletes the entire line of information. Pressing the Return key in any of these four fields causes the cursor to automatically warp to the next field. Users may append their Sign or sign autograph (see Mail(1)) once only to the end of the message text. Pressing the Deliver button causes the message to be delivered, while the right mouse button displays a menu for the Deliver, Cancel (and delete), and Cancel (and save in your dead.letter file) commands. Mail forwarded to another user will be bracketed by a "Begin Forwarded Message/End Forwarded Message" string pair when using the "forward message" Send command menu option. Also included will be a "Forwarded: Mail from ..." line in the mail header. Reply messages will include a "In-Reply-To: Mail from ..." string in the mail header. Like the "Forwarded:" header described above, it will include the name of the original sender, as well as the date the original message was received.

FOLDERS
If the right mouse button is pressed while the cursor is within the command panel folder button, xmail will display a menu of available mail folders. Dragging the cursor while still holding the right mouse button down will allow the user to highlight a particular folder name. Releasing the right button while a name is highlighted causes a copy of that name to be written in the command panel file window. The menu list is then unmapped. Releasing the right button while outside any folder selection causes the folder menu list to disappear. Folders which are actually directories (that might possibly contain additional folder files) are displayed with a trailing slash character. Clicking the left mouse button within a directory folder (while still holding down the right mouse button) causes xmail to search that directory and display (on a higher menu level) any files found there. Dragging the cursor over one of these selections and releasing the right mouse button copies the complete folder path name to the file window. This nesting of folder names may occur as often as there are legitimate folder directories. Clicking the left mouse button on an empty folder directory rings the terminal bell. Dragging the cursor beyond one of these nested menu levels causes that menu to disappear, without making a selection. Re-clicking the left mouse button on the directory folder redisplays the nested menu. The first request for the folder menu extracts (from Mail or the system) the necessary information to create the menu. Subsequent requests simply redisplay that menu. To force xmail to recalculate the folder menu content, press the Newmail button, which causes xmail to destroy the current folder menu and re-display your system mail folder. This provides access to folders created after the start of xmail.

FONTS
xmail now supports a wider variety of font styles, such as Courier and new century schoolbook. Previous restrictions to a small set of fixed width fonts have been eliminated. Certain font styles (such as Helvetica) still produce unusable results, as xmail attempts to use the font metrics to determine the initial window dimensions fail, producing a window with more width than needed or desired.

RESOURCES
xmail recognizes resource definitions for each of its component windows and command buttons. Wherever possible, button resources have been named for the label (or first word in the label) of the command button. (The exception is the preserve "set" menu, whose resources are identified by the second word in each label.) Thus :

    *read
        specifies resources for the read command button

    *save
        specifies resources for the save command button

    *autoprint
        specifies resources for the set autoprint command button, and

    *noautoprint
        specifies resources for the set noautoprint command button.

Color may be added (on a color display device) to enhance the appearance of xmail. Resources in the application defaults file may be overridden by designations in the user's ./Xdefaults file, or (in some cases) by command line options. Resources specified in the user's ./Xdefaults file should be preceded with either the xmail application or XMail Class resource identifier. In addition to those resources named for a particular xmail command button, the following additional resource names are recognized:

    .geometry: +XOff+YOff
        This resource defines the initial startup location for the xmail window. Note the dot (.) just in front of the geometry resource name. Users are cautioned to not specify this resource with the wildcard (*) designation, as this would force all popup windows (help, menus, and send/reply) to orient to that same starting location, rather than be anchored to the intended window.

    *iconic: <boolean>
        This boolean defines whether the xmail application should be started in iconic state or not. It is highly recommended that only the application resource identifier be used if specifying this resource. Use of the XMail Class identifier would also constrain any message entry windows to be started iconic, which could prove confusing to the unaware user.

    *iconGeometry: +XOff+YOff
        This resource defines an initial location for the icon, whenever the xmail application is iconified.

    *bellRing: <boolean>
        Normally true, this boolean enables ringing of the terminal bell during status and error message display.

    *helpFont: <fontname>
        denotes a preferred font to use when displaying help information.

    *mailopt_n: <boolean>
        Normally false, this resource duplicates the effect of the -n command line option.

    *mailopt_U: <boolean>
        Normally false, this resource duplicates the effect of the -U command line option.

    *MFileName: <foldername>
        Normally null, this resource duplicates the effect of the -f folder command line option.

    *Show_Last: <boolean>
        Normally true, this boolean enables display of the last message in a folder, providing no other is newer or unread. Setting this resource to false causes folder displays to start with the first (or new or unread) message.

    *icon
        controls resources for the icon window. In addition to specifications of foreground and background colors, it is possible to also specify mailWatch widget resources, such as the following:

        *icon*reverseVideo: <boolean>
            If set to true, reverses the foreground and background colors for the icon.

        *icon*update: <seconds>
            Specifies the update interval for checking new mail (default is 30 seconds).

        *icon*bell: <boolean>
            If set to False, prevents the mailWatch widget from ringing the bell when new mail arrives. See also the .mailrc variable setting for bell.

    *titleBar
        controls resources for the titleBar window

    *indexWindow
        controls resources for the index window

    *statusWindow
        controls resources for the status window

    *commandPanel
        controls resources for the command panel

    *fileWindow
        controls resources for the file window within the command panel

    *textWindow
        controls resources for the text window

    *list
        controls resources for the folder list popup window

    *menu
        controls resources for all of the command button popup menus

    *To controls resources for the To: entry window

    *Subject
        controls resources for the Subject: entry window

    *Cc controls resources for the Cc: entry window

    *Bcc
        controls resources for the Bcc: entry window

    "XMail*vt100.<resource: value>".
        definitions control resources for the send or reply message entry windows
A set of default resource definitions are provided in the file /usr/lib/X11/app-defaults/XMail. User's may wish to include appropriate alternate definitions in their ~/.Xdefaults file, to tailor preferences for colors and/or fonts.

ENVIRONMENT
Several process environment variables are of potential interest to xmail.

    DEAD
        Normally specified in the user's .mailrc file, this variable indicates the name of the file to use when storing dead letters. If unspecified, it defaults to "dead.letter" in the user's HOME directory.

    HOME
        Defines the path to the user's home directory, and is used in determining the complete path for mail folder and dead letter files.

    MAILRC
        If defined, denotes the full name of the user preferred Mail program startup file, used to define various mail state variables. By default, Mail (and xmail) will look for the file .mailrc, in your home directory.

    MBOX
        Normally specified in the user's .mailrc file, this variable denotes the preferred file to use when storing letters that are no longer to be preserved in the system mail folder, and letters copied or saved to no other specific file.

    USER
        Defines the login name of the current user, and is used in determining the name of the author of any message compositions.

    VISUAL
        Normally specified in the user's .mailrc file, this variable denotes the preferred editor to use when composing messages in xmail.

    XMAILER
        If defined, points to the particular executable to be used as the Mail program. Normally, xmail establishes connections with Mail in the default path of the process (assumed to be at least "/bin /usr/bin /usr/ucb"). If need be, the XMAILER environment variable can be used to provide a specific path to the Mail program. Note: xmail will not work correctly with any mail program other than the intended Berkeley Mail program.

MAIL VARIABLES
xmail also uses the existence and value of several Mail environment variables (defined in the user's .mailrc file) to aid in controlling it's operation.

    alwaysignore
        If set, causes xmail to ignore those header fields specified with the ignore .mailrc environment variable, when printing messages or when including message text in a send/reply composition. This variable can be altered during the execution of xmail. (See the section below on Changing Variables.)

    autoprint
        If enabled, causes the current message text to be displayed when deleting or undeleting messages. If not enabled, users must select or read the desired message. This variable can also be altered within the current xmail execution.

    bell=value
        If defined, determines the number of times the terminal bell would be rung to indicate the arrival of new mail. A minimum of once and a maximum of five times is the permissible range. Whether the terminal bell rings at all when new mail arrives is controlled by the "*icon*bell: <boolean>" resource (or -nb command line option) described above.

    hold
        Like mailtool, xmail sets "hold" on the user's system mail folder, unless "nohold" has been explicitly specified in the user's .mailrc file. This variable can also be altered during xmail execution.

    printmail=printer command
        This variable, originally created for the Sunview mailtool, allows the user to specify a preferred command to use when printing messages. The default command is "lpr -p".

    sendmail=shell-command
        If set, specifies an alternate procedure to use in lieu of the default /usr/lib/sendmail for delivering mail. User supplied procedures must be prepared to search the message file for recipients and ignore or process unexpected options (which ultimately must be passed on to the real sendmail program).

Some Mail variables have no effect on xmail operation, and are in fact ignored if found to be set.

    replyall
        has no effect on the meaning of commands within xmail. This prevents confusion due to a difference between how a command is labeled, and how it reacts in use.

    crt=<value>
        is ignored, and always defaults to nocrt. This prevents user specified paging mechanisms from interfering with full message delivery to xmail.

    screen=<value>
        For X11 Release 3, the screen limit is 100 headers. With X11 Release 4, a maximum of 500 mail message headers will be displayed, as required.

    unset <variable>
        should not be used to control variable settings, as xmail ignores any "unset" commands it may find. Use the set no<variable> construct to disable selected variables instead.

CHANGING VARIABLES
xmail provides a method of altering the values of three of the Mail environment variables used to control xmail (and Mail) operations. The states of alwaysignore, autoprint, and hold can now be "toggled" from a special menu attached to the preserve command button.

Pressing the right mouse button while the mouse pointer is within the preserve command button box presents a menu of "set" commands which indicate the state the environment variables would be changed to, if the mouse button were released while one of these commands was highlighted.

Changing the state of the variable alters the next presentation of the menu, such that the opposite state will always be presented as the command option.

SEE ALSO
Mail(1)

BUGS
Repeated pressings of a command button prior to its completion of an operation may cause xmail to crash. Users are cautioned against imposing too many requests too quickly when using xmail.

AUTHOR
Copyright 1989 - National Semiconductor Corporation ALL RIGHTS RESERVED Michael Wagnitz, National Semiconductor Corporation, Santa Clara, CA

Much of the design and insight for xmail was provided by contributions from the following authors: The xdbx contribution by Po Cheung (po@volta.ece.utexas.edu)
    Copyright 1989 The University of Texas at Austin
The mailWatch widget by Dan Heller (argv@sun.com)
    used as the xmail icon window.