
NOTE: This program is still in beta testing mode, so please read the
      file BETANOTES


   TkMail v2.0 -- A Tk/Tcl interface to Mail
	    		by Paul Raines (raines@slac.stanford.edu)

   TkMail is an X windows interface to mail built using Tk/Tcl and
   Perl.  Reading, sending, and managing mail messages can almost all
   be done using only the mouse (except for the body of the message,
   of course).  TkMail writes its folders in the format of the
   standard unix 'Mail' command.  It also uses 'sendmail' commands to
   do the mail delivery work.

   Major Features:
	- listbox interface to messages for easy click and read
	- multiple viewers can be opened on different or the same folder
	- dynamic (at startup) menus for quick access to mail folders
	  for reading, copying, and moving messages
	- button bar for quick composing, replying to, and forwarding of
	  mail messages
	- built in 'biff' icon for notification of new mail
	- easy inclusion of files into message compositions with
	  automatic uuencoding and compression, if desired
	- access alternate editor for compositions to send
	- spell check compositions using a X windows interface
	  (must have the ispell program version 3.0.09, not 4.0!)
	- reads aliases from either standard .mailrc or elm aliases.txt
	- easy piping of message text through unix filters
	- emacs-like key-bindings for text editing
	- emacs-like autosave
	- sorting of messages on any field and the ability to
	  write out the folder physically in that order
	- simple MIME reading and compostion tools
	- viewed messages are editable inside viewing widget so
	  one can add or delete text for printing or piping X selections

   TkMail is built using only scripts for maximum portability. Still,
   there may be aspects which are still not standard across all
   platforms or even versions of operatings systems. Also, there is no
   guarantee that it is bug free, so don't trust TkMail without at
   least running it through a few tests yourself!  Make a backup copy
   of your ~/mbox file and some of your folders and then test out
   TkMail's operations on those files.

   See the USER SETTINGS section below to get a real feel for
   what TkMail can do.

GENERAL USAGE:

     From your unix command line, type

     	tkmail [-i] [-l lib_dir] [-g set_file] [-p dot_file] [folder] &

	-i		Start TkMail in iconic mode
	-l lib_dir	Directory containing TkMail support files
	-s set_file	File to source for global settings
	-p dot_file	File to source for personal settings.
	folder		Initial mail folder to read

     If you do not specify a folder, your ~/mbox will be shown.

     Most things in the menu should be self evident (yeah...that is
     what they always say). A few menu items are also on the button
     bar. Many menu items can be accessed with accelerator characters
     using the Alt key or Alt-Shift keys.  Also F10 will let you do
     keyboard traversal of the menu.

     Because of the hassle of dealing with the system inbox, I have
     the app incorporate new mail into the ~/mbox instead of treating
     it as just another folder. This might change in a future release.

     When you get new mail, just click the 'Incorp' button and you
     will be taken to the ~/mbox folder at the first new message.  The
     ~/mbox serves as the central place to dish out messages to your
     folders using the copy and move menu items. If you set
     mf(mail-auto-incorp) to '1', TkMail will automatically
     incorporate new mail as long as you don't have a viewer for your
     mf(mail-mbox) folder currently mapped for viewing. Otherwise, you
     must explicity hit the Incorp button. This feature prevents it
     incorporation from interrupting your viewing of another message.

     If a ~/.tkmailrc or ~/tk/tkmailrc file exists, they are sourced so
     that the individual user can change the User Settings described
     below. This resource file name can be overridden with the -p
     option.  This file provides the ability to do powerful
     customization to TkMail for the knowledgable Tcl/Tk programmer.

     One can define a procedure called mfv:compose-hook in these files
     that will be evaluated each time a compose message window is
     created. Another procedure called mfv:viewer-hook can be defined
     which will be evaluated one the main viewer is built. See the
     included example.tkmailrc.

     The viewed message will always have the '>' character in front of
     it.  The Delete, Copy, Move, Save, and Print commands operate on
     all selected messages. The Reply and Forward operate on only the
     currently viewed one.

     For efficiency and undo ability, deletes are not done immediately.
     Deletes are processed when changing folders or quitting. This means
     that if the something kills TkMail, any impending deletes are not
     done. This most often happens when someone quits their window
     manager without first quiting TkMail.  TkMail doesn't always trap
     this situation correctly on some systems.

     An autosave file is periodically written out to a filename formed
     by enclosing the folder name in #'s. This can be used to recover
     lost deletes and such.

     For most mail operations, a check is made to make sure that the
     current folder has not been externally modified.  This often happens
     when someone runs two TkMail's or TkMail and a separate Mail session.
     TkMail does check for new mail being appended to an open folder and
     should handle it correctly. Still, that is risk business and I don't
     suggest that as a normal mode of operation.

