EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) NAME exmh-custom - A guide to customizing the exmh mail user interface. CUSTOMIZING EXMH This man page describes the four mechanisms used to custom- ize _E_x_m_h: Preferences, the MH profile, X resources, and custom Tcl code. _E_x_m_h is built with the assumption that you will want to cus- tomize it to some degree. The simplest way is by the Preferences user interface, which exposes numerous knobs and dials that you can adjust to control a lot of the behavior of _e_x_m_h. 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 _e_x_m_h. 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 _e_x_m_h to slip in your new feature. It is also possible to completely replace any module of the _e_x_m_h implementation. Finally, there are a few MH profile components introduced by _e_x_m_h, although these may eventually migrate out of the profile and into the Preferences package. PREFERENCES After you have used _e_x_m_h a little, you should explore all its capabilities by clicking on the Preferences 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. There are three types of options you can set through the Preferences 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 _e_x_m_h runtime behavior. Then, when you click Save in the dialog, the values are saved as X resource settings in your ~/.exmh- defaults file. 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 Exmh 1.6.1 Last change: May 23, 1995 1 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) 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 for the change to take effect immedi- ately (or choose Save). You can cycle through all the preference dialogs by using the Next button, which takes you to the next preference sec- tion. 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 avail- able. If you decide you like your settings, click Save in the main Preferences dialog to save them in a .exmh-defaults file in your home directory. Click Reset All in the main dialog to restore all the settings to those of your last Save. Within each module's preference dialog there is a Reset button that resets only those module's settings. _W_a_r_n_i_n_g! If you click Dismiss in the main dialog, some preferences may have been set for the current session, but they will not have been saved to your ~/.exmh-defaults file. PREFERENCE SECTIONS 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. Hacking Support A debug log can be enabled, and you can define the directory for personal Tcl code. (main.tcl) MH Tweaks Background sending can be enabled. The naming conven- tion for deleted files (leading , or #) is set. The age of files to purge can be defined. (mh.tcl) Simple Editor Formatting parameters can be adjusted and automatic signatures can be enabled. (sedit.tcl) Editor Support An external editor, spell program, and MHN command can be defined. (editor.tcl) Printing The print command can be defined. You can also enter an arbitrary UNIX command to apply to a message. (print.tcl) Exmh 1.6.1 Last change: May 23, 1995 2 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) Scan Listing 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) MIME 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) WWW Exmh 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 mes- sage 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) Incorporate Mail 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) Windows & Scrolling Scrolling speed and parameters related to constrained text scrolling can be defined. Constrained scrolling keeps the last line of text stuck to the bottom of the text display. (exwin.tcl and widgetText.tcl) Folder Cache Set how many lines are in your folder cache display, and what folders are permanently in your folder cache. (fcache.tcl) Folder Display Set the number of rows of labels in the folder display. The style of nested folder display is controlled here. (fdisp.tcl) Sound The sound effects can be controlled. (sound.tcl) Faces The use of the facesaver database and the decompression of X-Face components can be controlled. (faces.tcl) PGP interface You choose whether _e_x_m_h can remember your pass phrase or if all PGP programs are run under an xterm instead. (pgp.tcl) Exmh 1.6.1 Last change: May 23, 1995 3 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) Background Processing What actions occur in the background, and how fre- quently. (background.tcl) FS Box The file selector has a few parameters, including the threshold size for large directories and whether or not you want to see files whos names begin with a period. Busy Indicator What method of signaling that exmh is busy. (busy.tcl) BINDING UI There are a number of keystroke bindings already defined by _e_x_m_h that invoke different Tcl commands. You can change the bindings and add bindings for new commands via the Bind dia- log. Open the dialog from the _C_o_m_m_a_n_d_s 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. Binding Syntax. The following is a very brief summary of the Tk bind syntax. For the complete story, consult the Tk man page for the _b_i_n_d command. The Tk syntax for the bind- ings events looks like this: <_m_o_d_i_f_i_e_r-_t_y_p_e-_d_e_t_a_i_l> A _m_o_d_i_f_i_e_r is a key that you hold down while pressing another key. The modifiers you are likely to use are listed below. Capitalization is important. Control Shift Meta The _t_y_p_e is the event type, and it can left out if the detail part implies the type. The types you will usually use are: Key Button The _d_e_t_a_i_l 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., , which can be shortened to . For punctuation, how- ever, the keysyms are words. Here are some examples, and again the Key type is left out. Exmh 1.6.1 Last change: May 23, 1995 4 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) 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. bind . {puts stdout "keysym = %K letter = %A"} MH PROFILE _E_x_m_h uses a couple of things from your .mh_profile file, including several components that are new. Header-Suppress and Header-Display 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 _r_e_g_u_l_a_r _e_x_p_r_e_s_s_i_o_n _p_a_t_t_e_r_n_s that are used to match against the header. Case is _n_o_t significant in the patterns. Its easiest to explain by giving the algorithm that uses these patterns. 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 If you are a mail junky, you may want to use Header-Suppress to explicitly suppress the boring header componets 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. Folder-Order 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 _g_l_o_b pattern to match on the folder names. All folder names that match the same pattern are sorted alphabeti- cally. Longer pattern matches have priority over shorter patterns. The glob patterns use the syntax of Tcl's string match function, which is similar to that used in many shells. Exmh 1.6.1 Last change: May 23, 1995 5 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) * 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 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, _e_x_m_h 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 _C_y_c_l_e _b_a_c_k _t_o _f_i_r_s_t preference setting under the Unseen Folders section. Folder-Unseen The Folder-Unseen component lets you contrain the search through folders for the ones with messages in the unseen message sequence. Its value is a set of "glob" patterns that are matched against folder names. Note that glob has filename smarts, so you'll have to take into account subfolders in your glob patterns. For example, inbox* will match all folders whose name begins with inbox, but it will not match subfolders of inbox. Use inbox/* to match the first level of folders under inbox, and inbox/*/* to match the next level, etc. Folder-Ignore The Folder-Ignore component specifys a set of patterns for folder names you want to ignore. It defaults to .*, which causes _e_x_m_h to ignore all directories whose name begins with a period. Again, you'll have to take subfolders into account explicitly in your glob pat- terns for Folder-Ignore. Draft-Folder The Draft-Folder component is used to know where to put messages being composed. _E_x_m_h will ask you if it is ok to create a Draft-Folder entry if you do not already have one. ExmhShowProc The ExmhShowProc component lets you define a program Exmh 1.6.1 Last change: May 23, 1995 6 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) that pre-filters a message before displaying it. If an ExmhShowProc is defined, then _e_x_m_h 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 spe- cial show proc. Scan-Proc The Scan-Proc component can be used to define an alter- native 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. _E_x_m_h depends on this. (It makes no attempt to decipher scan formats.) MailDrop 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/_u_s_e_r_n_a_m_e. If you do not define MailDrop correctly then Inc will not do any- thing because it will not file your new messages in the system spool file. Path The Path component is used to find your mail folders. _E_x_m_h will abort if this entry is not there on the presumption that you have not set yourself up to use MH properly. X RESOURCES The X resource database is used as a repository of Prefer- ence 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 app-defaults file that is kept in the script library directory for _e_x_m_h. Color- specific resources are contained in the app-defaults-color or app-defaults-mono file. One of these two is used depend- ing on the display. 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, _e_x_m_h will also read the local.app-defaults-color or local.app- defaults-mono if those files exist. Each user has a ~/.exmh-defaults file in their home direc- tory. To handle personal color-specific resources, _e_x_m_h will also read your ~/.exmh-defaults-color or ~/.exmh- defaults-mono if those files exist. Exmh 1.6.1 Last change: May 23, 1995 7 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) 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 over- ridden by things in your ~/.exmh-defaults file. The ~/.exmh-defaults file is divided into sections. The first section is for things you add by hand. The remaining sections are automatically managed by _e_x_m_h. If you manually add settings to your ~/.exmh-defaults file, add entries to the _b_e_g_i_n_n_i_n_g of this file. Add them before the comment about the rest of the file being automatically generated and you will not lose your changes. 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-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. *scrollbarSide: left *c_current: violet red 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 _e_x_m_h. 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-defaults file. (_H_i_n_t: 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.) WIDGET CLASS HIERARCHY 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 _t_k_i_n_s_p_e_c_t program, which you can find in the Tcl archives. Main Top row of buttons and title label Fdisp Folder label display Fltop Folder label display when it is in a detached toplevel. Exmh 1.6.1 Last change: May 23, 1995 8 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) Fops Folder operation buttons and folder label Ftoc Folder table of contents display Mid Frame around Face, Msgid, Status, Mops Mid.Face Bitmap display Mid.Right.Status.label Message label Mid.Right.Status.msg Status line Mid.Right.Mops Message buttons Msg Message display Clip Detached message display Sedit Simple editor top-levels Help Help window Key Color key window Pref Preferences dialogs Log Error/debug log Pick The pick dialog Glimpse The glimpse dialog NewFolder The new folder dialog. DeleteFolder The delete folder dialog. WhatNow The What Now? dialog. Error Error popups Dialog General popups Exmh 1.6.1 Last change: May 23, 1995 9 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) RESOURCES FOR BUTTONS _e_x_m_h uses X resources to specify its buttons and menus on the main display, the editor window, and the What Now dia- log. You can add a button to one of these areas of the user interface by listing it in a ubuttonlist 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 _e_x_m_h. *Main.ubuttonlist *Fops.ubuttonlist *Mops.ubuttonlist *Sedit.Menubar.ubuttonlist *WhatNow.ubuttonlist Fops is the set of folder operation buttons. Mops is the set of message operations buttons. Sedit.Menubar is the buttons in the built-in editor. WhatNow is the What Now dialog used with external editors. The ubuttonlist resource is necessary because there is no easy way to enumerate the contents of the resource database. 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 but- tons 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: 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. When _e_x_m_h creates a set of buttons, (e.g., the *Main but- tons), 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 but- tons: *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 The *Main.buttonlist resource names the buttons that appear Exmh 1.6.1 Last change: May 23, 1995 10 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) in the top row of buttons. Its value, in turn causes _e_x_m_h 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 dif- ferent attributes of a Tk button via resources, but you'll have to consult the Tk man page on _b_u_t_t_o_n for the details. As another example, here is how you would add a Repl button to the message buttons. By default, there are a few varia- tions on Reply under the Reply... menu. You might like a Repl button that does your most common form of reply. The Msg_Reply Tcl command takes regular arguments for the MH _r_e_p_l program. *Mops.ubuttonlist: myrepl *Mops.myrepl.text: Repl *Mops.myrepl.command: Msg_Reply -filter myrepl.filter -cc all 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 inter- nal name of each button. *Mops.u-buttonlist: reply RESOURCES FOR MENUS The menus in _e_x_m_h 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 paral- lel sets of resources for the system-defined and user- defined parts. Each section has a list of menus defined with the following resources: 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. Each menu, in turn, has a text resource that defines the label on the menubutton. The entrylist resource lists the entries that are found under the menu. Again, the system- defined entries are listed under entrylist, the administra- tor defines lentrylist, and users are meant to add new entries to uentrylist. System (or local) defined entries can be removed by adding them to the l-entrylist and u- entrylist resources. For each menu entry there are resources with the following naming convention (this is not standard Tk): if the entryl- ist item is _f_o_o, then: Exmh 1.6.1 Last change: May 23, 1995 11 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) l__f_o_o defines the label (text) for the entry. c__f_o_o defines the command. t__f_o_o defines the type: "command", "check", "radio", "cascade", or "separator". v__f_o_o defines the variable associated with check and radio entries. m__f_o_o defines the menu associated with cascade entries. More more information, it might be helpful to consult the Tk man page for _m_e_n_u. For example, here is how the main menus for exmh are defined: *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 Note the additional .m component in the *Main.help.m.entrylist resource name. The *Main.help resource corresponds to the menubutton, and *Main.help.m corresponds to the menu associated with that button. For another example, we can use the uentrylist 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-defaults would look something like this: *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) In this case the Tcl variable is ftoc(skipMarked), which is an element of an associative Tcl array. Menu entries that use Tcl variables defined by _e_x_m_h 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 Exmh 1.6.1 Last change: May 23, 1995 12 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) for Preferences_Add calls. These calls set up the relea- tionship between the internal Tcl variables and the Prefer- ence items you see in the interface. In most cases the variables are elements of an associative array. In this example, ftoc is the array that holds the state variables for ftoc.tcl, which implements the scan listing. BUTTON GROUPS When you use _e_x_m_h, 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 _c_u_r_r_e_n_t, _r_a_n_g_e, and _n_o_d_r_a_f_t. 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. 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. *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: Exmh 1.6.1 Last change: May 23, 1995 13 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) *Mops.ug_nodraft: *Mops.ugm_nodraft: *Mops.l-g_nodraft: *Mops.l-gm_nodraft: *Mops.u-g_nodraft: *Mops.u-gm_nodraft: The naming convention for buttons and menu entries is dif- ferent. The buttons are named the same way they appear in the buttonlist 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. _W_a_r_n_i_n_g! 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 but- tons and menus is different. COLOR RESOURCES The basic TK widget color attributes are listed below. Most of these are defined in app-defaults-color to obtain a fam- ily of gray levels. background The main background of a widget. Default is a light gray (#efefef) foreground The foreground, (e.g., for text). Default is black. activeBackground The background of a button or menu when the mouse is over it. Default is white. activeForeground The foreground of a button or menu when the mouse is over it. Default is black. disabledForeground The foreground color of a button or menu that has been disabled. Default is grey50. selectBackground The background of text when it is selected. Default is canary blue. highlightColor The color of the focus highlight rectangle when a widget has focus. Default is black. highlightBackground The color of the focus highlight rectangle when a Exmh 1.6.1 Last change: May 23, 1995 14 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) widget does not have focus. Default is the same gray as background. selector The color of the checkbutton and radiobutton glyph when the button is selected. Default is black. troughColor The "other background" for scrollbars and scales. Default is gray (#dfdfdf) 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: *Label.foreground: blue The following resources are used to control the looks in the scan listing and 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 greyscale users, you can specify all of them. You might also look at the fdispColor.tcl and ftocColor.tcl files that use these resources. c_current The color for the current message and current folder. Default is violet red. c_currentBg The background color for the current message. Default is white. c_unseen The color for unseen messages and folders that contain unseen messages. Default is blue. c_unseenBg The background color for unseen messages. Default is normal background (same as text widget default back- ground). c_moved The background color for messages that are marked for refile, and the background label color for the target folder for refile. Default is yellow. c_movedFg The foreground color for messages that are marked for refile. The default is normal forground. Exmh 1.6.1 Last change: May 23, 1995 15 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) c_deletedFg The foreground color for messages marked for delete. Default is normal foreground. c_foreground The foreground color for labels in the folder display. Default is black. c_background The background color for labels in the folder display. Default is white. c_popup The color for the popups that display nested folders. Default is grey. c_st_normal The color for normal status messages. Default is blue. c_st_error The color for error messages. Default is purple. c_st_warn The color for warning messages. Default is red. c_st_background The color for messages from the background process. Default is medium sea green. c_uri The color used to highlight URL and URN text by the Highlight URI function. The default is thistle. COLORIZING HEADERS A set of resources are used to specify colors and other font attributes of message headers. m_tagnames 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__t_a_g_n_a_m_e (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). For example, here is what I have in my own ~/.exmh-defaults file: Exmh 1.6.1 Last change: May 23, 1995 16 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) *m_tagnames: hidden subject from x-filters-matched *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" GEOMETRY AND POSITION RESOURCES Exmh automatically remembers the position of top-level win- dows, both within a session and between successive runs of _e_x_m_h. It does this by saving some position resource specif- ications in your ~/.exmh-defaults file. In addition, _e_x_m_h will remember the geometry of the main window and of the detached folder display. _W_a_r_n_i_n_g: If you use a virtual root window manager, the memory of a window location will cause problems if you start _e_x_m_h in a new "room". If you move _e_x_m_h to a new room, you'll have to edit your ~/.exmh-defaults and delete all the *position resource specifications. Or, you can turn off the _R_e_m_e_m_b_e_r _W_i_n_d_o_w _P_o_s_i_t_i_o_n_s preference item under Window Stuff. Then, when exmh exits, it removes these for you. You can adjust the width and height of some of the text win- dows. Here are the default values. *Fltop*Canvas.width: 300 *Fltop*Canvas.height: 100 *Sedit*Text.width: 80 *Sedit*Text.height: 24 *Clip*Text.width: 80 *Clip*Text.height: 48 *Help*Text.width: 80 *Help*Text.height: 30 *Log*Text.width: 80 *Log*Text.height: 20 ICON POSIITONS The iconposition 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 posi- tion is relative to the lower-right corner instead of the Exmh 1.6.1 Last change: May 23, 1995 17 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) upper-left corner. By default no position is specified so your window manager will place the icon. The iconic resource indicates the startup disposition of the window. exmh.iconposition: (empty - no default position) exmh.iconic: 0 *Fltop.iconposition: (empty - no default position) *Fltop.iconic: 0 ICON APPEARANCE 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 bit- map 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 abso- lute pathname otherwise. *iconUpBitmap: flagup.bitmap *iconDownBitmap: flagdown.bitmap *iconSpoolBitmap: flagup.bitmap *iconUpLabel: $flist(newMsgs) Unseen *iconDownLabel: exmh *iconSpoolLabel: $exmh(numUnInced) Spooled You can reference any global exmh variable in the icon label. The two most useful are $flist(newMsgs), 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. FOLDER DISPLAY RESOURCES fl_font The font for the labels in the folder display. Default is "fixed". fl_xgap The horizontal gap, in pixels, between labels in the folder display. The default is 8. Exmh 1.6.1 Last change: May 23, 1995 18 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) fl_ygap The vertical gap, in pixels, between labels in the folder display. The default is 8. fl_curbutton The button that choses the current folder in the folder display. The default is 1. (1=left, 2=middle, 3=right). fl_navbutton The button that navigates nested folders in the folder display. The default is 2. (1=left, 2=middle, 3=right). fl_tarbutton The button that choses the target folder for refile in the folder display. The default is 3. (1=left, 2=mid- dle, 3=right). MIME RESOURCES Resources are used to define the set of understood MIME types and to define the font families used to display mes- sages in various character sets. mimeTypes This lists the Content-Types for which handler pro- cedures are defined. For each of these there is a corresponding mime__c_o_n_t_e_n_t/_t_y_p_e resource that specifies the Tcl command used to display a part of that type. mimeUTypes is the parallel resource so that users can add content types of their own. For example: 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 mimeCharsets Exmh 1.6.1 Last change: May 23, 1995 19 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) 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 char- set, which lacks special characters used in many Euro- pean 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. *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: * mime__c_h_a_r_s_e_t_plain_families 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 mes- sages. *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 mime__c_h_a_r_s_e_t_fixed_families The fixed families are used to display fixed-width fonts. Fixed is one of the types allowd by text/enriched fonts. *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 mime__c_h_a_r_s_e_t_proportional_families The proportional families are used for text/enriched. *mime_us-ascii_proportional_families: times "new century schoolbook" \ lucidabright charter lucida helvetica *mime_iso-8859-1_proportional_families: times "new century schoolbook" \ Exmh 1.6.1 Last change: May 23, 1995 20 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) lucidabright charter lucida helvetica *mime_iso-8859-8_proportional_families: *mime_iso-2022-jp_proportional_families: mime__c_h_a_r_s_e_t_title_families The title families are used for menu and section titles. *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: mimeExtMethods This resource lists thte 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. *mimeExtMethods: local-file anon-ftp *mimeUExtMethods: *mime_local-file: MimeLocalFileTransfer *mime_anon-ftp: MimeFTPTransfer MISCELLANEOUS RESOURCES helpInOneWindow Set this to 1 to get a new preferences interface. PROGRAMMING EXMH _E_x_m_h is implemented as a Tcl/Tk script that uses the MH pro- grams 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 implementa- tion. It is more awkward to override the definition of a single Tcl procedure, as explained below. By the way, if you do anything interesting to the sources, send the results to exmhbugs@parc.xerox.com so they can be folded back into the master sources. Many of the good features in _e_x_m_h came about this way. 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 Exmh 1.6.1 Last change: May 23, 1995 21 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) Tk. There are books about Tcl, too. John Ousterhout, the creator of Tcl and Tk, has written _T_c_l _a_n_d _t_h_e _T_k _T_o_o_l_k_i_t, by Addison-Wesley. I am writing _P_r_a_c_t_i_c_a_l _P_r_o_g_r_a_m_m_i_n_g _i_n _T_c_l _a_n_d _T_k, to be published in early 1995 by Prentice-Hall. 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 tclIndex up-to-date. This index file records which files implement which Tcl procedures. The normal Tcl shells (tclsh and wish) provide a Tcl command auto_mkindex that generates this file for you. Within a Tcl shell you use it like this: auto_mkindex ~/.tk/exmh *.tcl The first argument is a directory name, and the second argu- ment 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. The Tcl library facility is used by _e_x_m_h 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 _e_x_m_h are invoked. The per-user library direc- tory is search first, which means you can replace parts of the _e_x_m_h 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. Also, when a new _e_x_m_h release comes out, there might be incompatibilities with your customized code. 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 _e_x_m_h script), let me know. 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. 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. You should be able to override individual Tcl procs in User_Layout without having them trashed by the auto load facility. In this case you'd just source a file that has the new definitions. It turns out that Tcl procs have a Exmh 1.6.1 Last change: May 23, 1995 22 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) global scope, so you could also just define the procs right inside User_Layout. Say, for example, you hate the con- strained text scrolling. Try this: proc User_Layout {} { # This procedure is called late, after WidgetTextYview has # been defined by the Exmh library. Let's override it now. proc WidgetTextYview { t args } { eval {$t yview} $args } } 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. 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: Hook_FolderChange $folder Called after you changed into the named folder. folderHook(enter,$folder) folderHook(leave,$folder) The folderHook array can be used to define enter and leave hooks for a folder. Just set these array ele- ments to be the Tcl commands you want invoked before and after the folder change. Hook_CheckPoint Called at Quit time. Hook_SeditSend $draft Called as a message is being sent. The argument is the pathname of the draft message. You could frob the mes- sage here before it is delivered. If this raises an error, the message is not sent. Hook_MsgShow $pathname mimeHdr Called before a message is displayed. The first argu- ment is the pathname of the message file. The second is the name of an array that contains the header infor- mation plucked out of the message. Because of Exmh 1.6.1 Last change: May 23, 1995 23 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) multipart messages, the elements of the array look like: mimeHdr(0=1,hdrs) Lists all the headers defined in the message. The header keys are downcased (from, to, subject, etc.). mimeHdr(0=1,hdr,_k_e_y) Contains the header line with the given _k_e_y, e.g. from or subject. 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. CODE ORGANIZATION I've tried to split up _e_x_m_h 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 defini- tions. 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. 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 explaination of what the Tcl procedures in it are for. exmh.MASTER This is the main script. It gets patched with site- dependent information and the results are written to _e_x_m_h, which gets installed. It doesn't define much because it loads just about everything from the script library. exmh-bg.MASTER 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 rendez-vous between the background process is imple- mented in this script and in some supporting routines in background.tcl install.tcl These are supporting routines for the installation Exmh 1.6.1 Last change: May 23, 1995 24 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) process. This should be generic enough for use with your own Tcl application. Feel free to borrow it. exmh.install This is the installation script for exmh. exmh-async This is the wrapper for external editors. The remainder of the files are kept in the script library. aliases.tcl A browser for the MH aliases file. audit.tcl Maintain an audit log of mail handling operations. background.tcl 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. bindings.tcl This has the default bindings and the implementation of the binding user interface. busy.tcl Three different ways to indicate that exmh is busy doing something. buttons.tcl The resource-based button and menu implementation. cutbuffer.tcl A stub for the C cutbuffer extension. dragNdrop.tcl Drag-and-drop for exmh. editor.tcl The interface to editors for message composition. error.tcl The error handler. extrasInit.tcl This has Init routines for optional modules. The idea is to avoid loading their complete implementation until they are actually used. Exmh 1.6.1 Last change: May 23, 1995 25 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) exwin.tcl The main window display is set up here. The code that remembers where toplevel windows go is here. faces.tcl The interface to the faces database. fcache.tcl The folder cache display. fdisp.tcl The main folder display. fdispColor.tcl The color definitions for the folder display. fdispPopup.tcl The nested folder popup implementation. fileselect.tcl The file selection dialog. find.tcl The find dialog. flag.tcl The appearance of the icon is managed here. flist.tcl The set of unseen folders is managed by this module. folder.tcl Folder operations like Folder_Change and Folder_Commit. folderNew.tcl The folder create and delete dialogs. ftoc.tcl The scan listing (folder table-of-contents). ftocColor.tcl Color definitinos for the highlights in the scan list- ing. ftocFind.tcl The search routines over the scan listing. help.tcl Some very simple help text and a color key. import.tcl Routines to import folders from UCB mail. Exmh 1.6.1 Last change: May 23, 1995 26 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) inc.tcl Several ways to incorporate mail. labels.tcl There are three labels in the display - can you see them? mailcap.tcl Routines to parse the mailcap files. main.tcl The main Exmh procedure, plus Exmh_Status and Exmh_Debug. mh.tcl A basic layer on top fo the MH commands. mime.tcl The mime display code. mosaic.tcl Code to request Mosaic to display an HTML page. msg.tcl Message operations - although these tend to be distri- buted partly among ftoc.tcl and mh.tcl as well. msgShow.tcl This used to be the main message display code, but it has become dwarfed by the mime display. partial.tcl Code to concatinate the parts of a message/partial MIME message. pgp.tcl An interface to the Pretty Good Privacy system. pgpEWN.tcl This implements the PGP function in the external editor What Now dialog. pgpExec.tcl This executs the PGP program to get things done. pgpMatch.tcl This looks for keys in your keyring. pgpMisc.tcl This has the main post-processing hook for messages. pick.tcl Exmh 1.6.1 Last change: May 23, 1995 27 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) An interface to the MH _p_i_c_k program. preferences.tcl The preferences user interface. print.tcl Routines to print messages. ps.tcl Code to rummage through the process table. OS- specific. report.tcl This impelemnts the Bug Report and Register New User forms. rich2tk.tcl This parses text/enriched MIME content-types. scan.tcl This manages the scan caches. sedit.tcl The main routines for the built-in editor. seditBind.tcl The keybindings for the built-in editor. seditCompose.tcl The mapping for the Compose key sequences that allow input of 8-bit characters. seditEnriched.tcl The composition of text/enriched is implemented here. seditExtras.tcl More editor stuff, like Whom, Spell, Sign, Find, and the dialogs associated with Insert Part. seditMime.tcl The MIME multipart structuring is implemented here. seditQP.tcl This is code to handle 8-bit characters via the MIME quoted-printable encoding. select.tcl The keyboard selection of folders and messages is implemeted here. sound.tcl Sound effects. Exmh 1.6.1 Last change: May 23, 1995 28 EXMH CUSTOM(1) User Commands EXMH CUSTOM(1) text.tcl Some text tagging routines. textButton.tcl An implementation of a pseudo-button in a text widget. textSelect.tcl The main guts of text bindings. thread.tcl This displays the messages related to the current sub- ject. user.tcl Stubs for User_Init and User_Layout. widgetMenu.tcl Support for the popup menus used in MIME messages. widgetText.tcl Contrained text scrolling and dragging a selection off the window is handled by the routines here. widgets.tcl A basic layer on top of the Tk widgets. These routines integrate the pack geometry manager. Even more impor- tant, they guard against errors that occur because of missing fonts. You should try and use these instead of the straight Tk widget commands. xns.tcl An interface to xnsgetmail for those folks with mail on an XNS mail server. SEE ALSO exmh-use, exmh-ref, exmh, mh AUTHOR Brent.Welch@Sun.COM THANKS 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. Exmh 1.6.1 Last change: May 23, 1995 29