Z-Mail 2.1 Release Notes
========================

Z-Mail 2.1 provides a number of extensions above and beyond Z-Mail 2.0
that facilitate folder management, improve multimedia mail support, and
considerably improve the graphical user interface.

Highlights include a spelling checker for editable text windows; iconic
representations for multimedia attachments; dynamic and interactive
modification for colors, text labels, and fonts; a new file-selection
capability added to the Folder Manager, Save, and Attachments dialogs; a
Task Meter for monitoring and interrupting time-consuming tasks; search
and replace dialogs for windows that contain read-only or editable text;
and access to more internal commands, configuration variables, and
parameters.

This document has the following sections:

-    GUI Additions and Changes
-    General Z-Mail Functionality Changes
-    New or Changed Variables
-    Z-Script Changes and Additions
-    Network License Server Support
-    Known Problems in Z-Mail 2.1
-    Using Z-Mail in an NFS Environment
-    Folder Indexing in Z-Mail 2.1


GUI Additions and Changes
-------------------------

*   Search and Replace dialog
    This new dialog is available from most text windows, and provides
    pattern-search capabilities.  For windows where the text is
    editable, "replace" capabilities permit replacing one string with
    another.

*   Opened Folders dialog
    This new dialog, accessible from the File menu, lets you perform
    Update, Activate, and Close actions and set indexing options for
    your opened folders.

*   Spelling Checker
    As part of the Message Composition window, the Search and Replace
    dialog now has a spelling checker built in.  Click on "Spell" and a
    scrolled list appears with all the misspelled words that are found.
    Select a word from the list to copy it to the "Search" field, and
    type the replacement word in the "Replace" field.

    The spelling checker uses the "spell" program. See the $speller
    variable below if you want to use a program other than
    "spell" as your spelling checker.

*   Expanded File menu
    The Main window's File menu has several new items:
    -   Folder Manager, which pops up the new Folder Manager dialog.
    -   Add Folder, which pops up a File Finder dialog so you can
        open a new folder and make it active.  Folders that were
        aleady open stay open.
    -   Close Folder, which closes the currently active folder.
    -   Opened Folders, which pops up the new Opened Folders dialog.
    -   Save Configuration, which writes out changes you've made to
        Z-Mail's configuration.  See the saveopts Z-Script
        function below and in the on-line help for more information.
    -   Iconify, which shrinks Z-Mail the Main window to an icon.

*   Search dialogs have moved
    The Pattern and Date Search dialog items have been moved from the
    Edit menu to the View menu in the Main window.

*   New initial input focus
    When the Main window first appears, input focus is on the message
    list instead of the Command area.

