XMH(1)

💌 XMH(1) — the xmh manual, bestie edition 💌

okay so this is the manual page for xmh, from the General Commands Manual section — it's giving "send and read mail with an X interface to MH" and honestly? iconic. let's get into it 🫶

---

✨ NAME ✨

xmh — send and read mail with an X interface to MH

🌸 SYNOPSIS 🌸

xmh [-path mailpath] [-initial foldername] [-flag] [-toolkitoption ...]

💅 DESCRIPTION 💅

okay so xmh is literally a graphical user interface for the MH Message Handling System. to actually do things with your mail, it makes calls to the MH package. you can compose, send, receive, reply to, forward, sort, and store electronic mail messages in folders — all of it. and the way xmh provides extensive mechanism for customization of the user interface?? obsessed. 💖

also, heads up: this document introduces many aspects of the Athena Widget Set. so if you're like "why is this manual talking about scrollbars," that's why. iykyk.

🎀 OPTIONS 🎀

• -path directory — this one specifies an alternate collection of mail folders to process mail in. the directory is specified as an absolute pathname. the default mail path is the value of the Path component in the MH profile, which is determined by the MH environment variable and defaults to $HOME/.mh_profile. and if the MH Path isn't given in the profile? $HOME/Mail gets used as the path instead.
• -initial folder — specifies an alternate folder which may receive new mail and is initially opened by xmh. default initial folder is ``inbox''.
• -flag — this one makes xmh change the appearance of appropriate folder buttons, and request the window manager to change the appearance of the xmh icon when new mail has arrived. by default, xmh will change the appearance of the ``inbox'' folder button when new mail is waiting. the application-specific resource checkNewMail can be used to turn off this notification — and the -flag option will still override it. slay.
• these three options have corresponding application-specific resources — MailPath, InitialFolder, and MailWaitingFlag — which can be specified in a resource file. 💫
• the standard toolkit command line options are given in X(7).
• -help — indicates that xmh should print a usage message and exit.
• -version — indicates that xmh should print version info and exit.

🦋 INSTALLATION 🦋

xmh requires that you're already set up to use MH, version 6. to do that, see if there's a file called .mh_profile in your home directory.

• if it exists, check whether it contains a line that starts with ``Current-Folder''.
• if it does, you've been using version 4 or earlier of MH. to convert to version 6, you must remove that line.

⚠️ fr fr, do not skip this: failure to remove that line causes spurious output to stderr, which can hang xmh depending on your setup. like, actually hang it. not cute. 😭

if you do not already have a .mh_profile, you can create one (and everything else you need) by typing ``inc'' to the shell. you should do this before using xmh to incorporate new mail.

for more information, refer to the mh(1) documentation. 📖

much of the user interface of xmh is configured in the Xmh application class defaults file — and if this file was not installed properly, a warning message will appear when xmh is used. xmh is backwards compatible with the R4 application class defaults file, which is honestly so generous of it. 💜

📌 also note: the default value of the SendBreakWidth resource has changed since R4.

🌈 BASIC SCREEN LAYOUT 🌈

xmh starts out with a single window, divided into four major areas:

• Six buttons with pull-down command menus.
• A collection of buttons, one for each top level folder. New users of MH will have two folders: drafts'' and inbox''.
• A listing, or Table of Contents, of the messages in the open folder. Initially, this will show the messages in ``inbox''.
• A view of one of your messages. Initially this is blank.

👑 XMH AND THE ATHENA WIDGET SET 👑

xmh uses the X Toolkit Intrinsics and the Athena Widget Set. many of the features described below (scrollbars, buttonboxes, etc.) are actually part of the Athena Widget Set, and are described here only for completeness. for more information, see the Athena Widget Set documentation. 💅

🖱️ SCROLLBARS 🖱️

some parts of the main window will have a vertical area on the left containing a grey bar. that area is a scrollbar. they're used whenever the data in a window takes up more space than can be displayed. the grey bar indicates what portion of your data is visible — so if the entire length of the area is grey, then you're looking at all your data; if only the first half is grey, then you're looking at the top half of your data. the message viewing area will have a horizontal scrollbar if the text of the message is wider than the viewing area. ✨

you can use the pointer in the scrollbar to change what part of the data is visible:

• click with pointer button 2 → the top of the grey area moves to where the pointer is, and the corresponding portion of data is displayed.
• hold down pointer button 2 → you can drag around the grey area. this makes it easy to get to the top of the data: just press with button 2, drag off the top of the scrollbar, and release. 🫶 easy.
• click with button 1 → the data to the right of the pointer will scroll to the top of the window.
• click with pointer button 3 → the data at the top of the window will scroll down to where the pointer is.

🔘 BUTTONBOXES, BUTTONS, AND MENUS 🔘

any area containing many words or short phrases, each enclosed in a rectangular or rounded boundary, is called a buttonbox. each rectangle or rounded area is actually a button that you can press by moving the pointer onto it and pressing pointer button 1. if a given buttonbox has more buttons in it than can fit, it will be displayed with a scrollbar, so you can always scroll to the button you want. no cap. 💫

some buttons have pull-down menus. pressing the pointer button while the pointer is over one of these buttons will pull down a menu. continuing to hold the button down while moving the pointer over the menu — that's called dragging the pointer — will highlight each selectable item on the menu as the pointer passes over it. to select an item in the menu, release the pointer button while the item is highlighted. ate. 💅

📐 ADJUSTING THE RELATIVE SIZES OF AREAS 📐

if you're not satisfied with the sizes of the various areas of the main window, they can easily be changed. near the right edge of the border between each region is a black box, called a grip. simply point to that grip with the pointer, press a pointer button, drag up or down, and release. exactly what happens depends on which pointer button you press:

• pointer button 2 → only that border will move. this mode is simplest to understand, but is the least useful. 🙈
• pointer button 1 → you're adjusting the size of the window above. xmh will attempt to compensate by adjusting some window below it.
• pointer button 3 → you're adjusting the size of the window below. xmh will attempt to compensate by adjusting some window above it.

all windows have a minimum and maximum size; you will never be allowed to move a border past the point where it would make a window have an invalid size. the app simply will not let you. ⭐

🧚 PROCESSING YOUR MAIL 🧚

this section will define the concepts of the selected folder, current folder, selected message(s), current message, selected sequence, and current sequence. each xmh command is introduced. 📬