ALIASES:

     TkMail can parse either BSD or elm aliases files at startup. Which
     one is used depends on the settings of the mf(mail-alias-file) and
     mf(mail-alias-type) variables.  To use aliases in your ~/.mailrc
     file, put the following in your ~/.tkmailrc file
         set mf(mail-alias-file) $env(HOME)/.mailrc
	 set mf(mail-alias-type) bsd

     To use aliases in the elm alias file ~/.elm/aliases.text, put
     the following in your ~/.tkmailrc file
         set mf(mail-alias-file) $env(HOME)/.elm/aliases.text
	 set mf(mail-alias-type) elm
     
     The mf(mail-alias-file) settings can be a list of files, so one
     can add the global elm alias file to it.

     Alias resolution is recursive, so aliases may contain other aliases.
     Whether aliases are treated case sensitively is controlled by the
     mf(mail-alias-case) settings.

     If you wish to have a default machine address appended to addresses
     that do not include one, use the mf(compose-addr-postfix) settings.
     For example, the following would append @slac.stanford.edu to addresses
     without a @machine part
         set mf(compose-addr-postfix) {@slac.stanford.edu}
     This is done after alias expansion so only true mail addresses will
     get appended.

     NOTE: sendmail will not send the mail to any of the users
     listed if any one of them is not valid.

MOUSE BINDINGS:

     Mouse bindings in the header list box are:
         B1 Click - view clicked message and make it the sole selection
         B1 Drag - select additional messages for later possible operations.
	 Shift B1 - extend selection
	 Control B1 - toggle selection
	 B2 Drag - do quick scan (scrolling) of list
         B3 Click - select message clicked with viewing.
         B3 Drag - select all messages dragged over.
         Shift B3 Click - unselect message clicked if not the viewed one.
         Shift B3 Drag - unselect messages dragged over

     Note that in a future release that will use Tk4.0, these bindings
     may change to be more in line with the new listbox abilities.

     Mouse bindings in the message and compose window are normal Text
     bindings.  B2 will insert the current selection and B3 will
     unselect it.  Alt-Shift-B2 will insert the current selection with
     the mail prefix. See the Tk 'text' man page for more info.

     Using B3 on the Reply button will cause the message to be
     automatically included in the compose text. Using B3 on the Compose
     button will do the same but leave the To: field blank (for
     Forwarding with editing). B2 on these buttons does the operation as
     B3 except that no prefixing of including text is done. This can be
     used to "bounce" mail.

     Using B1 on the Split button will split the message window into
     two panes, both with the current message.  When a different message
     is selected, only the top pane will change.  If the window is
     already split when the Split button is pressed, the current message
     will be copied to the lower pane.  Using B3 on the Split button will
     remove the lower pane (Unsplit).  Using B2 on the Split button will
     detach the current message into its own independent window.

     In the compose window, B2 on the 'Insert Message' button will insert
     the message without prefix. B3 on the 'Send' button will send the
     message without removing the compose window.

KEY BINDINGS:

     Most menu item can be accessed through keystrokes by using the
     Control key along with the letter in brackets next to the item. For
     emacs binding users (see below), a Control-c followed by the letter
     is needed. This prefix key can be changed using the mf(menu-key)
     setting.  Pressing F10 will let you traverse the complete menu with
     the arrow keys. See the example.tkmailrc file to on how to set your
     own key settings.

     Non-emacs users have the following key bindings:
     Text and Entry Widgets
	 Control-x		Cut
	 Control-c		Copy
	 Control-v		Paste
	 Control-<number>	Set repeat for next non-number key
     Text Only
	 Control-z		Undo
	 Control-a		Select All
	 Control-f		Search
	 Control-g		Search Again
	 Control-.		Set Fill Column
	 Control-j		Format Paragraph
	 Control-V	        Paste with Prefix
	 Shift-<movement key>	Selection

     Control-Home goes to top of text, Control-End to the
     end. Control-Left and Control-Right move by words. Home goes to the
     beginning of the line and End goes to the end.  PageUp, PageDown,
     and the arrow keys do their obvious operations.

     In dialog boxes, buttons can be invoked by pressing the Meta key
     along with the capital letter in the button. As special cases,
     the Accept/Ok button is usually invoked by the Return key and the
     Cancel/Dismiss button with Escape.  If mf(bind-use-meta) is set
     to zero or mf(bind-emacs) is 1, then the Meta key bindings will
     be replaced by ones using mf(menu-key) as a prefix.

     For an example of how to make you own bindings, see the example
     ~/.tkmailrc file.