*   Fonts and Colors dialogs
    These dialogs allow interactive configuration of objects' colors, fonts
    and labels.  This eliminates the need to edit resource files.  (This
    feature does not require X11R5's "editres" capability.) Note that if you
    change the size of fonts in a particular object class, the objects
    themselves do not resize to accomodate the new font sie until you close
    and reopen the window.

*   New Aliases dialog
    The new Aliases dialog in the Compose window, accessible from the
    Headers menu, that lets you rapidly add alias addresses to your
    composition.

*   Expanded Message window menubar
    This window now contains a menubar where you can access a wider
    range of functions including:
    -   print message
    -   forward, with edits
    -   resend (unedited forwarding), with or without added comments
    -   four kinds of replies (as in the main window)
    -   access to pattern search and date search dialogs
    -   access to the Save Messages and Folder Manager dialogs
    -   delete/undelete, preseve, mark, and set/clear priorities
    -   read next related message by author, subject, or message-id
    -   iconic representations of attachments, if any
	(Click on the icon to automatically detach the attachment
        and start its associated viewing program.)

*   Message Window menu accelerator change
    The CTRL+D accelerator that was previously used to send mail has been
    changed to SHIFT+CTRL+D.  This was changed because of a large
    number of complaints that people's emacs bindings for the compose
    window were not working -- CTRL+D was sending mail rather than
    performing the emacs function (which is to delete the character
    to the right of the cursor).

*   Attachment bitmaps (icons)
    You can associate an icon with each attachment type by setting the
    new BITMAP directive in the attach.types file.  We have provided
    some default bitmaps for you in the "bitmaps" directory of the Z-Mail
    library.  Attachment icons pop up at the bottom of the
    message reading window when a message with attachments is read.

*   Folders and Save dialogs
    These two dialogs have been consolidated into the Folder Manager
    dialog that allows you to perform all saving and loading operations
    associated with folder management.  This includes removing,
    renaming, merging, and creating folders and directories (which
    are called "subfolders" by the Folder Manager).

    New, simplified Save Messages and Add Folder dialogs, based on the
    File Finder, have been added.

*   File Finder functionality in dialogs
    All dialogs that have file-search capabilities now have the new File
    Finder that is used consistently throughout Z-Mail.  The File
    Finder presents a list of files and directories and provides a
    summary of the files being viewed including file types (directory,
    file or unknown), modification times, and sizes.

*   Task Meter
    This window pops up during lengthy tasks such as loading large
    folders, searching for user names or other strings in messages,
    sorting, updating, and so on.  The threshold for how time-consuming
    a task will be before popping up the Task Meter is configurable, since
    performance varies greatly from one machine to the next.  Each task
    affects a certain number of messages (or number of bytes if the
    number of messages isn't known).  You can set the threshold level by
    10's of messages.  That is, setting the level to 50 means that a
    task meter window will only pop up if the action involves more than
    500 messages.

    The Task Meter also allows you to stop some actions.  For
    example, if you accidentally opened a 3-megabyte folder and
    want to stop without waiting for the open to complete, 
    press "Stop" in the Task Meter and the action terminates.  If
    an action cannot be stopped, the Stop button is disabled.  Note that
    stopping some actions may cause a warning dialog to appear that
    tells you the consequences of having stopped the action.

*   New Options dialog available in Compose window
    There are many options available that affect message composition;
    so many, in fact, that we've created a dialog that allows these 
    options to be set interactively.  These options are:
    -  return-receipt (also available in the compose window)
	When set, causes a return-receipt request to be sent along with the
	message.
    -  autoformat (also available in the compose window)
	When set, makes lines in the message automatically wrap to the width
	of the text area.
    -  edit-hdrs (also available in the compose window and variables dialog)
	When set, moves the To, Cc, and Subject fields into the body
	text area for editing.  Can be toggled off and on dynamically.
    -  autoclear
	When set, automatically clears the text window after a "send"
	or "cancel".
    -  verbose (also available through the variables dialog)
	When set, tells the MTA to be verbose about its
	output.  This is useful for tracking what actually happens
	to your message when you send it.  Possibly useful for
	debugging the sendmail configuration files, for example.
    -  record-user (also available through the variables dialog)
	When set, if the any of the recipients of the message
	has a corresponding folder name in your $folder
	directory (usually ~/Mail), then the message is automatically filed
	there.  This is convenient for automatically logging mail
	to frequently-mailed people when the correspondence must be
	documented.
    -  logfile (also available in the variables dialog)
	Set logfile to the folder where message "logs" are kept.  Any time
	mail is sent, the "log" stores only the header info about the
	message (To, Subject, Cc, etc), but not the body of the message.
    -  record (also available in the compose window and variables dialog)
	Set record to the folder where a copy of all outgoing mail is recorded.
	Messages are recorded in their entirety.
    -  autosign  (also available in the compose and variables dialogs)

*   New toggle in Variables dialog
    The Variables dialog has a new "Expand variable/file references"
    toggle that causes variables and file metacharacters embedded in
    variable definitions to be expanded to their actual values.

*   Popup menu for Main window message summaries
    Access to commonly used functions is now available in a popup menu
    in the message summaries list.  Press the right mouse button in the
    message summary list to pop up the menu.  (This doesn't add any new
    functionality, just convenience.)

*   Main window's Alias dialog
    You may now select more than one alias from the list. A
    new "Mail" button initiates a composition to the aliases
    specified.  A new "Clear" button lets you easily erase the
    text-entry areas of the dialog.

*   Date Search Dialog
    Searching for messages sent or received between two dates has been added.

*   Ability to add or remove panes in the Main window
    Any or all of the following panes may be removed from (or added to)
    the Main window: the command area, the text output window, the
    button panel, the message summary list, the folder/messages pane, or
    the folder status line (just below the menubar).

*   New Reuse button in Compose window
    After sending a message (and the window hasn't been cleared by
    autoclear), the Reuse button starts a new composition using the same
    message used by the previous composition.

*   Separate address type-ins in the Compose window
    A set of new text fields for message addressing is now available in
    the Compose window.  A scrolled list next to the addressing fields
    holds the list of addresses from the selected address field so that you
    can easily select one or more of the addresses for modification.

    Edit-hdrs mode pulls these addressing fields into the message body
    where they can be edited further. See edit-hdrs in the "New Options
    dialog" section, above.

*   List of printers to select from in Print dialog
    In the Print dialog, you can interactively choose
    from the list of available printers.  (The printer list
    is initially set by the system administrator; see below.)

*   New features for the Attachments dialog
    -  The Attachments dialog has been reorganized, with a File Finder
       at the top and the list of attached files near the bottom.
    -  Three new buttons in the dialog let you create a new
       attachment, display an attachment, or edit an attachment.
    -  Error reporting for attachment displaying and decoding programs
       has been improved.  Errors (or other non-zero status) from attachment
       processing programs are now displayed in a "pager" window.
 
*   Pattern Search dialog can now search multiple headers
    The restriction that you must search for a pattern in a single
    "part" of the message has been lifted.  You may now search for
    a pattern from any combination of one or more of To:, Cc:, Subject:,
    any arbitrary header, and/or the entire message.

*   More flexible "perform operation on all found" in Search dialogs
    Search dialogs that let you perform an operation on more than one
    folder now behave slightly differently when you request a "save" or
    "copy" operation.  You are now prompted for a destination folder or
    file for each folder in which messages are found.

*   Dialog-sizing safety constraints
    Some dialogs now have constraints upon how small they can be sized;
    others cannot be changed in size at all, to prevent them from
    becoming unusable.

*   Do Not Enter pointer
    Z-Mail now uses the standard Motif "Do Not Enter" pointer to indicate
    temporarily inaccessible windows.

*   Drag-and-drop
    Z-Mail now supports a number of drag-and-drop actions.  (To
    drag-and-drop, click the item you wish to drag with the middle mouse
    button, drag the pointer to the target, and release the mouse button.)
    Within Z-Mail's windows, you can perform the following actions:
    -  Drag one or more message summaries from the Main window to
       the text area of the Compose window, where they will be embedded
       in the composition starting at the end of the text.
    -  Drag one or more message summaries from the Main window to the
       Attachments drop target, which will automatically attach the
       messages to the composition and open the Attachments dialog.
       (The Attachments drop target is the small square to the left of
       the Attachments button.)
    -  Drag one or more message summaries from the Main window to the
       Attachments dialog, where they will be attached to the
       composition.

    If you use IXI Limited's X.desktop product, you can perform
    the following actions in addition:
    -  All the actions listed above, plus they can be performed with
       files (from other applications) as well as message summaries.
    -  Drop folders onto the Main window to open them. If the Main
       window is iconified, then it will be uniconified for you.
    -  Drag message summaries from the Main window to another
       application to save them.
    -  Drag Attachment icons to other applications to detach their
       associated files.

*   Expanded Help menu
    Expanded Main window Help menu lets you go directly to on-line
    help that refers to parts of the Main window.

*   On-line Help for Z-Script
    Help for Z-Script commands is now available in the Help Index.

*   Improved Headers dialog
    Multiple-line selections are now permitted in the Headers
    dialog.

*   The X-Face header is fully supported.  When you read a message that
    contains an X-Face header, the face of the sender (or any other 48x48
    bitmap the sender chose) appears in the upper-right of the message
    reading window.  If you create your own X-Face, you can include it in your
    outgoing compositions via the Envelope item of the Options menu.
    The supplied 'compface' program creates X-Face files from Sun icons,
    and the supplied 'facetohdr' sed script creates
    properly-formatted X-Face headers from an X-Face files.

*   Improved child-process error reporting
    The capture of output from child processes has been made more
    reliable in general.


General Z-Mail Functionality Changes
------------------------------------

*   Folder indexing
    
    Folder indices vastly improve Z-Mail's folder-loading speed.
    Whenever a folder is opened and updated, an index can be written
    into the folder so that the next time it is opened, all the
    information from the last time it was open will be available without
    requiring Z-Mail to scan the messages in the folder.  Folder
    indexing can be turned on or off as desired on a per-folder basis in
    the Folder Manager and Opened Folders dialogs.

    Folder indexing is described in more detail in the section "Folder
    Indexing in Z-Mail 2.1", below.

*   No folder message limit
    The limit on the number of messages that can be in a single folder
    has been lifted. The number of messages that may exist in a folder is
    now limited only by disk space.

*   Support for MMDF and V7 
    Z-Mail now reads and writes both MMDF and V7 format folders
    automatically.  The format of folders is retained; that is, an
    MMDF folder will remain an MMDF folder when it is updated or closed.

*   Support for MH-format folders
    Z-Mail can now read MH-format folders, and includes a utility
    shell script mh2zm (in /usr/lib/Zmail/bin) that converts MH folders to 
    Z-Mail format.  Also, the convert.mh file in /usr/lib/Zmail is a
    Z-Script function that you can use from within Z-Mail to convert MH
    folders to Z-Mail format.

    When you open an MH-format folder, then close it, Z-Mail will ask
    you if you want to convert the folder to Z-Mail's format.

*   Support for new attachment formats
    The RFC1154 (e.g., Poste) and Sun "mailtool" message formats are now
    fully supported, both for sending and receiving.  The MIME message
    format is supported for received mail; to send MIME format mail, use
    the program "mailto" in the directory /usr/lib/Zmail/bin.  A man
    page for mailto is provided in /usr/lib/Zmail/man.  Note that mailto
    is NOT a Z-Code product, and is provided solely as a convenience.

*   Saving dynamic attachment types
    Saving of attachment types (in attach.types format) that are added
    at runtime is now supported.  See the "attach" Z-Script command for
    more information.

*   Attaching from the command line improved
    Attaching files to a message from the Z-Mail command line has been
    improved.  Previously, attempting to override the "attachment
    description" prompt by redirecting input from /dev/null caused
    problems; this has been fixed.

*   Aliases can contain themselves
    Mail aliases may be "self-referential;" for example:
	alias bart	bart@zigzag, bart, well!barts
    In such cases, references to the alias name within the alias are not
    recursively expanded, but are instead used as destination addresses.

    Note that this is not transitive; for example, in:
	alias bart	bart@zigzag, schaefer
	alias schaefer	bart, well!barts
    The aliases "bart" and "schaefer" will recursively expand within one
    another until Z-Mail complains about "too many addresses".

*   Backup folders
    Better handling of backup folders (normally only one backup at a time)
    This should eliminate many confusing messages about "backup folders".
    Z-Mail 2.1 is more intelligent about when backup folders really need to be
    made.

*   ZMLIB 
    The ZMLIB environment variable is now set to /usr/lib/Zmail upon
    startup of Z-Mail if it was unset and no -lib parameter was
    specified. Note that if ZMLIB was unset upon startup and the Z-Mail
    library is not in /usr/lib/Zmail, Z-Mail cannot run.

*   Use ~s, ~t, etc. in line-mode compose even if $edit_hdrs is set
    The restriction that ~ commands can't be used when $edit_hdrs
    is set has been lifted.

*   New Printing Behavior
    If the $printer or $printer_opt variable is set and empty, then
    Z-Mail will ignore the values of both of these variables.  The
    default printer options as determined by Z-Mail will be used instead,
    even if you attempt to supply your own printer options in the
    print command line.  In addition, the %P and %O metacharacters
    will insert nothing where they occur in $print_cmd and $printer_opt.

*   Metamail
    The metamail program is supplied in the Z-Mail distribution.
    Metamail is used by Z-Mail to display MIME-compliant messages.
    Other uses of metamail are NOT supported by Z-Code, nor is
    metamail a Z-Code product.

*   Be Aware of the NLS in Your Environment
    If your site takes advantage of the new Network License Server
    capabiliity of Z-Mail, you should be aware that Z-Mail must be able
    to find your license server, even if Z-Mail is run in shell scripts and
    .forward files.  Typically, Z-Mail consults the ZNCLSERV environment
    variable for the name and socket number of a license server, such as:

      setenv ZCNLSERV "my-nls-host-here:2722"

    or you can usr the command-line option zcnlserv.  For example, in a
    .forward file, you might use:

      "| zmail -receive -zcnlserv my-nls-host-here:2722"

    Check with your site adminstrator or license host's /etc/services
    file for the NLS socket number to use; 2722 is the default.

New or Changed Variables
------------------------

(See the Variables dialog for more details about the following new or
changed variables.)

*   $autodisplay (string)
    Lists the attachment types that should be automatically
    displayed when a message containing one of those attachments is
    read.  Autodisplay is performed only in GUI mode.

*   $autoformat (boolean)
    When set, automatically formats messages in the composition window
    according to the width of the window.

*   $detach_dir (string)
    Set to the path of the directory where attachment display processing
    files should be kept.

*   $dot_lock (boolean)
    Specifies whether Z-Mail should use file-based locking (".lock" files)
    to synchronize with the MTA.  Essential for NFS-mounted mail spools.

*   $hangup (boolean)
    When you are logged in via a modem and the line drops unintentionally, or
    when you are using an X display and the communication between Z-Mail and
    the X server is interrupted, a "HUP" (hangup) signal is generated and
    sent to Z-Mail.  The setting of the $hangup variable affects how
    Z-Mail reacts to the HUP signal.
    
    If $hangup is false, then Z-Mail exits immediately without updating
    any indexes, modifying any folders, or deleting any temporary files.
    
    If $hangup is true, then Z-Mail quits normally, and performs any
    updates that were outstanding at the time the HUP was received.  This
    is equivalent to you quitting Z-Mail normally, and answering "Yes" to
    any dialogs that ask whether you want to update.

*   $index_dir (string)
    Gives the path name (relative to $folder) of the directory where Z-Mail
    should create external folder index files.

*   $index_size (numeric)
    Gives the size in tens of messages that a folder must reach before an
    index is automatically created for it.

*   $intr_level (numeric)
    Gives a threshhold for how time-consuming a task must be before the
    task meter will be popped up to show progress and, in some cases,
    allow you to interactively stop the task in progress.

*   $main_panes (multivalued)
    Specifies which panes of the Z-Mail main window should be visible at
    program startup.

*   $picky_mta (multivalued)
    Imposes restrictions on the way Z-Mail communicates with the Mail
    Transport Agent.  Use $picky_mta to tune Z-Mail to the quirks of
    your MTA.

*   $printer (string) The $printer variable now allows multiple printer
    names to be specified.  $printer can also have a leading "-" to
    specify additional parameters to print-command.  See "New Printing
    Behavior," above, for other details about the operation of this variable.

*   $printer_opt (string)
    Describes the command-line options used to tell your printing
    program which printer to use. See "New Printing Behavior," above, for
    other details about the operation of this variable.
    You can now embed the %P metacharacter in $printer_opt variable to
    insert the setting of the $printer variable.
    
*   $print_cmd (string)
    You can now embed two metacharacters into the print_cmd:
       %P  --  the printer name
       %O  --  the print options from $printer_opt

    See "New Printing Behavior," above, for details about the operation
    of these metacharacters.

*   $speller (string)
    Set this variable to the full pathname of the spell-checking
    program of your choice ("spell" by default).  In order to
    work properly, your chosen speller must output misspelled words on
    stdout, one word per line.

*   $unix (boolean)
    When $unix is set to true, Z-Mail will attempt to execute any
    command that isn't Z-Script as a UNIX command.  This is now
    supported in the GUI.

    If a UNIX command is executed in this way from GUI mode, Z-Mail will
    wait a few seconds for it to complete.  If the command does not
    finish within this time, Z-Mail will display the Task Meter to let
    you know that an external command is running.  Press the Stop button
    to "background" the running command and continue your Z-Mail session.

*   $verify (multivalued)
    You can now set $verify to "dead" (GUI mode only) to ask for
    confirmation of saving a dead letter file when a Compose window is
    cancelled.


Z-Script Changes and Additions
------------------------------

See the on-line Help for more details about these Z-Script modifications.

*   "saveopts" behavior
    The saveopts command writes out the current Z-Mail configuration,
    including variable settings, to a specified file, or else the file
    named in the ZMAILRC environment variable, or else ~/.zmailrc.  The
    file is overwritten if it exists.  Note that only those settings
    that differ from the defaults are written to the file.

    Since "the defaults" are different for different Z-Mail UIs (e.g.,
    line-mode has slightly different defaults than GUI-mode), some
    settings you've made that ARE written out in GUI-mode may NOT be
    written out in line-mode or vice-versa.  This can cause your
    settings of some variables, notably

        askcc
        autoprint
        verify
        window_shell

    to be saved (or not) depending upon which mode of Z-Mail you are
    using.

*   New "-file" option to "ask"
    The new -file option is an extension of the -input option that prompts
    for a string.  When -file is used, a File Finder is used rather than
    a simple textfield.

*   New "-list" option to "ask"
    The new -list option is another extension of the -input option that
    displays a list of message summaries.

*   "ask" command in Z-Mail "line mode"
    Numbers the list of choices and accepts a number for the user's selection.

*   "redraw", "popup", and "uniconify" commands in GUI
    New commands to let scripts control more aspects of the GUI display.

*   New option to "dialog"
    The "dialog" command now supports "-iconic" to allow dialogs to be
    initially displayed in iconic form rather than as an open window.
    The -Icon option allows the user to specify a file to use as the
    dialog's icon (both in iconic state and in normal state).

*   New "pinup" command to pin messages
    "Pinup" allows a message (or group) to be pinned up in its own window.

*   New "attach" command
    Dynamic addition of attachent types via the new "attach" command.

*   New option to "pick"
    "Pick" now allows you to search between two dates.
    pick -d date1 -d date2
	or
    pick -b date1 date2

    Previously, this was handled by:
	pick -d +date1 | pick -d -date2
    Use the new pick syntax to improve performance for this kind of search.

*   New "set multival += field", "set multival -= field", and
    "set string += stuff" to modify multivalues and append to strings.

*   New "trap" command traps signals
    Use trap in scripts that need to perform actions when signals are
    received.

*   New "page" command displays files, even in GUI
    This is a general convenience tool to allow file browsing. Especially
    useful for Z-Script writers.

*   New remove and rmfolder commands
    These commands allow the user to remove [optionally interactively]
    files and folders.

*   sh argument handling improved
    The "sh" command now processes multi-argument shell commands slightly
    differently to improve argument integrity. However, this may cause
    some of your existing Z-Script functions that use sh to break.  See the
    online help for sh for details.  Also, there are new options to sh
    that display the Task Meter during lengthy operations.

    If you use the new options to display the Task Meter, note that sh
    commands of the form:

       sh -m "Message" command1 ; command2

    cause the following behavior:  when command1 finishes, Z-Mail
    disables the "Stop" button in the Task Meter, but the Task Meter
    doesn't go away.  Instead, command2 is interpreted as a second Z-Script
    command, and, provided $unix is set to true and command2 is not
    a valid Z-Script command, it is run as a UNIX command.  After a few
    seconds, the Stop button will become enabled again so that you can
    return to Z-Mail if command2 takes too long, or doesn't terminate.

*   filters can now use "display"
    The "filter" command now permits the "display" command (or its
    synonyms) to be used within a filtering script.
---------------------------------------------------------------------------


Network License Server Support
==============================

Z-Mail now supports the new Z-Code Network License Server (NLS) for Z-Mail
licensing via your network.  The NLS lets you make more efficient use of
your Z-Mail licenses by allowing users to exercise their license at any
machine on your network.

The NLS software is shipped with every copy of Z-Mail 2.1, but requires
an activation key to work.  If you ordered the NLS as part of your
Z-Mail package, you should contact Z-Code Customer Support at
(415)499-8649 to receive your activation key(s).

At sites that use the NLS, Z-Mail may display various license-related
error messages in the event of an NLS problem or outage.  These errors
are self-explanitory.  For more information about the NLS, see the
file README.NLS in the zcnls directory of the Z-Mail distribution.
---------------------------------------------------------------------------


Known Problems in Z-Mail 2.1
============================


Motif-induced problems
----------------------

The 1.1.4 version of the Motif libraries, used to build Z-Mail, is very
stable under normal use and causes far fewer appearance and performance
problems than in libraries used in earlier versions of Z-Mail.  However,
some problems remain.

Certain combinations of geometry settings don't make much sense, and can
actually cause the Motif library to become so confused that it crashes
Z-Mail.  This is extremely rare, but occurs more often on some X servers
than on others.  Setting the borderWidth resource or using very large
(18-point or bigger) fonts can also cause problems for Motif with some
X servers, notably HP-UX.

Attempting to drag the sashes (small square buttons on the separator
lines) in the Main window while the Task Meter is visible can cause the
Motif library to crash Z-Mail.

X resources beginning with the class name "Zmail" may not work for all
Z-Mail windows.  This is due to an X toolkit bug that prevents certain
window types from being assigned a class name upon creation.  The workaround
is to omit the class name "Zmail" and instead begin the resource with a "*"
and the name of the window, e.g. "*compose_window".  If you find that the
names of the Z-Mail windows are clashing with other applications (a common
problem seems to be other applications with a *message_window), try putting
your resource specifications in the ~/.zmcolors or ~/.zmfonts files, which
are read only by Z-Mail.

Using an accelerator key sequence can occasionally cause the keyboard to
stop responding until you type the key corresponding to the accelerator.
For example, if you use the CTRL+F accelerator to open the Folder
Manager dialog, the keyboard may appear to stop working until you type
an F.  This problem is caused by a bug in Motif where key-release events
are sometimes lost.

Other Problems
--------------

In some heterogeneous networks, Z-Mail file locking when accessing files
that reside on a Sun4 NFS server will result in a deadlock of the network
lock daemons.  This is a problem with the Sun lock daemon, which can
affect other programs in the same way that it does Z-Mail.  Sun has a
patch for the rpc.lockd program to take care of this.  The patch is called the
"rpc.lockd jumbo patch for hanging/crashing lockd, #100075, 8th revision".
Ask your Sun technical support representative for it by name.

On DEC workstations, setting the NAME environment variable may cause the
Mail Transport Agent to crash.  Z-Mail attempts to prevent this, but
it may mean that your "real name" setting does not appear in the headers of
your outgoing mail.  Note that this problem affects other MUAs as well.

If you are using a "virtual window manager," some Z-Mail windows may be
placed outside the boundary of the current visible screen area.  If you
don't know what this means, you won't have this problem.

Shared folders (described in detail below) have the following problem.
If the size of a shared folder changes (due to modifications made to it
by the owner) while users are reading it, then users' external indices
to the folder will become invalid.  Any changes made by users to the
(read-only) folder during that session will not be written to their
external indices, and therefore will be lost. To avoid triggering this
problem, any reordering or removal of messages from shared folders
should happen when no one is reading them (such as in the early morning
hours).  See the "cron" example at the end of this document for hints.

Clicking the mouse buttons rapidly during or immediately after a
drag-and-drop operation can occasionally cause Z-Mail to refuse to let
go of the mouse pointer.  This effectively hangs the X server until the
Z-Mail process is killed.
---------------------------------------------------------------------------


Using Z-Mail in an NFS Environment
==================================

In general, NFS-mounted filesystems that are acting as mail delivery areas
do not support file locking.  If you use NFS-mounted filesystems for mail
delivery, and your MTA supports dot-locking, you should put the line

    set dot_lock

into your site's system.zmailrc file to tell Z-Mail to use ".lock" lock
files for synchronization with the MTA, as well as file locking.  Note
that this will require you to ensure that the Z-Mail program has the
ability to create and remove lock files in the mail delivery area.  If
your mail delivery area is already "world-write and owner-delete"
(world permission "t") then you're set.  Otherwise, you'll have to give
the Z-Mail executable the "set-group-id" permission and place it into
the group that owns the mail delivery area.

If your MTA does NOT support dot-locking and you are using NFS-mounted
filesystems for mail delivery, you may be in for trouble.  We don't
recommend that you set your mail delivery system up this way, since
file locking on NFS servers is non-robust.
---------------------------------------------------------------------------


Folder Indexing in Z-Mail 2.1
=============================

A significant new feature of Z-Mail 2.1 is the indexing facility for mail
folders.  Each folder may have an index of the messages contained in that
folder.  An index is a summary of the information Z-Mail collects from
the messages as it loads the folder, plus the state information that
accumulates as you read and manipulate the messages with Z-Mail.

Indices speed up opening large folders by saving, in one place, the
information that would otherwise have to be read separately from each
message.  Indices can also be used to record information about the state
of a folder without modifying the folder itself.  This permits shared
(group-accessed) folders to be maintained.  Each user sees an image of
the shared folder as recorded in their personal index.

A folder index may be either internal (stored in the folder along with the
messages) or external (stored in a separate file).  An internal index is
automatically used for writable folders, and an external index is
automatically used for read-only folders.  It is possible for a folder to
have both an internal and an external index, in which case the internal
index is given precedence.  The external index is referenced only if the
internal index is incomplete or if the sorting order of the external index
is different.


Index Management with Z-Script
------------------------------

Folder indices may be manipulated via the "folder" family of commands
(close, open, update, etc.) with the "-index" (-x) and "-noindex" (-X)
options.  To create an index, use "update -index" or "close -index".
Once the index has been created, Z-Mail will keep it up-to-date at each
folder update.  To turn off indexing of a folder, "update -noindex" or
"close -noindex" causes all indexes that Z-Mail knows about to be
removed.  To load a folder without reference to the existing index, use
"open -noindex".

The variable "index_size" also controls index creation.  It is set to
the size (in tens of messages) that a folder must reach before an index
of the folder is automatically created.  For example, a value of 5 (the
default) would cause an index to automatically be created for any folder
of 50 or more messages.  Note that an index is created only when a
folder is updated.  If a folder is opened and closed without update, no
index will be created regardless of the folder's size.  If a folder is
opened with "open -noindex" and the folder size exceeds the setting of
index_size, then an index will be created (or updated) when the folder
is updated.

For smaller folders, an index may not be desired.  Set index_size
according to your preference for automatic index creation.  A value of 0
(zero) or boolean true (set, but no numeric value) means that all
folders should be indexed, regardless of size.  If index_size is not
set, folders are not automatically indexed.  The default for index_size
is 5.

Updating a read-only folder will write an external index for that
folder rather than rewriting the internal index.  To force this behavior
on a folder that is not read-only, use "update -external".  External
index files can thus "checkpoint" a writable folder as well as save the
state of a read-only folder.  Whenever the folder is loaded (except with
"open -noindex"), the external index file created in this way is used to
restore the sorting order, saved/deleted/replied status, etc. of the
messages.

Note that the index of a folder opened in read-only mode (by the
"-readonly" option when starting Z-Mail or when using the "folder"
command) is not normally updated.  However, if index_size is set and the
folder is large enough, an external index file is created when the
read-only folder is updated or closed, even if the file already has an
index.  An index is created automatically if you update a folder when
you do not have permission to write to the folder itself.

The pathname of the directory where external folder index files are to
be kept is specified in the variable "index_dir".  This path is used by
"update -external" (and other commands) to create the external index
file for a folder.  If a complete pathname is not given, the name of the
folder directory (abbreviated as "+"; see the "folder" variable) is
prepended.

If index_dir is not set or is an empty string, then the directory
"+index.dir" is used for external index files.  The name of the index
file within the index directory is the same as the name of the folder.
If the index directory and the directory containing the folder are the
same (e.g. index_dir is set to "+") then the index file name is the
folder name with ".ix" appended.  On systems with file name length
limits, the folder name is truncated before appending ".ix".

External index files are removed by "rmfolder -x foldername", or when
the folder itself is removed by "rmfolder foldername".  When a writable
folder is updated, the external index is removed when an internal index
is written or when all messages have been deleted.


Index Management from the Graphical User Interface
--------------------------------------------------

If a folder has an index, you may use it when loading the folder by
selecting the "Use Index" toggle in the Folders dialog.  If "Use Index"
is not selected when you open your folder, Z-Mail ignores the index and
loads the folder normally.  Note that ignoring the index on load also
causes it to be omitted when the folder is updated, unless the folder
exceeds the index_size.  The index may of course be explicitly created
at update (via "update -index"), even if it was ignored when loading.

You may use the Opened Folders dialog to add an index to a folder when you
update it; just select the "Create if Needed" toggle from the Indexing
Options in that dialog.  Toggles in the Opened Folders dialog also permit
you to suppress the index on update.  When updating or closing from the main
window menu, indexing cannot be specified.  In this case, Z-Mail will update
the index if one was used to load the folder.  Otherwise, Z-Mail omits the
index.  This is equivalent to the "Update if Present" option when updating
from the Opened Folders dialog.

The Variables dialog may be used to set the values of index_size and
index_dir.


Indexing and Shared (Group) Folders
-----------------------------------

A shared, or group, folder is simply a folder file to which many users have
read access, but to which only one (or a few) have write access.  The shared
folder acts as a "bulletin board" where users can read messages of common
interest.  This has some advantages over sending a copy of each message to
all the interested users.  For example, when an outdated message is deleted
by the maintainer of the folder, it disappears from every user's image of
the folder as well.  Further, each new message is delivered only to the
shared folder, rather than one copy to each user; this saves disk space.

Z-Mail's external folder indices permit each user of a shared folder to
maintain their own image of the state of that folder.  The shared folder
should be writable only by a designated maintainer, so when other users open
it, Z-Mail automatically uses read-only mode.  If a user replies to,
deletes, or otherwise modifies messages, Z-Mail tracks his changes.  Then,
when the user updates or closes the folder, Z-Mail updates that user's
external index file.

The next time the same user opens the shared folder, Z-Mail uses the
index file to restore the folder state as nearly as possible.  Messages
that have been deleted by the folder maintainer are lost.  However,
almost all other state is restored, including sorting order if the user
changed it.  New messages that have been placed in the folder since the
user last accessed the folder are appended after those that are
referenced in the user's index.


Creating a Shared Folder
------------------------

To set up a shared folder, determine first how new messages should be
added to that folder.  If messages are to be sent automatically to the
group, you may wish to create a "pseudo-user".  A pseudo-user is a user
name that exists on the system but does not correspond to any real
person.  Pseudo-users often have logins disabled, so that only the
super-user or another specially designated user can act in the name of
the pseudo-user.  In this case, the folder maintainer, if there is one,
is that designated user.

The system mailbox of the pseudo-user becomes the shared folder.  A
pseudo-user can receive electronic mail even if "he" can never log in to
read it.  The mailbox should be created and made readable by the group that
is to share the messages (or by all if everyone is to have access).  It
should be both readable and writable by the pseudo-user account only.
Messages to the group are sent to the pseudo-user, so they show up in the
shared folder (the pseudo-user's mailbox).

For example, suppose that we wish to create a shared folder to be read by
Z-Mail users, for discussion of the Z-Mail program.  We first create a
pseudo-user named "mailGhost".  (The details of user creation vary among
different UNIX systems.)  Next, we create a mailbox named "mailGhost" in the
system mail area (/usr/mail or /usr/spool/mail, usually).  Any user should
be allowed to read this folder, so we set the permissions for "read" and
"write" by owner only and "read" by all.  Now, users can submit messages to
the shared folder by sending mail to "mailGhost".  Once messages have begun
to arrive, Z-Mail users can open the folder "%mailGhost" to read the
messages.  The abbreviation "%" in Z-Mail means the system mail area, so
"%mailGhost" refers to the system mailbox of user mailGhost.

Sometimes, it is desirable to have new messages screened before they are
made available for group access.  Z-Mail's filtering mechanism can be
used to automate this process on behalf of a pseudo-user.  However, there
may be cases where automated filtering is not sufficient.  In these
cases, it is necessary to appoint one user (or possibly a few) as
maintainer of the shared folder.  Messages to the group are sent to the
maintainer, who adds them to the folder as appropriate.  A folder maintainer
who has this responsibility is often called a "moderator" in e-mail lingo.

When a shared folder has a moderator, it is not necessary to establish a
pseudo-user and system mailbox.  Instead, any folder that is writable by the
maintainer only, and that is readable (but not writable) by the interested
group, can be used as a shared folder.


Maintaining a Shared Folder
---------------------------

In addition to screening the messages, a maintainer is responsible for
deleting outdated (or "expired") messages from the shared folder.  As with
delivery, it is possible to automate the expiration of messages from the
shared folder with Z-Script functions and/or filters.  In this case, a
system process such as "cron" periodically executes Z-Mail to run the
Z-Script commands that handle message expiration.

If the folder is a pseudo-user's system mailbox, cron can be told to
act as the pseudo-user when running the Z-mail script.  Otherwise, cron
should be told to run as the maintainer of the shared folder.

The following command deletes messages that are 31 days old or older from
the shared folder of the previous example:

    su mailGhost -c 'zmail -exec "search -ago -31days | delete; quit"'

Here, the owner of the shared folder is the pseudo-user "mailGhost," so we are
issuing an su command to cause the command following the "-c" to be run by
the user mailGhost.  The command which mailGhost will execute is

    zmail -exec "search -ago -31days | delete; quit"

Examining this command, we see that Z-Mail is started and passed, via the
-exec option, the Z-Script command

    search -ago -31days | delete; quit

which selects the messages in mailGhost's system folder (the shared folder)
that are 31 days old or more, pipes the selected message list to the delete
command which marks them as deleted, then quits Z-Mail.  The messages which
have been marked as deleted are purged automatically by the quit command.
If a cron entry is set up to run this command every day, the shared folder
will be automatically cleaned of outdated messages with no further
intervention.

Additional details of Z-Script and cron use are beyond the scope of this
document.  It is possible to create complex, powerful Z-Scripts for this
type of automated folder maintenance.  The techniques described here can
be applied to any folder, not just to maintenance of shared folders.