for use in customization, action procedures corresponding to each command are given; these action procedures can be used to customize the user interface — particularly the keyboard accelerators and the functionality of the buttons in the optional button box created by the application resource CommandButtonCount. 💖

🗂️ FOLDERS AND SEQUENCES 🗂️

a folder contains a collection of mail messages, or is empty. xmh supports folders with one level of subfolders.

the selected folder is whichever foldername appears in the bar above the folder buttons. note that this is not necessarily the same folder that is currently being viewed. to change the selected folder, just press on the desired folder button with pointer button 1; if that folder has subfolders, select a folder from the pull-down menu. 🫶

the Table of Contents, or toc, lists the messages in the viewed folder. the title bar above the Table of Contents displays the name of the viewed folder.

the toc title bar also displays the name of the viewed sequence of messages within the viewed folder. every folder has an implicit all'' sequence, which contains all the messages in the folder, and initially the toc title bar will show inbox:all''. 💫

📁 FOLDER COMMANDS 📁

the Folder command menu contains commands of a global nature:

• Open Folder — display the data in the selected folder. thus, the selected folder also becomes the viewed folder. the action procedure corresponding to this command is XmhOpenFolder([foldername]). it takes an optional argument as the name of a folder to select and open; if no folder is specified, the selected folder is opened. it may be specified as part of an event translation from a folder menu button or from a folder menu, or as a binding of a keyboard accelerator to any widget other than the folder menu buttons or the folder menus. 👑
• Open Folder in New Window — displays the selected folder in an additional main window. note, however, that you cannot reliably display the same folder in more than one window at a time, although xmh will not prevent you from trying. 😭 the corresponding action is XmhOpenFolderInNewWindow().
• Create Folder — create a new folder. you will be prompted for a name for the new folder; to enter the name, move the pointer to the blank box provided and type. subfolders are created by specifying the parent folder, a slash, and the subfolder name. for example, to create a folder named xmh'' which is a subfolder of an existing folder named clients'', type ``clients/xmh''. click on the Okay button when finished, or just type Return; click on Cancel to cancel this operation. the action corresponding to Create Folder is XmhCreateFolder(). ✨
• Delete Folder — destroy the selected folder. you will be asked to confirm this action (see CONFIRMATION WINDOWS). destroying a folder will also destroy any subfolders of that folder. 💀 the corresponding action is XmhDeleteFolder().
• Close Window — exits xmh, after first confirming that you won't lose any changes; or, if selected from any additional xmh window, simply closes that window. the corresponding action is XmhClose().

💖 HIGHLIGHTED MESSAGES, SELECTED MESSAGES, AND THE CURRENT MESSAGE 💖

okay so bestie, you can absolutely highlight a set of adjacent messages in the area of the Table of Contents. To highlight a message, click on it with pointer button 1. To highlight a range of messages, click on the first one with pointer button 1 and on the last one with pointer button 3; or press pointer button 1, drag, and release. To extend a range of selected messages, use pointer button 3. To highlight all messages in the table of contents, click rapidly three times with pointer button 1. To cancel any selection in the table of contents, click rapidly twice.

The selected messages are the same as the highlighted messages, if any. If no messages are highlighted, then the selected messages are considered the same as the current message.

The current message is indicated by a + next to the message number. It usually corresponds to the message currently being viewed. Upon opening a new folder, for example, the current message will be different from the viewed message. When a message is viewed, the title bar above the view will identify the message. 👑

---

🎀 TABLE OF CONTENTS COMMANDS 🎀

The Table of Contents command menu contains commands which operate on the open, or viewed, folder. 💅

• Incorporate New Mail — Add any new mail received to viewed folder, and set the current message to be the first new message. This command is selectable in the menu and will execute only if the viewed folder is allowed to receive new mail. By default, only inbox is allowed to incorporate new mail. The corresponding action is XmhIncorporateNewMail().
• Commit Changes — Execute all deletions, moves, and copies that have been marked in this folder. The corresponding action is XmhCommitChanges().
• Pack Folder — Renumber the messages in this folder so they start with 1 and increment by 1. The corresponding action is XmhPackFolder().
• Sort Folder — Sort the messages in this folder in chronological order. (As a side effect, this may also pack the folder.) The corresponding action is XmhSortFolder().
• Rescan Folder — Rebuild the list of messages. This can be used whenever you suspect that xmh's idea of what messages you have is wrong. (In particular, this is necessary if you change things using straight MH commands without using xmh.) The corresponding action is XmhForceRescan().

---

💌 MESSAGE COMMANDS 💌

The Message command menu contains commands which operate on the selected message(s), or if there are no selected messages, the current message. 🫶

• Compose Message — Composes a new message. A new window will be brought up for composition; a description of it is given in the COMPOSITION WINDOWS section below. This command does not affect the current message. The corresponding action is XmhComposeMessage().
• View Next Message — View the first selected message. If no messages are highlighted, view the current message. If current message is already being viewed, view the first unmarked message after the current message. The corresponding action is XmhViewNextMessage().
• View Previous — View the last selected message. If no messages are highlighted, view the current message. If current message is already being viewed, view the first unmarked message before the current message. The corresponding action is XmhViewPrevious().
• Delete — Mark the selected messages for deletion. If no messages are highlighted, mark the current message for deletion and automatically display the next unmarked message. The corresponding action is XmhMarkDelete().
• Move — Mark the selected messages to be moved into the currently selected folder. (If the selected folder is the same as the viewed folder, this command will just beep.) If no messages are highlighted, mark the current message to be moved and display the next unmarked message. The corresponding action is XmhMarkMove().
• Copy as Link — Mark the selected messages to be copied into the selected folder. (If the selected folder is the same as the viewed folder, this command will just beep.) If no messages are highlighted, mark the current message to be copied. Note that messages are actually linked, not copied; editing a message copied by xmh will affect all copies of the message. The corresponding action is XmhMarkCopy().
• Unmark — Remove any of the above three marks from the selected messages, or the current message, if none are highlighted. The corresponding action is XmhUnmark().
• View in New — Create a new window containing only a view of the first selected message, or the current message, if none are highlighted. The corresponding action is XmhViewInNewWindow().
• Reply — Create a composition window in reply to the first selected message, or the current message, if none are highlighted. The corresponding action is XmhReply().
• Forward — Create a composition window whose body is initialized to contain an encapsulation of the selected messages, or the current message if none are highlighted. The corresponding action is XmhForward().
• Use as Composition — Create a composition window whose body is initialized to be the contents of the first selected message, or the current message if none are selected. Any changes you make in the composition will be saved in a new message in the drafts folder, and will not change the original message. However, there is an exception to this rule. If the message to be used as composition was selected from the drafts folder, (see BUGS), the changes will be reflected in the original message (see COMPOSITION WINDOWS). The action procedure corresponding to this command is XmhUseAsComposition().
• Print — Print the selected messages, or the current message if none are selected. xmh normally prints by invoking the enscript(1) command, but this can be customized with the xmh application-specific resource PrintCommand. The corresponding action is XmhPrint().