EMACS KEY BINDINGS:

     Set the mf(bind-emacs) variable to '1' to get the typical emacs
     bindings for Control a,e,f,b,n,p,o,d,k,w,y and space. Also, the
     Escape key as a prefix or the Alt key as a modifier for f,b,d,w,q,
     y, [, ], and \. A limited undo is bound to Control
     underscore. Since undo is very memory intensive, the setting
     btp(undo-level) will control the number of steps saved.

     Since the Escape key is used as a prefix key, a Control-Escape must
     be used to cancel dialogs.

     Control-Shift-S will pop up a window to enter a string for searching
     in the current Text widget. Control-s will search again. Regular
     expression and backward search is supported.

     Arguments are supported along with Control u for univeral argument.
     The kill ring contains a maxium of 10 deletions.  If a region of
     the text is selected with the mouse, Control-w will cut it and
     Alt-w will copy it onto the kill-ring.  Control-y will paste it and
     Control-Y will paste prefixed by the value of the mf(insert-prefix)
     setting.

     Very primitive auto-wrapping is supported with the emacs bindings.
     Once you are at the column where you wish the text to wrap, type
     "Control-x f".  To return to no wrapping, do a "Control-x f" when
     the cursor is in column zero.  Setting for one text widget will set
     it for all text widgets. If you want wrapping always set to a
     certain column, put a line like the following in your ~/.tkmailrc
     file
	  set btp(fillcol) 65
     Doing an Escape-q will try to auto-format the current paragraph.
     All btp() settings are sourced only at startup. The Option Save
     command knows nothing about them.

     ATTENTION FOREIGN KEYBOARD USERS!  If wish to have only the Escape
     bindings, you can put the following line in your ~/.tkmailrc file
	set mf(bind-use-meta) 0
     to prevent bindings with the Alt key for emacs functions.  This
     might be necessary for non-English keyboards to access special
     characters.

VIEWER MENU:

     Folder:	Open...		Select new folder to view
		Close		Close folder view
		Quit		Quit TkMail (processes deletions)
		Main Box	View main mail box (usually ~/mbox)
		Incorporate	Incorporate new mail from system box
		Process Del	Process messages marked for deletion
		Save Sorted	Write folder to file in sorted order 
				(this will also processes deletes)
		Force Autosave  Forces an autosave to the #folder# file
		Rebuild Menu	Rebuilds dynamic folder menus
		Reread Alias	Reread your alias file
		Recent		A menu of recently accessed folders to view
		<Folders>	List of folders in folder directory to open
				  Directories will become pull right menus
		++chopped++	If presents, signals that there where more
				folders present that could not be put in menu

     Edit:	Cut		Cut selection into private buffer
		Copy		Copy selection into private buffer
		Paste		Paste private buffer at insert mark
		Select All	Select the whole text buffer
		Search...	Search the message for a string
		Search Again	Repeat last search command
		Save X Sel	Select file to current X selection to
		Print X Sel	Select printer command to print X selection to
		Eval TCL X Sel	Evaluate the current X selection as Tcl
		Pipe UNIX X Sel	Pipe the current X selection through a UNIX cmd
				  and choose what to do with results

     Mesg:	Next		View next message in list
		Prev		View previous message in list
		Reread		Reread the current message from file
		Show Full Head	Show all headers (ignoring strip options)
		Select All	Select all message in header list
		Copy =>		Show folders to copy selected messages to
		Move =>		Show folders to move selected messages to
		Save		Select file to save message to
		Print		Select printer command to print messages with
		Pipe		Select UNIX command to pipe messages through
		Delete		Mark selected messages for deletion
		Delete All	Mark all messages for deletion
		Undelete ...	Selectively unmark messages marked for deletion
		Undelete All	Unmark all messages marked for deletion
		Undelete Last	Unmark last message marked for deletion
		Detach		Copy current message to its own window
		Split		Split view and Copy current message to lower pane
		Unsplit		Remove lower pane of viewer
		Quick Decode    Search mesg for uuencode enclosures,
				 and decode them

     Mail:	Compose		Popup window to compose new message
		Reply		Popup window to reply to current message
		Reply All	Reply to sender and recipients of message
		Forward		Forward selected messages to a user
		Alias Current	Requests an alias for the current sender
		Restore Last	Restore last composition window 
		TkMail Support	Mail a comment/bug report to author
		<Names>		List of addresses in mf(menu-quick-send)

     Viewer:    New...		    Pop up a new folder viewer
		Sort Normal	    Sort messages in physical file order
		Sort From Addr	    Sort messages by address received from
		Sort Full Name	    Sort messages by real name of sender if available
		Sort Subject	    Sort messages by subjects
		Sort Time Receiv    Sort messages by the time they were received
		Fixed-space Font    Toggle use of fixed space font
		Reverse Order	    Toggles display of messages in reverse order
		Reverse Video	    Toggles display of messages in reverse video
		

     Options:   Edit Globa Set ...  Pops up the settings editor
		Edit Aliases ...    Pops up a window to edit your alias file
		Auto Incorp	    Toggle auto incorporation of mail
		Popup Notice	    Toggle popping up of new mail notifier
		New Viewer Select   Toggle creation of new viewer on folder menu selection
		Ask on Long Mesg    Toggle requesting to continue on long messages
		Strip Header	    Toggle stripping of headers on compose insert
	        Parse MIME:         Toggle parsing of MIME messages


     Help:	<Sections>	    popup window displaying section from help.txt
		Show Log	    popup window showing logging of actions

