File: custom.html

package info (click to toggle)
exmh 1%3A2.9.0-8
links: PTS
area: main
in suites: forky, sid, trixie
size: 4,932 kB
sloc: tcl: 38,143; perl: 1,647; makefile: 130; sh: 101; exp: 75; csh: 9; sed: 2
file content (1820 lines) | stat: -rw-r--r-- 68,974 bytes
parent folder | download | duplicates (4)
<Html>
<Head>
<Title>Exmh 2.0 - EXMH CUSTOM (1)</Title>
<!-- Author: bwelch -->
</Head>
<Body>



<h1><center>CUSTOMIZING EXMH</center></h1>
<h2><a NAME="CONTENTS">Contents</a></h2>
<ul>
<h4><a HREF="#NAME">NAME</a></h4>
<h4><a HREF="#CUSTOMIZING EXMH">CUSTOMIZING EXMH</a></h4>
<h4><a HREF="#PREFERENCES">PREFERENCES</a></h4>
<h4><a HREF="#PREFERENCE SECTIONS">PREFERENCE SECTIONS</a></h4>
<h4><a HREF="#BINDING UI">BINDING UI</a></h4>
<h4><a HREF="#MH PROFILE">MH PROFILE</a></h4>
<h4><a HREF="#X RESOURCES">X RESOURCES</a></h4>
<h4><a HREF="#WIDGET CLASS HIERARCHY">WIDGET CLASS HIERARCHY</a></h4>
<h4><a HREF="#RESOURCES FOR BUTTONS">RESOURCES FOR BUTTONS</a></h4>
<h4><a HREF="#RESOURCES FOR MENUS">RESOURCES FOR MENUS</a></h4>
<h4><a HREF="#BUTTON GROUPS">BUTTON GROUPS</a></h4>
<h4><a HREF="#COLOR RESOURCES">COLOR RESOURCES</a></h4>
<h4><a HREF="#COLORIZING HEADERS">COLORIZING HEADERS</a></h4>
<h4><a HREF="#GEOMETRY AND POSITION RESOURCES">GEOMETRY AND POSITION
RESOURCES</a></h4>
<h4><a HREF="#ICON POSITIONS">ICON POSITIONS</a></h4>
<h4><a HREF="#ICON APPEARANCE">ICON APPEARANCE</a></h4>
<h4><a HREF="#FOLDER DISPLAY RESOURCES">FOLDER DISPLAY RESOURCES</a></h4>
<h4><a HREF="#MIME RESOURCES">MIME RESOURCES</a></h4>
<h4><a HREF="#SEDIT BINDING RESOURCES">SEDIT BINDING RESOURCES</a></h4>
<h4><a HREF="#MISCELLANEOUS RESOURCES">MISCELLANEOUS RESOURCES</a></h4>
<h4><a HREF="#PROGRAMMING EXMH">PROGRAMMING EXMH</a></h4>
<h4><a HREF="#CODE ORGANIZATION">CODE ORGANIZATION</a></h4>
<h4><a HREF="#SEE ALSO">SEE ALSO</a></h4>
<h4><a HREF="#AUTHOR">AUTHOR</a></h4>
<h4><a HREF="#THANKS">THANKS</a></h4>
</ul>
<h3><a NAME="NAME" HREF="#CONTENTS">NAME</a></h3>
exmh-custom - A guide to customizing the exmh mail user interface.
<h3><a NAME="CUSTOMIZING EXMH" HREF="#CONTENTS">CUSTOMIZING EXMH</a></h3>
<p>
This man page describes the four mechanisms used to customize <i>Exmh</i>:
<button -command Preferences_Dialog>Preferences</button>, the MH
profile, X resources, and custom Tcl code.
<p>
<i>Exmh</i> is built with the assumption that you will want to customize
it to some degree. The simplest way is by the
<button -command Preferences_Dialog>Preferences</button> user
interface, which exposes numerous knobs and dials that you can adjust
to control a lot of the behavior of <i>exmh</i>. The second way is by
defining X resources. You will need to do this if you want to control
fonts and colors. It would be great if there was a user interface for
this, but this is something that has not been crossed off the TODO
list, yet. You also use X resources to define new buttons and
menus. The third way is by adding custom Tcl code to the
implementation of <i>exmh</i>. A personal library of Tcl routines is
supported. You can either add new buttons or menus to invoke your
functionality, or take advantage of some hook points inside
<i>exmh</i> to slip in your new feature. It is also possible to
completely replace any module of the <i>exmh</i>
implementation. Finally, there are a few MH profile components
introduced by <i>exmh</i>, although these may eventually migrate out
of the profile and into the
<button -command Preferences_Dialog>Preferences</button> package.

<h3><a NAME="PREFERENCES" HREF="#CONTENTS">PREFERENCES</a></h3>
<p>
After you have used <i>exmh</i> a little, you should explore all its
capabilities by clicking on the
<button -command Preferences_Dialog>Preferences</button> button. There
is a two-level preferences scheme, mainly because there are too many
knobs and dials. At the top-level you see a menu that corresponds to
different modules of the implementation. Clicking on one of the items
brings up the preferences items for that module. Use the
Help... button to display more detailed information about the
preference items. If you click on the label of an item, the help text
is scrolled to the information for that item.

<p>
There are three types of options you can set through the
<button -command Preferences_Dialog>Preferences</button> dialog:
choices, booleans, and general items. Each of these are tied to a Tcl
variable and an X resource name. Changes in the Preference user
interface change the value of the Tcl variable, which affects the
<i>exmh</i> runtime behavior. Then, when you click <b>Save</b> in the
dialog, the values are saved as X resource settings in your
~/.exmh/exmh-defaults file.
<p>
Choices are represented by radio-style buttons where only one button
in the set can be enabled at once. Changes take effect immediately.
Booleans are represented by check-style buttons. If the checkbox is
dark, then the option is turned on. Changes take effect immediately.
Numeric and filename settings have entry widgets in which you can type
in a new value. Press &lt;Return&gt; for the change to take effect
immediately (or choose <b>Save</b>).
<p>
You can cycle through all the preference dialogs by using the <b>Next</b>
button, which takes you to the next preference section. There is also
a Prev button to go back. You should take time at least once to go
through all the Preference sections to get an idea of what sort of
options are available.
<p>
If you decide you like your settings, click <b>Save</b> in the main
<button -command Preferences_Dialog>Preferences</button> dialog to
save them in a exmh-defaults file in your ~/.exmh directory. Click
<b>Reset All</b> in the main dialog to restore all the settings to
those of your last <b>Save</b>. Within each module's preference dialog
there is a <b>Reset</b> button that resets only those module's
settings.
<p>
<i>Warning!</i> If you click <b>Dismiss</b> in the main dialog, some
preferences may have been set for the current session, but they will
not have been saved to your ~/.exmh/exmh-defaults file.