---

🌈 SEQUENCE COMMANDS 🌈

The Sequence command menu contains commands pertaining to message sequences (See MESSAGE-SEQUENCES), and a list of the message-sequences defined for the currently viewed folder. The selected message-sequence is indicated by a check mark in its entry in the margin of the menu. To change the selected message-sequence, select a new message-sequence from the sequence menu. ✨

• Pick Messages — Define a new message-sequence. The corresponding action is XmhPickMessages().

The following menu entries will be sensitive only if the current folder has any message-sequences other than the all message-sequence.

• Open Sequence — Change the viewed sequence to be the same as the selected sequence. The corresponding action is XmhOpenSequence().
• Add to Sequence — Add the selected messages to the selected sequence. The corresponding action is XmhAddToSequence().
• Remove from Sequence — Remove the selected messages from the selected sequence. The corresponding action is XmhRemoveFromSequence().
• Delete Sequence — Remove the selected sequence entirely. The messages themselves are not affected; they simply are no longer grouped together to define a message-sequence. The corresponding action is XmhDeleteSequence().

---

👀 VIEW COMMANDS 👀

Commands in the View menu and in the buttonboxes of view windows (which result from the Message menu command View In New) correspond in functionality to commands of the same name in the Message menu, but they operate on the viewed message rather than the selected messages or current message. 🦋

• Close Window — When the viewed message is in a separate view window, this command will close the view, after confirming the status of any unsaved edits. The corresponding action procedure is XmhCloseView().
• Reply — Create a composition window in reply to the viewed message. The related action procedure is XmhViewReply().
• Forward — Create a composition window whose body is initialized to contain an encapsulation of the viewed message. The corresponding action is XmhViewForward().
• Use As Composition — Create a composition window whose body is initialized to be the contents of the viewed message. Any changes made in the composition window will be saved in a new message in the drafts folder, and will not change the original message. An exception: if the viewed message was selected from the drafts folder, (see BUGS) the original message is edited. The action procedure corresponding to this command is XmhViewUseAsComposition().
• Edit Message — This command enables the direct editing of the viewed message. The action procedure is XmhEditView().
• Save Message — This command is insensitive until the message has been edited; when activated, edits will be saved to the original message in the view. The corresponding action is XmhSaveView().
• Print — prints whatever message you're currently viewing 💖. Under the hood xmh does it by invoking the enscript(1) command, but you can swap that out with the application-specific resource PrintCommand ✨. The matching action procedure is XmhPrintView().
• Delete — marks the message you're viewing for deletion 🗑️. The matching action procedure is XmhViewMarkDelete().

💅 OPTIONS 💅

The Options menu is, like, extremely low-maintenance — it has exactly one entry. One. That's it. Iconic minimalism honestly.

• Read in Reverse — when you select this, a check mark shows up in the margin of the menu entry 🎀. What it does: Read in Reverse flips the meaning of next and previous messages, and it'll increment to the current message marker in the opposite direction 🔄. Super useful if you like reading your mail most-recent-first, which, same tbh. It's a toggle, so pick it a second time from the menu to undo the whole thing 🙈. And yeah — the check mark appears when the option is selected. That's the whole vibe check.

🦋 COMPOSITION WINDOWS 🦋

Composition windows are the little pop-ups where you actually write your mail ✍️. You get one by choosing Compose Message from the Message command menu, or by choosing Reply or Forward or Use as Composition from the Message or View command menu 💌.

On top of all the normal text editing stuff, there are six command buttons hanging out in a composition window:

• Close Window — closes this composition window 🚪. Heads up though: if you've made changes since the most recent Save or Send, you'll get asked to confirm losing them 😭. The corresponding action is XmhCloseView().
• Send — sends this composition, go go go 🔥. The corresponding action is XmhSend().
• New Headers — replaces the current composition with an empty message ✨. Same warning as before: if changes have been made since the most recent Send or Save, you'll be asked to confirm losing them. The corresponding action is XmhResetCompose().
• Compose Message — brings up another brand new composition window, because you contain multitudes 🧚. The corresponding action is XmhComposeMessage().
• Save Message — saves this composition into your drafts folder 💾. Then you can safely close the composition, no stress. Later, at some future date of your choosing, you can keep working on it by opening the drafts folder, selecting the message, and using the ``Use as Composition'' command 👑. The corresponding action is XmhSave().
• Insert — inserts a related message into the composition 🫶. Here's the rule: if the composition window was created with a ``Reply'' command, the related message is the message being replied to. Otherwise, no related message is defined and this button is insensitive 🚫. The message may get filtered before it's inserted — see ReplyInsertFilter under APPLICATION RESOURCES for the deets. The corresponding action is XmhInsert().

⚡ ACCELERATORS ⚡

Accelerators are shortcuts, bestie — they let you fire off commands without digging through the menus, either from the keyboard or with the pointer 🖱️.

xmh defines pointer accelerators for the common actions: to select and view a message with a single click, use pointer button 2 on that message's entry in the table of contents 👆. To select and open a folder or a sequence in a single action, make the folder or sequence selection with pointer button 2.

To mark the highlighted messages — or the current message if none have been highlighted — to be moved to a folder in a single action, use pointer button 3 to select the target folder and simultaneously mark the messages 🔥. Similarly, selecting a sequence with pointer button 3 will add the highlighted or current message(s) to that sequence. In both of these operations, the selected folder or sequence and the viewed folder or sequence are not changed — nobody gets moved around behind your back, ok? 💅

xmh defines the following keyboard accelerators over the surface of the main window, except in the view area while editing a message:

Meta-I       Incorporate New Mail
Meta-C       Commit Changes
Meta-R       Rescan Folder
Meta-P       Pack Folder
Meta-S       Sort Folder