<Sender> MENU ITEM:

     The <Sender> menu item is the third item (just under the Other...
     item) int the Mesg:Copy and Mesg:Move menus. Selecting the item
     will copy or move the message into a folder determined by the
     mf(mail-archive-folder) setting. If it is set to a filename, then
     the operation will be to that file. If it is a value which starts
     with a '@' character, then the rest of the setting is interpreted
     as a Tcl procedure and evaluated with the pathname of the viewer
     passed as an argument. The value returned is the filename to use
     for <Sender> operations.

     The default value for the mf(mail-archive-folder) setting is
     {@mfv:sender-default-hook 1} which will return the sender's email
     address as the archive filename. By default, the it only uses the
     part of the address before the '@'. The whole address will be
     used if 1 is set to a 0 in after @mfv:sender-default-hook.  Also,
     all letters of the resulting string are convert to lowercase.

     See the example ~/.tkmailrc file in the TkMail distribution for an
     example of a personalized mf(mail-archive-folder) settings.

COMPOSE MENU:

     File:	Insert File...	Select a file to insert into composition
				   - can encode, compress, and prefix
		Insert Mesg...  Select messages to insert into composition
		MIME Attach...  Prompt of a MIME attachment to message
		Send		Mail the composition
		Cancel		Kill the window and don't send
		Alt Editor	Bring up alternate editor

     Edit:	Cut		Cut selection into private buffer
		Copy		Copy selection into private buffer
		Paste		Paste private buffer at insert mark
		Search...	Do a string search in text
		Search Again    Repeat last search
		Expand Aliases  Do alias expansion on contents of entry widgets
		Ispell		Run tkispell on composition
		Eval TCL Sel	Evaluate the current X selection as Tcl
		Pipe UNIX Sel	Pipe the current X selection through a UNIX cmd
				  and choose what to do with results
     Options:
		Show Cc/Bcc	Toggle on/off the Cc/Bcc entries
		Show Fcc	Toggle on/off the Fcc entry
		Fixed Space	Toggle showing text in fixed space font
		Reverse Video   Toggle showing text in reverse video

     When you run the alternate editor, the Alternate Editor button on the
     bottom of the screen will change to say Finished AltEdit. If the
     send command does not work because of xauth security, you must press
     this button to get the changes from the alternate editor.

PRINTING AND PIPING:

     Note that there are two Print menu items. One prints the current X
     selection and the other prints the currently selected mail
     messages. Both prompt the user for a unix print command (this can
     be turned off after the first prompting).  In this command line, the
     following printf style substitutions will be made (evaluated in
     this order):

	   %F	the name of the temporary file for printing. If
		it is ommitted, the name fo the temporary file
		will be appended to the end of the command line.
	   %D   The send date of the currently selected message.
	   %W   The sender (From) of the currently selected message.
	   %S   The subject of the currently selected message.

     In order to account for Tcl style parsing of whitespace, you
     must surround the complete token where %S, %W and %D are used
     with curly braces. For example:

           enscript {-b%S} -plw2 %F

     It is important to understand Tcl syntax rules if you plan to
     use the $,{},"", or \ characters in your command line. In general,
     where at the unix shell, you would normally do

	   -b"A quoted string"

     you should use

           {-bA quoted string}

     The printf-sytle placeholders will also work for the pipe commands.

