source: trunk/third/xmh/xmh.man @ 9658

Revision 9658, 57.5 KB checked in by ghudson, 28 years ago (diff)
This commit was generated by cvs2svn to compensate for changes in r9657, which included commits to RCS files with non-trunk default branches.
RevLine 
[9657]1.\" $XConsortium: xmh.man,v 1.28 91/08/01 01:20:41 converse Exp $
2.TH XMH 1 "Release 5" "X Version 11"
3.SH NAME
4\fIxmh\fR \- send and read mail with an X interface to MH
5.SH SYNOPSIS
6.B xmh
7[\-path \fImailpath\fR] [\-initial \fIfoldername\fR] [\-flag] [\-\fItoolkitoption\fR ...]
8.SH DESCRIPTION
9The
10.I xmh
11program provides a graphical user interface to the \fIMH\fR Message
12Handling System.  To actually do things with your mail, it makes calls to the
13\fIMH\fR package.  Electronic mail messages may be composed, sent,
14received, replied to, forwarded, sorted, and stored in folders.  \fIxmh\fR
15provides extensive mechanism for customization of the user interface.
16.PP
17This document introduces many aspects of the Athena Widget Set.
18
19.SH OPTIONS
20.TP 8
21.B \-path \fIdirectory\fP
22This option specifies an alternate collection of mail folders in which to
23process mail.  The directory is specified as an absolute pathname.
24The default mail path is the value of the Path component in the \fIMH\fP
25profile, which is determined by the \fBMH\fP environment variable and
26defaults to $HOME/.mh_profile.  $HOME/Mail will be used as the path if
27the \fIMH\fP Path is not given in the profile.
28.TP 8
29.B \-initial \fIfolder\fP
30This option specifies an alternate folder which may receive new mail and is
31initially opened by \fIxmh\fR. 
32The default initial folder is ``inbox''.
33.TP 8
34.B \-flag
35This option will cause \fIxmh\fR to change the appearance of appropriate
36folder buttons and to request the window manager to change the appearance
37of the \fIxmh\fP icon when new mail has arrived.  By default,
38\fIxmh\fP will change the appearance of the ``inbox'' folder button when
39new mail is waiting.  The application-specific resource \fBcheckNewMail\fP
40can be used to turn off this notification, and the \fB\-flag\fP option will
41still override it.
42.PP
43These three options have corresponding application-specific resources,
44\fBMailPath\fR, \fBInitialFolder\fR, and \fBMailWaitingFlag\fR, which
45can be specified in a resource file.
46.PP
47The standard toolkit command line options are given in \fIX(1)\fP.
48
49.SH INSTALLATION
50.PP
51\fIxmh\fR requires that the user is already set up
52to use \fIMH\fR, version 6.  To do so, see if there is a file
53called .mh_profile in your home directory.  If it exists, check to see if it
54contains a line that starts with ``Current-Folder''.  If it does,
55you've been using version 4 or earlier of \fIMH\fR; to convert to version
566, you must remove that line.  (Failure to do so causes spurious output to
57stderr, which can hang \fIxmh\fR depending on your setup.)
58.PP
59If you do not already have a .mh_profile, you can create one (and
60everything else you need) by typing ``inc'' to the shell.  You should
61do this before using \fIxmh\fR to incorporate new mail.
62.PP
63For more information, refer to the \fImh(1)\fP documentation.
64.PP
65Much of the user interface of \fIxmh\fP is configured in the \fIXmh\fP
66application class defaults file; if this file was not installed properly
67a warning message will appear when \fIxmh\fP is used.  \fIxmh\fP is
68backwards compatible with the R4 application class defaults file.
69.PP
70The default value of the SendBreakWidth resource has changed since R4.
71
72.SH BASIC SCREEN LAYOUT
73\fIxmh\fR starts out with a single window, divided into four major areas:
74
75.TP 4
76.B \-
77Six buttons with pull-down command menus.
78.PP
79.TP 4
80.B \-
81A collection of buttons, one for each top level folder.
82New users of \fIMH\fP will have two folders, ``drafts'' and ``inbox''.
83.PP
84.TP 4
85.B \-
86A listing, or Table of Contents, of the messages in the open folder.
87Initially, this will show the messages in ``inbox''.
88.PP
89.TP 4
90.B \-
91A view of one of your messages.  Initially this is blank.
92
93.SH XMH AND THE ATHENA WIDGET SET
94\fIxmh\fR uses the X Toolkit Intrinsics and the Athena Widget Set.
95Many of the features described below (scrollbars, buttonboxes, etc.) are
96actually part of the Athena Widget Set, and are described here only for
97completeness.  For more information, see the Athena Widget Set documentation.
98
99.SS SCROLLBARS
100Some parts of the main window will have a vertical area on the left containing
101a grey bar.  This area is a \fIscrollbar\fR.  They are used whenever the
102data in a window takes up more space than can be displayed.
103The grey bar indicates what portion of your data is visible. Thus, if the
104entire length of the area is grey, then you are looking at all your data.
105If only the first half is grey, then you are looking at the top half of
106your data. 
107The message viewing area will have a horizontal scrollbar if the text
108of the message is wider than the viewing area.
109.PP
110You can use the pointer in the scrollbar to change what part of the data is
111visible.  If you click with pointer button 2, the top of the grey
112area will move to where the pointer is, and the corresponding
113portion of data will be displayed.  If you hold down pointer button 2,
114you can drag around the grey area.  This makes it easy to get to the top
115of the data: just press with button 2, drag off the top of the
116scrollbar, and release.
117.PP
118If you click with button 1, then the data to the right of the
119pointer will scroll to the top of the window.  If you click with pointer
120button 3, then the data at the top of the window will scroll down to where
121the pointer is.
122
123.SS BUTTONBOXES, BUTTONS, AND MENUS
124Any area containing many words or short phrases, each enclosed in a
125rectangular or rounded boundary, is called a \fIbuttonbox\fR. 
126Each rectangle or rounded area is actually a button that you
127can press by moving the pointer onto it and pressing pointer button 1.
128If a given buttonbox has more buttons in it than can fit, it will
129be displayed with a scrollbar, so you can always scroll to the button you
130want.
131.PP
132Some buttons have pull-down menus.
133Pressing the pointer button while the pointer is over one of these
134buttons will pull down a menu.  Continuing to hold the button down while
135moving the
136pointer over the menu, called dragging the pointer, will highlight each
137selectable item
138on the menu as the pointer passes over it.  To select an item in the menu,
139release the pointer button while the item is highlighted.
140
141.SS ADJUSTING THE RELATIVE SIZES OF AREAS
142If you're not satisfied with the sizes of the various areas of the main window,
143they can easily be changed.  Near the right edge of the border between
144each region is a black box, called a \fIgrip\fR.  Simply point to that
145grip with the pointer, press a pointer button, drag up or down, and
146release.  Exactly what happens depends on which pointer button you press.
147.PP
148If you drag with the pointer button 2, then only that border will move.  This
149mode is simplest to understand, but is the least useful.
150.PP
151If you drag with pointer button 1, then you are adjusting the size of
152the window above.  \fIxmh\fR will attempt to compensate by adjusting some
153window below it.
154.PP
155If you drag with pointer button 3, then you are adjusting the size
156of the window below.  \fIxmh\fR will attempt to compensate by adjusting
157some window above it.
158.PP
159All windows have a minimum and maximum size; you will never be allowed to
160move a border past the point where it would make a window have an invalid
161size.
162
163.SH PROCESSING YOUR MAIL
164This section will define the concepts of the selected folder, current folder,
165selected message(s), current message, selected sequence, and current
166sequence.  Each \fIxmh\fR command is introduced. 
167.PP
168For use in customization,
169action procedures corresponding to each command are given; these action
170procedures can be used to customize the user interface, particularly the
171keyboard accelerators and the functionality of the buttons in the optional
172button box created by the application resource \fBCommandButtonCount\fR.
173
174.SS FOLDERS AND SEQUENCES
175A folder contains a collection of mail messages, or is empty.  \fIxmh\fP
176supports folders with one level of subfolders.
177.PP
178The selected folder is whichever foldername appears in the bar above the
179folder buttons.  Note that this is not necessarily the same folder that is
180currently being viewed. 
181To change the selected folder, just press on the desired folder button
182with pointer button 1;
183if that folder has subfolders, select a folder from the pull-down menu.
184.PP
185The Table of Contents, or toc, lists the messages in the viewed folder.
186The title bar above the Table of Contents displays the name of the
187viewed folder.
188.PP
189The toc title bar also displays the name of the viewed sequence of messages
190within the viewed folder.
191Every folder has an implicit ``all'' sequence, which contains all the messages
192in the folder, and initially the toc title bar will show ``inbox:all''.
193
194.SS FOLDER COMMANDS
195The \fIFolder\fR command menu contains commands of a global nature:
196
197.TP 8
198.B Open Folder
199Display the data in the selected folder.  Thus, the selected folder also
200becomes the viewed folder. 
201The action procedure corresponding
202to this command is \fBXmhOpenFolder(\fR[\fIfoldername\fR]\fB)\fR.
203It takes an optional argument as the name of a folder to select and open; if no
204folder is specified, the selected folder is opened.  It may be specified
205as part of an event translation from a folder menu button or from a
206folder menu, or as a binding of a keyboard accelerator to any widget other
207than the folder menu buttons or the folder menus.
208.TP 8
209.B Open Folder in New Window
210Displays the selected folder in an additional main window.
211Note, however, that you cannot reliably display the same folder in more
212than one window at a time, although \fIxmh\fR will not prevent you from trying.
213The corresponding action is \fBXmhOpenFolderInNewWindow()\fR.
214.TP 8
215.B Create Folder
216Create a new folder.
217You will be prompted for a name for the new folder;
218to enter the name, move the pointer to the blank box provided and type.
219Subfolders are created by specifying the parent folder, a slash, and the
220subfolder name.  For example,
221to create a folder named ``xmh'' which is a subfolder of an existing folder
222named ``clients'', type ``clients/xmh''.
223Click on the Okay button when finished, or just type Return;
224click on Cancel to cancel this operation.
225The action corresponding to Create Folder is \fBXmhCreateFolder()\fR.
226.PP
227.TP 8
228.B Delete Folder
229Destroy the selected folder.  You will be asked to confirm this action (see
230CONFIRMATION WINDOWS).  Destroying a folder will also destroy any subfolders
231of that folder.  The corresponding action is \fBXmhDeleteFolder()\fP.
232.PP
233.TP 8
234.B Close Window
235Exits \fIxmh\fR, after first confirming that you won't lose any changes;
236or, if selected from any additional \fIxmh\fP window, simply closes that
237window.  The corresponding action is \fBXmhClose()\fP.
238
239.SS HIGHLIGHTED MESSAGES, SELECTED MESSAGES
240.SS AND THE CURRENT MESSAGE
241It is possible to highlight a set of adjacent messages in the area of the
242Table of Contents.
243To highlight a message, click on it with pointer button 1.
244To highlight a range of messages, click on the first one with
245pointer button 1 and on the last one with pointer button 3; or
246press pointer button 1, drag, and release.
247To extend a range of selected messages, use pointer button 3. 
248To highlight all messages in the table of contents,
249click rapidly three times with pointer button 1. 
250To cancel any selection in the table of contents, click rapidly twice.
251
252The selected messages are the same as the highlighted messages, if any.  If no
253messages are highlighted, then the selected messages are considered the same
254as the current message.
255
256The current message is indicated by a `+' next to the message number.  It
257usually corresponds to the message currently being viewed.  Upon opening
258a new folder, for example, the current message will be different from the
259viewed message.
260When a message is viewed, the title bar above the view will identify the message.
261
262.SS TABLE OF CONTENTS COMMANDS
263The \fITable of Contents\fP command menu
264contains commands which operate on the open, or viewed, folder.
265
266.TP 18
267.B Incorporate New Mail
268Add any new mail received to viewed folder, and set the current
269message to be the first new message.  This command is selectable in the menu
270and will execute only if the viewed folder is allowed to receive new mail.
271By default, only ``inbox'' is allowed to incorporate new mail.
272The corresponding action is \fBXmhIncorporateNewMail()\fP.
273.TP 18
274.B Commit Changes
275Execute all deletions, moves, and copies that have been marked in this
276folder.  The corresponding action is \fBXmhCommitChanges()\fP.
277.TP 18
278.B Pack Folder
279Renumber the messages in this folder so they start with 1 and increment by
2801.  The corresponding action is \fBXmhPackFolder()\fP.
281.TP 18
282.B Sort Folder
283Sort the messages in this folder in chronological order.  (As a side
284effect, this may also pack the folder.)  The corresponding action is
285\fBXmhSortFolder()\fP.
286.TP 18
287.B Rescan Folder
288Rebuild the list of messages.  This can be used whenever you suspect
289that \fIxmh\fR's
290idea of what messages you have is wrong.  (In particular, this is necessary
291if you change things using straight \fIMH\fR commands without using
292\fIxmh\fR.)  The corresponding action is \fBXmhForceRescan()\fP.
293
294.SS MESSAGE COMMANDS
295The \fIMessage\fR command menu contains commands which operate on the selected
296message(s), or if there are no selected messages, the current message.
297
298.TP 18
299.B Compose Message
300Composes a new message.  A new window will be brought up for composition;
301a description of it is given in the COMPOSITION WINDOWS section below.
302This command does not affect the current message.
303The corresponding action is \fBXmhComposeMessage()\fP.
304.PP
305.TP 18
306.B View Next Message
307View the first selected message.  If no messages are highlighted, view the
308current message.  If current message is already being viewed, view the
309first unmarked message after the current message.
310The corresponding action is \fBXmhViewNextMessage()\fP.
311.PP
312.TP 18
313.B View Previous
314View the last selected message.  If no messages are highlighted, view the
315current message.  If current message is already being viewed, view the
316first unmarked message before the current message.
317The corresponding action is \fBXmhViewPrevious()\fP.
318.PP
319.TP 18
320.B Delete
321Mark the selected messages for deletion.  If no messages are highlighted,
322mark the current message for deletion and automatically display the
323next unmarked message.
324The corresponding action is \fBXmhMarkDeleted()\fP.
325.PP
326.TP 18
327.B Move
328Mark the selected messages to be moved into the currently selected folder.
329(If the selected folder is the same as the viewed folder,
330this command will just beep.)  If no messages are highlighted,
331mark the current message to be moved and display the next unmarked message.
332The corresponding action is \fBXmhMarkMove()\fP.
333.PP
334.TP 18
335.B Copy as Link
336Mark the selected messages to be copied into the selected folder.  (If the
337selected folder is the same as the viewed folder, this command will just
338beep.)  If no messages are highlighted, mark the current message to be
339copied.  Note that messages are actually linked, not copied; editing
340a message copied by \fIxmh\fP will affect all copies of the message.
341The corresponding action is \fBXmhMarkCopy()\fP.
342.PP
343.TP 18
344.B Unmark
345Remove any of the above three marks from the selected messages, or the
346current message, if none are highlighted.
347The corresponding action is \fBXmhUnmark()\fP.
348.PP
349.TP 18
350.B View in New
351Create a new window containing only a view of the first selected message,
352or the current message, if none are highlighted.
353The corresponding action is \fBXmhViewInNewWindow()\fP.
354.PP
355.TP 18
356.B Reply
357Create a composition window in reply to the first selected message, or the
358current message, if none are highlighted.
359The corresponding action is \fBXmhReply()\fP.
360.PP
361.TP 18
362.B Forward
363Create a composition window whose body is initialized to contain an
364encapsulation of
365of the selected messages, or the current message if none are highlighted.
366The corresponding action is \fBXmhForward()\fP.
367.PP
368.TP 18
369.B Use as Composition
370Create a composition window whose body is initialized to be the contents
371of the first selected message, or the current message if none are selected.
372Any changes you make in the composition will be saved in a new
373message in the ``drafts'' folder, and will not change the original message.
374However, there is an exception to this rule.
375If the message to be used as composition was selected from the ``drafts''
376folder, (see BUGS), the changes will be reflected in the original message
377(see COMPOSITION WINDOWS).  The action procedure corresponding to this
378command is \fBXmhUseAsComposition()\fR.
379.PP
380.TP 18
381.B Print
382Print the selected messages, or the current message if none are selected.
383\fIxmh\fR normally prints by invoking
384the \fIenscript\fR(1) command, but this can be customized with the \fIxmh\fP
385application-specific resource \fBPrintCommand\fR.
386The corresponding action is \fBXmhPrint()\fR.
387
388.SS SEQUENCE COMMANDS
389The \fISequence\fR command menu contains commands pertaining to
390message sequences (See MESSAGE-SEQUENCES),
391and a list of the message-sequences defined for the currently viewed folder.
392The selected message-sequence is indicated by a check mark in its entry
393in the margin of the menu.  To change the selected message-sequence,
394select a new message-sequence from the sequence menu. 
395
396.TP 18
397.B Pick Messages
398Define a new message-sequence. 
399The corresponding action is \fBXmhPickMessages()\fP.
400.PP
401The following menu entries will be sensitive only if the current folder
402has any message-sequences other than the ``all'' message-sequence. 
403.TP 18
404.B Open Sequence
405Change the viewed sequence to be the same as the selected sequence.
406The corresponding action is \fBXmhOpenSequence()\fP.
407.PP
408.TP 18
409.B Add to Sequence
410Add the selected messages to the selected sequence.
411The corresponding action is \fBXmhAddToSequence()\fP.
412.PP
413.TP 18
414.B Remove from Sequence
415Remove the selected messages from the selected sequence.
416The corresponding action is \fBXmhRemoveFromSequence()\fP.
417.PP
418.TP 18
419.B Delete Sequence
420Remove the selected sequence entirely.  The messages themselves are
421not affected; they simply are no longer grouped together to define a
422message-sequence.  The corresponding action is \fBXmhDeleteSequence()\fP.
423
424.SS VIEW COMMANDS
425Commands in the \fIView\fP menu and in the buttonboxes of view windows
426(which result from the \fIMessage\fP menu command \fBView In New\fP)
427correspond in functionality to commands of the same
428name in the \fIMessage\fP menu, but they operate on the viewed message
429rather than the selected messages or current message.
430
431.TP 18
432.B Close Window
433When the viewed message is in a separate view window, this command will
434close the view, after confirming the status of any unsaved edits.
435The corresponding action procedure is \fBXmhCloseView()\fR.
436.TP 18
437.B Reply
438Create a composition window in reply to the viewed message.
439The related action procedure is \fBXmhViewReply()\fR.
440.TP 18
441.B Forward
442Create a composition window whose body is initialized contain an
443encapsulation of
444the viewed message.  The corresponding action is \fBXmhViewForward()\fR.
445.TP 18
446.B Use As Composition
447Create a composition window whose body is initialized to be the contents of
448the viewed message.  Any changes made in the composition window will be
449saved in a new message in the ``drafts'' folder, and will not change the
450original message.  An exception: if the viewed message was selected from
451the ``drafts'' folder, (see BUGS) the original message is edited.
452The action
453procedure corresponding to this command is \fBXmhViewUseAsComposition()\fR.
454.TP 18
455.B Edit Message
456This command enables the direct editing of the viewed message.
457The action procedure is \fBXmhEditView()\fR.
458.TP 18
459.B Save Message
460This command is insensitive until the message has been edited; when
461activated, edits will be saved to the original message in the view.
462The corresponding action is \fBXmhSaveView()\fR.
463.TP 18
464.B Print
465Print the viewed message.  \fIxmh\fR prints by invoking
466the \fIenscript\fR(1) command, but this can be customized with the
467application-specific resource \fBPrintCommand\fR.
468The corresponding action procedure is \fBXmhPrintView()\fR.
469.TP 18
470.B Delete
471Marks the viewed message for deletion.
472The corresponding action procedure is \fBXmhViewMarkDelete()\fR.
473
474.SH OPTIONS
475The \fIOptions\fR menu contains one entry.
476
477.TP
478.B Read in Reverse
479When selected, a check mark appears in the margin of this menu entry.
480Read in Reverse will switch the meaning of the next and previous
481messages, and will increment to the current message marker
482in the opposite direction.  This is useful
483if you want to read your messages in the order of most recent first.
484The option acts as a toggle; select it from the menu a second time to
485undo the effect.  The check mark appears when the option is selected.
486
487.SH COMPOSITION WINDOWS
488Composition windows are created by selecting \fBCompose Message\fP
489from the \fIMessage\fP command menu, or by selecting
490\fBReply\fP or \fBForward\fP or \fBUse as Composition\fP from the
491\fIMessage\fP or \fIView\fP command menu.
492These are used to compose mail messages.
493Aside from the normal text editing functions, there are six command
494buttons associated with composition windows:
495.TP 18
496.B Close Window
497Close this composition window.  If changes have been made since the
498most recent Save or Send, you will be asked to confirm losing them.
499The corresponding action is \fBXmhCloseView()\fP.
500.PP
501.TP 18
502.B Send
503Send this composition.  The corresponding action is \fBXmhSend()\fP.
504.PP
505.TP 18
506.B New Headers
507Replace the current composition with an empty message.  If changes have
508been made since the most recent Send or Save, you will be
509asked to confirm losing them.
510The corresponding action is \fBXmhResetCompose()\fP.
511.PP
512.TP 18
513.B Compose Message
514Bring up another new composition window.  The corresponding action
515is \fBXmhComposeMessage()\fP.
516.PP
517.TP 18
518.B Save Message
519Save this composition in your drafts folder.  Then you can safely close the
520composition.  At some future date, you can continue working on the
521composition by opening the drafts folder, selecting the message, and
522using the ``Use as Composition'' command. 
523The corresponding action is \fBXmhSave()\fP.
524.PP
525.TP 18
526.B Insert
527Insert a related message into the composition.  If the composition window
528was created with a ``Reply'' command, the related message is the message
529being replied to, otherwise no related message is defined and this button
530is insensitive.  The message may be filtered before being inserted;
531see \fBReplyInsertFilter\fP under APPLICATION RESOURCES for more information.
532The corresponding action is \fBXmhInsert()\fP.
533
534.SH ACCELERATORS
535Accelerators are shortcuts.  They allow you to invoke commands
536without using the menus, either from the keyboard or by using the pointer.
537.PP
538\fIxmh\fP defines pointer accelerators for common actions:
539To select and view a message with a single click, use pointer button
5402 on the message's entry in the table of contents.  To select and open
541a folder or a sequence in a single action, make the folder or sequence
542selection with pointer button 2.
543
544To mark the highlighted messages,
545or current message if none have been highlighted,
546to be moved to a folder in a single action, use pointer button 3 to select
547the target folder and simultaneously mark the messages.
548Similarly, selecting a sequence with pointer button 3 will add
549the highlighted or current message(s) to that sequence.
550In both of these operations, the selected folder or sequence
551and the viewed folder or sequence are not changed.
552
553\fIxmh\fP defines the following keyboard accelerators over the surface of
554the main window, except in the view area while editing a message:
555.nf
556        Meta-I          Incorporate New Mail
557        Meta-C          Commit Changes
558        Meta-R          Rescan Folder
559        Meta-P          Pack Folder
560        Meta-S          Sort Folder
561
562        Meta-space      View Next Message
563        Meta-c          Mark Copy
564        Meta-d          Mark Deleted
565        Meta-f          Forward the selected or current message
566        Meta-m          Mark Move
567        Meta-n          View Next Message
568        Meta-p          View Previous Message
569        Meta-r          Reply to the selected or current message
570        Meta-u          Unmark
571
572        Ctrl-V          Scroll the table of contents forward
573        Meta-V          Scroll the table of contents backward
574        Ctrl-v          Scroll the view forward
575        Meta-v          Scroll the view backward
576.fi
577
578.SH TEXT EDITING COMMANDS
579All of the text editing commands are actually defined by the Text widget
580in the Athena Widget Set.
581The commands may be bound to different keys than the defaults
582described below through the X Toolkit Intrinsics key re-binding mechanisms.
583See the X Toolkit Intrinsics and the Athena Widget Set documentation for
584more details.
585
586Whenever you are asked to enter any text, you will be using a standard
587text editing interface.  Various control and meta keystroke combinations
588are bound to a somewhat Emacs-like set of commands.  In addition, the
589pointer buttons may be used to select a portion of text or to move the
590insertion point in the text.  Pressing pointer button 1 causes the
591insertion point to move to the pointer.  Double-clicking
592button 1 selects a word, triple-clicking selects a line, quadruple-clicking
593selects a paragraph, and clicking rapidly five times selects
594everything.  Any selection may be extended in
595either direction by using pointer button 3.
596
597In the following, a \fIline\fR refers to one displayed row of characters
598in the window.  A \fIparagraph\fR refers to the text between carriage
599returns.  Text within a paragraph is broken into lines for display based on the
600current width of the window.
601When a message is sent, text is broken into lines based upon the values
602of the \fBSendBreakWidth\fP and \fBSendWidth\fP application-specific
603resources.
604
605The following keystroke combinations are defined:
606.sp
607.nf
608.ta 1.0i 3.0i 4.5i
609Ctrl-a  Beginning Of Line       Meta-b  Backward Word
610Ctrl-b  Backward Character      Meta-f  Forward Word
611Ctrl-d  Delete Next Character   Meta-i  Insert File
612Ctrl-e  End Of Line     Meta-k  Kill To End Of Paragraph
613Ctrl-f  Forward Character       Meta-q  Form Paragraph
614Ctrl-g  Multiply Reset  Meta-v  Previous Page
615Ctrl-h  Delete Previous Character       Meta-y  Insert Current Selection
616Ctrl-j  Newline And Indent      Meta-z  Scroll One Line Down
617Ctrl-k  Kill To End Of Line     Meta-d  Delete Next Word
618Ctrl-l  Redraw Display  Meta-D  Kill Word
619Ctrl-m  Newline Meta-h  Delete Previous Word
620Ctrl-n  Next Line       Meta-H  Backward Kill Word
621Ctrl-o  Newline And Backup      Meta-<  Beginning Of File
622Ctrl-p  Previous Line   Meta->  End Of File
623Ctrl-r  Search/Replace Backward Meta-]  Forward Paragraph
624Ctrl-s  Search/Replace Forward  Meta-[  Backward Paragraph
625Ctrl-t  Transpose Characters
626Ctrl-u  Multiply by 4   Meta-Delete     Delete Previous Word
627Ctrl-v  Next Page       Meta-Shift Delete       Kill Previous Word
628Ctrl-w  Kill Selection  Meta-Backspace  Delete Previous Word
629Ctrl-y  Unkill  Meta-Shift Backspace    Kill Previous Word
630Ctrl-z  Scroll One Line Up
631.sp
632In addition, the pointer may be used to copy and paste text:
633.ta .5i 2.0i
634        Button 1 Down   Start Selection
635        Button 1 Motion Adjust Selection
636        Button 1 Up     End Selection (copy)
637
638        Button 2 Down   Insert Current Selection (paste)
639
640        Button 3 Down   Extend Current Selection
641        Button 3 Motion Adjust Selection
642        Button 3 Up     End Selection (copy)
643.fi
644.sp
645.SH CONFIRMATION DIALOG BOXES
646Whenever you press a button that may cause you to lose some work or is
647otherwise dangerous, a popup dialog box will appear asking you to confirm the
648action.  This window will contain an ``Abort'' or ``No'' button and a
649``Confirm'' or ``Yes''
650button.  Pressing the ``No'' button cancels the operation, and pressing
651the ``Yes'' will proceed with the operation.
652
653Some dialog boxes contain messages from \fIMH\fR.  Occasionally when the
654message is more than one line long,
655not all of the text will be visible.  Clicking on the message field will
656cause the dialog box to resize so that you can read the entire message.
657
658.SH MESSAGE-SEQUENCES
659An \fIMH\fP message sequence is just a set of messages associated with some name.
660They are local to a particular folder; two different folders can have
661sequences with the same name.  The sequence named ``all'' is predefined in
662every folder; it consists of the set of all messages in that folder.  As
663many as nine sequences may be defined for each folder, including
664the predefined ``all'' sequence.  (The
665sequence ``cur'' is also usually defined for every folder; it consists of
666only the current message.  \fIxmh\fR hides ``cur'' from the user, instead
667placing a ``+'' by the current message.  Also, \fIxmh\fR does not support
668\fIMH\fP's``unseen'' sequence, so that one is also hidden from the user.)
669
670The message sequences for a folder (including one for ``all'') are
671displayed in the ``Sequence'' menu, below the sequence commands.
672The table of contents (also known as the ``toc'') is at any one time
673displaying one message sequence.  This is called the ``viewed sequence'',
674and its name will be displayed in the toc title bar after the
675folder name.  Also, at any time one of the sequences in the menu will
676have a check mark next to it.  This is called the ``selected sequence''.
677Note that the viewed sequence and the selected sequence are not necessarily
678the same.  (This all pretty much corresponds to the way folders work.)
679
680The \fBOpen Sequence\fR, \fBAdd to Sequence\fR, \fBRemove from Sequence\fR,
681and \fBDelete Sequence\fR commands are active only if the viewed folder
682contains message-sequences other than ``all'' sequence.
683.PP
684Note that none of the above actually affect whether a message is in the
685folder.  Remember that a sequence is a set of messages within the folder;
686the above operations just affect what messages are in that set.
687
688To create a new sequence, select the ``Pick'' menu entry.  A new window will
689appear, with lots of places to enter text. Basically, you can describe the
690sequence's initial set of messages based on characteristics of the
691message.  Thus, you can define a sequence to be all the messages that were
692from a particular person, or with a particular subject, and so on.  You
693can also connect things up with boolean operators, so you can select all
694things from ``weissman'' with a subject containing ``xmh''.
695
696The layout should be fairly obvious.  The simplest cases are the
697easiest: just point to the proper field and type.  If you enter in more
698than one field, it will only select messages which match all non-empty
699fields.
700
701The more complicated cases arise when you want things that match one field
702or another one, but not necessarily both.  That's what all the ``or''
703buttons are for.  If you want all things with subjects that include ``xmh'' or
704``xterm'', just press the ``or'' button next to the ``Subject:'' field.
705Another box will appear where you can enter another subject.
706
707If you want all things either from ``weissman'' or with subject ``xmh'', but
708not necessarily both, select the ``\-Or\-'' button.  This will essentially
709double the size of the form.  You can then enter ``weissman'' in a from: box
710on the top half, and ``xmh'' in a subject: box on the lower part.
711
712If you select the ``Skip'' button, then only those messages that
713\fIdon't\fR match the fields on that row are included.
714
715Finally, in the bottom part of the window will appear several more boxes.
716One is the name of the sequence you're defining.  (It defaults to the name
717of the selected sequence when ``Pick'' was pressed, or to ``temp'' if
718``all'' was the selected sequence.)  Another box defines which sequence to
719look through for potential members of this sequence; it defaults to the
720viewed sequence when ``Pick'' was pressed.
721
722Two more boxes define a date range; only messages within that date range
723will be considered.  These dates must be entered in RFC 822-style format: each
724date is of the form ``dd mmm yy hh:mm:ss zzz'', where dd is a one or two
725digit day of the month, mmm is the three-letter abbreviation for a month,
726and yy is a year.  The remaining fields are optional: hh, mm, and ss
727specify a time of day, and zzz selects a time zone.  Note that if the time
728is left out, it defaults to midnight; thus if you select a range of ``7
729nov 86'' \- ``8 nov 86'', you will only get messages from the 7th, as all
730messages on the 8th will have arrived after midnight.
731
732``Date field'' specifies which field in the header to look at for
733this date range; it defaults to ``Date''.  If the sequence
734you're defining already exists, you can optionally merge the old set with
735the new; that's what the ``Yes'' and ``No'' buttons are all about.
736Finally, you can ``OK'' the whole thing, or ``Cancel'' it.
737
738In general, most people will rarely use these features.  However, it's
739nice to occasionally use ``Pick'' to find some messages, look through
740them, and then hit ``Delete Sequence'' to put things back in their original
741state.
742
743.SH WIDGET HIERARCHY
744In order to specify resources, it is useful to know the hierarchy of
745widgets which compose \fIxmh\fR.  In the notation below, indentation
746indicates hierarchical structure.  The widget class name is given first,
747followed by the widget instance name.
748The application class name is Xmh.
749.PP
750The hierarchy of the main toc and view window is identical for additional
751toc and view windows, except that a TopLevelShell widget is inserted
752in the hierarchy between the application shell and the Paned widget.
753.sp
754.nf
755.ta .5i 1.0i 1.5i 2.0i 2.5i 3.0i 3.5i 4.0i 4.5i 5.0i 5.5i 6.0i 6.5i 7.0i
756Xmh xmh
757        Paned xmh
758                SimpleMenu  folderMenu
759                        SmeBSB  open
760                        SmeBSB  openInNew
761                        SmeBSB  create
762                        SmeBSB  delete
763                        SmeLine  line
764                        SmeBSB  close
765                SimpleMenu  tocMenu
766                        SmeBSB  inc
767                        SmeBSB  commit
768                        SmeBSB  pack
769                        SmeBSB  sort
770                        SmeBSB  rescan
771                SimpleMenu  messageMenu
772                        SmeBSB  compose
773                        SmeBSB  next
774                        SmeBSB  prev
775                        SmeBSB  delete
776                        SmeBSB  move
777                        SmeBSB  copy
778                        SmeBSB  unmark
779                        SmeBSB  viewNew
780                        SmeBSB  reply
781                        SmeBSB  forward
782                        SmeBSB  useAsComp
783                        SmeBSB  print
784                SimpleMenu  sequenceMenu
785                        SmeBSB  pick
786                        SmeBSB  openSeq
787                        SmeBSB  addToSeq
788                        SmeBSB  removeFromSeq
789                        SmeBSB  deleteSeq
790                        SmeLine  line
791                        SmeBSB  all
792                SimpleMenu  viewMenu
793                        SmeBSB  reply
794                        SmeBSB  forward
795                        SmeBSB  useAsComp
796                        SmeBSB  edit
797                        SmeBSB  save
798                        SmeBSB  print
799                SimpleMenu  optionMenu
800                        SmeBSB  reverse
801                Viewport.Core  menuBox.clip
802                        Box  menuBox
803                                MenuButton  folderButton
804                                MenuButton  tocButton
805                                MenuButton  messageButton
806                                MenuButton  sequenceButton
807                                MenuButton  viewButton
808                                MenuButton  optionButton
809                Grip  grip
810                Label folderTitlebar
811                Grip  grip
812                Viewport.Core  folders.clip
813                        Box  folders
814                                MenuButton  inbox
815                                MenuButton  drafts
816                                        SimpleMenu  menu
817                                                SmeBSB <folder_name>
818                                                        .
819                                                        .
820                                                        .
821
822                Grip  grip
823                Label  tocTitlebar
824                Grip  grip
825                Text toc
826                        Scrollbar  vScrollbar
827                Grip  grip
828                Label  viewTitlebar
829                Grip  grip
830                Text  view
831                        Scrollbar  vScrollbar
832                        Scrollbar  hScrollbar
833.sp
834\fIThe hierarchy of the Create Folder popup dialog box:\fR
835.sp
836        TransientShell  prompt
837                Dialog  dialog
838                        Label  label
839                        Text  value
840                        Command  okay
841                        Command  cancel
842.sp
843\fIThe hierarchy of the Notice dialog box, which reports messages from MH:\fR
844.sp
845        TransientShell  notice
846                Dialog  dialog
847                        Label  label
848                        Text  value
849                        Command  confirm
850.sp
851\fIThe hierarchy of the Confirmation dialog box:\fR
852.sp
853        TransientShell  confirm
854                Dialog  dialog
855                        Label  label
856                        Command  yes
857                        Command  no
858.sp
859\fIThe hierarchy of the dialog box which reports errors:\fR
860.sp
861        TransientShell  error
862                Dialog  dialog
863                        Label  label
864                        Command  OK
865.sp
866\fIThe hierarchy of the composition window:\fR
867.sp
868        TopLevelShell  xmh
869                Paned  xmh
870                        Label  composeTitlebar
871                        Text  comp
872                        Viewport.Core  compButtons.clip
873                                Box  compButtons
874                                        Command  close
875                                        Command  send
876                                        Command  reset
877                                        Command  compose
878                                        Command  save
879                                        Command  insert
880.sp
881\fIThe hierarchy of the view window:\fR
882.sp
883        TopLevelShell  xmh
884                Paned  xmh
885                        Label  viewTitlebar
886                        Text  view
887                        Viewport.Core  viewButtons.clip
888                                Box  viewButtons
889                                        Command  close
890                                        Command  reply
891                                        Command  forward
892                                        Command  useAsComp
893                                        Command  edit
894                                        Command  save
895                                        Command  print
896                                        Command  delete
897.sp
898\fIThe hierarchy of the pick window:\fR
899\fI(Unnamed widgets have no name.)\fR
900.sp
901        TopLevelShell  xmh
902                Paned  xmh
903                        Label  pickTitlebar
904                        Viewport.Core  pick.clip
905                                Form  form
906                                        Form  groupform
907\fIThe first 6 rows of the pick window have identical structure:\fR
908                                                Form  rowform
909                                                        Toggle
910                                                        Toggle
911                                                        Label
912                                                        Text
913                                                        Command
914
915                                                Form  rowform
916                                                        Toggle
917                                                        Toggle
918                                                        Text
919                                                        Text
920                                                        Command
921                                                Form  rowform
922                                                        Command
923                        Viewport.core  pick.clip
924                                Form  form
925                                        From  groupform
926                                                Form  rowform
927                                                        Label
928                                                        Text
929                                                        Label
930                                                        Text
931                                                Form  rowform
932                                                        Label
933                                                        Text
934                                                        Label
935                                                        Text
936                                                        Label
937                                                        Text
938                                                Form  rowform
939                                                        Label
940                                                        Toggle
941                                                        Toggle
942                                                Form  rowform
943                                                        Command
944                                                        Command
945                                               
946.fi                             
947.SH APPLICATION-SPECIFIC RESOURCES
948.PP
949The application class name is \fBXmh\fP.
950Application-specific resources are listed below by name.
951Application-specific resource class names always begin with an upper case
952character, but unless noted, are otherwise identical to the instance names
953given below.
954.PP
955Any of these options may also be specified on the command line by
956using the X Toolkit Intrinsics resource specification mechanism.
957Thus, to run \fIxmh\fR showing all message headers,
958.br
959% xmh \-xrm '*HideBoringHeaders:off'
960.PP
961If \fBTocGeometry\fR, \fBViewGeometry\fR, \fBCompGeometry\fR, or
962\fBPickGeometry\fR are not
963specified, then the value of \fBGeometry\fR is used instead.  If the resulting
964height is not specified (e.g., "", "=500", "+0-0"), then the default
965height of windows is calculated from fonts and line counts. If
966the width is not specified (e.g., "", "=x300", "-0+0"), then half of the
967display width is used.  If unspecified, the height of a pick window
968defaults to half the height of the display.
969.PP
970The following resources are defined:
971.TP 8
972.B banner
973A short string that is the default label of the folder, Table of Contents,
974and view.  The default is "xmh    MIT X Consortium    R5".
975.PP
976.TP 8
977.B blockEventsOnBusy
978Whether to disallow user input and show a busy cursor while \fIxmh\fP is
979busy processing a command.  Default is true.
980.PP
981.TP 8
982.B busyCursor
983The name of the symbol used to represent the position of the pointer,
984displayed if \fBblockEventsOnBusy\fR is true, when \fIxmh\fR is
985processing a time-consuming command.
986The default is "watch".
987.PP
988.TP 8
989.B busyPointerColor
990The foreground color of the busy cursor.  Default is XtDefaultForeground.
991.PP
992.TP 8
993.B checkFrequency
994How often to check for new mail, make checkpoints, and rescan the Table
995of Contents, in minutes.  If \fBcheckNewMail\fR is true, \fIxmh\fR checks
996to see if you have new mail each interval.  If \fBmakeCheckpoints\fR is
997true, checkpoints are made every fifth interval.  Also every fifth
998interval, the Table of Contents is checked for inconsistencies with the
999file system, and rescanned if out of date.  To prevent all of these checks
1000from occurring, set \fBCheckFrequency\fR to 0.  The default is 1.
1001This resource is retained for backward compatibility with user resource
1002files; see also \fBcheckpointInterval\fP, \fBmailInterval\fP,
1003and \fBrescanInterval\fP.
1004.PP
1005.TP 8
1006.B checkNewMail
1007If true, \fIxmh\fP will check at regular intervals to see if new mail
1008has arrived for any of the top level folders and any opened subfolders.
1009A visual indication will be given if new mail is waiting to be incorporated
1010into a top level folder.
1011Default is true.
1012The interval can be adjusted with \fBmailInterval\fR.
1013.PP
1014.TP 8
1015.B "checkpointInterval \fP(class \fBInterval\fP)"
1016Specifies in minutes how often to make checkpoints of volatile state,
1017if \fBmakeCheckpoints\fP is true.
1018The default is 5 times the value of \fBcheckFrequency\fP.
1019.PP
1020.TP 8
1021.B checkpointNameFormat
1022Specifies how checkpointed files are to be named.  The value of this
1023resource will be used to compose a file name by inserting the message
1024number as a string in place of the required single occurance of `%d'.  If
1025the value of the resource is the empty string, or if no `%d' occurs in
1026the string, or if "%d" is the value of the resource, the default will be
1027used instead.  The default is "%d.CKP".  Checkpointing is done in the
1028folder of origin unless an absolute pathname is given.  \fIxmh\fP does
1029not assist the user in recovering checkpoints, nor does it provide for
1030removal of the checkpoint files.
1031.PP
1032.TP 8
1033.B commandButtonCount
1034The number of command buttons to create in a button box in between the toc
1035and the view areas of the main window.  \fIxmh\fP will create these buttons
1036with the names \fIbutton1, button2\fP and so on, in a box with the name
1037\fIcommandBox\fR.   The default is 0.
1038\fIxmh\fP users can specify labels and actions for the buttons in a private
1039resource file; see the section ACTIONS AND INTERFACE CUSTOMIZATION.
1040.PP
1041.TP 8
1042.B compGeometry
1043Initial geometry for windows containing compositions.
1044.PP
1045.TP 8
1046.B cursor
1047The name of the symbol used to represent the pointer.  Default is ``left_ptr''.
1048.PP
1049.TP 8
1050.B debug
1051Whether or not to print information to stderr as \fIxmh\fP runs.
1052Default is false.
1053.PP
1054.TP 8
1055.B draftsFolder
1056The folder used for message drafts.  Default is ``drafts''.
1057.PP
1058.TP 8
1059.B geometry
1060Default geometry to use.  Default is none.
1061.PP
1062.TP 8
1063.B hideBoringHeaders
1064If ``on'', then \fIxmh\fR will attempt to skip uninteresting header lines
1065within messages by scrolling them off the top of the view.
1066Default is ``on''.
1067.PP
1068.TP 8
1069.B initialFolder
1070Which folder to display on startup.  May also be set with the command-line
1071option \fB\-initial\fR.  Default is ``inbox''. 
1072.PP
1073.TP 8
1074.B initialIncFile
1075The absolute path name of your incoming mail drop file.
1076In some installations, for example those using the Post Office Protocol,
1077no file is appropriate.
1078In this case, \fBinitialIncFile\fR should not be specified,
1079or may be specified as the empty string,
1080and \fIinc\fR will be invoked without a \-file argument.
1081By default, this resource has no value.
1082This resource is ignored if \fIxmh\fP finds an \fI.xmhcheck\fP file; see
1083the section on multiple mail drops.
1084.PP
1085.TP 8
1086.B "mailInterval (\fPclass\fB Interval)"
1087Specifies the interval in minutes at which the mail should be checked, if
1088\fBmailWaitingFlag\fP or \fBcheckNewMail\fP is true.
1089The default is the value of \fBcheckFrequency\fR.
1090.PP
1091.TP 8
1092.B mailPath
1093The full path prefix for locating your mail folders.  May also be set
1094with the command line option, \fB\-path\fR.  The default is the
1095Path component in the \fIMH\fP profile, or ``$HOME/Mail'' if none.
1096.PP
1097.TP 8
1098.B mailWaitingFlag
1099If true, \fIxmh\fP will attempt to set an indication in its icon when
1100new mail is waiting to be retrieved.  If \fBmailWaitingFlag\fP is true, then
1101\fBcheckNewMail\fP is assumed to be true as well.  The \fB\-flag\fP command
1102line option is a quick way to turn on this resource.
1103.PP
1104.TP 8
1105.B makeCheckpoints
1106If true, \fIxmh\fP will attempt to save checkpoints of volatile edits.
1107The default is false.  The frequency of checkpointing is controlled by the
1108resource \fBcheckpointInterval\fR.  For the location of checkpointing, see
1109\fBcheckpointNameFormat\fP.
1110.PP
1111.TP 8
1112.B mhPath
1113What directory in which to find the \fIMH\fR commands.  If a command isn't
1114found in the user's path, then the path specified here is used.
1115Default is ``/usr/local/mh6''.
1116.PP
1117.TP 8
1118.B "newMailBitmap \fP(class \fBNewMailBitmap\fP)"
1119The bitmap to show in the folder button when a folder has new mail.
1120The default is ``black6''.
1121.PP
1122.TP 8
1123.B "newMailIconBitmap \fP(class \fBNewMailBitmap\fP)"
1124The bitmap suggested to the window manager for the icon when any folder
1125has new mail.  The default is ``flagup''.
1126.PP
1127.TP 8
1128.B "noMailBitmap (\fPclass\fB NoMailBitmap)"
1129The bitmap to show in the folder button when a folder has no new mail.
1130The default is ``box6''.
1131.PP
1132.TP 8
1133.B "noMailIconBitmap (\fPclass\fB NoMailBitmap)"
1134The bitmap suggested to the window manager for the icon when no folders
1135have new mail.  The default is ``flagdown''.
1136.PP
1137.TP 8
1138.B pickGeometry
1139Initial geometry for pick windows.
1140.PP
1141.TP 8
1142.B pointerColor
1143The foreground color of the pointer.  Default is XtDefaultForeground.
1144.PP
1145.TP 8
1146.B prefixWmAndIconName
1147Whether to prefix the window and icon name with "xmh: ".  Default is true.
1148.PP
1149.TP 8
1150.B printCommand
1151An \fIsh\fP command to execute to print a message.  Note that stdout and
1152stderr must be specifically redirected.  If a message or range of messages is
1153selected for printing, the full file paths of each message file are
1154appended to the specified print command.  The default is ``enscript >/dev/null
11552>/dev/null''.
1156.PP
1157.TP 8
1158.B replyInsertFilter
1159An \fIsh\fP command to be executed when the \fIInsert\fP button is activated
1160in a composition window.  The full path and filename of the source
1161message is appended to the command before being passed to \fIsh\fP(1).
1162The default filter is \fIcat\fP; i.e. it inserts the entire message
1163into the composition.  Interesting filters are:
1164\fIsed 's/^/> /'\fP or
1165\fIawk -e '{print "    " $0}'\fP or
1166\fI<mh directory>/lib/mhl \-form mhl.body\fP.
1167.PP
1168.TP 8
1169.B "rescanInterval \fP(class \fBInterval\fP)"
1170How often to check the Table of Contents of currently viewed folders
1171and of folders with messages currently being viewed, and to update the Table
1172of Contents if \fIxmh\fP sees inconsistencies with the file system in these
1173folders.
1174The default is 5 times the value of \fBcheckFrequency\fP.
1175.PP
1176.TP 8
1177.B reverseReadOrder
1178When true, the next message will be the message prior to the current message
1179in the table of contents, and the previous message will be the message
1180after the current message in the table of contents.  The default is false.
1181.PP
1182.TP 8
1183.B sendBreakWidth
1184When a message is sent from \fIxmh\fP, lines longer than this value will be
1185split into multiple lines, each of which is no longer than \fBSendWidth\fP.
1186This value may be overridden for a single message by inserting an additional
1187line in the message header of the form \fISendBreakWidth: value\fP.  This
1188line will be removed from the header before the message is sent.
1189The default is 2000 (to allow for sending mail containing source patches).
1190.PP
1191.TP 8
1192.B sendWidth
1193When a message is sent from \fIxmh\fP, lines longer than \fBSendBreakWidth\fP
1194characters will be split into multiple lines, each of which is no longer than
1195this value.
1196This value may be overridden for a single message by inserting an additional
1197line in the message header of the form \fISendWidth: value\fP.  This
1198line will be removed from the header before the message is sent.
1199The default is 72.
1200.PP
1201.TP 8
1202.B showOnInc
1203Whether to automatically show the current message after incorporating new
1204mail.  Default is true.
1205.PP
1206.TP 8
1207.B skipCopied
1208Whether to skip over messages marked for copying when using ``View Next
1209Message'' and ``View Previous Message''.  Default is true.
1210.PP
1211.TP 8
1212.B skipDeleted
1213Whether to skip over messages marked for deletion when using ``View Next
1214Message'' and ``View Previous Message''.  Default is true.
1215.PP
1216.TP 8
1217.B skipMoved
1218Whether to skip over messages marked for moving to other folders when
1219using ``View Next Message'' and ``View Previous Message''.  Default is true.
1220.PP
1221.TP 8
1222.B stickyMenu
1223If true, when popup command menus are used, the most recently selected
1224entry will be under the cursor when the menu pops up.  Default is false.
1225See the file \fIclients/xmh/Xmh.sample\fR for an example of how to
1226specify resources for popup command menus.
1227.PP
1228.TP 8
1229.B tempDir
1230Directory for \fIxmh\fR to store temporary files.  For privacy, a user
1231might want to change this to a private directory.  Default is ``/tmp''.
1232.PP
1233.TP 8
1234.B tocGeometry
1235Initial geometry for main \fIxmh\fR toc and view windows.
1236.PP
1237.TP 8
1238.B tocPercentage
1239The percentage of the main window that is used to display the Table of
1240Contents.  Default is 33.
1241.PP
1242.TP 8
1243.B tocWidth
1244How many characters to generate for each message in a folder's table of
1245contents.  Default is 100.  Use less if the geometry of the main \fIxmh\fP
1246window results in the listing being clipped at the right hand boundary, or
1247if you plan to use \fImhl\fR a lot,
1248because it will be faster, and the extra characters may not be useful.
1249.PP
1250.TP 8
1251.B viewGeometry
1252Initial geometry for windows showing a view of a message.
1253
1254.SH MULTIPLE MAIL DROPS
1255.PP
1256Users may need to incorporate mail from multiple spool files or mail drops.
1257If incoming mail is forwarded to the \fIMH slocal\fP program, it can
1258be sorted as specified by the user into multiple incoming mail drops.
1259Refer to the \fIMH\fP man page for \fIslocal\fP to learn how to specify
1260fowarding and the automatic sorting of incoming mail in a \fI.maildelivery\fP
1261file.
1262.PP
1263To inform \fIxmh\fP about the various mail drops, create a file in your
1264home directory called \fI.xmhcheck\fP.  In this file, a mapping between
1265existing folder names and mail drops is created by giving a folder name
1266followed by the absolute pathname of the mail drop site, with some white
1267space separating them, one mapping per line.  \fIxmh\fP will read this file
1268whether or not resources are set for notification of new mail arrival, and
1269will allow incorporation of new mail into any folder with a mail drop.
1270\fIxmh\fP will invoke \fIinc\fP with the \fI\-file\fP argument,
1271and if \fIxmh\fP has been requested to check for new mail,
1272it will check directly, instead of using \fImsgchk\fP.
1273.PP
1274An example of \fI.xmhcheck\fP file format, for the folders ``inbox'' and
1275``xpert'':
1276.nf
1277inbox   /usr/spool/mail/converse
1278xpert   /users/converse/maildrops/xpert
1279.fi
1280.sp
1281.SH ACTIONS AND INTERFACE CUSTOMIZATION
1282.PP
1283Because \fIxmh\fR provides action procedures which correspond to command
1284functionality and installs accelerators, users can customize accelerators
1285and new button functionality in a private resource file.
1286For examples of specifying customized resources, see the file
1287\fImit/clients/xmh/Xmh.sample\fR.  To understand the syntax, see the
1288Appendix of the \fIX Toolkit Intrinsics\fP specification
1289on \fITranslation Table Syntax\fP, and any general explanation of
1290using and specifying \fIX\fP resources.
1291Unpredictable results can occur if
1292actions are bound to events or widgets for which they were not designed.
1293.PP
1294Here's an example of how to bind actions to your own \fIxmh\fP buttons,
1295and how to redefine the default accelerators so that the Meta key is
1296not required, in case you don't have access to the sample file mentioned
1297above.
1298.sp
1299.nf
1300! To create buttons in the middle of the main window and give them semantics:
1301
1302Xmh*CommandButtonCount:         5
1303
1304Xmh*commandBox.button1.label:   Inc
1305Xmh*commandBox.button1.translations: #override\\
1306        <Btn1Down>,<Btn1Up>: XmhIncorporateNewMail() unset()
1307
1308Xmh*commandBox.button2.label:   Compose
1309Xmh*commandBox.button2.translations: #override\\
1310        <Btn1Down>,<Btn1Up>: XmhComposeMessage() unset()
1311
1312Xmh*commandBox.button3.label:   Next
1313Xmh*commandBox.button3.translations: #override\\
1314        <Btn1Down>,<Btn1Up>: XmhViewNextMessage() unset()
1315
1316Xmh*commandBox.button4.label:   Delete
1317Xmh*commandBox.button4.translations: #override\\
1318        <Btn1Down>,<Btn1Up>: XmhMarkDelete() unset()
1319
1320Xmh*commandBox.button5.label:   Commit
1321Xmh*commandBox.button5.translations: #override\\
1322        <Btn1Down>,<Btn1Up>: XmhCommitChanges() unset()
1323
1324! To redefine the accelerator bindings to exclude modifier keys,
1325! and add your own keyboard accelerator for Compose Message:
1326
1327Xmh*tocMenu.accelerators: #override\\n\\
1328        !:<Key>I:       XmhIncorporateNewMail()\\n\\
1329        !:<Key>C:       XmhCommitChanges()\\n\\
1330        !:<Key>R:       XmhForceRescan()\\n\\
1331        !:<Key>P:       XmhPackFolder()\\n\\
1332        !:<Key>S:       XmhSortFolder()\\n
1333Xmh*messageMenu.accelerators: #override\\n\\
1334        !:<Key>E:       XmhComposeMessage()\\n\\
1335        !<Key>space:    XmhViewNextMessage()\\n\\
1336        !:<Key>c:       XmhMarkCopy()\\n\\
1337        !:<Key>d:       XmhMarkDelete()\\n\\
1338        !:<Key>f:       XmhForward()\\n\\
1339        !:<Key>m:       XmhMarkMove()\\n\\
1340        !:<Key>n:       XmhViewNextMessage()\\n\\
1341        !:<Key>p:       XmhViewPreviousMessage()\\n\\
1342        !:<Key>r:       XmhReply()\\n\\
1343        !:<Key>u:       XmhUnmark()\\n
1344.fi
1345.PP
1346\fIxmh\fR provides action procedures
1347which correspond to entries in the command menus; these are given in the
1348sections describing menu commmands, not here.
1349In addition to the actions corresponding to commands in the menus,
1350these action routines are defined:
1351.TP 10
1352.B XmhPushFolder(\fR[\fIfoldername, ...\fR]\fB)\fR
1353This action pushes each of its argument(s) onto a stack of foldernames.
1354If no arguments are given, the selected folder is pushed onto the stack.
1355.TP 10
1356.B XmhPopFolder()
1357This action pops one foldername from the stack and sets the selected folder.
1358.TP 10
1359.B XmhPopupFolderMenu()
1360This action should always be taken when the user selects a folder button.
1361A folder button represents a folder and zero or more subfolders.  The menu
1362of subfolders is built upon the first reference, by this routine.  If there
1363are no subfolders, this routine will mark the folder as having no subfolders,
1364and no menu will be built.  In that case the menu button emulates a toggle
1365button.  When subfolders exist, the menu will popup, using the menu button
1366action PopupMenu().
1367.TP 10
1368.B XmhSetCurrentFolder()
1369This action allows menu buttons to emulate toggle buttons in the function
1370of selecting a folder.  This action is for menu button widgets only,
1371and sets the selected folder.
1372.TP 10
1373.B XmhLeaveFolderButton()
1374This action ensures that the menu button behaves properly when the user
1375moves the pointer out of the menu button window.
1376.TP 10
1377.B XmhPushSequence(\fR[\fIsequencename, ...\fR]\fB)\fR
1378This action pushes each of its arguments onto the stack of sequence names.
1379If no arguments are given, the selected sequence is pushed onto the stack.
1380.TP 10
1381.B XmhPopSequence()
1382This action pops one sequence name from the stack of sequence names,
1383which then becomes the selected sequence.
1384.TP 10
1385.B XmhPromptOkayAction()
1386This action is equivalent to pressing the okay button in the Create Folder popup.
1387.TP 10
1388.B XmhReloadSeqLists()
1389This action rescans the contents of the public \fIMH\fP sequences for the
1390currently opened folder and updates the sequence menu if necessary.
1391.TP 10
1392.B XmhShellCommand(\fI parameter \fR[\fI, parameter\fR]\fB)\fR
1393At least one parameter must be specified.  The parameters will be concatenated
1394with a space character separator, into a single string, and the list of
1395selected messsages, or if no messages are selected, the current message,
1396will be appended to the string of parameters.  The string will be executed
1397as a shell command.  The messages are always given as absolute pathnames.
1398It is an error to cause this action to execute when there are no selected
1399messages and no current message.
1400.TP 10
1401.B XmhCheckForNewMail()
1402This action will check all mail drops known to xmh.  If no mail drops have
1403been specified by the user either through the \fI.xmhcheck\fR file or by
1404the \fBinitialIncFile\fP resource, the \fIMH\fP command \fImsgchk\fP is
1405used to check for new mail, otherwise, \fIxmh\fP checks directly.
1406.TP 10
1407.B XmhWMProtocols(\fP[\fBwm_delete_window\fP] [\fBwm_save_yourself\fP])
1408This action is responsible for participation in window manager communication
1409protocols.  It responds to delete window and save yourself messages.
1410The user can cause \fIxmh\fP to respond to one or both of these protocols,
1411exactly as if the window manager had made the request, by invoking the
1412action with the appropriate parameters.  The action is insensitive to the
1413case of the string parameters.  If the event received is a ClientMessage
1414event and parameters are present, at least one of the parameters must
1415correspond to the protocol requested by the event for the request to be
1416honored by \fIxmh\fP.
1417
1418.SH CUSTOMIZATION USING \fIMH\fR
1419The initial text displayed in a composition window is generated by
1420executing the corresponding \fIMH\fP command; i.e. \fIcomp\fP, \fIrepl\fP,
1421or \fIforw\fP, and therefore message components may be customized as
1422specified for those commands.  \fIcomp\fP is executed only once per
1423invocation of \fIxmh\fP and the message template is re-used for every
1424successive new composition.
1425.PP
1426\fIxmh\fP uses \fIMH\fP commands, including \fIinc\fP, \fImsgchk\fP,
1427\fIcomp\fP, \fIsend\fP, \fIrepl\fP, \fIforw\fP,
1428\fIrefile\fP, \fIrmm\fP, \fIpick\fP, \fIpack\fP, \fIsort\fP, and \fIscan\fP.
1429Some flags for these commands can be specified
1430in the \fIMH\fP profile; \fIxmh\fP may override them.  The application
1431resource \fBdebug\fP can be set to true to see how \fIxmh\fP
1432uses \fIMH\fP commands.
1433
1434.SH ENVIRONMENT
1435.br
1436HOME - users's home directory
1437.br
1438MH - to get the location of the \fIMH\fP profile file
1439.SH FILES
1440~/.mh_profile - \fIMH\fR profile, used if the MH environment variable is not set
1441.br
1442~/Mail - directory of folders, used if the \fIMH\fR profile cannot be found
1443.br
1444~/.xmhcheck - optional, for multiple mail drops in cooperation with \fIslocal\fP.
1445.br
1446/usr/local/mh6 - \fIMH\fR commands, as a last resort, see \fBmhPath\fP.
1447.br
1448~/Mail/<folder>/.xmhcache - \fIscan\fP output in each folder
1449.br
1450~/Mail/<folder>/.mh_sequences - sequence definitions, in each folder
1451.br
1452/tmp - temporary files, see \fBtempDir\fP.
1453.SH SEE ALSO
1454X(1), xrdb(1), X Toolkit Intrinsics, Athena Widget Set, mh(1), enscript(1)
1455.br
1456At least one book has been published about \fIMH\fP and \fIxmh\fP.
1457.SH BUGS
1458- When the user closes a window, all windows which are transient for that
1459window should also be closed by \fIxmh\fP.
1460.br
1461- When \fBXmhUseAsComposition\fP and \fBXmhViewUseAsComposition\fP operate
1462on messages in the \fBDraftsFolder\fP, \fIxmh\fP disallows editing of the
1463composition if the same message is also being viewed in another window.
1464.br
1465- Occasionally after committing changes, the table of contents will appear
1466to be completely blank when there are actually messages present.
1467When this happens, refreshing the display, or typing Control-L in the
1468table of contents, will often cause the correct listing to appear.
1469If this doesn't work, force a rescan of the folder.
1470.br
1471- Should recognize and use the ``unseen'' message-sequence.
1472.br
1473- Should determine by itself if the user hasn't used \fIMH\fR before, and
1474offer to create the .mh_profile, instead of hanging on inc.
1475.br
1476- A few commands are missing (rename folder, resend message).
1477.br
1478- WM_DELETE_WINDOW protocol doesn't work right when requesting deletion
1479of the first toc and view, while trying to keep other \fIxmh\fP windows around.
1480.br
1481- Doesn't support annotations when replying to messages.
1482.br
1483- Doesn't allow folders to be shared without write permission.
1484.br
1485- Doesn't recognize private sequences.
1486.br
1487- \fIMH\fP will report that the \fI.mh_sequences\fP file is poorly formatted
1488if any sequence definition in a particular folder contains more
1489than \fIBUFSIZ\fP characters.  \fIxmh\fP tries to capture these messages
1490and display them when they occur, but it cannot correct the problem.
1491.sp
1492.SH COPYRIGHT
1493Copyright 1988, 1989, Digital Equipment Corporation.
1494.br
1495Copyright 1989, 1991 Massachusetts Institute of Technology
1496.br
1497See \fIX(1)\fP for a full statement of rights and permissions.
1498.SH AUTHOR
1499Terry Weissman, formerly of Digital Western Research Laboratory
1500.br
1501Donna Converse, MIT X Consortium
Note: See TracBrowser for help on using the repository browser.