Meta-space   View Next Message
Meta-c       Mark Copy
Meta-d       Mark Deleted
Meta-f       Forward the selected or current message
Meta-m       Mark Move
Meta-n       View Next Message
Meta-p       View Previous Message
Meta-r       Reply to the selected or current message
Meta-u       Unmark

Ctrl-V       Scroll the table of contents forward
Meta-V       Scroll the table of contents backward
Ctrl-v       Scroll the view forward
Meta-v       Scroll the view backward

🌸 TEXT EDITING COMMANDS 🌸

Okay so plot twist: all of the text editing commands are actually defined by the Text widget in the Athena Widget Set 🎀. That means the commands can be bound to different keys than the defaults listed below, using the X Toolkit Intrinsics key re-binding mechanisms. Check the X Toolkit Intrinsics and the Athena Widget Set documentation for more on that, iykyk 📚.

Whenever you're asked to enter any text, you're working with a standard text editing interface ✍️. Various control and meta keystroke combos are bound to a somewhat Emacs-like set of commands. On top of that, the pointer buttons can select a chunk of text or move the insertion point around.

Pressing pointer button 1 moves the insertion point to wherever the pointer is 👆. Double-clicking button 1 selects a word, triple-clicking selects a line, quadruple-clicking selects a paragraph, and clicking rapidly five times selects everything 💀. Any selection can be extended in either direction using pointer button 3.

Real quick, definitions 🫶: a line means one displayed row of characters in the window. A paragraph means the text between carriage returns. Text within a paragraph gets broken into lines for display based on the current width of the window. When a message is actually sent, text is broken into lines based on the values of the SendBreakWidth and SendWidth application-specific resources ✨.

The following keystroke combinations are defined:

Ctrl-a                 Beginning Of Line
Ctrl-b                 Backward Character
Ctrl-d                 Delete Next Character
Ctrl-e                 End Of Line
Ctrl-f                 Forward Character
Ctrl-g                 Multiply Reset
Ctrl-h                 Delete Previous Character
Ctrl-j                 Newline And Indent
Ctrl-k                 Kill To End Of Line
Ctrl-l                 Redraw Display
Ctrl-m                 Newline
Ctrl-n                 Next Line
Ctrl-o                 Newline And Backup
Ctrl-p                 Previous Line
Ctrl-r                 Search/Replace Backward
Ctrl-s                 Search/Replace Forward
Ctrl-t                 Transpose Characters
Ctrl-u                 Multiply by 4
Ctrl-v                 Next Page
Ctrl-w                 Kill Selection
Ctrl-y                 Unkill
Ctrl-z                 Scroll One Line Up
Meta-b                 Backward Word
Meta-f                 Forward Word
Meta-i                 Insert File
Meta-k                 Kill To End Of Paragraph
Meta-q                 Form Paragraph
Meta-v                 Previous Page
Meta-y                 Insert Current Selection
Meta-z                 Scroll One Line Down
Meta-d                 Delete Next Word
Meta-D                 Kill Word
Meta-h                 Delete Previous Word
Meta-H                 Backward Kill Word
Meta-<                 Beginning Of File
Meta->                 End Of File
Meta-]                 Forward Paragraph
Meta-[                 Backward Paragraph
Meta-Delete            Delete Previous Word
Meta-Shift Delete      Kill Previous Word
Meta-Backspace         Delete Previous Word
Meta-Shift Backspace   Kill Previous Word

And on top of that, the pointer can copy and paste text too 💖:

Button 1 Down     Start Selection
Button 1 Motion   Adjust Selection
Button 1 Up       End Selection (copy)
Button 2 Down     Insert Current Selection (paste)
Button 3 Down     Extend Current Selection
Button 3 Motion   Adjust Selection
Button 3 Up       End Selection (copy)

🎀 CONFIRMATION DIALOG BOXES 🎀

Any time you press a button that might make you lose work — or is otherwise dangerous 😬 — a popup dialog box appears asking you to confirm the action. This window has an Abort'' or No'' button and a Confirm'' or Yes'' button. Pressing the No'' button cancels the operation; pressing Yes'' goes ahead with it. Choose wisely bestie 🫶.

When xmh is run under a Release 6 session manager, it'll prompt you for confirmation during a checkpoint operation 🔔. The dialog box asks whether any current changes should be committed (saved) during the checkpoint. Responding Yes'' has the same effect as pressing the Commit Changes'' or Save Message'' buttons in the respective folder and view windows ✨. Responding No'' causes the checkpoint to continue successfully to completion without actually saving any pending changes. And if the session manager disallows user interaction during the checkpoint, a ``Yes'' response is just assumed — meaning all changes will be committed during the checkpoint 💀.

Some dialog boxes contain messages from MH. Occasionally, when the message is more than one line long, not all of the text will be visible 😭. Clicking on the message field makes the dialog box resize so you can read the entire message. Slay. Problem solved 💅.

✨ MESSAGE-SEQUENCES ✨

okay so a message sequence is literally just a named set of messages, bestie. They're local to a folder, which means two different folders can absolutely have sequences with the same name — no cap, that's fine. The sequence named all is predefined in every single folder, and it's just every message in that folder. You can have as many as nine sequences per folder, and yes, that count includes the predefined all sequence. The sequence cur is also usually defined for every folder, and it holds only the current message. But xmh hides cur from you — instead it puts a literal + next to the current message. Also, xmh does not support MH's unseen sequence, so that one is hidden from the user too. 🙈

The message sequences for a folder — including the one for all — show up in the Sequence menu, below the sequence commands. The table of contents (aka the toc) is displaying exactly one message sequence at any one time. That one is called the viewed sequence, and its name shows up in the toc title bar after the folder name. Also, at any moment, one of the sequences in the menu will have a check mark next to it. That's the selected sequence. And plot twist: the viewed sequence and the selected sequence are not necessarily the same. (This all pretty much corresponds to the way folders work.)

The Open Sequence, Add to Sequence, Remove from Sequence, and Delete Sequence commands are active only if the viewed folder contains message-sequences other than the all sequence. None of this actually affects whether a message is in the folder, okay? Remember: a sequence is a set of messages within the folder, and those operations just change what messages are in that set. 🫶

To create a new sequence, select the Pick menu entry. A new window pops up with lots of places to enter text. Basically, you can describe the sequence's initial set of messages based on characteristics of the message. So yeah, you can define a sequence to be all the messages that were from a particular person, or with a particular subject, and so on. You can also connect things up with boolean operators, so you can select all things from weissman with a subject containing xmh. iconic.

The layout should be fairly obvious. The simplest cases are the easiest: just point to the proper field and type. If you enter in more than one field, it will only select messages which match all non-empty fields. 💅

The more complicated cases arise when you want things that match one field or another one, but not necessarily both. That's what all the or buttons are for. If you want all things with subjects that include xmh or xterm, just press the or button next to the Subject: field. Another box will appear where you can enter another subject. ✨

If you want all things either from weissman or with subject xmh, but not necessarily both, select the -Or- button. This will essentially double the size of the form. You can then enter weissman in a from: box on the top half, and xmh in a subject: box on the lower part.

If you select the Skip button, then only those messages that don't match the fields on that row are included.

Finally, in the bottom part of the window will appear several more boxes. One is the name of the sequence you're defining. (It defaults to the name of the selected sequence when Pick was pressed, or to temp if all was the selected sequence.) Another box defines which sequence to look through for potential members of this sequence; it defaults to the viewed sequence when Pick was pressed.

Two more boxes define a date range; only messages within that date range will be considered. These dates must be entered in RFC 822-style format: each date is of the form dd mmm yy hh:mm:ss zzz, where dd is a one or two digit day of the month, mmm is the three-letter abbreviation for a month, and yy is a year. The remaining fields are optional: hh, mm, and ss specify a time of day, and zzz selects a time zone. Note that if the time is left out, it defaults to midnight; thus if you select a range of 7 nov 86 - 8 nov 86, you will only get messages from the 7th, as all messages on the 8th will have arrived after midnight. 😭 time zones really said "not today."

Date field specifies which field in the header to look at for this date range; it defaults to Date. If the sequence you're defining already exists, you can optionally merge the old set with the new; that's what the Yes and No buttons are all about. Finally, you can OK the whole thing, or Cancel it. 🎀

In general, most people will rarely use these features. However, it's nice to occasionally use Pick to find some messages, look through them, and then hit Delete Sequence to put things back in their original state. lowkey therapeutic, ngl. 💖

🦋 WIDGET HIERARCHY 🦋

okay so bestie, if you're trying to specify resources, you lowkey need to know how xmh's widgets stack up. In the notation below, indentation = hierarchy. The widget class name comes first, then the widget instance name. The application class name is Xmh.

The hierarchy of the main toc and view window is exactly the same for extra toc and view windows, except a TopLevelShell widget gets inserted between the application shell and the Paned widget.

Xmh xmh
        Paned xmh
                SimpleMenu  folderMenu
                        SmeBSB  open
                        SmeBSB  openInNew
                        SmeBSB  create
                        SmeBSB  delete
                        SmeLine  line
                        SmeBSB  close
                SimpleMenu  tocMenu
                        SmeBSB  inc
                        SmeBSB  commit
                        SmeBSB  pack
                        SmeBSB  sort
                        SmeBSB  rescan
                SimpleMenu  messageMenu
                        SmeBSB  compose
                        SmeBSB  next
                        SmeBSB  prev
                        SmeBSB  delete
                        SmeBSB  move
                        SmeBSB  copy
                        SmeBSB  unmark
                        SmeBSB  viewNew
                        SmeBSB  reply
                        SmeBSB  forward
                        SmeBSB  useAsComp
                        SmeBSB  print
                SimpleMenu  sequenceMenu
                        SmeBSB  pick
                        SmeBSB  openSeq
                        SmeBSB  addToSeq
                        SmeBSB  removeFromSeq
                        SmeBSB  deleteSeq
                        SmeLine  line
                        SmeBSB  all
                SimpleMenu  viewMenu
                        SmeBSB  reply
                        SmeBSB  forward
                        SmeBSB  useAsComp
                        SmeBSB  edit
                        SmeBSB  save
                        SmeBSB  print
                SimpleMenu  optionMenu
                        SmeBSB  reverse
                Viewport.Core  menuBox.clip
                        Box  menuBox
                                MenuButton  folderButton
                                MenuButton  tocButton
                                MenuButton  messageButton
                                MenuButton  sequenceButton
                                MenuButton  viewButton
                                MenuButton  optionButton
                Grip  grip
                Label folderTitlebar
                Grip  grip
                Viewport.Core  folders.clip
                        Box  folders
                                MenuButton  inbox
                                MenuButton  drafts
                                        SimpleMenu  menu
                                                SmeBSB <folder_name>
                                                        .
                                                        .
                                                        .

                Grip  grip
                Label  tocTitlebar
                Grip  grip
                Text toc
                        Scrollbar  vScrollbar
                Grip  grip
                Label  viewTitlebar
                Grip  grip
                Text  view
                        Scrollbar  vScrollbar
                        Scrollbar  hScrollbar

The hierarchy of the Create Folder popup dialog box:

        TransientShell  prompt
                Dialog  dialog
                        Label  label
                        Text  value
                        Command  okay
                        Command  cancel

The hierarchy of the Notice dialog box, which reports messages from MH:

        TransientShell  notice
                Dialog  dialog
                        Label  label
                        Text  value
                        Command  confirm

The hierarchy of the Confirmation dialog box:

        TransientShell  confirm
                Dialog  dialog
                        Label  label
                        Command  yes
                        Command  no

The hierarchy of the dialog box which reports errors:

        TransientShell  error
                Dialog  dialog
                        Label  label
                        Command  OK

The hierarchy of the composition window:

        TopLevelShell  xmh
                Paned  xmh
                        Label  composeTitlebar
                        Text  comp
                        Viewport.Core  compButtons.clip
                                Box  compButtons
                                        Command  close
                                        Command  send
                                        Command  reset
                                        Command  compose
                                        Command  save
                                        Command  insert

The hierarchy of the view window:

        TopLevelShell  xmh
                Paned  xmh
                        Label  viewTitlebar
                        Text  view
                        Viewport.Core  viewButtons.clip
                                Box  viewButtons
                                        Command  close
                                        Command  reply
                                        Command  forward
                                        Command  useAsComp
                                        Command  edit
                                        Command  save
                                        Command  print
                                        Command  delete

The hierarchy of the pick window: (Unnamed widgets have no name.)

        TopLevelShell  xmh
                Paned  xmh
                        Label  pickTitlebar
                        Viewport.Core  pick.clip
                                Form  form
                                        Form  groupform

The first 6 rows of the pick window have identical structure:

                                                Form  rowform
                                                        Toggle
                                                        Toggle
                                                        Label
                                                        Text
                                                        Command

                                                Form  rowform
                                                        Toggle
                                                        Toggle
                                                        Text
                                                        Text
                                                        Command
                                                Form  rowform
                                                        Command

                        Viewport.core  pick.clip
                                Form  form
                                        From  groupform
                                                Form  rowform
                                                        Label
                                                        Text
                                                        Label
                                                        Text
                                                Form  rowform
                                                        Label
                                                        Text
                                                        Label
                                                        Text
                                                        Label
                                                        Text
                                                Form  rowform
                                                        Label
                                                        Toggle
                                                        Toggle
                                                Form  rowform
                                                        Command
                                                        Command

---

💅 APPLICATION-SPECIFIC RESOURCES 💅

The application class name is Xmh. Application-specific resources are listed below by name. Application-specific resource class names always start with an upper case character, but unless noted, they're otherwise identical to the instance names given below.

Any of these options can also be specified on the command line by using the X Toolkit Intrinsics resource specification mechanism. So, to run xmh showing all message headers:

% xmh -xrm '*HideBoringHeaders:off'

If TocGeometry, ViewGeometry, CompGeometry, or PickGeometry are not specified, then the value of Geometry is used instead. If the resulting height is not specified (e.g., "", "=500", "+0-0"), then the default height of windows is calculated from fonts and line counts. If the width is not specified (e.g., "", "=x300", "-0+0"), then half of the display width is used. If unspecified, the height of a pick window defaults to half the height of the display.

The following resources are defined:

• banner — a short string that's the default label of the folder, Table of Contents, and view. The default shows the program name, vendor, and release.
• blockEventsOnBusy — whether to disallow user input and show a busy cursor while xmh is busy processing a command. If false, the user can mouse ahead and type ahead; if true, user input is discarded when processing lengthy mh commands. The default is true.
• busyCursor — the name of the symbol used to represent the position of the pointer, displayed if blockEventsOnBusy is true, when xmh is processing a time-consuming command. The default is "watch".
• busyPointerColor — the foreground color of the busy cursor. Default is XtDefaultForeground.
• checkFrequency — how often (in minutes) to check for new mail, make checkpoints, and rescan the Table of Contents. If checkNewMail is true, xmh peeks for new mail every interval. If makeCheckpoints is true, checkpoints happen every fifth interval. Also every fifth interval, the Table of Contents gets checked against the file system and rescanned if it's out of date. Want none of that? Set CheckFrequency to 0. Default is 1. This resource is kept around for backward compatibility with user resource files — see also checkpointInterval, mailInterval, and rescanInterval. 💅
• checkNewMail — if true, xmh checks at regular intervals whether new mail has arrived for any of the top level folders and any opened subfolders. You get a visual indication when new mail is waiting to be incorporated into a top level folder. Default is true. Adjust the interval with mailInterval. ✨
• checkpointInterval (class Interval) — tells xmh how often, in minutes, to make checkpoints of volatile state, assuming makeCheckpoints is true. Default is 5 times the value of checkFrequency.
• checkpointNameFormat — how checkpointed files get named. xmh takes this resource's value and composes a file name by inserting the message number as a string in place of the required single occurrence of %d. If the value is the empty string, or there's no %d in it, or if "%d" is the value, the default gets used instead. Default is "%d.CKP". Checkpointing happens in the folder of origin unless you give an absolute pathname. Heads up: xmh does not help you recover checkpoints, and it doesn't provide for removal of the checkpoint files either. 🫶
• commandButtonCount — the number of command buttons to create in a button box between the toc and the view areas of the main window. xmh creates these with the names button1, button2, and so on, in a box named commandBox. Default is 0. You can specify labels and actions for the buttons in a private resource file; see the section ACTIONS AND INTERFACE CUSTOMIZATION.
• compGeometry — initial geometry for windows containing compositions.
• cursor — the name of the symbol used to represent the pointer. Default is left_ptr. 🖱️
• debug — whether or not to print information to stderr as xmh runs. Default is false.
• draftsFolder — the folder used for message drafts. Default is drafts.
• geometry — default geometry to use. Default is none.
• hideBoringHeaders — if on, xmh attempts to skip uninteresting header lines within messages by scrolling them off the top of the view. Default is on. 🙈
• initialFolder — which folder to display on startup. May also be set with the command-line option -initial. Default is inbox.
• initialIncFile — the absolute path name of your incoming mail drop file. In some installations (for example, ones using the Post Office Protocol) no file is appropriate. In that case initialIncFile should not be specified, or may be specified as the empty string, and inc will be invoked without a -file argument. By default this resource has no value. It's ignored if xmh finds an .xmhcheck file; see the section on multiple mail drops.
• mailInterval (class Interval) — the interval in minutes at which mail should be checked, if mailWaitingFlag or checkNewMail is true. Default is the value of checkFrequency. ⏰
• mailPath — the full path prefix for locating your mail folders. May also be set with the command line option -path. Default is the Path component in the MH profile, or $HOME/Mail if there isn't one.
• mailWaitingFlag — if true, xmh attempts to set an indication in its icon when new mail is waiting to be retrieved. And if mailWaitingFlag is true, then checkNewMail is assumed to be true as well. The -flag command line option is a quick way to turn this resource on. 🚩
• makeCheckpoints — if true, xmh attempts to save checkpoints of volatile edits. Default is false. The frequency of checkpointing is controlled by checkpointInterval. For where checkpointing goes, see checkpointNameFormat.
• mhPath — what directory to find the MH commands in. If a command isn't found in your path, the path specified here is used. Default is /usr/local/mh6.
• newMailBitmap (class NewMailBitmap) — the bitmap to show in the folder button when a folder has new mail. Default is black6.
• newMailIconBitmap (class NewMailBitmap) — the bitmap suggested to the window manager for the icon when any folder has new mail. Default is flagup.
• noMailBitmap (class NoMailBitmap) — the bitmap to show in the folder button when a folder has no new mail. Default is box6.
• noMailIconBitmap (class NoMailBitmap) — the bitmap suggested to the window manager for the icon when no folders have new mail. Default is flagdown. 🌈
• pickGeometry — initial geometry for pick windows.
• pointerColor — the foreground color of the pointer. Default is XtDefaultForeground.
• prefixWmAndIconName — whether to prefix the window and icon name with "xmh: ". Default is true.
• printCommand — an sh command to execute to print a message. Important: stdout and stderr must be specifically redirected. If a message or range of messages is selected for printing, the full file paths of each message file are appended to the specified print command. Default is enscript >/dev/null 2>/dev/null. 🖨️
• replyInsertFilter — an sh command to be executed when the Insert button is activated in a composition window. The full path and filename of the source message is appended to the command before being passed to sh(1). The default filter is cat, meaning it inserts the entire message into the composition. Interesting filters include: sed 's/^/> /' or awk -e '{print " " $0}' or <mh directory>/lib/mhl -form mhl.body.
• rescanInterval (class Interval) — how often to check the Table of Contents of currently viewed folders and of folders with messages currently being viewed, and to update the Table of Contents if xmh sees inconsistencies with the file system in these folders. Default is 5 times the value of checkFrequency.
• reverseReadOrder — when true, the next message will be the message prior to the current message in the table of contents, and the previous message will be the message after the current message in the table of contents. Default is false. 🔄
• sendBreakWidth — when a message is sent from xmh, lines longer than this value will be split into multiple lines, each of which is no longer than SendWidth. This value may be overridden for a single message by inserting an additional line in the message header of the form SendBreakWidth: value. That line will be removed from the header before the message is sent. Default is 2000 (to allow for sending mail containing source patches). 🧚
• sendWidth — when a message is sent from xmh, lines longer than SendBreakWidth characters will be split into multiple lines, each of which is no longer than this value. This value may be overridden for a single message by inserting an additional line in the message header of the form SendWidth: value. This line will be removed from the header before the message is sent. Default is 72.
• showOnInc — whether to automatically show the current message after incorporating new mail. Default is true.
• skipCopied — whether to skip over messages marked for copying when using "View Next Message" and "View Previous Message". Default is true.
• skipDeleted — whether to skip over messages marked for deletion when using "View Next Message" and "View Previous Message". Default is true.
• skipMoved — whether to skip over messages marked for moving to other folders when using "View Next Message" and "View Previous Message". Default is true. 💀
• stickyMenu — if true, when popup command menus are used, the most recently selected entry will be under the cursor when the menu pops up. Default is false. See the file clients/xmh/Xmh.sample for an example of how to specify resources for popup command menus.
• tempDir — directory for xmh to store temporary files. For privacy, a user might want to change this to a private directory. Default is /tmp. 🔒
• tocGeometry — initial geometry for main xmh toc and view windows.
• tocPercentage — the percentage of the main window that is used to display the Table of Contents. Default is 33.
• tocWidth — how many characters to generate for each message in a folder's table of contents. Default is 100. Use less if the geometry of the main xmh window results in the listing being clipped at the right hand boundary, or if you plan to use mhl a lot — because it will be faster, and the extra characters may not be useful. ⭐
• viewGeometry — initial geometry for windows showing a view of a message.

💌 MULTIPLE MAIL DROPS 💌

Okay bestie, so sometimes you need mail from more than one spool file or mail drop. If incoming mail gets forwarded to the MH slocal program, it can be sorted the way you specify into multiple incoming mail drops. Go read the MH man page for slocal to learn how to set up forwarding and automatic sorting of incoming mail in a .maildelivery file. iykyk 🦋

To tell xmh about all those mail drops, make a file in your home directory called .xmhcheck. In this file you create a mapping between existing folder names and mail drops: folder name first, then the absolute pathname of the mail drop site, with some white space separating them, one mapping per line. xmh reads this file whether or not resources are set for notification of new mail arrival, and it will let you incorporate new mail into any folder that has a mail drop. xmh invokes inc with the -file argument, and if xmh has been asked to check for new mail, it checks directly instead of using msgchk. no cap 💅

Example .xmhcheck format for the folders inbox'' and xpert'' — literally this:

inbox     /usr/spool/mail/converse
xpert     /users/converse/maildrops/xpert

---

🎀 ACTIONS AND INTERFACE CUSTOMIZATION 🎀

Because xmh gives you action procedures that correspond to command functionality and installs accelerators, you can customize accelerators and new button functionality in a private resource file. For examples of specifying customized resources, see the file mit/clients/xmh/Xmh.sample. To understand the syntax, see the Appendix of the X Toolkit Intrinsics specification on Translation Table Syntax, and any general explanation of using and specifying X resources.

🚨 Careful, queen: unpredictable results can occur if actions are bound to events or widgets for which they were not designed. Don’t just bind random stuff and act surprised, bestie.

Here’s an example of how to bind actions to your own xmh buttons, and how to redefine the default accelerators so the Meta key is not required, in case you don’t have access to the sample file mentioned above. iconic behavior fr fr 💖

! To create buttons in the middle of the main window and give them semantics:

Xmh*CommandButtonCount:         5

Xmh*commandBox.button1.label:   Inc
Xmh*commandBox.button1.translations: #override\
        <Btn1Down>,<Btn1Up>: XmhIncorporateNewMail() unset()

Xmh*commandBox.button2.label:   Compose
Xmh*commandBox.button2.translations: #override\
        <Btn1Down>,<Btn1Up>: XmhComposeMessage() unset()

Xmh*commandBox.button3.label:   Next
Xmh*commandBox.button3.translations: #override\
        <Btn1Down>,<Btn1Up>: XmhViewNextMessage() unset()

Xmh*commandBox.button4.label:   Delete
Xmh*commandBox.button4.translations: #override\
        <Btn1Down>,<Btn1Up>: XmhMarkDelete() unset()

Xmh*commandBox.button5.label:   Commit
Xmh*commandBox.button5.translations: #override\
        <Btn1Down>,<Btn1Up>: XmhCommitChanges() unset()

! To redefine the accelerator bindings to exclude modifier keys,
! and add your own keyboard accelerator for Compose Message:

Xmh*tocMenu.accelerators: #override\n\
        !:<Key>I:       XmhIncorporateNewMail()\n\
        !:<Key>C:       XmhCommitChanges()\n\
        !:<Key>R:       XmhForceRescan()\n\
        !:<Key>P:       XmhPackFolder()\n\
        !:<Key>S:       XmhSortFolder()\n
Xmh*messageMenu.accelerators: #override\n\
        !:<Key>E:       XmhComposeMessage()\n\
        !<Key>space:    XmhViewNextMessage()\n\
        !:<Key>c:       XmhMarkCopy()\n\
        !:<Key>d:       XmhMarkDelete()\n\
        !:<Key>f:       XmhForward()\n\
        !:<Key>m:       XmhMarkMove()\n\
        !:<Key>n:       XmhViewNextMessage()\n\
        !:<Key>p:       XmhViewPreviousMessage()\n\
        !:<Key>r:       XmhReply()\n\
        !:<Key>u:       XmhUnmark()\n

xmh provides action procedures that correspond to entries in the command menus; those are given in the sections describing menu commands, not here. In addition to the actions corresponding to commands in the menus, these action routines are defined:

• XmhPushFolder([foldername, ...]) — This action pushes each of its argument(s) onto a stack of foldernames. If no arguments are given, the selected folder is pushed onto the stack. 💅
• XmhPopFolder() — This action pops one foldername from the stack and sets the selected folder.
• XmhPopupFolderMenu() — This action should always be taken when the user selects a folder button. A folder button represents a folder and zero or more subfolders. The menu of subfolders is built upon the first reference, by this routine. If there are no subfolders, this routine will mark the folder as having no subfolders, and no menu will be built. In that case the menu button emulates a toggle button. When subfolders exist, the menu will popup, using the menu button action PopupMenu(). 🦋
• XmhSetCurrentFolder() — This action allows menu buttons to emulate toggle buttons in the function of selecting a folder. This action is for menu button widgets only, and sets the selected folder.
• XmhLeaveFolderButton() — This action ensures that the menu button behaves properly when the user moves the pointer out of the menu button window.
• XmhPushSequence([sequencename, ...]) — This action pushes each of its arguments onto the stack of sequence names. If no arguments are given, the selected sequence is pushed onto the stack.
• XmhPopSequence() — This action pops one sequence name from the stack of sequence names, which then becomes the selected sequence.
• XmhPromptOkayAction() — This action is equivalent to pressing the okay button in the Create Folder popup.
• XmhReloadSeqLists() — This action rescans the contents of the public MH sequences for the currently opened folder and updates the sequence menu if necessary.
• XmhShellCommand( parameter [, parameter]) — At least one parameter must be specified. The parameters will be concatenated with a space character separator, into a single string, and the list of selected messages, or if no messages are selected, the current message, will be appended to the string of parameters. The string will be executed as a shell command. The messages are always given as absolute pathnames. It is an error to cause this action to execute when there are no selected messages and no current message. 😭
• XmhCheckForNewMail() — This action will check all mail drops known to xmh. If no mail drops have been specified by the user either through the .xmhcheck file or by the initialIncFile resource, the MH command msgchk is used to check for new mail, otherwise, xmh checks directly.
• XmhWMProtocols([wm_delete_window] [wm_save_yourself]) — This action is responsible for participation in window manager communication protocols. It responds to delete window and save yourself messages. The user can cause xmh to respond to one or both of these protocols, exactly as if the window manager had made the request, by invoking the action with the appropriate parameters. The action is insensitive to the case of the string parameters. If the event received is a ClientMessage event and parameters are present, at least one of the parameters must correspond to the protocol requested by the event for the request to be honored by xmh. 💀

---

🌸 CUSTOMIZATION USING MH 🌸

The initial text displayed in a composition window is generated by executing the corresponding MH command; i.e. comp, repl, or forw, and therefore message components may be customized as specified for those commands. comp is executed only once per invocation of xmh and the message template is re-used for every successive new composition. main character energy tbh ✨

xmh uses MH commands, including inc, msgchk, comp, send, repl, forw, refile, rmm, pick, pack, sort, and scan. Some flags for these commands can be specified in the MH profile; xmh may override them. The application resource debug can be set to true to see how xmh uses MH commands. obsessive? maybe. useful? yes bestie 🫶

---

🌈 ENVIRONMENT 🌈

• HOME — users's home directory
• MH — to get the location of the MH profile file

---

🎀 FILES 🎀

• ~/.mh_profile — MH profile, used if the MH environment variable is not set
• ~/Mail — directory of folders, used if the MH profile cannot be found
• ~/.xmhcheck — optional, for multiple mail drops in cooperation with slocal.
• /usr/local/mh6 — MH commands, as a last resort, see mhPath.
• ~/Mail/<folder>/.xmhcache — scan output in each folder
• ~/Mail/<folder>/.mh_sequences — sequence definitions, in each folder
• /tmp — temporary files, see tempDir.

---

🦋 SEE ALSO 🦋

• X(7)
• xrdb(1)
• X Toolkit Intrinsics
• Athena Widget Set
• mh(1)
• enscript(1)

At least one book has been published about MH and xmh. periodt 💅

---

💀 BUGS 💀

• When the user closes a window, all windows which are transient for that window should also be closed by xmh.
• When XmhUseAsComposition and XmhViewUseAsComposition operate on messages in the DraftsFolder, xmh disallows editing of the composition if the same message is also being viewed in another window.
• Occasionally after committing changes, the table of contents will appear to be completely blank when there are actually messages present. When this happens, refreshing the display, or typing Control-L in the table of contents, will often cause the correct listing to appear. If this doesn't work, force a rescan of the folder. 🙈
• Should recognize and use the ``unseen'' message-sequence.
• Should determine by itself if the user hasn't used MH before, and offer to create the .mh_profile, instead of hanging on inc.
• A few commands are missing (rename folder, resend message).
• WM_DELETE_WINDOW protocol doesn't work right when requesting deletion of the first toc and view, while trying to keep other xmh windows around.
• Doesn't support annotations when replying to messages.
• Doesn't allow folders to be shared without write permission.
• Doesn't recognize private sequences.
• MH will report that the .mh_sequences file is poorly formatted if any sequence definition in a particular folder contains more than BUFSIZ characters. xmh tries to capture these messages and display them when they occur, but it cannot correct the problem.
• Should save a temporary checkpoint file rather than requiring changes to be committed in the non-shutdown case.

---

👑 AUTHOR 👑

• Terry Weissman, formerly of Digital Western Research Laboratory
• Donna Converse, MIT X Consortium

okay bestie, that’s the whole page — footer sign-off: X Version 11 · xmh 1.0.5 · XMH(1) — source/version + date slot, and we’re out 💖✨