HEADER FIELD STRIPPING:

     The mf(header-retain) settings can be set to a list of fields which
     will be the only ones shown in the viewer if available. The
     mf(header-strip) settings can be set to a list of fields which will
     be stripped from those available before showing. If mf(header-retain)
     is used, there is no reason to use mf(header-strip).

     Messages copied or moved between folders will not have their 
     headers stripped.  Messages saved using the 'Save' operation will
     have the headers stripped and is really the only difference between
     the 'Save' and 'Copy' operations.

SUMMARY LISTBOX FORMAT:

     Them mf(headlist-format) setting is a printf style string with
     the following placehoders (taken from VM for emacs).

        c - number of characters in message (ignoring headers)
        d - numeric day of month message received
        D - full date string
        f - author's address
        F - author's full name (same as f if full name not found)
        h - hour message received
        i - message ID
        l - number of lines in message (ignoring headers)
        m - month message received
        s - message subject
        w - day of the week message received
        y - year message received

     Use "%%" to get a single "%".


CC:, BCC: and FCC:

     The mf(compose-show-cc) variable controls whether two extra entry
     boxes appear in the compose window when the compose window is
     first mapped. If the entry boxes are shown in the compose window
     when the message is sent, then they will be used if non-blank.
     If they are not shown, what ever was put in them before will be
     ignored.

     When Reply All is choosen for a message and the To: field in a
     Reply message appears to have multiple addresses, all of the
     addresses (including yours) will be added to the Cc: list. Also,
     the original messages Cc: list if present will be copied to the
     Cc: entry.

     The button on the right side of the entry widgets can be used to
     popup a text window for easier editing of long address lists. Any
     newline characters inserted into the text widget will be replaced
     with spaces.  You must click the Accept button on the text window
     before sending for your changes to be used.

     The mf(compose-alternates) variable can be used to prevent mail
     from being sent to any address in the Cc: listing. It is a list in
     which the elements must be an exact match or regular expression
     (e.g. raines[a-zA-Z@\.]* ) of the address to ignore. Be careful
     that the regular expression excludes spaces and commas to prevent
     mangling of two or more addresses.

     The FCC: entry contains the name of the file to which a copy of the
     message will be recorded. This is always set to the value of
     mf(compose-fcc-folder) when first mapped, but can be changed.
     Whether this file is used or not depends on whether the Fcc: entry
     is shown or not at send time. Multiple files can be specified if
     separated by commas. The button at the side of the entry widget
     will popup a file selection box.

     If one sets mf(compose-fcc-folder) to a value that begins with a
     '@' character, then the rest of the setting is taken as a Tcl
     command which will be evaluted with the pathname of the compose
     window toplevel appended. The return value is then used as the Fcc:
     folder. See the example ~/.tkmailrc file.

     The Fcc: entry will be calculated when the compose window is first
     mapped and whenever the To: field is edited and then loses focus.
     It WILL NOT be calculated on send, so what you see at send time is
     what you get. Well, not exactly true since if the focus was in the
     To: entry at the time you selected Send, then that qualifies as a
     loss of focus and the Fcc is recalculated.

     The button on the side of the Subject entry widget has no command
     associated with it and is only there for symmetry. If anyone has a
     good idea about what this button should do, drop me a line. Using
     mouse button 3 on an entry's button will clear that entry.

SIGNATURE:

     The mf(insert-signature) settings points to the file to be inserted
     at the end of each compostion before being sent. The button "Sign"
     on the compose button bar allows one to sign the message before it
     sent to one may verify the text inserted and change it if they
     wish. The mf(insert-auto-sign) setting can be set to true so that
     the signature file will be automatically inserted when the compose
     window is first popped up. If you wish to have not signature, just
     set mf(insert-signature) to the empty string.

     If mf(insert-signature) starts with the '@' character, the rest of
     it will be interpreted as a Tcl command which will be evaluted each
     composition with the compose window pathname passed as an
     argument. The return value will be taken as the file to insert as
     the signature. This can be useful in using different signatures for
     local and remote sends. See the example ~/.tkmailrc file for how to
     do this.

     The mf(insert-prefix-sig) settings is a character string that will
     be inserted write before the text included from the signature file.
     The unofficial standard for this seems to be two dashes and a
     newline which is the default. If the compose window is in MIME
     composition mode, then the mf(insert-prefix-sig) is ignored and the
     signature is inserted in its own text/plain part at the end of the
     composition.