<h3><a NAME="PREFERENCE SECTIONS" HREF="#CONTENTS">PREFERENCE SECTIONS</a></h3>
<p>
Here is a short summary of the preference sections and what features
they control. The Tcl module that the section corresponds to is listed
so you can dig into the code if you want to.
<dl>
  <dt><a name="topten">The Top Ten</a>
  <dd>A collection of the ten most important preference settings.

  <dt><a name="addr">Address Database</a>
  <dd>Control automatic address memorization, limit it to certain
      folders. (addr.tcl)

  <dt><a name="background">Background Processing</a>
  <dd>What actions occur in the background, and how
     frequently. (background.tcl)

  <dt><a name="bayesian">Bayesian Spam Filter</a>
  <dd>An interface to external spam-filtering software, such as
      SpamAssassin, bogofilter, spamoracle, and others. (bogo.tcl)

  <dt><a name="busy">Busy Indicator</a>
  <dd>What method of signaling that exmh is busy. (busy.tcl)

  <dt><a name="editor">Editor Support</a>
  <dd>An external editor, spell program, and mhbuild command can be defined.
      (editor.tcl)

  <dt><a name="fsbox">FS Box</a>
  <dd>The file selector has a few parameters, including the threshold
      size for large directories and whether or not you want to see
      files who's names begin with a period. (fileselect.tcl)

  <dt><a name="faces">Faces</a>
  <dd>The use of the facesaver database and the decompression of
      X-Face and X-Image-URL components can be controlled. (faces.tcl)

  <dt><a name="fcache">Folder Cache</a>
  <dd>Set how many lines are in your folder cache display, and what
      folders are permanently in your folder cache. (fcache.tcl)

  <dt><a name="fdisp">Folder Display</a>
  <dd>Set the number of rows of labels in the folder display. The
      style of nested folder display is controlled here. (fdisp.tcl)

  <dt><a name="fonts">Fonts</a>
  <dd>A font selection dialog. (fontsel.tcl)

  <dt><a name="pgp">General PGP Interface</a>
  <dd><i>exmh</i> has support for a number of different versions of
      the Pretty Good Privacy email security program.  This dialog
      allows you to set parameters that apply to all supported
      versions of PGP.  For example, you can choose whether
      <i>exmh</i> can remember your pass phrase or
      if all PGP programs are run under an xterm instead.  There are
      preferences dialogs for each supported version of PGP; they may
      or may not appear in your installed version depending on which
      versions of PGP are detected when <i>exmh</i> is run. (pgpMain.tcl)

  <dt><a name="glimpse">Glimpse</a>
  <dd>Settings for the Glimpse full-text indexing
      system. (glimpse.tcl)

  <dt><a name="gpg">GnuPG Interface</a>
  <dd>Preferences that apply to GPG (the GNU Privacy Guard). (pgpGpg.tcl)

  <dt><a name="hacking">Hacking Support</a>
  <dd>A debug log can be enabled, and you can define the directory for
      personal Tcl code. (main.tcl)

  <dt><a name="htmlviewer">Html Viewer</a>
  <dd>Settings for the built-in HTML viewer, including the proxy
      server and port. (html.tcl)

  <dt><a name="ispell">I-Spell</a>
  <dd>This is a module to allow interactive spelling within a sedit
      window it has many fine features include suggested correction
      and the ability to add new words to a session or to your
      personnel dictionary.  For words that are either not correct or
      not generated by a combination of roots or compounds, the word
      is marked as not spelled correctly. (ispell.tcl)

  <dt><a name="incmail">Incorporate Mail</a>
  <dd>The method you use to Inc can be set. You can set inc to run
      when you start exmh and when you open the exmh window. (inc.tcl)

  <dt><a name="sigs">Intelligent Signatures</a>
  <dd>Controls how different signature files are chosen based on the
      recipient. (seditExtras.tcl)

  <dt><a name="mhtweaks">MH Tweaks</a>
  <dd>Background sending can be enabled. The naming convention for deleted
      files (leading , or #) is set. The age of files to purge can be defined.
      (mh.tcl)

  <dt><a name="mime">MIME</a>
  <dd>There are several adjustments you can make to the MIME message
      display. Note that the font sizes chosen here do not affect
      non-MIME messages. (mime.tcl)

  <dt><a name="nntp">NNTP Support</a>
  <dd>Set the news server here, and the newsgroups to retrieve if you
      have background news retrieval enabled. (post.tcl, getnews.tcl)

  <dt><a name="pgp2">PGP 2.6 Interface</a>
  <dd>Preferences that apply to PGP 2.6. (pgpPgp2.tcl)

  <dt><a name="pgp5">PGP 5.0 Interface</a>
  <dd>Preferences that apply to PGP 5.0. (pgpPgp5.tcl)

  <dt><a name="pgp6">PGP 6.5 Interface</a>
  <dd>Preferences that apply to PGP 6.5. (pgpPgp6.tcl)

  <dt><a name="printing">Printing</a>
  <dd>The print command can be defined. You can also enter an
      arbitrary UNIX command to apply to a message. (print.tcl)

  <dt><a name="quote">Quoting</a>
  <dd><i>Exmh</i> has the ability to write to a quoting file ('@' by
      default).  This controls how this is done.  (quote.tcl)

  <dt><a name="scanlisting">Scan Listing</a>
  <dd>You set the number of lines in the scan listing here. There are
      several tweaks on message viewing: Implied Direction, Next
      Guard, Auto Commit, Advance After Link, Show New Messages, Skip
      Marked. You can also choose the scan format width
      here. (ftoc.tcl)

  <dt><a name="seqwin">Sequences Window</a>
  <dd>This is a summary window that lists which folders have messages
  in sequences. (seqwin.tcl)

  <dt><a name="sedit">Simple Editor</a>
  <dd>Formatting parameters can be adjusted and automatic signatures
      can be enabled. (sedit.tcl)

  <dt><a name="slowdisplay">Slow Display</a>
  <dd>If your display is slow (due to being over a slow link or
      encryption or whatever), exmh will recognize that the display is
      slow and can disable certain network intensive, but non-critical
      operations. (extrasInit.tcl)

  <dt><a name="sound">Sound</a>
  <dd>The sound effects can be controlled. (sound.tcl)

  <dt><a name="www">WWW</a>
  <dd><i>Exmh</i> can communicate with an external HTML viewer (e.g.,
      Mosaic or netscape) in order to display pages from the World
      Wide Web. It can scan the current message for embedded URL. The
      URLs are changed into active text buttons. Click on one and the
      web browser is asked to display the page. Use the preferences to
      choose the external viewer and to control if the URL scanning is
      done automatically. (uri.tcl)

  <dt><a name="windows">Windows &amp; Scrolling</a>
  <dd>Scrolling speed and parameters related to constrained text
      scrolling can be defined. Also can enable Wheel Mouse. Constrained
      scrolling keeps the last line of text stuck to the bottom of the
      text display. (exwin.tcl and widgetText.tcl)

</dl>
<h3><a NAME="BINDING UI" HREF="#CONTENTS">BINDING UI</a></h3>
<p>
There are a number of keystroke bindings already defined by <i>exmh</i>
that invoke different Tcl commands. You can change the bindings and
add bindings for new commands via the Bind dialog. Open the dialog
from the <button -command Bind_Pref>Commands</button> menu entry under
the Bindings menu. The dialog presents a scrollable column of commands
and their bindings, plus an area at the top to define a new binding.
<p>
<b>Binding Syntax</b>. The following is a very brief summary of the
Tk bind syntax. For the complete story, consult the Tk man page for
the <i>bind</i> command. The Tk syntax for the bindings events looks
like this:
<pre><blockquote>&lt;<i>modifier</i>-<i>type</i>-<i>detail</i>&gt;
</blockquote></pre>A <i>modifier</i>
is a key that you hold down while pressing another key. The modifiers
you are likely to use are listed below. Capitalization is important.
<pre><blockquote>Control
Shift
Meta
</blockquote></pre>The <i>type</i> is the event type,
and it can left out if the detail part implies the type. The types
you will usually use are:
<pre><blockquote>Key
Button
</blockquote></pre>The <i>detail</i> specifies the
key or button number for the event. Keys are named by their X keysym.
For the letters and digits, the keysym is just the letter or digit,
e.g., &lt;Key-a&gt;, which can be shortened to &lt;a&gt;. For punctuation,
however,
<dl>
</dl>
<p>
the keysyms are words. Here are some examples, and again the Key type
is left out.
<pre><blockquote>&lt;comma&gt;
&lt;period&gt;
&lt;dollar&gt;
&lt;asciicircum&gt;
&lt;question&gt;
&lt;exclam&gt;
</blockquote></pre>Perhaps the easiest way to figure
out the keysym is to use the following Tcl/Tk command. Run the Tcl/Tk
shell, wish, and enter this command. Then type with the mouse over
the little window it displays.
<pre><blockquote>bind . &lt;Any-Key&gt; {puts stdout "keysym = %K letter = %A"}
</blockquote></pre>

<h3><a NAME="MH PROFILE" HREF="#CONTENTS">MH PROFILE</a></h3>
<p>
<i>Exmh</i> uses a couple of things from your .mh_profile file, including
several components that are new.
<dl>
<dt>Header-Suppress and Header-Display
<dd>You control what headers are displayed in a message with a combination
of the Header-Suppress and Header-Display profile components. Hidden
headers are just scrolled off the top of the message display window.
Each of these profile components is a list of <i>regular expression
patterns</i> that are used to match against the header. Case is <i>not</i>
significant in the patterns. Its easiest to explain by giving the algorithm
that uses these patterns.
<pre><blockquote>By default, show all headers.
If a header is in the Header-Suppress list, do not show it.
If a header is in the Header-Display list, show it.

The default values for these profile components are:

Header-Suppress: .*
Header-Display: Subject To From Date Cc Newsgroups
</blockquote></pre></dl>
<p>
If you are a mail junky, you may want to use Header-Suppress to explicitly
suppress the boring header components you already know about. The new,
interesting components inserted by random mailers will be displayed
for you to check out. In contrast, the default for Header-Suppress
will hide everything, and you explicitly choose what headers you want
to see by setting Header-Display.
<dl>
<dt>Folder-Order
<dd>The Folder-Order component defines a sort ordering for your folder
labels in the folder display area. Each item in the order can be the
name of a folder, or a <i>string match</i> pattern to match on the
folder names. All folder names that match the same pattern are sorted
alphabetically. Longer pattern matches have priority over shorter patterns.
The patterns use the syntax of Tcl's string match function, which is
similar to that used in many shells.
<pre><blockquote>* matches a sequence of any characters.
? matches any character.

The default Folder-Order puts your inbox first.

Folder-Order: inbox *

My Folder-Order looks like:

Folder-Order: personal exmh mxedit * mail* sun m3 mach background

</blockquote></pre></dl>
<p>
The other effect of Folder-Order is to define a traversal order for
visiting folders with unread mail in them. When you do a Next and are
at the end of a folder, <i>exmh</i> will automatically change folders
to the next one in the Folder-Order that has unseen messages, if any.
When there are no more folders with unseen mail, then you will change
back to the first folder in your Folder-Order, unless you disable this
by turning off the <i>Cycle back to first</i> preference setting under
the Unseen Folders section.
<dl>
  <dt>Folder-Unseen
  <dd>The Folder-Unseen component lets you constrain the search
      through folders for the ones with messages in the unseen message
      sequence. Its value is a set of <i>string match</i> patterns
      that are matched against folder names. If a folder name matches
      the pattern, it is searched for unseen messages. If the pattern
      begins with a !, however, then a folder that matches the pattern
      (not including the !) is excluded from the search. The default
      is *, which matches everything. Put the negated patterns first
      in your list of patterns (e.g., !junk* inbox*).

  <dt>Folder-Ignore
  <dd>The Folder-Ignore component specifies a set of <i>string
      match</i> patterns for folder names you want to ignore. These
      folders are not even displayed by exmh. It defaults to ".* */.*
      */*/.* */*/*.*" , which causes <i>exmh</i> to ignore directories
      whose name begins with a period.

  <dt>Draft-Folder
  <dd>The Draft-Folder component is used to know where to put messages
      being composed. <i>Exmh</i> will ask you if it is OK to create a
      Draft-Folder entry if you do not already have one.

  <dt>ExmhShowProc
  <dd>The ExmhShowProc component lets you define a program that
      pre-filters a message before displaying it. If an ExmhShowProc
      is defined, then <i>exmh</i> runs that program with the current
      message as the standard input and displays what is generated on
      the program's standard output. Note that the Header-Suppress and
      Header-Display mechanism is still used even if you have a
      special show proc.

  <dt>Scan-Proc
  <dd>The Scan-Proc component can be used to define an alternative
      scan program. If you change the scan format, you need to make
      sure that the first item on each scan line is the message
      number. <i>Exmh</i> depends on this. (It makes no attempt to
      decipher scan formats.)

  <dt>MailDrop
  <dd>The MailDrop component is required if you do not have your
      system mail spool file in the "standard" location, which is
      typically /usr/spool/mail/<i>username</i>. If you do not define
      MailDrop correctly then Inc will not do anything because it will
      not file your new messages in the system spool file.

  <dt>Path
  <dd>The Path component is used to find your mail
      folders. <i>Exmh</i> will abort if this entry is not there on
      the presumption that you have not set yourself up to use MH
      properly.

</dl>
<h3><a NAME="X RESOURCES" HREF="#CONTENTS">X RESOURCES</a></h3>
<p>
The X resource database is used as a repository of Preference settings,
window positions, and definitions of fonts, colors, buttons, and menus.
The information in the database can come from a variety of sources,
which can be confusing. The default values come from the <b>app-defaults</b>
file that is kept in the script library directory for <i>exmh</i>.
Color-specific resources are contained in the app-defaults-color or
app-defaults-mono file. One of these two is used depending on the display.
<p>
A site administrator can add local resource specifications in the
local-app-defaults file. Put this into the exmh script library
directory (the same place as app-defaults). To handle site-specific
color-specific resources, <i>exmh</i> will also read the
local.app-defaults-color or local.app-defaults-mono if those files exist.
<p>
Each user has a ~/.exmh/exmh-defaults file in their home directory. To
handle personal color-specific resources, <i>exmh</i> will also read
your ~/.exmh/exmh-defaults-color or ~/.exmh/exmh-defaults-mono if
those files exist.
<p>
I do not recommend putting exmh-related resource settings in your
~/.Xdefaults, although you can do that. If you do, be warned that
values from the ~/.Xdefaults file and the RESOURCE_MANAGER property on
the root window will be overridden by things in your
~/.exmh/exmh-defaults file.
<p>
The ~/.exmh/exmh-defaults file is divided into sections. The first
section is for things you add by hand. The remaining sections are
automatically managed by <i>exmh</i>. If you manually add settings to
your ~/.exmh/exmh-defaults file, add entries to the <i>beginning</i>
of this file. Add them before the comment about the rest of the file
being automatically generated and you will not lose your changes.
<p>
If a resource has a multiword value, you *should not quote* the value
in the resource file. The right way to specify these in your
~/.exmh/exmh-defaults file is shown below. The leading "*" gets around
quirks in the way Tk names its applications; different instances of
the application have different names.
<pre><blockquote>*scrollbarSide:      left
*c_current: violet red
</blockquote></pre>
<p>
Finally, if you are really serious about fiddling with resources, you
should look through the app-defaults file. For one thing, there is no
guarantee that the resource names used in this man page, which
correspond to version 1.5, will be exactly the same in later versions
of <i>exmh</i>.  Furthermore, there might be new goodies that appear
in future versions that are not described here. Only by reading the
app-defaults file of the current version will you be sure you are
setting things correctly in your ~/.exmh/exmh-defaults
file. (<i>Hint:</i> read through the main exmh script for the
definition of the exmh(library) Tcl variable, which is the script
library where app-defaults lives. The script is short, and the
definition is near the beginning.)

<h3><a NAME="WIDGET CLASS HIERARCHY" HREF="#CONTENTS">WIDGET CLASS
HIERARCHY</a></h3>
<p>
If you want to dive into the widget tree and fiddle with fonts and
colors and such, here are the class descriptions. I also highly
recommend the <i>tkinspect</i> program, which you can find in the Tcl
archives.

<dl>

  <dt>Main
  <dd>Top row of buttons and title label

  <dt>Fdisp
  <dd>Folder label display

  <dt>Fltop
  <dd>Folder label display when it is in a detached toplevel.

  <dt>Fops
  <dd>Folder operation buttons and folder label

  <dt>Ftoc
  <dd>Folder table of contents display

  <dt>Mid
  <dd>Frame around Face, Msgid, Status, Mops

  <dt>Mid.Face
  <dd>Bitmap display

  <dt>Mid.Right.Status.label
  <dd>Message label

  <dt>Mid.Right.Status.msg
  <dd>Status line

  <dt>Mid.Right.Mops
  <dd>Message buttons

  <dt>Msg
  <dd>Message display

  <dt>Clip
  <dd>Detached message display

  <dt>Sedit
  <dd>Simple editor top-levels

  <dt>Help
  <dd>Help window

  <dt>Key
  <dd>Color key window

  <dt>Pref
  <dd>Preferences dialogs

  <dt>Log
  <dd>Error/debug log

  <dt>Pick
  <dd>The pick dialog

  <dt>Glimpse
  <dd>The glimpse dialog

  <dt>NewFolder
  <dd>The new folder dialog.

  <dt>DeleteFolder
  <dd>The delete folder dialog.

  <dt>WhatNow
  <dd>The What Now? dialog.

  <dt>Error
  <dd>Error popups

  <dt>Dialog
  <dd>General popups

</dl>
<h3><a NAME="RESOURCES FOR BUTTONS" HREF="#CONTENTS">RESOURCES FOR
BUTTONS</a></h3>
<p>
<i>exmh</i> uses X resources to specify its buttons and menus on the
main display, the editor window, and the What Now dialog. You can add
a button to one of these areas of the user interface by listing it
in a <b>ubuttonlist</b> resource and then adding some more resources
that describe the button. X resource names are hierarchical, and these
are the button list resources used by <i>exmh</i>.
<pre><blockquote>*Main.ubuttonlist
*Fops.ubuttonlist
*Mops.ubuttonlist
*Sedit.Menubar.ubuttonlist
*WhatNow.ubuttonlist
</blockquote></pre>
<b>Fops</b> is the set of folder operation buttons. Mops is the set of
message operations buttons. <b>Sedit.Menubar</b> is the buttons in the
built-in editor. <b>WhatNow</b> is the What Now dialog used with
external editors. The <b>ubuttonlist</b> resource is necessary because
there is no easy way to enumerate the contents of the resource database.
<p>
There are actually several resources associated with each set of buttons
in order to provide maximum flexibility. There are three sources of
button definitions: system buttons are defined by the base release
("at the factory"); local buttons are defined by your site administrator;
user buttons are defined by each user. In addition, the site and the
user can delete buttons with other resources. The resources are:
<pre><blockquote>buttonlist    The list of system defined buttons
lbuttonlist   The list of local (site) defined buttons
ubuttonlist   The list of user defined buttons
l-buttonlist  The list of buttons deleted at the local level.
u-buttonlist  The list of buttons deleted at the user level.
</blockquote></pre>When <i>exmh</i> creates a set
of buttons, (e.g., the *Main buttons), t asks for the definition of
all these resources to determine what buttons are being defined (e.g.,
*Main.buttonlist, *Main.ubuttonlist, and so on.) For each of these
buttons, additional resources specify the text label and command for
each button. This is best explained by an example. Here are the definitions
for the main buttons:
<pre><blockquote>*Main.buttonlist:    quit pref alias
*Main.quit.text:     Quit
*Main.quit.command:  Exmh_Done
*Main.pref.text:     Preferences
*Main.pref.command:  Preferences_Dialog
*Main.alias.text:    Aliases
*Main.alias.command: Aliases_Pref
</blockquote></pre>The <b>*Main.buttonlist</b> resource
names the buttons that appear in the top row of buttons. Its value,
in turn causes <i>exmh</i> to look around for the other resources that
define the text and command attributes for each button. The command
is a Tcl command, and most are simple commands of one or two words.
If you are really inspired you can set many different attributes of
a Tk button via resources, but you'll have to consult the Tk man page
on <i>button</i> for the details.
<p>
As another example, here is how you would add a Repl button to the
message buttons. By default, there are a few variations on Reply under
the Reply... menu. You might like a Repl button that does your most
common form of reply. The <b>Msg_Reply</b> Tcl command takes regular
arguments for the MH <i>repl</i> program.
<pre><blockquote>*Mops.ubuttonlist: myrepl
*Mops.myrepl.text: Repl
*Mops.myrepl.command: Msg_Reply -filter myrepl.filter -cc all
</blockquote></pre>
<p>
If you hate the Reply... menu altogether, you can remove it by adding
it to the u-buttonlist resource. You'll have to look at the master
app-defaults file to find out the internal name of each button.
<pre><blockquote>*Mops.u-buttonlist:  reply
</blockquote></pre>

<h3><a NAME="RESOURCES FOR MENUS" HREF="#CONTENTS">RESOURCES FOR MENUS</a></h3>
<p>
The menus in <i>exmh</i> are defined in a similar way. It is a little
more complex because there is more to a menu than a button, but the
general idea is the same. There are parallel sets of resources for
the system-defined and user-defined parts. Each section has a list
of menus defined with the following resources:
<pre><blockquote>menulist      The list of system defined menus
lmenulist     The list of local (site) defined menus
umenulist     The list of user defined menus
l-menulist    The list of menus deleted at the local level.
u-menulist    The list of menus deleted at the user level.
</blockquote></pre>
<p>
Each menu, in turn, has a <b>text</b> resource that defines the label
on the menubutton. The <b>entrylist</b> resource lists the entries
that are found under the menu. Again, the system-defined entries are
listed under <b>entrylist</b>, the administrator defines <b>lentrylist</b>,
and users are meant to add new entries to <b>uentrylist</b>. System
(or local) defined entries can be removed by adding them to the
<b>l-entrylist</b> and <b>u-entrylist</b> resources.
<p>
For each menu entry there are resources with the following naming
convention (this is not standard Tk): if the entrylist item is
<i>foo</i>, then:

<pre><blockquote>l_<i>foo</i> defines the label (text) for the entry.
c_<i>foo</i> defines the command.
t_<i>foo</i> defines the type: "command", "check", "radio", "cascade", or "separator".
v_<i>foo</i> defines the variable associated with check and radio entries.
m_<i>foo</i> defines the menu associated with cascade entries.
</blockquote></pre>For
more information, it might be helpful to consult the Tk man page for
<i>menu</i>. For example, here is how the main menus for exmh are defined:
<pre><blockquote>*Main.menulist:             bind help

*Main.bind.text:     Bindings
*Main.bind.m.entrylist: command sedit
*Main.bind.m.l_command: Commands
*Main.bind.m.c_command: Bind_Pref
*Main.bind.m.l_sedit:       Simple Edit
*Main.bind.m.c_sedit:       Sedit_Pref

*Main.help.text:     Help...
*Main.help.m.entrylist:     help colorkey faq
*Main.help.m.l_colorkey:    Color Legend
*Main.help.m.c_colorkey:    Help_KeyDisplay
*Main.help.m.l_help: Quick Intro
*Main.help.m.c_help: Help
*Main.help.m.l_faq:  Frequently Asked Questions
*Main.help.m.c_faq:  Help FAQ
</blockquote></pre>
<p>
Note the additional <b>.m</b> component in the <b>*Main.help.m.entrylist</b>
resource name. The <b>*Main.help</b> resource corresponds to the menubutton,
and <b>*Main.help.m</b> corresponds to the menu associated with that
button.
<p>
For another example, we can use the <b>uentrylist</b> resource to add
a new menu entry to the message More... menu. It will be a check-button
type entry that will set the Tcl variable that controls the "skip marked"
behavior of Next and Prev. In addition, we will separate the user-defined
entries from the system entries with a special separator menu entry.
The resources in your ~/.exmh/exmh-defaults would look something like this:

<pre><blockquote>*Mops.more.m.uentrylist: sep skip
*Mops.more.m.t_sep: separator
*Mops.more.m.t_skip: check
*Mops.more.m.l_skip: Skip marked messages
*Mops.more.m.v_skip: ftoc(skipMarked)
</blockquote></pre>
<p>
In this case the Tcl variable is <b>ftoc(skipMarked)</b>, which is
an element of an associative Tcl array. Menu entries that use Tcl variables
defined by <i>exmh</i> might stop working in a future release. However,
you can easily get an idea of what the important variables are by searching
through the code for Preferences_Add calls. These calls set up the
relationship between the internal Tcl variables and the Preference
items you see in the interface. In most cases the variables are elements
of an associative array. In this example, <b>ftoc</b> is the array
that holds the state variables for ftoc.tcl, which implements the scan
listing.

<h3><a NAME="BUTTON GROUPS" HREF="#CONTENTS">BUTTON GROUPS</a></h3>
<p>
When you use <i>exmh</i>, you will notice that some of the message
buttons are disabled when there is no current message. This is implemented
by putting the Mops buttons and menu entries into groups. The group
membership is defined via resources. The groups are <i>current</i>,
<i>range</i>, and nodraft. The current group contains all the buttons
and menu entries that are enabled when there is a current message.
The range group contains buttons and menu entries that can be applied
to multiple messages. The nodraft group is for those buttons and menu
entries that ought to be disabled when you are in the drafts folder.

<p>
For each group there are several corresponding resources that list
the buttons, (system, local, and user), and menu entries, (system,
local, and user), in the group. These are the group-defining resources
and (part of) their default values.
<pre><blockquote>*Mops.g_current:     link move delete reply forward
*Mops.gm_current:    Print {Unmark (Undo)} Clip Redistribute {Burst Digest}
*Mops.lg_current:
*Mops.lgm_current:
*Mops.ug_current:
*Mops.ugm_current:
*Mops.l-g_current:
*Mops.l-gm_current:
*Mops.u-g_current:
*Mops.u-gm_current:

*Mops.g_range:              link move delete forward
*Mops.gm_range:             Print Unmark {Mark Unseen}
*Mops.lg_range:
*Mops.lgm_range:
*Mops.ug_range:
*Mops.ugm_range:
*Mops.l-g_range:
*Mops.l-gm_range:
*Mops.u-g_range:
*Mops.u-gm_range:

*Mops.g_nodraft:     reply forward
*Mops.gm_nodraft:    Redistribute
*Mops.lg_nodraft:
*Mops.lgm_nodraft:
*Mops.ug_nodraft:
*Mops.ugm_nodraft:
*Mops.l-g_nodraft:
*Mops.l-gm_nodraft:
*Mops.u-g_nodraft:
*Mops.u-gm_nodraft:
</blockquote></pre>The naming convention for buttons
and menu entries is different. The buttons are named the same way they
appear in the <b>buttonlist</b> resource specification. The menu entries
are named by their textual label. If a menu entry label includes spaces,
then the label must be grouped. Braces are used for compatibility with
the Tcl grouping syntax.
<p>
<i>Warning!</i> If you move things between the *Mops.buttonlist and
the *Mops.more.m.entrylist, then you will have to adjust your group
settings because the naming convention for buttons and menus is different.


<h3><a NAME="COLOR RESOURCES" HREF="#CONTENTS">COLOR RESOURCES</a></h3>
<p>
The basic TK widget color attributes are listed below. Most of these
are defined in app-defaults-color to obtain a family of gray levels.

<dl>

  <dt>background
  <dd>The main background of a widget. Default is a light gray (#efefef)

  <dt>foreground
  <dd>The foreground, (e.g., for text). Default is black.

  <dt>activeBackground
  <dd>The background of a button or menu when the mouse is over
      it. Default is white.

  <dt>activeForeground
  <dd>The foreground of a button or menu when the mouse is over
      it. Default is black.

  <dt>disabledForeground
  <dd>The foreground color of a button or menu that has been
      disabled. Default is grey50.

  <dt>selectBackground
  <dd>The background of text when it is selected. Default is canary
      blue.

  <dt>highlightColor
  <dd>The color of the focus highlight rectangle when a widget has
      focus. Default is black.

  <dt>highlightBackground
  <dd>The color of the focus highlight rectangle when a widget does
      not have focus. Default is the same gray as background.

  <dt>selector
  <dd>The color of the checkbutton and radiobutton glyph when the
      button is selected. Default is black.

  <dt>troughColor
  <dd>The "other background" for scrollbars and scales. Default is
      gray (#dfdfdf)

</dl>
<p>
You can specify colors for particular classes of widgets. All the labels
are blue in exmh, by default, because of the following in app-defaults:

<pre><blockquote>*Label.foreground: blue
</blockquote></pre>
<p>
The following resources are used to control the looks in the folder
label display. The fact that some have a trailing Bg or Fg is purely
historical accident. Originally you could only specify the foreground
(for current and unseen) or the background (for moved and deleted) but
now, for the benefit of grayscale users, you can specify all of
them. You might also look at the fdispColor.tcl and ftocColor.tcl
files that use these resources.
<dl>

  <dt>c_current
  <dd>The color for the current message and current folder. Default is
      violet red.

  <dt>c_unseen
  <dd>The color for unseen messages and folders that contain unseen
      messages. Default is blue.

  <dt>c_unseenBg
  <dd>The background color for unseen messages. Default is normal
      background (same as text widget default background).

  <dt>c_moved
  <dd>The background color for messages that are marked for refile,
      and the background label color for the target folder for
      refile. Default is yellow.

  <dt>c_movedFg
  <dd>The foreground color for messages that are marked for
      refile. The default is normal foreground.

  <dt>c_foreground
  <dd>The foreground color for labels in the folder display. Default
      is black.

  <dt>c_background
  <dd>The background color for labels in the folder display. Default
      is white.

  <dt>c_popup
  <dd>The color for the popups that display nested folders. Default is
      grey.

  <dt>c_st_normal
  <dd>The color for normal status messages. Default is blue.

  <dt>c_st_error
  <dd>The color for error messages. Default is red.

  <dt>c_st_warn
  <dd>The color for warning messages. Default is purple.

  <dt>c_st_bg_msgs
  <dd>The color for messages from the background process. Default is
      medium sea green.

  <dt>c_uri
  <dd>The color used to highlight URL and URN text by the Highlight
      URI function. The default is thistle.

  <dt>Text.c_link
  <dd>The color used for links in HTML display. The default is blue.

</dl>
<p>
The following resources are used to control how sequences are
highlighted in the scan listing.  This includes both (n)mh sequences
and also some exmh specific sequences.
<dl>

  <dt><A NAME=sequences>sequences</A>
  <dd>The priority of sequences for display.  Sequences which are not
  in this list will not be displayed.  If a message is in two
  different sequences, the latter sequence will be applied on top of
  the former seqeunce.  To add your own sequences, simply redefine
  this resource and add a sequence_yoursequence resource.  Default is:
  mrange drange range moved deleted.
  selected unseen current.
  <dt>sequence_cur
  <dd>"cur" is not really an (n)mh sequence.  This describes how the
  current message is displayed.  Default is: -foreground {violet red}
  -background white.
  <dt>sequence_unseen
  <dd>This is the sequence for unseen messages.  Default is:
  -foreground blue.
  <dt>sequence_moved
  <dd>This is the seqeunce for moved messages.  This is not an (n)mh
  sequence, but is instead merely a marking of messages which are to
  be moved to a different folder.  Default is: -background yellow.
  <dt>sequence_deleted
  <dd>This is the sequence for deleted messages.  This is not an (n)mh
  sequence, but is instead merely a marking of messages which are to
  be deleted.  Default is: -overstrike 1.
  <dt>sequence_selected
  <dd>This is the seqeunce for selected messages.  This is not an (n)mh
  sequence, but is instead merely a marking of messages which are to
  be processed.  Default is: -foreground black -background #ececec.
</dl>
</p>
<h3><a NAME="COLORIZING HEADERS" HREF="#CONTENTS">COLORIZING HEADERS</a></h3>
<p>
A set of resources are used to specify colors and other font attributes
of message headers.
<dl>

  <dt>m_tagnames
  <dd>This defines a list of mail headers for which you want to define
      special looks when they are displayed in the message area. For
      each tagname, you should define another resource with name
      m_<i>tagname</i> (e.g, m_subject) that has the text tag
      configuration options for that header line. Consult the Tk man
      page on the text widget to see what sort of tag configuration
      options there are. In addition, two special tagnames are used
      for defaults if there are no more specific matching tag
      name. "default" applies to displayed headers, while "hidden"
      applies to hidden ones (scrolled off the top).
</dl>
<p>
For example, here is what I have in my own ~/.exmh/exmh-defaults file:
<pre><blockquote>*m_tagnames:  hidden subject from x-filters-matched default
*m_hidden:    -font 6x10
*m_default:   -foreground black
*m_subject:   -foreground blue
*m_x-phase-of-moon:  -foreground blue
*m_from:      -foreground "medium sea green"
</blockquote></pre>

<h3><a NAME="GEOMETRY AND POSITION RESOURCES" HREF="#CONTENTS">GEOMETRY
AND POSITION RESOURCES</a></h3>
<p>
Exmh automatically remembers the position of top-level windows, both
within a session and between successive runs of <i>exmh</i>. It does
this by saving some <b>position</b> resource specifications in your
~/.exmh/exmh-defaults file. In addition, <i>exmh</i> will remember the geometry
of the main window and of the detached folder display.
<p>
<i>Warning</i>: If you use a virtual root window manager, the memory
of a window location will cause problems if you start <i>exmh</i> in
a new "room". If you move <i>exmh</i> to a new room, you'll have to
edit your ~/.exmh/exmh-defaults and delete all the *position resource specifications.
Or, you can turn off the <i>Remember Window Positions</i> preference
item under Window Stuff. Then, when exmh exits, it removes these for
you.
<p>
You can adjust the width and height of some of the text windows. Here
are the default values.
<dl>
<dt>*Fltop*Canvas.width:
<dd>300
<dt>*Fltop*Canvas.height:
<dd>100
<dt>*Sedit*Text.width:
<dd>80
<dt>*Sedit*Text.height:
<dd>24
<dt>*Clip*Text.width:
<dd>80
<dt>*Clip*Text.height:
<dd>48
<dt>*Help*Text.width:
<dd>80
<dt>*Help*Text.height:
<dd>30
<dt>*Log*Text.width:
<dd>80
<dt>*Log*Text.height:
<dd>20
</dl>
<h3><a NAME="ICON POSITIONS" HREF="#CONTENTS">ICON POSITIONS</a></h3>
<p>
The <b>iconposition</b> resources specify the location of the icons,
both for the main window and the detached folder display (if any).
The format is +X+Y to specify the upper-left hand point. If you use
- instead of +, then the position is relative to the lower-right corner
instead of the upper-left corner. By default no position is specified
so your window manager will place the icon. The <b>iconic</b> resource
indicates the startup disposition of the window.
<dl>

  <dt>exmh.iconposition:
  <dd>(empty - no default position)

  <dt>exmh.iconic:
  <dd>0

  <dt>*Fltop.iconposition:
  <dd>(empty - no default position)

  <dt>*Fltop.iconic:
  <dd>0

</dl>
<h3><a NAME="ICON APPEARANCE" HREF="#CONTENTS">ICON APPEARANCE</a></h3>
<p>
You can control the bitmap and the label on the icon. There are three
states for the icon: no mail, spooled mail, and unread mail. For each
of these states you can define a bitmap and a label. The label can
include references to exmh variables, as you will see in the default
values. The value for the Bitmap is a file name. If it is relative
then it is assumed to be in the exmh script library. Specify an absolute
pathname otherwise.
<dl>

  <dt>*iconUpBitmap:
  <dd>flagup.bitmap

  <dt>*iconDownBitmap:
  <dd>flagdown.bitmap

  <dt>*iconSpoolBitmap:
  <dd>flagspool.bitmap

  <dt>*iconUpMask:
  <dd>flagup.mask

  <dt>*iconDownMask:
  <dd>flagdown.mask

  <dt>*iconSpoolMask:
  <dd>flagspool.mask

  <dt>*iconUpLabel:
  <dd>$flist(newMsgs) Unseen

  <dt>*iconDownLabel:
  <dd>exmh

  <dt>*iconSpoolLabel:
  <dd>$exmh(numUnInced) Spooled

  <dt>*iconUpGlyph:
  <dd>flagup.gif

  <dt>*iconDownGlyph:
  <dd>flagdown.gif

  <dt>*iconSpoolGlyph:
  <dd>flagspool.gif
</dl>
<p>
You can reference any global exmh variable in the icon label. The two
most useful are $flist(totalcount,unseen), which is a count across all
folders of messages in the unseen sequence, and $exmh(numUnInced), which
is the number of messages in your system spool file. This later value
is only computed by the background "count" operation.
<p>
The icon*Glyph values are color images for the icons; the icon*Bitmap
values are black & white images for the icons and are used if the
Glyph is not available; the icon*Mask values are masks to allow
transparency in black and white icons.
<p>
The color icons may be disabled and the black and white used in their
place by providing a meaningless value (such as "none") for the
Glyph.

<h3><a NAME="FOLDER DISPLAY RESOURCES" HREF="#CONTENTS">FOLDER DISPLAY
RESOURCES</a></h3>
<dl>

  <dt>fl_font
  <dd>The font for the labels in the folder display. Default is "fixed".

  <dt>fl_xgap
  <dd>The horizontal gap, in pixels, between labels in the folder
      display. The default is 8.
  <dt>fl_ygap
  <dd>The vertical gap, in pixels, between labels in the folder
      display. The default is 8.

  <dt>fl_curbutton
  <dd>The button that chooses the current folder in the folder
      display. The default is 1. (1=left, 2=middle, 3=right).

  <dt>fl_navbutton
  <dd>The button that navigates nested folders in the folder
      display. The default is 2. (1=left, 2=middle, 3=right).

  <dt>fl_tarbutton
  <dd>The button that chooses the target folder for operations in the
      folder display. The default is 3. (1=left, 2=middle, 3=right).

</dl>
<h3><a NAME="MIME RESOURCES" HREF="#CONTENTS">MIME RESOURCES</a></h3>
<p>
Resources are used to define the set of understood MIME types and to
define the font families used to display messages in various character
sets.
<dl>

  <dt>mimeTypes
  <dd>This lists the Content-Types for which handler procedures are
      defined. For each of these there is a corresponding
      mime_<i>content/type</i> resource that specifies the Tcl command
      used to display a part of that type. <b>mimeUTypes</b> is the
      parallel resource so that users can add content types of their
      own. For example:
<pre><blockquote>text/plain text/richtext text/enriched multipart/mixed
       multipart/digest multipart/parallel multipart/alternative
       application/octet-stream message/external-body message/rfc822
       image/gif
*mimeUTypes:

*mime_text/plain:           Mime_ShowText
*mime_text/richtext:        Mime_ShowRichText
*mime_text/enriched:        Mime_ShowRichText
*mime_multipart/mixed:             Mime_ShowMultipart
*mime_multipart/digest:            Mime_ShowMultipartDigest
*mime_multipart/parallel:   Mime_ShowMultipartParallel
*mime_multipart/alternative:       Mime_ShowMultipartAlternative
*mime_application/octet-stream:    Mime_ShowApplicationOctet
*mime_message/external-body:       Mime_ShowMessageExternal
*mime_message/rfc822:              Mime_ShowRfc822
*mime_image/gif:            Mime_ShowImage
</blockquote></pre>

  <dt>mimeCharsets
  <dd>A font has a character set, which is an encoding for the
     characters.  This is an optional parameter to the text
     Content-type. us-ascii is the basic ASCII charset, which lacks
     special characters used in many European languages. The
     iso-8859-1 character set has 8-bit characters and is used to
     encode accented and other special characters used in latin-based
     languages. The iso-8859-8 is used for Hebrew. The iso-2022-jp is
     used for kanji. You need a specialized version of the Tk toolkit
     to display kanji.
<pre><blockquote>*mimeCharsets: us-ascii iso-8859-1 iso-8859-8 iso-2022-jp
*mimeUCharsets:
*mime_us-ascii_registry:    iso8859
*mime_us-ascii_encoding:    *
*mime_iso-8859-1_registry:  iso8859
*mime_iso-8859-1_encoding:  1
*mime_iso-8859-8_registry:  iso8859
*mime_iso-8859-8_encoding:  8
*mime_iso-2022-jp_registry:   jisx0208.1983
*mime_iso-2022-jp_encoding:   *
</blockquote></pre>

  <dt>mime_<i>charset</i>_plain_families
  <dd>A font has a family that determines the basic look for the font,
      like times or helvetica. Each of the family resources specifies
      a list of families that are tried, in order, to find a font that
      is supported by the X server. The plain family resource lists a
      set of font families that are used for ordinary text/plain messages.
<pre><blockquote>*mime_us-ascii_plain_families:     fixed clean lucidatypewriter courier terminal
*mime_iso-8859-1_plain_families:   lucidatypewriter fixed courier terminal
*mime_iso-8859-8_plain_families:   fixed
*mime_iso-2022-jp_plain_families:     fixed
</blockquote></pre>

  <dt>mime_<i>charset</i>_fixed_families
  <dd>The fixed families are used to display fixed-width fonts. Fixed
      is one of the types allowed by text/enriched fonts.
<pre><blockquote>*mime_us-ascii_fixed_families:     lucidatypewriter fixed clean courier terminal
*mime_iso-8859-1_fixed_families:   lucidatypewriter fixed courier terminal
*mime_iso-8859-8_fixed_families:   fixed
*mime_iso-2022-jp_fixed_families:     fixed
</blockquote></pre>

  <dt>mime_<i>charset</i>_proportional_families
  <dd>The proportional families are used for text/enriched.

<pre><blockquote>*mime_us-ascii_proportional_families:     times "new century schoolbook"
                                   lucidabright charter lucida helvetica
*mime_iso-8859-1_proportional_families:   times "new century schoolbook"
                                   lucidabright charter lucida helvetica
*mime_iso-8859-8_proportional_families:
*mime_iso-2022-jp_proportional_families:
</blockquote></pre>

  <dt>mime_<i>charset</i>_title_families
  <dd>The title families are used for menu and section titles.

<pre><blockquote>*mime_us-ascii_title_families:     times "new century schoolbook"
                            lucidabright charter lucida helvetica
*mime_iso-8859-1_title_families:   times "new century schoolbook"
                            lucidabright charter lucida helvetica
*mime_iso-8859-8_title_families:
*mime_iso-2022-jp_title_families:
</blockquote></pre>

  <dt>mimeExtMethods
  <dd>This resource lists the set of external access methods for use
      with message/external-body MIME parts. For each of these methods
      there is a corresponding resource that lists the Tcl command
      that handles the access method.

<pre><blockquote>*mimeExtMethods:     local-file anon-ftp
*mimeUExtMethods:
*mime_local-file:    MimeLocalFileTransfer
*mime_anon-ftp:             MimeFTPTransfer
</blockquote></pre>
</dl>

<h3><a NAME="SEDIT BINDING RESOURCES" HREF="#CONTENTS">SEDIT BINDING
RESOURCES</a></h3>
<dl>

  <dt>sedit_typeKillsSel
  <dd>Set to 1 or 0 to enable or disable type-in-kills selection: if
      there is selected text, typing new characters delete the
      selection.
  <dt>sedit_scrollButton
  <dd>Set to Middle (the default), Shift-Middle, or Right, to control
  which button is used for drag-scrolling text widgets.

  <dt>sedit_editprocs
  <dd>This is a list of built-in editing functions. It doesn't really
      make sense to change this unless you edit seditBind.tcl to
      provide an implementation for the edit function.

  <dt>sedit_key_<i>function</i>
  <dd>There is a corresponding resource for each function listed in
      sedit_editprocs. The value of the resources is one or more event
      sequences that trigger the function.

</dl>
<h3><a NAME="MISCELLANEOUS RESOURCES" HREF="#CONTENTS">MISCELLANEOUS
RESOURCES</a></h3>
<dl>

  <dt>helpInOneWindow
  <dd>Set this to 1 to get a new preferences interface.
      <br>
      <br>

  <dt>localTimeFormat
  <dd>If a message was sent from another time zone, the local
      equivalent is calculated and appended in parentheses to the
      displayed <code>Date:</code> header.  This resource describes
      the format, which uses the <code>strftime(3C)</code> syntax.
      The default value is:
<pre><blockquote>%H:%M %Z
</blockquote></pre>

  <dt>mime_alternative_prefs
  <dd>If a message contains a MIME part of type multipart/alternative,
      exmh will select one of the alternatives for display.  You can
      control the order of preference of the various alternatives.
      The most common use for this is to establish the precedence of
      text/plain over text/html for exmh users who do not use the
      in-line html viewer for showing text/html content.
      <p>
      Example:

<pre><blockquote>
*mime_alternative_prefs: text/plain text/richtext text/html
</blockquote></pre>

      If no value of mime_alternative_prefs is provided, exmh will
      display the last alternative that it is capable of displaying.

</dl>
<h3><a NAME="PROGRAMMING EXMH" HREF="#CONTENTS">PROGRAMMING EXMH</a></h3>
<p>
<i>Exmh</i> is implemented as a Tcl/Tk script that uses the MH programs
to manage your mail. The script is interpreted at runtime and is therefore
distributed in source form. You can read the source to figure out what
really going on. Furthermore, you can take advantage of the Tcl library
facility in order to override parts of the implementation. Warning:
it is easy to add new Tcl procedures, or to replace whole modules (i.e.,
files) of the exmh implementation. It is more awkward to override the
definition of a single Tcl procedure, as explained below.
<p>
By the way, if you do anything interesting to the sources, send the
results to <a
href="mailto:exmh-workers@redhat.com">exmh-workers@redhat.com</a> so
they can be folded back into the master sources. Many of the good
features in <i>exmh</i> came about this way.
<p>
Even if you do not know Tcl you can probably figure it out as you read
through the source. There is not enough room here to talk in any detail
about Tcl programming. There are reasonably good on-line manual pages
that come with Tcl and Tk. There are books about Tcl, too. John Ousterhout,
the creator of Tcl and Tk, has written <i>Tcl and the Tk Toolkit</i>,
by Addison-Wesley. I have written <i>Practical Programming in Tcl and
Tk</i>, published by Prentice-Hall, ISBN 0-13-616830-2.
<p>
Your custom Tcl code is kept in your ~/.tk/exmh directory. You maintain
this as a Tcl library, which amounts to keeping a file called <b>tclIndex</b>
up-to-date. This index file records which files implement which Tcl
procedures. The normal Tcl shells (tclsh and wish) provide a Tcl command
<b>auto_mkindex</b> that generates this file for you. Within a Tcl
shell you use it like this:
<pre><blockquote>auto_mkindex ~/.tk/exmh  *.tcl
</blockquote></pre>The first argument is a directory
name, and the second argument is a filename pattern, which is usually
*.tcl. If you add a new file or procedure to this directory, remember
to update the index by running this command.
<p>
The Tcl library facility is used by <i>exmh</i> for the main sources,
too. The implementation has been chopped up into over 50 files, and
these are loaded on demand as different features of <i>exmh</i> are
invoked. The per-user library directory is search first, which means
you can replace parts of the <i>exmh</i> implementation. While this
is quite flexible, it is not ideal. The natural unit of replacement
is a whole file, which might contain several Tcl procedures, even though
you only want to change one. See below for an explanation of the
patch procedure that lets you modify a main library script file.
<p>
NOTE: if you use TclX, then the auto_path stuff is different and the
personal library seems not to work. If you figure out the right thing
to do in auto_path_update (in the main <i>exmh</i> script), let me
know.
<p>
In most cases you will merely supply new code as opposed to replacing
(i.e., fixing) parts of the implementation. Because you can define
buttons and menus that invoke this new code without touching the released
sources, you should be able to graft on new functionality somewhat
cleanly.
<p>
The user.tcl file contains two empty hook procedures, User_Init and
User_Layout. User_Init is called early, before most other modules are
initialized. User_Layout is called late, just after the widget tree
has been created and basically every module initialized.
<p>
<i>IMPORTANT</i>You must supply both User_Init and User_Layout because
of the way Tcl auto-loading works. Just copy user.tcl and edit it.

<p>
Version 2.0.2 and later support a patching facility.  Suppose you want
to change the Msg_CompTo procedure in the standard msg.tcl file.  You
could edit a copy of msg.tcl and put that into your user script
library directory.  However, then you need to track changes to msg.tcl
when new releases come out.  Another way is to put the procedure definition
into msg.patch and put that file into your script library.  Now, enable
the "source hook" preference item in Hacking Support and restart exmh.
The next time exmh sources msg.tcl from its main library, it will
also source the msg.patch file from your private library.  Your new
definition of Msg_CompTo will replace the standard version.
<p>
There are some optional hook procedures with names beginning with Hook_.
These procedures are called if they exist, so you do not need stub
versions if you don't use them. Because of the way the library facility
works, though, you have to include your Hook procedures in your copy
of user.tcl or source the file that contains them from inside your
User_Init procedure.
<p>
In addition, you can have several hook procedures called from the same
point by appending things to the standard hook names. That is, the
implementation will call all procedures that match the pattern Hook_Foo*,
so you could define Hook_FooBrent and Hook_FooWelch and both would
be called at the Foo hook point. The hook points are:
<dl>

  <dt>Hook_FolderChange $folder
  <dd>Called after you changed into the named folder.

  <dt>folderHook(enter,$folder)
  <dd>

  <dt>folderHook(leave,$folder)
  <dd>The <b>folderHook</b> array can be used to define enter and
      leave hooks for a folder. Just set these array elements to be
      the Tcl commands you want invoked before and after the folder
      change.

  <dt>Hook_CheckPoint
  <dd>Called at Quit time.

  <dt>Hook_SeditSend $draft
  <dd>Called as a message is being sent. The argument is the pathname
      of the draft message. You could frob the message here before it
      is delivered. If this raises an error, the message is not sent.

  <dt>Hook_MsgShow $pathname mimeHdr
  <dd>Called before a message is displayed. The first argument is the
      pathname of the message file. The second is the name of an array
      that contains the header information plucked out of the
      message. Because of multipart messages, the elements of the
      array look like:

  <dt>mimeHdr(0=1,hdrs)
  <dd>Lists all the headers defined in the message. The header keys
      are downcased (from, to, subject, etc.).

  <dt>mimeHdr(0=1,hdr,<i>key</i>)
  <dd>Contains the header line with the given <i>key</i>,
      e.g. <b>from</b> or <b>subject</b>.

</dl>
<p>
Note that the MsgParseFrom procedure, which is defined in msgShow.tcl,
will extract the address part of a header line, so use it as a starting
point for your code.

<h3><a NAME="CODE ORGANIZATION" HREF="#CONTENTS">CODE ORGANIZATION</a></h3>
<p>
I've tried to split up <i>exmh</i> into meaningful modules, separating
out display modules (e.g., fdisp) from those that maintain display-independent
data structures (e.g., flist). Things like the Find and Pick dialogs
are in their own file, so you can easily replace those. I have not
documented the interfaces between modules at all, so you'll have to
read some code. Note that the .tcl file names reflect the names of
the procedures defined in them so you can locate definitions. In addition,
many modules use a single global array to hold their state variables,
and this array variable has the same name as the module.
<p>
If you are really interested in the internals of exmh (i.e., something
about it really bugs you!) you can look into the implementation in
order to see what is wrong and how you might do things better. The
following is a list of the files in the implementation along with a
short explanation of what the Tcl procedures in it are for.
<dl>

  <dt>exmh.MASTER
  <dd>This is the main script. It gets patched with site-dependent
      information and the results are written to <i>exmh</i>, which
      gets installed. It doesn't define much because it loads just
      about everything from the script library.

  <dt>exmh-bg.MASTER
  <dd>This is the main script for the background process. It redefines
      a few procedures, and loads in the rest of its implementation
      from the library. The initial rendezvous between the background
      process is implemented in this script and in some supporting
      routines in background.tcl

  <dt>install.tcl
  <dd>These are supporting routines for the installation process. This
      should be generic enough for use with your own Tcl
      application. Feel free to borrow it.

  <dt>exmh.install
  <dd>This is the installation script for exmh.

  <dt>exmh-async
  <dd>This is the wrapper for external editors.

</dl>
<p>
The remainder of the files are kept in the script library.
<dl>

  <dt>addr.tcl
  <dd>A mail address book that can automatically memorize
      addresses of received mail.

  <dt>aliases.tcl
  <dd>A browser for the MH aliases file.

  <dt>audit.tcl
  <dd>Maintain an audit log of mail handling operations.

  <dt>autorefile.tcl
  <dd>Automatically refiles messages into folders.

  <dt>background.tcl
  <dd>The background processing module. This can run in a separate
      process or as part of the main process. The BgRPC routine is
      used to invoke a background operation, and it works in either
      case.

  <dt>base64.tcl
  <dd>Base64 encoding utility routines.

  <dt>bindings.tcl
  <dd>This has the default bindings and the implementation of the
      binding user interface.

  <dt>bogo.tcl
  <dd>Interface to various Bayesian spam filtering packages.

  <dt>busy.tcl
  <dd>Three different ways to indicate that exmh is busy doing
      something.

  <dt>buttons.tcl
  <dd>The resource-based button and menu implementation.

  <dt>cutbuffer.tcl
  <dd>A stub for the C cutbuffer extension.

  <dt>crypt.tcl
  <dd>Generalized support for multipart/signed and multipart/encrypted
      messages in exmh.

  <dt>dragNdrop.tcl
  <dd>Drag-and-drop for exmh.

  <dt>editor.tcl
  <dd>The interface to editors for message composition.

  <dt>env.tcl
  <dd>Environment variable initialization.

  <dt>error.tcl
  <dd>The error handler.

  <dt>exec.tcl
  <dd>A wrapper around the Tcl exec command that caches the locations
      of executables in the user's search path.

  <dt>extrasInit.tcl
  <dd>This has Init routines for optional modules. The idea is to
      avoid loading their complete implementation until they are actually used.

  <dt>exwin.tcl
  <dd>The main window display is set up here. The code that remembers
      where toplevel windows go is here.

  <dt>faces.tcl
  <dd>The interface to the faces database.

  <dt>fcache.tcl
  <dd>The folder cache display.

  <dt>fdisp.tcl
  <dd>The main folder display.

  <dt>fdispColor.tcl
  <dd>The color definitions for the folder display.

  <dt>fdispPopup.tcl
  <dd>The nested folder popup implementation.

  <dt>fileselect.tcl
  <dd>The file selection dialog.

  <dt>find.tcl
  <dd>The find dialog.

  <dt>flag.tcl
  <dd>The appearance of the icon is managed here.

  <dt>flist.tcl
  <dd>The set of unseen folders is managed by this module.

  <dt>folder.tcl
  <dd>Folder operations like Folder_Change and Folder_Commit.

  <dt>folderNew.tcl
  <dd>The folder create and delete dialogs.

  <dt>fontsel.tcl
  <dd>The font selection dialog.

  <dt>ftoc.tcl
  <dd>The scan listing (folder table-of-contents).

  <dt>ftp_get.tcl
  <dd>Procedures to retrieve files via FTP.

  <dt>getnews.tcl
  <dd>Code to retrieve news via NNTP.

  <dt>glimpse.tcl
  <dd>Support code for use with the Glimpse indexing and searching
      utility.

  <dt>help.tcl
  <dd>Some very simple help text and a color key.

  <dt>html.tcl
  <dd>Exmh HTML browser.  The other html_*.tcl files implement various
      portions of the functionality of the HTML browser.

  <dt>import.tcl
  <dd>Routines to import folders from UCB mail.

  <dt>inc.tcl
  <dd>Several ways to incorporate mail.

  <dt>ispell.tcl
  <dd>Tcl interactive spell checker, using the ispell utility.

  <dt>labels.tcl
  <dd>There are three labels in the display - can you see them?

  <dt>mailcap.tcl
  <dd>Routines to parse the mailcap files.

  <dt>main.tcl
  <dd>The main Exmh procedure, plus Exmh_Status and Exmh_Debug.

  <dt>mh.tcl
  <dd>A basic layer on top of the MH commands.

  <dt>mime.tcl
  <dd>The mime display code.

  <dt>mimeSun.tcl
  <dd>Support to turn X-sun-attachments into MIME format.

  <dt>mosaic.tcl
  <dd>Code to request Mosaic to display an HTML page.

  <dt>msg.tcl
  <dd>Message operations - although these tend to be distributed
      partly among ftoc.tcl and mh.tcl as well.

  <dt>msgShow.tcl
  <dd>This used to be the main message display code, but it has become
      dwarfed by the mime display.

  <dt>partial.tcl
  <dd>Code to concatenate the parts of a message/partial MIME message.

  <dt>pgpBase.tcl
  <dd>Initialization for PGP support.

  <dt>pgpEWN.tcl
  <dd>This implements the PGP function in the external editor What Now
      dialog.

  <dt>pgpExec.tcl
  <dd>This executes the PGP program to get things done.

  <dt>pgpGpg.tcl
  <dd>Support code for the Gnu Privacy Guard.

  <dt>pgpMain.tcl
  <dd>An interface to the Pretty Good Privacy system.

  <dt>pgpMatch.tcl
  <dd>This looks for keys in your keyring.

  <dt>pgpMisc.tcl
  <dd>This has the main post-processing hook for messages.

  <dt>pgpOld.tcl
  <dd>Somewhat-obsolescent PGP support routines.

  <dt>pgpPgp2.tcl
  <dd>Support code for Pretty Good Privacy 2.6.

  <dt>pgpPgp5.tcl
  <dd>Support code for Pretty Good Privacy 5.0.

  <dt>pgpPgp65.tcl
  <dd>Support code for Pretty Good Privacy 6.5.

  <dt>pgpShared.tcl
  <dd>Initialization for PGP support.

  <dt>pgpWWW.tcl
  <dd>Support for querying keyservers for public keys via HTTP and HKP.

  <dt>pick.tcl
  <dd>An interface to the MH <i>pick</i> program.

  <dt>pop.tcl
  <dd>POP3 support for exmh.

  <dt>post.tcl
  <dd>News posting client for exmh.

  <dt>preferences.tcl
  <dd>The preferences user interface.

  <dt>print.tcl
  <dd>Routines to print messages.

  <dt>ps.tcl
  <dd>Code to rummage through the process table. OS-specific.

  <dt>quote.tcl
  <dd>Quoting support for exmh.

  <dt>receipt.tcl
  <dd>Handling of message dispotion notifications (MDNs).

  <dt>report.tcl
  <dd>This implements the Bug Report and Register New User forms.

  <dt>rich2tk.tcl
  <dd>This parses text/enriched MIME content-types.

  <dt>scan.tcl
  <dd>This manages the scan caches.

  <dt>sedit.tcl
  <dd>The main routines for the built-in editor.

  <dt>seditBind.tcl
  <dd>The keybindings for the built-in editor.

  <dt>seditCompose.tcl
  <dd>The mapping for the Compose key sequences that allow input of
      8-bit characters.

  <dt>seditEnriched.tcl
  <dd>The composition of text/enriched is implemented here.

  <dt>seditExtras.tcl
  <dd>More editor stuff, like Whom, Spell, Sign, Find, and the dialogs
      associated with Insert Part.

  <dt>seditMime.tcl
  <dd>The MIME multipart structuring is implemented here.

  <dt>seditQP.tcl
  <dd>This is code to handle 8-bit characters via the MIME
  quoted-printable encoding.

  <dt>select.tcl
  <dd>The keyboard selection of folders and messages is implemented here.

  <dt>sequences.tcl
  <dd>Routines for handling sequences.

  <dt>send.tcl
  <dd>A version of Tk 'send' command that auto-clears the xhost list.

  <dt>seqwin.tcl
  <dd>Support for a small window listing sequences by folders.

  <dt>sound.tcl
  <dd>Sound effects.

  <dt>source.tcl
  <dd>A patching facility for exmh.

  <dt>text.tcl
  <dd>Some text tagging routines.

  <dt>textButton.tcl
  <dd>An implementation of a pseudo-button in a text widget.

  <dt>textSelect.tcl
  <dd>The main guts of text bindings.

  <dt>thread.tcl
  <dd>This displays the messages related to the current subject.

  <dt>tioga.tcl
  <dd>Support for viewing multipart/x-tioga messages.

  <dt>uri.tcl
  <dd>The code that scans messages for URLs.

  <dt>urlFace.tcl
  <dd>Retrieve an image from a URL and use it as a face.

  <dt>user.tcl
  <dd>Stubs for User_Init and User_Layout.

  <dt>utils.tcl
  <dd>Miscellaneous support routines.

  <dt>widgetMenu.tcl
  <dd>Support for the popup menus used in MIME messages.

  <dt>widgetText.tcl
  <dd>Constrained text scrolling and dragging a selection off the
      window is handled by the routines here.

  <dt>widgets.tcl
  <dd>A basic layer on top of the Tk widgets. These routines integrate
      the pack geometry manager. Even more important, they guard
      against errors that occur because of missing fonts. You should
      try and use these instead of the straight Tk widget commands.

  <dt>xns.tcl
  <dd>An interface to xnsgetmail for those folks with mail on an XNS
      mail server.

</dl>

<h3><a NAME="AUTHOR" HREF="#CONTENTS">AUTHOR</a></h3>
welch@acm.org "Brent Welch"

<h3><a NAME="THANKS" HREF="#CONTENTS">THANKS</a></h3>
To Xerox PARC/CSL, for supporting this work initially, to Sun Microsystems
Laboratories for continuing the support, and to all the exmh users
that contributed ideas and code.

<hr><a HREF="index.html">exmh</a> |
<a HREF="software.html">software</a> |
<a HREF="Intro.html">intro</a> |
<a HREF="exmh-faq.html">faq</a> |
<a HREF="guide.html">guide</a> |
<a HREF="reference.html">reference</a> ]

</Body>
</Html>