MIME:

     TkMail can handle reading most of the standard MIME types outlined in RFC
     1521. The exceptions are the message/external-body types that require an
     outside network connection (eg. ftp). The text/plain and text/enriched
     types are displayed internally in TkMail, while others will require an
     external viewer. These can be configured with the
     mf(mime-external-viewers) setting. For example,

     set mf(mime-external-viewers) { 
	 {Image xv} \
	 {Text/HTML Mosaic} \
	 {Audio {cat %F > /dev/audio}} \
	 {Application/PostScript ghostview} }

     Since mime parsing can be time intensive, it can be toggled on and off
     with the mf(mime-parse) setting. Mime parsing will make extensive use
     of temporary files in your mf(mail-tmpdir) directory. If TkMail is killed
     ungracefully, you may want to look there to clean up some files yourself.

     In the compose window, MIME compositions are supported through the Attach
     Mime item in the File menu. This will build the MIME message in source
     form in the compose window, though some file inclusions may be delayed
     until send time. If mf(mime-parse) is on and one does a Forward operation,
     the forwarded message will be included as message/rfc822 subpart. Using
     the "Insert Message" button will also attach the target message as a
     message/rfc822 subpart.  Doing an "Insert File" will still only insert the
     contents of the file verbatim in the compose window. Use the Attach Mime
     menu item for real file attachments.


USER SETTINGS:

     Below are settings you may want to customize in the ~/.tkmailrc file.
     The contents of this file are sourced by TkMail as normal Tcl code.
     Settings that were most likely set to the proper defaults during
     installation are marked with an (*).  These should only be set by
     the knowledgable individual user.

     TkMail uses the array mf() to store all its "known" settings. If
     your customization requires you make your own global settings, you
     should use the mfuser() array to store them.  This will allow you
     to edit them in the TkMail Option Editor using the "User" category
     and TkMail will store them alongside the mf() settings in your
     ~/.tkmailrc file.

     If you want the Option Save command to be able to overwrite mf()
     and mfuser() settings in your ~/.tkmailrc file, put them between two 
     comment lines as in the following:
         # USER SETTINGS
	 set mf(variables) here
	 set mfuser(variables) here
	 # END OF USER SETTINGS
     TkMail will overwrite anything except comments that appear between
     these two comment lines. DO NOT put btp() settings or procedure
     definitions between them.

      * mf(mail-mbox) 		- main mail box for messages to incorporate to
				  ( this is usually ~/mbox )
				  ( should match corresponding .mailrc value)
      * mf(mail-deliver) 	- mail delivery command
      * mf(mail-system) 	- system mail box where mail is received
      * mf(mail-tmpdir)		- temporary file directory to use
	mf(mail-interval)	- number of milliseconds between mail checks
	mf(mail-directory) 	- directory containing mail folders
				  ( hidden files will be ignored )
				  ( should match corresponding .mailrc value)
	mf(mail-auto-incorp)	- whether to incorporate new mail automatically
				  ( see GENERAL USAGE above for details )
	mf(mail-flush)		- number of bytes between flushes to I/O
				  ( needed to handle large messages > 15000 bytes )
	mf(mail-read-ask)	- whether TkMail should ask to continue
				  when reading in large messages
	mf(mail-read-max)	- maximum number of lines to read before asking (when
				  mf(mail-read-ask) is true)
        mf(mail-alias-file)	- list of files containing alias definitions
        mf(mail-alias-type)	- format of alias files: bsd or elm
	mf(mail-archive-folder) - default archive file (see <Sender> above)

	mf(disp-left-scroll)	- set to 1 for scroll bar on left side of text widget

      * mf(viewer-bitmap-nomail) - bitmap to use to signal no mail
      * mf(viewer-bitmap-mail)	- bitmap to use to signal mail
	mf(viewer-print)	- UNIX commmand for printing (with %F subst for file)
	mf(viewer-geom)		- initial geometry for main mail window
	mf(viewer-beep-new)	- Tcl command to run when mail received
				  ( set to {} for no beep )
	mf(viewer-beep-empty)	- Tcl command to run when system mail is emptied
	mf(viewer-beep-error)	- Tcl beep command to run on error or notification
	mf(viewer-state)	- 'normal' or 'disabled' to allow mesg window editing
	mf(viewer-pipe-dir)	- directory to run piped UNIX commands

	mf(menu-folders-max)	- maximum number of folders displayed in menu
				   at one level
	mf(menu-depth-max)	- maximum depth of pull-right menus
	mf(menu-quick-send)	- list of common addresses for composing mail
				  ( can include aliases )
	mf(menu-folders-ignore) - files to ignore in mf(mail-directory) directory when adding
			  	   to menus at startup. These can be shell glob patterns.
				   A subdirectory path relative to mf(mail-directory) is
				   required.
	mf(menu-recent-max)	- maximum number of folders to keep track off in the
				  Recent menus
	mf(menu-default-new)    - create new viewer instead of reusing old one

	mf(headlist-reverse)	- set to 1 so that most recent message at top
	mf(headlist-sort)	- header field to sort on (i.e. subject, sm-from)
	mf(headlist-height)	- number of messages visible in top list at one time
	mf(headlist-format)	- see SUMMARY LISTBOX FORMAT above

	mf(compose-geom)	- initial geometry of compose window
	mf(compose-show-cc)	- whether to show Cc and Bcc entries in compose
	mf(compose-save-send)	- whether to save text of last compose window
        mf(compose-alt-editor)	- command to run alternate editor for compositions
				  ( must be an X-window command )
	mf(compose-alt-auto) 	- whether to automatically call up alternate editor
	mf(compose-alternates)  - list of email address that you want stripped
			  	  stripped from Cc: since they are yours
      * mf(compose-icon-bitmap)	- bitmap to use for compose window
        mf(compose-addr-postfix) - a string of form @machine to add to addresses
				    that lack it
        mf(compose-quick-forward) - whether Forward should bring up a compose window
        mf(compose-require-subject) - whether a subject should be required
					 or not on outgoing messages
        mf(compose-from-field)  - Text to include on From: line
	mf(compose-fcc-folder)	- file to record outgoing messages in ( use {} for none )
	mf(compose-fcc-swap)	- whether or not when recording outgoing messages
				  to record them as being "sent" by the addressee
	mf(compose-fcc-forward)	- whether or not to record forwarded messages

	mf(header-retain)	- see HEADER FIELD STRIPPING above
	mf(header-strip)	- see HEADER FIELD STRIPPING above
				  ( use this cautiously as it can delete body )
        mf(header-config)	- a text tag config argument to apply to the header
				  lines of a mail message

	mf(bind-emacs)		- whether to put in emacs bindings
				  ( see key bindings above )
	mf(bind-alt-key)        - Key to press in order to access menu accelarators
	mf(bind-use-meta)       - Whether or not to use Alt modifier for bindings
	mf(bind-use-esc)        - Whether or not to use Esc prefix for emacs bindings

	mf(insert-prefix)	- prefix for included messages
        mf(insert-headers)	- text to automatically put at top of all compositions
	mf(insert-signature)	- file to include at end of compostions (use {} for none)
	mf(insert-auto-sign)	- whether to automatically include signature file
				  when the compose window is first popped up
	mf(insert-encoder)	- program to use for encoding inserted files
	mf(insert-compress)	- program to use for compressing inserted files
	mf(insert-compress-suffix) - suffix used by compress program
	mf(insert-strip)	- whether or not the header of inserted messages should
				  be completely stripped
	mf(insert-prefix-sig)	- text to insert before contents of signature file
	mf(insert-cite-format)  - Format for citing at top of included messages
	mf(insert-forward-format) - Format of line put at top of forwarded messages
      * mf(ispell-present)	- whether your site has ispell or not

	mf(mime-parse)		   - Whether to do MIME parsing
	mf(mime-external-default)  - Default command to run on mime parts 
	mf(mime-external-viewers)  - List of content-type / program pairs
	mf(mime-font-default)      - Font as {foundry family fntsize} for 
					deriving fonts for mime
	mf(mime-font-fixed)        - Font as {foundry family fntsize} for 
					deriving fixed fonts for mime

     An example line in the ~/.tkmailrc file is shown below (note that
     you must use $env(HOME) instead of ~ for your home directory).
     Tcl does not do automatic globbing!

	set mf(mail-directory) $env(HOME)/Mail

     The site adminstrator only has to modify the mfp(globalset)
     variable at the top of the tkmail source file and can put the
     rest of the settings in the pointed to file.

WIDGET CONFIGURATION:

     All widget configuration options can be accessed through your .Xdefaults
     file in the normal Tk way.  See the 'options' and individual widget man
     pages for more info. The main viewer window has resource class MailView
     and the compose window has resource class MailCompose. A few examples are:

        Tk.Mail*Button.foreground:      blue
	Tk.Mail*Text.font:	   	fixed
	Tk.Mail*Scrollbar.background:	grey42
	Tk.MailView*Text.background:    seashell2
	Tk.MailCompose*Text.background: thistle

     These can also be set inside the ~/.tkmailrc file using the following
     Tcl code lines

	option add Tk.Mail*Button.foreground blue
	option add Tk.Mail*Text.font fixed
	option add Tk.Mail*Scrollbar.background grey42
	option add Tk.MailView*Text.background seashell2
	option add Tk.MailCompose*Text.background thistle

     Note that there is no colon used with this command. Also, the font of the
     viewer and compose text display cannot be set this way. You must use the
     mf(mime-font-default) for that.

USEFUL METHODS:

     Here are a few methods one might find useful in the various hooks
     possible in the ~/.tkmailrc file.

     mfv:xterm-command $mft $cmd 

	Will popup an xterm in which the current message in the viewer
	$mft will be piped through the unix shell command $cmd. Before
	exiting, the user will be asked to press return

     mfv:reset-fcc $mfc

	Recalculates the FCC entry in the compose window $mfc. Should be
	called at the end of any routine which changes the contents of a
	compose window's entries.

     mfv:viewer-get-field $mft $fieldlist

	Returns the content of the first header field in $fieldlist that
	exists for the current message in the viewer $mft. Returns the
	empty string if none of them exist.

     mfv:compose-get-field $mfc $field

	Returns the contents of the $field entry in the compose window
	$mfc where $field may be to, subj, cc, bcc, or fcc.

     mfv:extract-address $addrfieldstring $pos

	Extracts the $pos'th e-mail address from the address field
	$addrfieldstring (e.g. From:, To:, Cc:). Not very robust yet, so
	I would appreciate being sent valid address fields it does not
	work on so I can improve it.

     mfv:strip-comment $fieldstring $keepq

	Returns $fieldstring with comments and quoted strings stripped
	from it. If $keepq is 1, then only comments are stripped.

     mfv:mime-attach $mfc $type $subtype $params $enc $file $desc

        Attach a mime subpart of $type/$subtype to the composition in
	the compose window whose toplevel is $mfc. All other arguments
	may be the empty string. If $file is given, the contents for the
	subpart will be taken from the given file and encoded according
	to $enc (default is no encoding) at send time. If $file is empty,
	the insert cursor is placed at the right position for the user
	to enter the contents manually.

BUGS:

     The bell doesn't work when the shell TkMail was run from is
     killed. This is because the normal way of sounding the bell in Tcl
     is writing a '\007' to standard out. So until Tk supports a bell
     command (Tk4.0 will), you must either make sure not to quit the
     shell TkMail was run from, or get one of the many patches to Tk
     that implement a bell (i.e. blt_wish). I have created the user
     setting of mf(viewer-beep-new) to put an alternate bell command if
     you have one.

     I am sure there are plenty of other bugs in this, so mail me
     about them (raines@slac.stanford.edu)

TODO:
     rewrite this help file into something readable
     support MIME external message type
     some sort of MIME enriched text composition tool
     support Sun Mailtool attachments
     encryption (PGP)
     incoming mail filtering
     handle unshar similar to uudecode
     compressed folder support
     better emacs bindings
     a true bounce
     better customization interface
     global mail searching
     mail response tracking
     XFaces

COPYRIGHT:
     Copyright 1994 by Paul Raines (raines@slac.stanford.edu)

     Permission to use, copy, modify, and distribute this software and
     its documentation for any purpose and without fee is hereby
     granted, provided that the above copyright notice appear in all
     copies.  The University of Pennsylvania makes no representations
     about the suitability of this software for any purpose.  It is
     provided "as is" without express or implied warranty.

DISCLAIMER:
     UNDER NO CIRCUMSTANCES WILL THE AUTHOR OF THIS SOFTWARE OR THE
     UNIVERSITY OF PENNSYLVANIA, STANFORD UNIVERSITY, THE STANFORD
     LINEAR ACCELERATOR CENTER, OR THE DEPARTEMENT OF ENERGY BE HELD
     RESPONSIBLE FOR ANY DIRECT OR INCIDENTAL DAMAGE ARISING FROM THE
     USE OF THIS SOFTWARE AND ITS DOCUMENTATION. THE SOFTWARE HEREIN IS
     PROVIDED "AS IS" WITH NO IMPLIED OBLIGATION TO PROVIDE SUPPORT,
     UPDATES, OR MODIFICATIONS.

 Please mail any suggestions, bugs, whines to raines@slac.stanford.edu

 The latest version is always available by anonymous ftp at
	ftp.slac.stanford.edu:software/TkMail/tkmail.tar.gz

 If you have slac.stanford.edu mounted as an AFS volume at your site,
 you can find it at /afs/slac.stanford.edu/public/sofware/TkMail.
