4.4BSD/usr/src/contrib/mh-6.8/doc/MH.me

.\"	@(#)MH.me	8.1 (Berkeley) 8/14/93
.\"
.\"	This file is automatically generated.  Do not edit!
.\" @(#)$Id: MH.rf,v 1.26 1992/12/02 19:03:15 jromine Exp $
.eh 'USD:8-%''The RAND Message Handling System: User Manual'
.oh 'The RAND Message Handling System: User Manual''USD:8-%'
.po +.75i
.de $c                          \" Major Heading printer
.ce
.b "\\s12\\n+(ch.\\ \\$1\\s0"   \" 12 Point Bold Header
.(x

\ \ \ \\n(ch.\\ \\ \\$1
.)x
.sp 45p         \" 45 point space or about 1/2 inch
..
\".nr xs .15v     \" Put index entries closer together
.(x

Section
.)x _
.de $0          \" Sub-Heading macro called AFTER printing the heading
.(x
.sp .3v
.ti .5i
\\$1
.)x
..
.de $s          \" Macro to print footnote separator
\"\l'2i'        \" No line drawn
.if n \
.       sp 1.3  \" But extra space to make up for it.
..
.fc ^ ~         \" The characters ^ and ~ CANNOT BE USED
\"                 throughout this document except as field
\"                 delimiter & pad indicator!
.\" .he ''-%-''
.ll 32P         \" 32 Picas or about 5+1/3 inch Line Length
.if n .ll 72m   \" Use 72 ems for nroff
.nr ss 30p      \" 30 point space before section titles
.nr fm 5v       \" RAND likes bigger than normal [3v] bottom margins
.nr bm 7v       \"   ditto
.ds . \\fB.\\fP\\h'-(1m/3)' \" Bold period to stand out.
.ds << <\\h!-(\\w'<'/2)!<
.ds >> >\\h!-(\\w'>'/2)!>
.ds ** \v'-3p'\s+1*\s0\v'+3p'
.so version.rf
.tp
.(l C
\fIdiscard this page\fR
.sp 4
The RAND \fIMH\fR
Message Handling System:
User's Manual
.sp
UCI Version
.sp 2
\*(td
\*(MH
.)l
.++ C
.\"	And now the COVER sheet
.po +.325i
.ll 32P
.nf
 
.sp 1.5in
.ps 24
.vs 32
.ft B
.ce 4
THE RAND MH
MESSAGE HANDLING
SYSTEM:
USER'S MANUAL
.ft R
.sp .8i
.ps 20
.vs 24
.ce
UCI Version
.sp 0.7i
.ce 2
Marshall T. Rose
John L. Romine
.sp 0.5i
.ce 2
Based on the original manual by
Borden, Gaines, and Shapiro
.vs
.sp 1i
.ps 18
.vs 22
.ce 2
\*(td
\*(MH
.de $c
.ce
.b "\\s12\\$1\\s0"   \" 12 Point Bold Header
.(x y
.sp
\\$1
.)x
.sp 3
..
.\" .++ P
.bp 4
.fo ''''
.\" .he ''-%-''
.+c "READ THIS"
.pp
Although the \fIMH\fR system was originally developed by the RAND Corporation,
and is now in the public domain,
the RAND Corporation assumes no responsibility for \fIMH\fR
or this particular version of \fIMH\fR.
.pp
In addition,
the Regents of the University of California issue the following
\fBdisclaimer\fR in regard to the UCI version of \fIMH\fR:
.sp 1
.in +.5i
\*(lqAlthough each program has been tested by its contributor,
no warranty, express or implied,
is made by the contributor or the University of California,
as to the accuracy and functioning of the program
and related program material,
nor shall the fact of distribution constitute any such warranty,
and no responsibility is assumed by the contributor
or the University of California in connection herewith.\*(rq
.in -.5i
.pp
This version of \fIMH\fR is in the public domain,
and as such,
there are no real restrictions on its use.
The \fIMH\fR source code and documentation have no licensing restrictions
whatsoever.
As a courtesy,
the authors ask only that you provide appropriate credit to the RAND
Corporation and the University of California for having developed the software.
.pp
\fIMH\fR is a software package that is supported neither by the RAND
Corporation nor the University of California.
However,
since we do use the software ourselves and plan to continue using
(and improving) \fIMH\fR,
bug reports and their associated fixes should be reported back to us so that
we may include them in future releases.
The current computer mailbox for \fIMH\fR is \fBBug\-MH@ICS.UCI.EDU\fR
(in the ARPA Internet),
and \fB...!ucbvax!ucivax!bug\-mh\fR (UUCP).
Presently,
there are two Internet discussion groups, \fBMH\-Users@ICS.UCI.EDU\fR
and \fBMH\-Workers@ICS.UCI.EDU\fR.  \fBMH\-Workers\fP is for people
discussing code changes to \fIMH\fP.  \fBMH-Users\fP is for general
discussion about how to use \fIMH\fP.
\fBMH\-Users\fR is bi-directionally 
gatewayed into USENET as \fBcomp.mail.mh\fR.
.lp
.b "HOW TO GET MH"
.pp
Since you probably already have \fIMH\fP,
you may not need to read this unless you suspect you have an old version.
There are two ways to get the latest release:
.pp
1.  If you can FTP to the ARPA Internet, use anonymous FTP to
ics.uci.edu [128.195.1.1] and retrieve the file pub/mh/mh-6.8.tar.Z.
This is a tar image after being run through the compress program
(approximately 1.8MB).  There should also be a \fBREADME\fR file in
that directory which tells what the current release of \fIMH\fP
is, and how to get updates.
.pp
This tar file is also available on louie.udel.edu 
[128.175.1.3] in portal/mh-6.8.tar.Z.  You may also find MH on
various other hosts; to make sure you get the latest version and
don't waste your time re-fixing bugs, it's best to get it from
either ics.uci.edu or louie.udel.edu.
.pp
2.  You can send $75 US to the address below.
This covers the cost of a 6250 BPI 9-track magtape,
handling, and shipping.  In addition, you'll get a
laser-printed hard-copy of the entire MH documentation set.  Be
sure to include your USPS address with your check.  Checks 
must be drawn on U.S\&. funds and should be made payable to:

.ti +1i
Regents of the University of California

The distribution address is:  

.nf
.in +1i
Computing Support Group 
Attn: MH distribution
Department of Information and Computer Science
University of California, Irvine
Irvine, CA  92717

714/856-7554
.fi
.in -1i
.pp
If you just want the hard-copies of the documentation, you
still have to pay the $75.  The tar image has the documentation
source (the manual is in roff format, but the rest are in TeX
format).  Postscript formatted versions of the TeX papers are 
available, as are crude tty-conversions of those papers.
.+c FOREWORD
.pp
This document describes the RAND \fIMH\fR Message Handling System.
Its primary purpose is to serve as a user's manual.
It has been heavily based on a previous version of the manual,
prepared by Bruce Borden, Stockton Gaines, and Norman Shapiro.
.pp
\fIMH\fR is a particularly novel system,
and thus it is often more prone to change than other pieces of production
software.
As such, some specific points in this manual may not be correct in the
future.
In all cases, the on\-line sections of this manual,
available through the UNIX\** \fIman\fR command,
should present the most current information.
.(f
\** UNIX is a trademark of AT&T Bell Laboratories.
.)f
.pp
When reading this document as a user's manual,
certain sections are more interesting than others.
The Preface and Summary are not particularly interesting to those
interested in learning \fIMH\fR.
The Introduction is slightly more interesting,
as it touches upon the organization of the remainder of this document.
The most useful sections are the Overview, Tutorial, and Detailed
Description.
The Overview should be read by all \fIMH\fR users, regardless of their
expertise (beginning, novice, advanced, or hacker).
The Tutorial should be read by all beginning and novice \fIMH\fR users,
as it presents a nice description of the \fIMH\fR system.
The Detailed Description should be read by the day\-to\-day user of \fIMH\fR,
as it spells out all of the realities of the \fIMH\fR system.
The Advanced Features section discusses some powerful \fIMH\fR capabilities for
advanced users.
Appendix A is particularly useful for novices,
as it summarizes the invocation syntax of all the \fIMH\fR commands.
.pp
There are also several other documents which may be useful to you:
\fIThe RAND MH Message Handling System: Tutorial\fR,
which is a tutorial for \fIMH\fR;
\fIThe RAND MH Message Handling System: The UCI BBoards Facility\fR,
which describes the BBoards handling under \fIMH\fR;
\fIMH.5: How to process 200 messages a day and still get some real work
done\fR,
which was presented at the 1985 Summer Usenix Conference and
Exhibition in Portland, Oregon;
\fIMH: A Multifarious User Agent\fR,
which has been accepted for publication by Computer Networks;
\fIMZnet: Mail Service for Personal Micro\-Computer Systems\fR,
which was presented at the First International Symposium on Computer Message
Systems in Nottingham, U.K.;
and,
\fIDesign of the TTI Prototype Trusted Mail Agent\fR,
which describes a proprietary \*(lqtrusted\*(rq mail system built on \fIMH\fR.
There are also documents, mostly specific to U.C.\0Irvine which you may find
interesting:
\fIMH for Beginners\fR, and \fIMH for MM Users\fR.
All of these documents exist in the \fImh.6\fR distribution sent to your
site.
There's also a document,
\fIChanges to the RAND MH Message Handling System: MH.6\fR,
which describes user\-visible changes made to \fIMH\fR since the last major
release.
.pp
This manual is very large, as it describes a large, powerful system in
gruesome detail.
The important thing to remember is:
.sp 2
.ce
.b "\s+4DON'T PANIC\s0\**"
.sp 2
As explained in the tutorial, you really need to know only 5 commands to
handle most of your mail.
.(f
\** Note the large, \fIfriendly\fR letters.
.)f
.pp
Very advanced users may wish to consult 
\fIThe RAND MH Message Handling System: Administrator's Guide\fR,
which is also present in the \fImh.6\fR distribution sent to your site.
.+c ACKNOWLEDGMENTS
.pp
The \fIMH\fR system described herein is based on the original RAND \fIMH\fR
system.
It has been extensively developed (perhaps too much so) by Marshall T. Rose and
John L. Romine at the University of California, Irvine.
Einar A. Stefferud, Jerry N. Sweet, and Terry P. Domae provided numerous
suggestions to improve the UCI version of \fIMH\fR.
Of course,
a large number of people have helped \fIMH\fR along.
The list of ``\fIMH\fR immortals'' is too long to list here.
However, Van Jacobson deserves a special acknowledgement for his tireless
work in improving the performance of \fIMH\fR.
Some programs have been speeded-up by a factor of 10 or 20.
All of users of \fIMH\fR, everywhere, owe a special thanks to Van.
For this release, numerous \fIMH\-Workers\fP sent in fixes and other
changes.  A handful of courageous \fIMH\-Workers\fP volunteered
to beta\-test these changes; their help is particularly appreciated.
.pp
This manual is based on the original \fIMH\fR manual written at RAND by
Bruce Borden, Stockton Gaines, and Norman Shapiro.
.+c PREFACE
.pp
This report describes a system for dealing with messages transmitted on a
computer.  Such messages might originate with other users of the same
computer or might come from an outside source through a network to which the user's
computer is connected.  Such computer-based message systems are
becoming increasingly widely used, both within and outside the Department
of Defense.
.pp
The message handling system \fIMH\fR was developed for two reasons.
One was to investigate some
research ideas concerning how a message system might take advantage of
the architecture of the UNIX time-sharing operating system for
Digital Equipment Corporation PDP-11 and VAX computers, and the special
features of UNIX's command-level interface with the user (the
\*(lqshell\*(rq).  The other reason was to provide a better and more
adaptable base than that of conventional designs
on which to build a command and control message system.
The effort has succeeded in both
regards, although this report mainly describes the message system itself
and how it fits in with UNIX.
.pp
The present report should be of interest to three groups of readers.  First,
it is a complete reference manual for the users of \fIMH\fR.
Second, it should be
of interest to those who have a general knowledge of computer-based
message systems, both in civilian and military applications.  Finally,
it should be of interest to those who build large subsystems that
interface with users, since it illustrates a new approach to such
interfaces.
.pp
The original \fIMH\fR system was developed by Bruce Borden,
using an approach suggested by Stockton Gaines and Norman Shapiro.
Valuable assistance was provided by Phyllis Kantar in the later
stages of the system's implementation.
Several colleagues
contributed to the ideas included in this system, particularly
Robert Anderson and David Crocker.
In addition, valuable experience
in message systems, and a valuable source of ideas, was available
to us in the form of a previous message system for UNIX called
MS, designed at RAND by David Crocker.
.pp
This report was originally prepared as part of the RAND project entitled
\*(lqData Automation Research\*(rq, sponsored by Project AIR FORCE.
.+c SUMMARY
.pp
Electronic communication of text messages is becoming
commonplace.  Computer-based message systems\-software
packages that provide tools for dealing with messages\-are used in many
contexts.  In particular, message systems are becoming
increasingly important in command and control and intelligence
applications.
.pp
This report describes a message handling system called \fIMH\fR.
This system provides the user
with tools to compose, send, receive, store, retrieve, forward, and
reply to messages.  \fIMH\fR has been built on the UNIX time-sharing system,
a popular operating system developed for the DEC PDP-11 and VAX classes of
computers.
.pp
A complete description of \fIMH\fR is given for users of
the system.  For those who do not intend to use the system, this description
gives a general idea of what a message system is like.  The system involves
some new ideas about how large subsystems can be constructed.
.pp
The interesting and unusual features of \fIMH\fR include the
following:  The user command interface to \fIMH\fR is the UNIX \*(lqshell\*(rq
(the standard UNIX command interpreter).  Each separable
component of message handling, such as message composition or
message display, is a separate command.  Each program is driven from
and updates a private user environment, which is stored as a file
between program invocations.  This private environment also contains
information to \*(lqcustom tailor\*(rq \fIMH\fR to the individual's tastes.
\fIMH\fR stores each message as a separate file under UNIX, and it utilizes the
tree-structured UNIX file system to organize groups of files within
separate directories or \*(lqfolders\*(rq.  All of the UNIX facilities
for dealing with files and directories, such as
renaming, copying, deleting, cataloging, off-line printing, etc., are
applicable to messages and directories of messages (folders).  Thus,
important capabilities needed in a message system are available in \fIMH\fR
without the need (often seen in other message systems) for code that
duplicates the facilities of the supporting operating system.
It also allows users familiar with the shell to use \fIMH\fR with minimal
effort.
.+c INTRODUCTION
.pp
Although people can travel cross-country in hours and can
reach others by telephone in seconds, communications still depend
heavily upon paper, most of which is distributed through the mails.
.pp
There are several major reasons for this continued dependence on
written documents.
First, a written document may be proofread
and corrected prior to its distribution, giving the author
complete control over his words.
Thus, a written document is
better than a telephone conversation in this respect.
Second,
a carefully written document is far less likely to be
misinterpreted or poorly translated than a phone conversation.
Third, a signature offers reasonable verification of authorship,
which cannot be provided with media such as telegrams.
.pp
However, the need for
.u fast ,
accurate, and reproducible document distribution is
obvious.
One solution in widespread use is the telefax.
Another
that is rapidly gaining popularity is electronic mail.
Electronic mail is similar to telefax in that the data to be sent
are digitized, transmitted via phone lines, and
turned back into a document at the receiver.
The advantage of
electronic mail is in its compression factor.
Whereas a telefax
must scan a page in very fine lines and send all of the black and
white information, electronic mail assigns characters fixed
codes which can be transmitted as a few bits of information.
Telefax presently has the advantage of being able to transmit an
arbitrary page, including pictures, but electronic mail is
beginning to deal with this problem.
Electronic mail also integrates well
with current directions in office automation, allowing documents
prepared with sophisticated equipment at one site to be quickly
transferred and printed at another site.
.pp
Currently, most electronic mail is intraorganizational,
with mail transfer remaining within one computer.
As computer
networking becomes more common, however, it is becoming more feasible to
communicate with anyone whose computer can be linked to your
own via a network.
.pp
The pioneering efforts on general-purpose electronic mail
were by organizations using the DoD ARPAnet[1].
The capability to send messages between computers existed before
the ARPAnet was developed, but it was used only in limited ways.
With the advent of the
ARPAnet, tools began to be developed which made it convenient for
individuals or organizations to distribute messages
over broad geographic areas, using
diverse computer facilities.
The interest and activity in
message systems has now reached such proportions that steps
have been taken within the DoD to coordinate and
unify the development of military message systems.
The use of electronic mail is expected to increase
dramatically in the next few years.
The utility of such systems
in the command and control and intelligence environments is
clear, and applications in these areas will probably lead the
way.
As the costs for sending and handling electronic messages
continue their rapid decrease, such uses can be
expected to spread rapidly into other areas and, of course, will
not be limited to the DoD.
.pp
A message system provides tools that help users (individuals
or organizations) deal with messages in various ways.
Messages
must be composed, sent, received, stored, retrieved,
forwarded, and replied to.
Today's best interactive computer
systems provide a variety of word-processing and information
handling capabilities.
The message handling facilities should be
well integrated with the rest of the system, so as to be a
graceful extension of overall system capability.
.pp
The message system described in this report, \fIMH\fR, provides most of the
features that can be found in other message systems and also
incorporates some new ones.
It has been built on the UNIX time-sharing
system[2], a popular operating system for the DEC PDP-11\**
and VAX-11 classes of computers.
.(f
\** PDP and VAX are trademarks of Digital Equipment Corporation.
.)f
A \*(lqsecure\*(rq operating
system similar to UNIX is currently being developed[3],
and that system will also run \fIMH\fR.
.pp
This report provides a complete description of \fIMH\fR and
thus may serve as a user's manual, although parts of the report
will be of interest to non-users as well.
Sections 2 and 3, the
Overview and Tutorial, present the key
ideas of \fIMH\fR and will give those not familiar with message systems
an idea of what such systems are like.
.pp
\fIMH\fR consists of a set of commands which use some special
files and conventions.
The final section is divided into three parts.
The first part covers the information
a user needs to know in addition to the
commands.
Then, each of the \fIMH\fR commands is described in detail.
Finally, other obscure details are revealed.
A summary of the commands is given in Appendix A,
and the syntax of message sequences is given in Appendix B.
.pp
A novel approach has been taken in the design of \fIMH\fR.
Instead of creating a large subsystem that appears as a single
command to the user (such as MS[4]),
\fIMH\fR is a collection of separate commands
which are run as separate programs.
The file and directory
system of UNIX are used directly.
Messages are stored as
individual files (datasets), and collections of them are grouped
into directories.
In contrast, most other message systems store
messages in a complicated data structure within a monolithic
file.
With the \fIMH\fR approach, UNIX commands can be
interleaved with commands invoking the functions of the message
handler.
Conversely, existing UNIX commands
can be used in connection with messages.
For
example, all the usual UNIX editing, text-formatting, and printing
facilities can be applied directly to individual messages.
MH,
therefore, consists of a relatively small amount of new code; it
makes extensive use of other UNIX software to provide the
capabilities found in other message systems.
.+c OVERVIEW
.pp
There are three main aspects of \fIMH\fR\0:  the  way  messages  are
stored (the message database), the user's profile (which directs
how certain actions of the message handler take place), and the
commands for dealing with messages.
.pp
Under \fIMH\fR, each message is stored as a separate file.
A user
can take any action with a message that he could with an ordinary
file in UNIX.
A UNIX directory in which messages are stored is
called a folder.
Each folder contains some standard entries to support
the message-handling functions.
The messages in a folder have numerical
names.
These folders (directories)
are entries in a particular directory path, described in
the user profile, through which \fIMH\fR can find message folders.
Using the UNIX \*(lqlink\*(rq facility, it is possible for one copy of a
message to be \*(lqfiled\*(rq in more than one folder, providing a
message index facility.
Also, using the UNIX tree-structured
file system, it is possible to have a folder within a folder,
nested arbitrarily deep,
and have the full power of the \fIMH\fR commands available.
.pp
Each user of \fIMH\fR has a user profile, a file in
his \fB$HOME\fR (initial login) directory called \fI\&.mh\(ruprofile\fR.
This profile contains several
pieces of information used by the \fIMH\fR commands:
a path name to the directory that contains the message folders
and parameters that tailor \fIMH\fR commands
to the individual user's requirements.
There is also another file,
called the user context,
which contains information concerning which folder the user last referenced
(the \*(lqcurrent\*(rq folder).
It also contains
most of the necessary state information concerning how
the user is dealing with his messages, enabling \fIMH\fR to be
implemented as a set of individual UNIX commands, in contrast to the
usual approach of a monolithic subsystem.
.pp
In \fIMH\fR, incoming mail is appended
to the end of a file in a system spooling area for the user.
This area is called the mail drop directory,
and the file is called the user's mail drop.
Normally when the user logins in,
s/he is informed of new mail
(or the \fIMH\fR program \fImsgchk\fR may be run).
The user adds the new messages to his/her collection of \fIMH\fR messages
by invoking the command
\fIinc\fR.
The \fIinc\fR (incorporate) command adds the new
messages to a folder called \*(lqinbox\*(rq, assigning them names which
are consecutive integers starting with the next highest integer
available in inbox.
\fIinc\fR also produces a
\fIscan\fR summary of
the messages thus incorporated.
A folder can be compacted into a single file,
for easy storage,
by using the \fIpackf\fR command.
Also,
messages within a folder can be sorted by date and time with the \fIsortm\fR
command.

.pp
There are four commands for examining the messages in a
folder:
\fIshow\fR,
\fIprev\fR,
\fInext\fR,
and
\fIscan\fR.
The \fIshow\fR command displays a message in a folder,
\fIprev\fR displays the message preceding the current message, and
\fInext\fR displays the message following the current message.
\fIMH\fR lets the user choose the program that displays individual messages.
A special program, \fImhl\fR, can be used to display messages according
to the user's preferences.
The \fIscan\fR command summarizes the messages in a folder,
normally producing one line per message, showing who the message is from,
the date, the subject, etc.
.pp
The user may move a message from one folder to another with
the command
\fIrefile\fR.
Messages may be removed from a folder
by means of the command
\fIrmm\fR.
In addition, a user may query
what the current folder is and may specify that a new folder
become the current folder, through the command
\fIfolder\fR.
All folders may be summarized with the \fIfolders\fR command.
A message folder (or subfolder) may be removed by means of
the command
\fIrmf\fR.
.pp
A set of messages based on content may be selected by
use of the command \fIpick\fR.
This command searches through
messages in a folder and selects those that match a given
set of criteria.
These messages are then bound to a \*(lqsequence\*(rq name for use with other
\fIMH\fR commands.
The \fImark\fR command manipulates these sequences.
.pp
There are five commands enabling the user to create new
messages and send them:
\fIcomp\fR,
\fIdist\fR,
\fIforw\fR,
\fIrepl\fR,
and
\fIsend\fR.
The \fIcomp\fR command
provides the facility for the user to compose a
new message;
\fIdist\fR redistributes mail to additional addressees;
\fIforw\fR enables the user to forward messages; and
\fIrepl\fR facilitates the generation of a reply to an incoming message.
The last three commands may optionally annotate the original message.
Messages may be arbitrarily annotated with the \fIanno\fR command.
Once a draft has been constructed by one of the four above composition
programs,
a user\-specifiable program is run to query the user as to the disposition of
the draft prior to sending.
\fIMH\fR provides the simple \fIwhatnow\fR program to start users off.
If
a message is not sent directly by one of these commands, it may
be sent at a later time using the command
\fIsend\fR.
\fIMH\fR allows the use of any UNIX editor when composing a message.
For rapid entry, a special editor, \fIprompter\fR, is provided.
For programs, a special mail-sending program, \fImhmail\fR, is provided.
.pp
\fIMH\fR supports a personal aliasing facility which gives users the
capability to considerably shorten address typein
and use meaningful names for addresses.
The \fIali\fR program can be used to query \fIMH\fR as to the expansion of a
list of aliases.
After composing a message, but prior to sending, the \fIwhom\fR command
can be used to determine exactly who a message would go to.
.pp
\fIMH\fR provides a natural interface for telling the user's shell the names
of \fIMH\fR messages and folders.
The \fImhpath\fR program achieves this capability.
.pp
Finally, \fIMH\fR supports the UCI BBoards facility.
\fIbbc\fR can be used to query the status of a group of BBoards,
while \fImsh\fR can be used to read them.
The \fIburst\fR command can be used to \*(lqshred\*(rq digests of messages
into individual messages.
.pp
All of the elements summarized above
are described in more detail in the following sections.
Many of the
normal facilities of UNIX provide additional capabilities for
dealing with messages in various ways.
For example, it is
possible to print messages
on the line-printer without requiring any additional code within
\fIMH\fR\0.
Using standard UNIX facilities, any terminal output can be
redirected to a file for repeated or future viewing.
In general,
the flexibility and capabilities of the UNIX interface with the
user are preserved as a result of the integration of \fIMH\fR into the UNIX
structure.
.+c TUTORIAL
.pp
This tutorial provides a brief introduction to the \fIMH\fR commands.
It should be sufficient
to allow the user to read his mail, do some simple manipulations of
it, and create and send messages.
.pp
A message has two major pieces:  the
header and the body.
The body consists of the text of the message
(whatever you care to type in).
It follows the header and is separated from
it by an empty line.
(When you compose a message, the form that appears
on your terminal shows a line of dashes after the header.
This is for
convenience and is replaced by an empty line when the message is
sent.)  The header is composed of several components, including the
subject of the message and the person to whom it is addressed.
Each component starts with a name
and a colon; components must not start with a blank.
The text of the
component may take more than one line, but each continuation line must
start with a blank.
Messages typically have \*(lqTo:\*(rq, \*(lqcc:\*(rq, and
\*(lqSubject:\*(rq components.
When composing a message, you should include
the \*(lqTo:\*(rq and \*(lqSubject:\*(rq components;
the \*(lqcc:\*(rq (for people you want to send copies to) is not necessary.
.pp
The basic \fIMH\fR commands are
\fIinc\fR,
\fIscan\fR,
\fIshow\fR,
\fInext\fR,
\fIprev\fR,
\fIrmm\fR,
\fIcomp\fR,
and
\fIrepl\fR.
These are described below.

\fIinc\fR
.pp
When you get the message \*(lqYou have mail\*(rq, type the command \fIinc\fR.
You will get a \*(lqscan listing\*(rq such as:

.nf
.in +.5i
.ta \w'7+  'u +\w'11/26  'u +\w'To:norm  'u
7+	\07/13	Cas	revival of measurement work
8	10/\09	Norm	NBS people and publications
9	11/26	To:norm	question \*(<<Are there any functions
.re
.in -.5i
.fi
.pp
This shows the messages you received since the last time you
executed this command (\fIinc\fR adds these new messages to your inbox folder).
You can see this list again, plus a list of any
other messages you have, by using the
\fIscan\fR command.

\fIscan\fR
.pp
The scan listing shows the message number, followed by the
date and the sender.
(If you are the sender, the addressee in the \*(lqTo:\*(rq
component is displayed.
You may send yourself a message by including
your name among the \*(lqTo:\*(rq or \*(lqcc:\*(rq addressees.)
It also shows the message's subject; if
the subject is short, the first part of the body of the message is
included after the characters \*(<<.

.ne 5
\fIshow\fR
.pp
This command shows the current message, that is,
the first one of the new messages after an
\fIinc\fR.
If the message is not
specified by name (number), it is
generally the last message referred to by an \fIMH\fR command.
For example,


.ta \w'\fIshow\fR\0|\0\fIlpr\fR  'u
.ti .5i
^\fIshow\fP\05~^will show message 5.
.re

.pp
You can use the show command to copy a message or print a
message.

.(b L
.in .5i
.ta \w'\fIshow\fR\0|\0\fIlpr\fR  'u
^\fIshow\fR\0>\0\fIx\fR~^will copy the message to file x.
.br
^\fIshow\fR\0|\0\fIlpr\fR~^will print the message, using the \fIlpr\fR command.
.br
^\fInext\fR~^will show the message that follows the current message.
.br
^\fIprev\fR~^will show the message previous to the current message.
.br
^\fIrmm\fR~^will remove the current message.
.br
^\fIrmm\03\fR~^will remove message 3.
.)b

.ne 5
\fIcomp\fR
.pp
The
\fIcomp\fR command puts you in the editor to write or edit a message.
Fill in or
delete the \*(lqTo:\*(rq, \*(lqcc:\*(rq, and \*(lqSubject:\*(rq fields,
as appropriate, and type the body of the message.
Then
exit normally from the editor.
You will be asked
\*(lqWhat now?\*(rq.
Type a carriage return to see the options.
Typing \fBsend\fR
will cause the message to be sent; typing \fBquit\fR will cause an exit
from
\fIcomp\fR,
with the message draft saved.
.pp
If you quit without sending the message, it will be saved in a file
called <name>/Mail/draft (where <name> is your \fB$HOME\fR directory).
You can resume editing the message later with \*(lqcomp\0\-use\*(rq;
or you can send the message later, using the \fIsend\fR command.

.ne 4
\fIcomp\0\-editor\0prompter\fR
.pp
This command uses a different editor and is useful for preparing
\*(lqquick and dirty\*(rq messages.
It prompts you for each component of the
header.
Type the information for that component, or type a carriage
return to omit the component.
After that, type the body of the
message.
Backspacing is the only form of editing allowed with this editor.
When the body is complete, type a carriage return followed by <EOT>
(usually <CTRL-D>).
This completes the initial preparation of the message; from then on, use
the same procedures as with
\fIcomp\fR (above).

.ne 5
\fIrepl\fR
.br
\fIrepl\fR\0n 
.pp
This command makes up an initial message form with a header
that is appropriate for
replying to an existing message.
The message being answered is the
current message if no message number is mentioned, or n if a number
is specified.
After the header is completed, you can finish the message as in
\fIcomp\fR (above).
.pp
This is enough information to get you going using \fIMH\fR.
There are more commands,
and the commands described here have more features.
Subsequent sections
explain \fIMH\fR in complete detail.
The system is quite powerful if you
want to use its sophisticated features, but the foregoing commands
suffice for sending and receiving messages.
.pp
There are numerous additional capabilities you may wish to explore.
For example, the
\fIpick\fR command will select a subset of messages
based on specified criteria such as sender and/or subject.
Groups of
messages may be designated, as described in Sec. IV,
under \fBMessage Naming\fR.
The file \fI\&.mh\(ruprofile\fR can be used to tailor your use of
the message system to your needs and preferences, as described in Sec. IV,
under \fBThe User Profile\fR.
In general, you may
learn additional features of the system selectively, according to your
requirements,
by studying the relevant sections of this manual.
There is no need to
learn all the details of the system at once.
.+c "DETAILED DESCRIPTION"
.pp
This section describes the \fIMH\fR system in detail, including the components
of the user profile, the conventions for message naming, and some of
the other \fIMH\fR conventions.
Readers who are
generally familiar with computer systems will be able to follow
the principal ideas, although some details may be meaningful only to
those familiar with UNIX.
.uh "THE USER PROFILE"
.pp
The first time an \fIMH\fR command is issued by a new user, the system
prompts for a \*(lqPath\*(rq and creates an \fIMH\fR \*(lqprofile\*(rq.
.pp
Each \fIMH\fR user has a profile which contains tailoring
information for each individual program.
Other profile entries control the \fIMH\fR path (where folders and
special files are kept), folder and message protections, editor
selection, and default arguments for each \fIMH\fR program.
Each user of \fIMH\fR also has a context file which contains
current state information for the \fIMH\fR package
(the location of the context file is kept in the user's \fIMH\fR directory,
or may be named in the user profile).
When a folder becomes
the current folder, it is recorded in the user's context.
(Other state information is kept in the context file,
see the manual entry for \fImh\-profile\0\fR(5) for more details.)
In general,
the term \*(lqprofile entry\*(rq refer to entries in either the profile or
context file.
Users of \fIMH\fR needn't worry about the distinction,
\fIMH\fR handles these things automatically.
.pp
The \fIMH\fR profile is stored in the file \fI\&.mh\(ruprofile\fR in the
user's \fB$HOME\fR directory\**.
.(f
\** By defining the envariable \fB$MH\fR,
you can specify an alternate profile to be used by \fIMH\fR commands.
.)f
It has the format of a message without
any body.
That is, each profile entry is on one line, with a
keyword followed by a colon (:) followed by text particular to
the keyword.
.br
\(rh\ \ \&
\fIThis file must not have blank lines.\fR
.br
The keywords
may have any combination of upper and lower case.
(See the information of \fImh\-mail\fR later on in this manual
for a description of message formats.)
.pp
For the average \fIMH\fR user, the only profile entry of
importance is \*(lqPath\*(rq.
Path specifies a directory in which \fIMH\fR
folders and certain files such as \*(lqdraft\*(rq are found.
The
argument to this keyword must be a legal UNIX path that names an
existing directory.
If this path is not absolute
(i.e., does not begin with a \fB/\fR\0),
it will be presumed to start from the user's \fB$HOME\fR directory.
All folder and message references within
\fIMH\fR will relate to this path unless full path names are used.
.pp
Message protection defaults to 644, and folder protection to
711.
These may be changed by profile entries \*(lqMsg-Protect\*(rq
and \*(lqFolder-Protect\*(rq, respectively.
The argument to these
keywords is an octal number which is used as the UNIX file mode\**.
.(f
\** See \fIchmod\fR\0(1) in the \fIUNIX Programmer's Manual\fR\0[5].
.)f
.pp
When an \fIMH\fR program starts running, it looks through the
user's profile for an entry with a keyword matching the program's
name.
For example, when
\fIcomp\fR is run, it looks for a \*(lqcomp\*(rq
profile entry.
If one is found, the text of the profile entry is
used as the default switch setting until all defaults are overridden
by explicit switches passed to the program as arguments.
Thus the profile
entry \*(lqcomp:\0\-form\0standard.list\*(rq would direct
\fIcomp\fR to use the
file \*(lqstandard.list\*(rq as the message skeleton.
If an explicit
form switch is given to the
\fIcomp\fR command, it will override the
switch obtained from the profile.
.pp
In UNIX, a program may exist under several names,
either by linking or aliasing.
The actual invocation name is used by an \fIMH\fR
program when scanning for its profile defaults\**.
.(f
\** Unfortunately,
the shell does not preserve aliasing information when calling a program,
hence if a program is invoked by an alias different than its name,
the program will examine the profile entry for it's name,
not the alias that the user invoked it as.
The correct solution is to create a (soft) link in your \fI$HOME/bin\fR
directory to the \fIMH\fR program of your choice.
By giving this link a different name,
you can use an alternate set of defaults for the command.
.)f
Thus, each \fIMH\fR program
may have several names by which it can be invoked, and each name
may have a different set of default switches.
For example, if
\fIcomp\fR is invoked by the name
\fIicomp\fR,
the profile entry
\*(lqicomp\*(rq will control the default switches for this invocation of
the
\fIcomp\fR program.
This provides a powerful
definitional facility for commonly used switch settings.
.pp
The default editor
for editing within
\fIcomp\fR,
\fIrepl\fR,
\fIforw\fR,
and
\fIdist\fR,
is usually \fIprompter\fR,
but might be something else at your site,
such as \fI/usr/ucb/ex\fR or \fI/bin/e\fR.
A different editor may be used by specifying
the profile entry
\*(lqEditor: \*(rq.
The argument to \*(lqEditor\*(rq is the name of an
executable program or shell command file which can be found via
the user's $PATH defined search path, excluding the current
directory.
The \*(lqEditor:\*(rq profile specification
may in turn be overridden by a `\-editor\0<editor>'
profile switch associated with
\fIcomp\fR,
\fIrepl\fR,
\fIforw\fR,
or
\fIdist\fR.
Finally, an explicit editor switch specified with any
of these four commands will have ultimate precedence.
.pp
During message composition, more than one editor may be
used.
For example, one editor (such as \fIprompter\fR\0)
may be used
initially, and a second editor may be invoked later to revise
the message being composed
(see the discussion of
\fIcomp\fR in Section 5 for details).
A profile entry \*(lq<lasteditor>\-next:\0<editor>\*(rq specifies the name of
the editor to be used after a particular editor.
Thus \*(lqcomp:\0\-e\0prompter\*(rq
causes the initial text to be collected by
\fIprompter\fR,
and the profile entry \*(lqprompter\-next:\0ed\*(rq names ed as the
editor to be invoked for the next round of editing.
.pp
Some of the \fIMH\fR commands, such as
\fIshow\fR,
can be used on
message folders owned by others, if those folders are readable.
However,
you cannot write in someone else's folder.
All the \fIMH\fR command
actions not requiring write permission may be used with
a \*(lqread-only\*(rq folder.
.pp
Table 1 lists examples of some of the currently defined profile
entries, typical arguments, and the programs that reference the
entries.
.bp
.in .9i
.ll -.9i
.ta \w'<program>:\0default switches  'u
.sp 30p
.ce
Table 1
.sp 8p
.ce
P\s-2ROFILE\s0 C\s-2OMPONENTS\s0
.hl             \" ~12p preceding + 1v (12p) after
.nf
^^\fIMH\fR Programs that
^Keyword and Argument~^\ use Component\h'|\n(.lu-.9i'\v'4p'\l'|0'\v'-4p'  \" \l'..' does underlining
.sp
^Path:\0Mail~^All
^Current-Folder:\0inbox~^Most
^Editor:\0/usr/ucb/ex~^\fIcomp, dist, forw, repl\fR
^Inbox:\0inbox~^\fIinc, rmf\fR
^Msg\-Protect:\0644~^\fIinc\fR
^Folder\-Protect:\0711~^\fIinc, pick, refile\fR
^<program>:\0default switches~^All
^prompter\-next:\0ed~^\fIcomp, dist, forw, repl\fR
.hl
.ll +.9i
.in 0
.fi
.pp
Path
.u should
be present.
Current\-Folder is maintained
automatically by many \fIMH\fR commands (see the \fBContext\fR sections of
the individual commands in Sec. IV).
All other entries are optional,
defaulting to the values described above.
.uh "MESSAGE NAMING"
.pp
Messages may be referred to explicitly or implicitly when
using \fIMH\fR commands.
A formal syntax of message names is given in Appendix B, but the
following description should be sufficient for most \fIMH\fR users.
Some details of message naming that apply only to certain
commands are included in the description of those
commands.
.pp
Most of the \fIMH\fR commands accept arguments specifying one or
more folders, and one or more messages to operate on.
The use of
the word \*(lqmsg\*(rq as an argument to a command means that exactly one
message name may be specified.
A message name may be a number,
such as 1, 33, or 234, or it may be
one of the \*(lqreserved\*(rq message names:
first, last, prev, next, and cur.
(As a shorthand, a
period (\&.) is equivalent to cur.)
The meanings of these names are straightforward:
\*(lqfirst\*(rq is the first message in the folder;
\*(lqlast\*(rq is the last message in the folder;
\*(lqprev\*(rq is the message numerically previous to the current message;
\*(lqnext\*(rq is the message numerically following the current message;
\*(lqcur\*(rq (or \*(lq\&.\*(rq) is the current message in the folder.
In addition,
\fIMH\fR supports user\-defined\-sequences;
see the description of the \fImark\fR command for more information.
.pp
The default in commands that take a \*(lqmsg\*(rq argument is
always \*(lqcur\*(rq.
.pp
The word \*(lqmsgs\*(rq indicates that several messages may be
specified.
Such a specification consists of several message
designations separated by spaces.
A message designation is
either a message name or a message range.
A message range is a
specification of the form name1\-name2 or name1:n, where name1 and
name2 are message names and n is an integer.
The first form
designates all the messages from name1 to name2 inclusive; this
must be a non-empty range.
The second form specifies up to n
messages, starting with name1 if name1 is a number, or first,
cur, or next, and ending with name1 if name1 is last or
prev.
This interpretation of n is overridden if n is preceded
by a plus sign or a minus sign;
+n always means up to n messages starting with
name1, and \-n always means up to n messages ending with name1.
Repeated specifications of the same message have the same effect
as a single specification of
the message.
Examples of
specifications are:

.(b
1 5 7\-11 22
first 6 8 next
first\-10
last:5
.)b
.pp
The message name \*(lqall\*(rq is a shorthand for \*(lqfirst\-last\*(rq,
indicating all of the messages in the folder.
.pp
In commands that accept \*(lqmsgs\*(rq arguments, the default is
either cur or all, depending on which makes more sense.
.pp
In all of the \fIMH\fR commands, a plus sign preceding an argument
indicates a folder name.
Thus, \*(lq+inbox\*(rq is the name of the
user's standard inbox.
If an explicit folder argument is given
to an \fIMH\fR command, it will become the current folder (that is,
the \*(lqCurrent-Folder:\*(rq entry
in the user's profile will be changed to this folder).
In the case of the
\fIrefile\fR command, which
can have multiple output folders, a new source folder (other than
the default current folder) is specified by `\-src\0+folder'.
.uh "OTHER MH CONVENTIONS"
.pp
One very powerful feature of \fIMH\fR is that the \fIMH\fR commands may
be issued from any current directory, and the proper path to
the appropriate folder(s) will be taken from the user's profile.
If the \fIMH\fR path is not appropriate for a specific folder or file,
the automatic prepending of the \fIMH\fR path can be avoided by
beginning a folder or file name with \fB/\fR,
or with \fB\&./\fR or \fB\&.\&./\fR component.
Thus any specific absolute path may be specified along with any path
relative to the current working directory.
.pp
Arguments to the various programs may be given in any order,
with the exception of a few switches whose arguments must follow
immediately, such as `\-src\0+folder' for \fIrefile\fR.
.pp
Whenever an \fIMH\fR command prompts the user, the valid options
will be listed in response to a <RETURN>.
(The first of the
listed options is the default if end-of-file is encountered,
such as from a command file.)
A valid response is any \fIunique\fR abbreviation of one of the listed options.
.pp
Standard UNIX documentation conventions are used in this report
to describe \fIMH\fR command syntax.
Arguments enclosed in brackets
([ ]) are optional; exactly one of the arguments enclosed
within braces ({ }) must be specified, and all other
arguments are required.
The use of ellipsis dots (...) indicates
zero or more repetitions of the previous item.
For example,
\*(lq+folder ...\*(rq would indicate that one or more \*(lq+folder\*(rq
arguments is required
and \*(lq[+folder ...]\*(rq indicates that 0 or more
\*(lq+folder\*(rq arguments may be given.
.pp
\fIMH\fR departs from UNIX standards by using switches that consist of
more than one character, e.g. `\-header'.
To minimize typing,
only a unique abbreviation of a switch need be typed; thus, for
`\-header', `\-hea' is probably sufficient, depending on the
other switches the command accepts.
Each \fIMH\fR program
accepts the switch `\-help' (which \fBmust\fR be spelled out fully)
and produces a syntax description and a list of switches.
In the
list of switches, parentheses indicate required characters.
For example, all `\-help' switches will appear as \*(lq\-(help)\*(rq,
indicating that no abbreviation is accepted.
Furthermore,
the `\-help' switch tells the version of the \fIMH\fR program you invoked.
.pp
Many \fIMH\fR switches have both on and off forms, such as
`\-format' and `\-noformat'.
In many of the descriptions which follow,
only one form is defined; the other form, often used to
nullify profile switch settings, is assumed to be the opposite.
.br
.bp
.uh "MH COMMANDS"
.pp
The \fIMH\fR package comprises several programs:
.\"    I pity the fool who tampers with the next line...
.ds ZZ -me
.so mh.me
.pp
These programs are described below.
The form of the descriptions
conforms to the standard
form for the description of UNIX commands.
.if t \{
.ll 6.5i
.lt 6.5i
\}
.fo '[mh.6]'MH.6.8'UCI version'
.de SC
.\" .he '\\$1(\\$2)'-%-'\\$1(\\$2)'
.bp
.(x
.ti .8i
\\$1
.)x
..
.de NA
.b \\s-2NAME\\s0
.ti .5i
..
.de SY
.sp
.b \\s-2SYNOPSIS\\s0
.in 1i
.ti .5i
.na
..
.de DE
.ad
.sp
.in 0
.b  \\s-2DESCRIPTION\\s0
.sp
.fi
.in .5i
..
.de Uh
.ad
.sp
.ti -.25i
.b "\\s-2\\$1\\s0"
.sp
.fi
..
.de Hh
.ad
.sp
.in 0
.b "\\s-2Helpful Hints\\s0"
.sp
.fi
.in .5i
..
.de Fi
.(b L
.ti 0
.b \\s-2Files\\s0
.ta \w'/usr/contrib/mh-6.8/lib/ExtraBigFileName  'u
..
.de Pr
.)b
.(b L F
.ta \w'ExtraBigProfileName  'u
.ti 0
.b "\\s-2Profile Components\\s0"
.ti .5i
..
.de Ps
.ti .5i
..
.de Sa
.)b
.(b L F
.ti 0
.b "\\s-2See Also\\s0"
.br
..
.de De
.)b
.(b L
.in .5i
.ti 0
.b \\s-2Defaults\\s0
..
.de Ds
..
.de Co
.)b
.(b L F
.ti 0
.b \\s-2Context\\s0
.br
..
.de Hi
.)b
.(b L F
.ti 0
.b \\s-2History\\s0
.br
..
.de Bu
.)b
.(b L F
.ti 0
.b \\s-2Bugs\\s0
.br
..
.de En
.)b
.in 0
..
.de Hd
.eh 'USD:8-%'The RAND Message Handling System: User Manual'\\$1(\\$2)'
.oh '\\$1(\\$2)'The RAND Message Handling System: User Manual'USD:8-%'
..
.po -.50i
.Hd ALI 1
.so ali.me
.Hd ANNO 1
.so anno.me
.Hd BBC 1
.so bbc.me
.Hd BBOARDS 1
.so bboards.me
.\" No .Hd here because the bboards manpage is a full page one which triggers
.\" the eh/oh macro before the end of it's so.  The (hack) solution is to
.\" put the eh/oh calls in bboards.me.
.so burst.me
.Hd COMP 1
.so comp.me
.Hd DIST 1
.so dist.me
.Hd FOLDER 1
.so folder.me
.Hd FORW 1
.so forw.me
.Hd INC 1
.so inc.me
.Hd MARK 1
.so mark.me
.Hd MHL 1
.so mhl.me
.Hd MHMAIL 1
.so mhmail.me
.Hd MHN 1
.so mhn.me
.Hd MHOOK 1
.so mhook.me
.Hd MHPARAM 1
.so mhparam.me
.Hd MHPATH 1
.so mhpath.me
.Hd MSGCHK 1
.so msgchk.me
.Hd MSH 1
.so msh.me
.Hd NEXT 1
.so next.me
.Hd PACKF 1
.so packf.me
.Hd PICK 1
.so pick.me
.Hd PREV 1
.so prev.me
.Hd PROMPTER 1
.so prompter.me
.Hd RCVSTORE 1
.so rcvstore.me
.Hd REFILE 1
.so refile.me
.Hd REPL 1
.so repl.me
.Hd RMF 1
.so rmf.me
.Hd RMM 1
.so rmm.me
.Hd SCAN 1
.so scan.me
.Hd SEND 1
.so send.me
.Hd SHOW 1
.so show.me
.Hd SLOCAL 1
.so slocal.me
.Hd SORTM 1
.so sortm.me
.Hd VMH 1
.so vmh.me
.Hd WHATNOW 1
.so whatnow.me
.Hd WHOM 1
.so whom.me
.eh 'USD:8-%''The RAND Message Handling System: User Manual'
.oh 'The RAND Message Handling System: User Manual''USD:8-%'
.po +.50i
.\" .he ''-%-''
.fo ''''
.br
.if t \{
.ll 32P
.lt 32P
\}
.bp
.uh "MORE DETAILS"
.pp
This section describes some of the more intense points of the \fIMH\fR system,
by expanding on topics previously discussed.
The format presented conforms to the standard form for the description of UNIX
documentation.
.if t \{
.ll 6.5i
.lt 6.5i
\}
.fo '[mh.6]'MH.6.8'UCI version'
.po -.50i
.Hd MH-ALIAS 5
.so mh-alias.me
.Hd MH-FORMAT 5
.so mh-format.me
.Hd MH-MAIL 5
.so mh-mail.me
.Hd MH-PROFILE 5
.so mh-profile.me
.Hd MH-SEQUENCE 5
.so mh-sequence.me
.Hd AP 5
.so ap.me
.Hd CONFLICT 5
.so conflict.me
.Hd DP 5
.so dp.me
.Hd FMTDUMP 5
.so fmtdump.me
.Hd INSTALL-MH 5
.so install-mh.me
.Hd POST 5
.so post.me
.eh 'USD:8-%''The RAND Message Handling System: User Manual'
.oh 'The RAND Message Handling System: User Manual''USD:8-%'
.po +.50i
.\" .he ''-%-''
.fo ''''
.br
.if t \{
.ll 32P
.lt 32P
\}
.+c "REPORTING PROBLEMS"
.pp
If problems are encountered with an \fIMH\fR program,
the problems should be reported to the local maintainers of \fIMH\fR.
When doing this,
the name of the program should be reported,
along with the version information for the program.
To find out what version of an \fIMH\fR program is being run,
invoke the program with the `\-help' switch.
In addition to listing the syntax of the command,
the program will list information pertaining to its version.
This information includes the version of \fIMH\fR,
the host it was generated on,
and the date the program was loaded.
A second line of information,
found on versions of \fIMH\fR after #5.380 include \fIMH\fR configuration
options.
For example,

.in +.5i
version: MH 6.1 #1[UCI] (nrtc-gremlin) of Wed Nov  6 01:13:53 PST 1985
.br
options: [BSD42] [MHE] [NETWORK] [SENDMTS] [MMDFII] [SMTP] [POP]
.in -.5i

The `6.1 #1[UCI]' indicates that the program is from the UCI \fImh.6\fR
version of \fIMH\fR.
The program was generated on the host `nrtc-gremlin' on
`Wed Nov  6 01:13:53 PST 1985'.
It's usually a good idea to send the output of the `\-help' switch along
with your report.

If there is no local \fIMH\fR maintainer,
try the address \fBBug-MH\fR.
If that fails, use the Internet mailbox \fBBug-MH@ICS.UCI.EDU\fR.

.+c "ADVANCED FEATURES"
.de UH
.lp
.b "\\$1"
.pp
.(x
.ti .8i
\\$1
.)x
..
.pp
This section describes some features of \fIMH\fR that were included strictly
for advanced \fIMH\fR users.
These capabilities permit \fIMH\fR to exhibit more powerful behavior for the
seasoned \fIMH\fR users.
.uh "USER\-DEFINED SEQUENCES"
.pp
User\-defined sequences allow the \fIMH\fR user a tremendous amount of power
in dealing with groups of messages in the same folder
by allowing the user to bind a group of messages to a meaningful symbolic
name.
The user may choose any name for a message sequence,
as long as it consists of alphanumeric characters and does not conflict with
the standard \fIMH\fR reserved message names
(e.g., \*(lqfirst\*(rq, etc).
After defining a sequence,
it can be used wherever an \fIMH\fR command expects a `msg' or `msgs'
argument.
.pp
A restricted form of message ranges are allowed with user\-defined
sequences. The form \*(lqname:n\*(rq, specifies up to the first `n' messages
which are part of the user\-defined sequence `name'.
A leading plus sign is allowed on `n', but is ignored.
The interpretation of n is overridden if n is preceded
by a minus sign;
`\-n' always means up to the last `n' messages which are part of the
sequence `name'.
.pp
Although all \fIMH\fR commands expand user\-defined sequences as appropriate,
there are two commands that allow the user to define and manipulate them:
\fIpick\fR and \fImark\fR.
.UH "Pick and User\-Defined Sequences"
.pp
Most users of \fIMH\fR will use user\-defined sequences only with
the \fIpick\fR command.
By giving the `\-sequence\ name' switch to \fIpick\fR
(which can occur more than once on the command line),
each sequence named is defined as those messages which \fIpick\fR matched
according the the selection criteria it was given.
Hence,

.ti +.5i
pick\0\-from\0frated\0\-seq\0fred

finds all those messages in the current folder which were from
\*(lqfrated\*(rq,
creates a sequence called \*(lqfred\*(rq,
and then adds them to the sequence.
The user could then invoke

.ti +.5i
scan\0fred

to get a \fIscan\fR listing of those messages.
Note that by default,
\fIpick\fR creates the named sequences
before it adds the selected messages to the sequence.
Hence, if the named sequence already existed,
the sequence is destroyed prior to being re-defined
(nothing happens to the messages that were a part of this sequence,
they simply cease to be members of that sequence).
By using the `\-nozero' switch, this behavior can be inhibited,
as in

.in +.5i
pick\0\-from\0frated\0\-seq\0sgroup
.br
pick\0\-from\0fear\0\-seq\0sgroup\0\-nozero
.br
pick\0\-from\0freida\0\-seq\0sgroup\0\-nozero
.in -.5i

finds all those messages in the current folder which were from
\*(lqfrated\*(rq, \*(lqfear\*(rq, or \*(lqfreida\*(rq,
and defines the sequence called \*(lqsgroup\*(rq as exactly those messages.
These operations amounted to an \*(lqinclusive\-or\*(rq of three selection
criteria,
using \fIpick\fR,
one can also generate the \*(lqand\*(rq of some selection criteria as well:

.in +.5i
pick\0\-from\0frated\0\-seq\0fred
.br
pick\0\-before\0friday\0\-seq\0fred\0fred
.in -.5i

This example defines the sequence called \*(lqfred\*(rq as exactly those
messages from \*(lqfrated\*(rq that were dated prior to \*(lqfriday\*(rq.\**
.(f
\** Of course,
it is much easier to simply use the built\-in boolean operation of
\fIpick\fR to get the desired results:

.ti +.5i
pick\0\-from\0frated\0\-or\0\-from\0fear\0\-or\0\-from\0freida\0\-seq\0sgroup

and

.ti +.5i
pick\0\-from\0frated\0\-and\0\-before\0friday\0\-seq\0fred

do exactly the same thing as the five commands listed above.
Hence, the `\-nozero' option to \fIpick\fR is only useful to manipulate
existing sequences.
.)f
.pp
\fIPick\fR is normally used as a back\-quoted command,
for example,

.ti +.5i
scan\0`pick\0\-from\0postmaster`

Now suppose that the user decides that another command should be issued,
using exactly those messages.
Since,
\fIpick\fR wasn't given a `\-sequence\ name' argument in this example,
the user would end\-up typing the entire back\-quoted command again.
A simpler way is to add a default sequence name to the \&.mh\(ruprofile.
For example,

.ti +.5i
pick:\0\-seq\0select\0\-list

will tell \fIpick\fR to always define the sequence \*(lqselect\*(rq whenever
it's run.
The `-list' is necessary since the `\-sequence\ name' switch sets `\-nolist'
whenever the former is encountered.
Hence, this profile entry makes \fIpick\fR define the \*(lqselect\*(rq
sequence and otherwise behave exactly as if there was no profile entry at all.
.UH "Mark and User\-Defined Sequences"
.pp
The \fImark\fR command lets the user perform low\-level manipulation of
sequences,
and also provides a well\-needed debug facility to the
implementors/developers/maintainers of \fIMH\fR (the \fIMH\fR\-hacks).
In the future, a user\-friendly \*(lqfront\-end\*(rq for \fImark\fR will
probably be developed to give the \fIMH\fR user a way to take better
advantage of the underlying facilities.
.UH "Public and Private User\-Defined Sequences"
.pp
There are two kinds of sequences: \fIpublic\fR sequences,
and \fIprivate\fR sequences.
\fIPublic\fR sequences of a folder are accessible to any \fIMH\fR user that
can read that folder and are kept in the \&.mh\(rusequences file in the folder.
\fIPrivate\fR sequences are accessible only to the \fIMH\fR user that defined
those sequences and are kept in the user's \fIMH\fR context file.
By default,
\fIpick\fR (and \fImark\fR\0) create \fIpublic\fR sequences
if the folder for which the sequences are being defined is writable by the
\fIMH\fR user.
Otherwise, \fIprivate\fR sequences are created.
This can be overridden with the `\-public' and `\-nopublic' switches.
.UH "Sequence Negation"
.pp
In addition to telling an \fIMH\fR command to use the messages in the sequence
\*(lqseen\*(rq, as in

.ti +.5i
refile\0seen\0+old

it would be useful to be easily able to tell an \fIMH\fR command to use all
messages \fIexcept\fR those in the sequence.
One way of doing this would be to use \fImark\fR and define the sequence
explicitly,
as in

.ti +.5i
mark\0\-delete\0\-zero\0seen\0\-seq\0notseen

which,
owing to \fImark\fR\0's cryptic interpretation of `\-delete' and `\-zero',
defines the sequence \*(lqnotseen\*(rq to be all messages not in the sequence
\*(lqseen\*(rq.
Naturally,
anytime the sequence \*(lqseen\*(rq is changed,
\*(lqnotseen\*(rq will have to be updated.
Another way to achieve this is to define the entry
\*(lqSequence\-Negation:\*(rq in the \&.mh\(ruprofile.
If the entry was

.ti +.5i
Sequence\-Negation:\0not

then anytime an \fIMH\fR command was given \*(lqnotseen\*(rq as a `msg' or
`msgs' argument,
it would substitute all messages that are not a member of the sequence
\*(lqseen\*(rq.
That is,

.ti +.5i
refile\0notseen\0+new

does just that.
The value of the \*(lqSequence\-Negation:\*(rq entry in the profile can be
any string.
Hence,
experienced users of \fIMH\fR do not use a word,
but rather a special character which their shell does not interpret
(users of the \fICShell\fR use a single caret or circumflex (usually shift\-6),
while users of the Bourne shell use an exclamation\-mark).
This is because there is nothing to prevent a user of \fIMH\fR from defining a
sequence with this string as its prefix,
if the string is nothing by letters and digits.
Obviously,
this could lead to confusing behavior
if the \*(lqSequence\-Negation:\*(rq entry leads \fIMH\fR to believe that two
sequences are opposites by virtue of their names differing by the prefix
string.
.UH "The Previous Sequence"
.pp
Many times users find themselves issuing a series of commands on the same
sequences of messages.
If the user first defined these messages as a sequence,
then considerable typing may be saved.
If the user doesn't have this foresight,
\fIMH\fR provides a handy way of having \fIMH\fR remember the `msgs' or
`msg' argument last given to an \fIMH\fR command.
If the entry \*(lqPrevious\-Sequence:\*(rq is defined in the
\&.mh\(ruprofile,
then when the command finishes,
it will define the sequence(s) named in the value of this entry as being
exactly those messages that were specified.
Hence, a profile entry of

.ti +.5i
Previous\-Sequence:\0pseq

directs any \fIMH\fR command that accepts a `msg' or `msgs' argument to
define the sequence \*(lqpseq\*(rq as those messages when it finishes.
More than one sequence name may be placed in this entry,
separated with spaces.
The one disadvantage of this approach
is that the \fIMH\fR progams have to update the sequence information for
the folder each time they run
(although most programs read this information,
usually only \fIpick\fR and \fImark\fR have to write this information out).
.UH "The Unseen Sequence"
.pp
Finally, some users like to distinguish between messages which have been
previously seen by them.
Both \fIinc\fR and \fIshow\fR honorthe profile entry
\*(lqUnseen\-Sequence\*(rq to support this activity.
Whenever \fIinc\fR places new messages in a folder,
if the entry \*(lqUnseen\-Sequence\*(rq is defined in the \&.mh\(ruprofile,
then when the command finishes,
\fIinc\fR will add the new messages to the sequence(s) named in the value of
this entry.
Hence, a profile entry of

.ti +.5i
Unseen\-Sequence:\0 unseen

directs \fIinc\fR to add new messages to the sequence \*(lqunseen\*(rq.
Unlike the behavior of the \*(lqPrevious\-Sequence\*(rq entry in the profile
however,
the sequence(s) will \fBnot\fR be zero'd.
.pp
Similarly,
whenever \fIshow\fR (or \fInext\fR or \fIprev\fR\0) displays a message,
they remove those messages from any sequences named by the
\*(lqUnseen\-Sequence\*(rq entry in the profile.
.uh "COMPOSITION OF MAIL"
.pp
There are a number of interesting advanced facilities for the composition of
outgoing mail.

.UH "The Draft Folder"
.pp
The \fIcomp\fR, \fIdist\fR, \fIforw\fR, and \fIrepl\fR commands have two
switches, `\-draftfolder\0+folder' and `\-draftmessage\0msg'.
If `\-draftfolder\0+folder' is used,
these commands are directed to construct a draft message in the indicated
folder.
(The \*(lqDraft\-Folder:\*(rq profile entry may be used to declare a
default draft folder for use with
\fIcomp\fR, \fIdist\fR, \fIforw\fR, and \fIrepl\fR)
If `\-draftmessage\0msg' is not used, it defaults to `new'
(unless the user invokes \fIcomp\fR with `\-use',
in which case the default is `cur').
Hence, the user may have several message compositions in progress
simultaneously.
Now, all of the \fIMH\fR tools are available on each of the user's message
drafts
(e.g., \fIshow\fR, \fIscan\fR, \fIpick\fR, and so on).
If the folder does not exist,
the user is asked if it should be created (just like with \fIrefile\fR\0).
Also,
the last draft message the user was composing is known as `cur' in the
draft folder.
.pp
Furthermore,
the \fIsend\fR command has these switches as well.
Hence, from the shell,
the user can send off whatever drafts desired using the
standard \fIMH\fR `msgs' convention with `\-draftmessage msgs'.
If no `msgs' are given, it defaults to `cur'.
.pp
In addition,
all five programs have a `\-nodraftfolder' switch,
which undoes the last occurrence of `\-draftfolder\0folder'
(useful if the latter occurs in the user's \fIMH\fR profile).
.pp
If the user does not give the `\-draftfolder\0+folder' switch,
then all these commands act ``normally''.
Note that the `\-draft' switch to \fIsend\fR and \fIshow\fR
still refers to the file called `draft' in the user's \fIMH\fR
directory.
In the interests of economy of expression,
when using \fIcomp\fR or \fIsend\fR,
the user needn't prefix the draft `msg' or `msgs' with
`\-draftmessage'.
Both of these commands accept a `file' or `files' argument,
and they will, if given `\-draftfolder\0+folder' treat these arguments
as `msg' or `msgs'.\**
.(f
\** This may appear to be inconsistent, at first,
but it saves a lot of typing.
.)f
Hence,

.ti +.5i
send -draftf +drafts first

is the same as

.ti +.5i
send -draftf +drafts -draftm first

.pp
To make all this a bit more clear, here are some examples.
Let's assume that the following entries are in the \fIMH\fR profile:

.in +.5i
.nf
Draft\-Folder: +drafts
sendf: -draftfolder +drafts
.fi
.in -.5i

Furthermore,
let's assume that the program \fIsendf\fR is a (symbolic) link in the user's 
\fB$HOME/bin/\fR directory to \fIsend\fR.
Then, any of the commands

.in +.5i
.nf
comp
dist
forw
repl
.fi
.in -.5i

constructs the message draft in the `draft' folder using the `new'
message number.
Furthermore,
they each define `cur' in this folder to be that message draft.
If the user were to use the \fIquit\fR option at `What now?' level,
then later on,
if no other draft composition was done,
the draft could be sent with simply

.ti +.5i
sendf

Or,
if more editing was required,
the draft could be edited with

.ti +.5i
comp -use

Instead,
if other drafts had been composed in the meantime,
so that this message draft was no longer known as `cur' in the `draft'
folder,
then the user could \fIscan\fR the folder to see which message draft in the
folder should be used for editing or sending.
Clever users could even employ a back-quoted \fIpick\fR to do the work:

.ti +.5i
comp -use `pick +drafts -to bug-mh`

or

.ti +.5i
sendf `pick +drafts -to bug-mh`

Note that in the \fIcomp\fR example,
the output from \fIpick\fR must resolve to a single message draft
(it makes no sense to talk about composing two or more drafts with one
invocation of \fIcomp\fR\0).
In contrast,
in the \fIsend\fR example,
as many message drafts as desired can appear,
since \fIsend\fR doesn't mind sending more than one draft at a time.
.pp
Note that the argument `\-draftfolder\0+folder' is not
included in the profile entry for \fIsend\fR,
since when \fIcomp\fR, et. al., invoke \fIsend\fR directly,
they supply \fIsend\fR with the UNIX pathname of the message draft,
and \fBnot\fR a `draftmessage\0msg' argument.
As far as \fIsend\fR is concerned,
a \fIdraft folder\fR is not being used.
.pp
It is important to realize that \fIMH\fR treats the draft folder like a standard
\fIMH\fR folder in nearly all respects.
There are two exceptions:
.u first ,
under no circumstancs will the `\-draftfolder\0folder' switch cause the
named folder to become the current folder.\**
.(f
\** Obviously,
if the folder appeared in the context of a standard `+folder'
argument to an \fIMH\fR program, as in

.ti +.5i
scan +drafts

it might become the current folder, depending on the context changes of the
\fIMH\fR program in question.
.)f
.u Second ,
although conceptually \fIsend\fR deletes the `msgs' named in the draft
folder,
it does not call `delete-prog' to perform the deletion.

.UH "What Happens if the Draft Exists"
.pp
When the \fIcomp\fR, \fIdist\fR, \fIforw\fR, and \fIrepl\fR commands are
invoked and the draft you indicated already exists,
these programs will prompt the user for a reponse directing the program's
action.
The prompt is

.ti +.5i
Draft ``/usr/src/uci/mh/mhbox/draft'' exists (xx bytes).
.ti +.5i
Disposition?

The appropriate responses and their meanings are:
.u replace :
deletes the draft and starts afresh;
.u list :
lists the draft;
.u refile :
files the draft into a folder and starts afresh;
and,
.u quit :
leaves the draft intact and exits.
In addition, if you specified `\-draftfolder\0folder' to the command,
then one other response will be accepted:
.u new :
finds a new draft,
just as if `\-draftmessage\0new' had been given.
Finally, the \fIcomp\fR command will accept one more response:
.u use :
re-uses the draft,
just as if `\-use' had been given.

.UH "The Push Option at What now? Level"
.pp
The \fIpush\fR option to the \*(lqWhat now?\*(rq query
in the \fIcomp\fR, \fIdist\fR, \fIforw\fR, and \fIrepl\fR commands,
directs the command to \fIsend\fR the draft
in a special detached fashion,
with all normal output discarded.
If \fIpush\fR is used and the draft can not be sent,
then \fIMH\fR will send the user a message,
indicating the name of the draft file,
and an explanation of the failure.
.\" Although using \fIpush\fR calls \fIsend\fR\0(1),
.\" the \fIsend\fR command will consult the profile entry for \fIpush\fR.
.pp
The user can also invoke \fIsend\fR from the shell with the `\-push'
switch,
which makes \fIsend\fR act like it had been \fIpush\fR\0'd by one of the
composition commands.
.\" composition commands.\**
.\" .(f
.\" \** Note that in this case,
.\" \fIsend\fR consults the profile entry for whatever name it was invoked as,
.\" such as \fIsendf\fR.
.\" .)f
.pp
By using \fIpush\fR, the user can free the shell to do other things,
because it appears to the shell that the \fIMH\fR command has finished.
As a result the shell will immediately prompt for another command,
despite the fact that the command is really still running.
Note that if the user indicates that annotations are to be performed
(with `\-annotate' to \fIdist\fR, \fIforw\fR, or \fIrepl\fR),
the annotations will be performed after the message has been
successfully sent.
This action will appear to occur asynchronously.
Obviously, if one of the messages that is to be annotated is
removed before the draft has been successfully sent,
then when \fIMH\fR tries to make the annotations,
it won't be able to do so.
In previous versions of \fIMH\fR,
this resulted in an error message mysteriously appearing on the user's
terminal.
In \fImh.5\fR and later versions,
in this special circumstance, no error will be generated.
.pp
If send is \fIpush\fR\0'd,
then the `\-forward' switch is examined if a failure notice is generated.
If given,
then the draft is forwarded with the failure notice sent to the user.
This allows rapid \fIburst\fR\0'ing of the failure notice to retrieve the
unsent draft.

.UH "Options at What now? Level"
.pp
By default,
the message composition programs call a program called \fIwhatnow\fR before
the initial draft composition.
The \fIMH\fR user can specify any program for this.
Following is some information about the default \*(lqWhat now?\*(rq level.
More detailed information can be found in the \fIwhatnow\fR\0(1) manual entry.
.pp
When using the \fIcomp\fR, \fIdist\fR, \fIforw\fR, and \fIrepl\fR commands at
\*(lqWhat now?\*(rq level,
the \fIedit\fR, \fIlist\fR, \fIheaders\fR, \fIrefile\fR,
and (for the \fIdist\fR and \fIrepl\fR commands) the \fIdisplay\fR options
will pass on any additional arguments given them to whatever program they
invoke.
.pp
In \fImh.1\fR (the original RAND \fIMH\fR\0)
and \fImh.2\fR (the first UCI version of \fIMH\fR\0),
\fIMH\fR used a complicated heuristic to determine if the draft should be
deleted or preserved after an unsuccessful edit.
In \fImh.3\fR,
\fIMH\fR was changed to preserve the draft always,
since \fIcomp\fR, et. al.,
could usually look at a draft, apply another set of heuristics,
and decide if it was important or not.
With the notion of a \fIdraft folder\fR, 
in which one by default gets a `new' message draft,
the edit deletion/preservation algorithm was re-implemented,
to keep the draft folder from being cluttered with aborted edits.
.pp
Also,
note that by default,
if the draft cannot be successfully sent,
these commands return to \*(lqWhat now?\*(rq level.
But, when \fIpush\fR is used, this does not happen (obviously).
Hence,
if these commands were expected to annotate any messages,
this will have to be done by hand, later on, with the \fIanno\fR command.
.pp
Finally, if the `\-delete' switch is not given to the \fIquit\fR option,
then these commands will inform the user of the name of the unsent draft file.

.UH "Digests"
.pp
The \fIforw\fR command has the beginnings of a digestifying facility,
with the `\-digest\ list', `\-issue\ number', and `\-volume\ number' switches.

If \fIforw\fR is given \*(lqlist\*(rq to the `\-digest' switch
as the name of the discussion group,
and the `\-issue\ number' switch is not given,
then \fIforw\fR looks for an entry in the user's \fIMH\fR context called
\*(lq\fIdigest\fR\-issue\-list\*(rq and increments its value to use as the
issue number.
Similarly,
if the `\-volume\ number' switch is not given,
then \fIforw\fR looks for \*(lq\fIdigest\fR\-volume\-list\*(rq
(but does not increment its value) to use as the volume number.

Having calculated the name of the digest and the volume and issue numbers,
\fIforw\fR will now process the components file using the same format string
mechanism used by \fIrepl\fR.
The current `%'\-escapes are:

.nf
.ta \w'escape  'u +\w'integer  'u
\fIescape\fR	\fItype\fR	\fIsubstitution\fR
digest	string	digest name
msg	integer	issue number
cur	integer	volume number
.re
.fi

In addition, to capture the current date,
any of the escapes valid for \fIdp\fR\0(8) are also valid for \fIforw\fR.

The default components file used by \fIforw\fR when in digest mode is:

.nf
.in +.5i
.ne 10
.eo
.so /usr/contrib/mh-6.8/lib/digestcomps
.ec
.in -.5i
.fi

Hence, when the `\-digest' switch is present,
the first step taken by \fIforw\fR is to expand the format strings in the
component file.
The next step is to compose the draft using
the standard digest encapsulation algorithm
(even putting an \*(lqEnd of list Digest\*(rq trailer in the draft).
Once the draft is composed by \fIforw\fR,
\fIforw\fR writes out the volume and issue profile entries for the digest,
and then invokes the editor.

Naturally, when composing the draft,
\fIforw\fR will honor the `\-filter\ filterfile' switch,
which is given to \fImhl\fR to filter each message being forwarded prior to
encapsulation in the draft.
A good filter file to use, which is called \fImhl.digest\fR, is:

.nf
.in +.5i
.ne 10
.eo
.so /usr/contrib/mh-6.8/lib/mhl.digest
.ec
.in -.5i
.fi

.uh "FOLDER HANDLING"
.pp
There are two interesting facilities for manipulating folders:
relative folder addressing,
which allows a user to shorten the typing of long folder names;
and
the folder\-stack,
which permits a user to keep a stack of current folders.

.UH "Relative Folder Addressing"
.pp
By default, when `+folder' is given,
and the folder name is not absolute
(does not start with \fB/\fR, \fB\&./\fR, or \fB\&.\&./\fR),
then the UNIX pathname of the folder is interpreted relative to the user's
\fIMH\fR directory.
Although this mechanism works fine for top\-level folders and their immediate
sub\-folders,
once the depth of the sub\-folder tree grows, it becomes rather unwieldly:

.ti +.5i
scan\0+mh/mh.4/draft/flames

is a lot of typing.
\fIMH\fR can't do anything if the current folder was \*(lq+inbox\*(rq,
but if the current folder was, say, \*(lq+mh/mh.4/draft\*(rq,
\fIMH\fR has a short\-hand notation to reference a sub\-folder of the
current folder.
Using the `@folder' notation,
the \fIMH\fR user can direct any \fIMH\fR program which expects a `+folder'
argument to look for the folder relative to the current folder instead of the
user's \fIMH\fR directory.
Hence, if the current folder \fIwas\fR \*(lq+mh/mh.4/draft\*(rq,
then

.ti +.5i
scan\0@flames

would do the trick handily.
In addition, if the current folder \fIwas\fR \*(lq+mh/mh.4/draft\*(rq,

.ti +.5i
scan\0@../pick

would scan the folder \*(lq+mh/mh.4/pick\*(rq,
since, in the UNIX fashion,
it references the folder \*(lqpick\*(rq which is a sub\-folder of
the folder that is the parent of the current folder.
Since most advanced \fIMH\fR users seem to exhibit a large degree of locality
in referencing folders when they process mail,
this convention should receive a wide range of uses.

.UH "The Folder\-Stack"
.pp
The \fIfolder\-stack\fR mechanism in \fIMH\fR gives the \fIMH\fR user a
facility similar to the \fICShell\fR\0's directory\-stack.
Simply put,

.ti +.5i
folder\0\-push\0+foo

makes \*(lqfoo\*(rq the current folder,
saving the folder that was previously the current folder on the
\fIfolder\-stack\fR.
As expected,

.ti +.5i
folder\0\-pop

takes the top of the \fIfolder\-stack\fR and makes it the current folder.
Each of these switches lists the \fIfolder\-stack\fR when they execute.
It is simple to write a \fIpushf\fR command as a shell script.
It's one line:

.ti +.5i
exec\0folder\0\-push\0$@

Probably a better way is to link \fIfolder\fR to the $HOME/bin/ directory under
the name of \fIpushf\fR and then add the entry

.ti +.5i
pushf:\0\-push

to the \&.mh\(ruprofile.
.pp
The manual page for \fIfolder\fR discusses the analogy between the
\fICShell\fR directory stack commands and the switches in \fIfolder\fR which
manipulate the \fIfolder\-stack\fR.
The \fIfolder\fR command uses the context entry `Folder\-Stack:' to keep
track of the folders in the user's stack of folders.
\"
\"              On to the Appendices
\"
.fo ''-%-''
.\" .he ''''
.(x
.sp
Appendix
.)x _
.de $c                          \" Major Heading printer
.ce
Appendix \\n+(ch
.sp 2p
.ce
.b "\\s12\\$1\\s0"              \" 12 Point Bold Header
.(x
\ \ \ \\n(ch.\\ \\ \\$2
.)x
.sp 45p				\" 45 points or about 1/2 inch
..
.++ A
.bp
.$c "COMMAND SUMMARY" "Command Summary"
.po -.50i
.so mh-chart.me
.po +.50i
.if t \{
.ll 32P
.lt 32P
\}
.bp
.$c "MESSAGE NAME BNF" "Message Name BNF"

.nf
.in 1i
.ta \w'user-defined-sequence 'u +\w':=  'u +\w'user-defined-sequence  'u
msgs	:=	msgspec	|
		msgs msgspec

msgspec	:=	msg	|
		msg-range	|
		msg-sequence	|
		user-defined-sequence

msg	:=	msg-name	|
		<number>

msg-name	:=	\*(lqfirst\*(rq	|
		\*(lqlast\*(rq	|
		\*(lqcur\*(rq	|
		\*(lq\&.\*(rq	|
		\*(lqnext\*(rq	|
		\*(lqprev\*(rq

msg-range	:=	msg\*(lq\-\*(rqmsg	|
		\*(lqall\*(rq

msg-sequence	:=	msg\*(lq:\*(rqsigned-number

signed-number	:=	\*(lq+\*(rq<number>	|
		\*(lq\-\*(rq<number>	|
		<number>

user-defined-sequence	:=	<alpha>	|
		<alpha><alphanumeric>*
.re
.fi
.sp
.lp
Where <number> is a decimal number greater than zero.
.lp
Msg-range specifies all of the messages in the given range
and must not be empty.
.lp
Msg-sequence specifies up to <number> of messages, beginning
with \*(lqmsg\*(rq (in the case of first, cur, next, or <number>),
or ending with \*(lqmsg\*(rq (in the case of prev or last).
+<number> forces \*(lqstarting with msg\*(rq, and \-<number> forces
\*(lqending with number\*(rq.
In all cases, \*(lqmsg\*(rq must exist.
.lp
User\-defined sequences are defined and manipulated with the \fIpick\fR
and \fImark\fR commands.
.in 0
.bp
.ce
.b \\s12REFERENCES\\s0
.(x
.sp
REFERENCES
.)x
.sp 3
.in .4i
.ti 0
1.  Crocker, D. H., J. J. Vittal, K. T. Pogran, and D. A. Henderson, Jr.,
\*(lqStandard for the Format of ARPA Network Text Messages,\*(rq
\fIRFC733\fR,
November 1977.

.ti 0
2.  Thompson, K., and D. M. Ritchie, \*(lqThe UNIX Time-sharing System,\*(rq
\fICommunications of the ACM\fR, Vol. 17, July 1974, pp. 365-375.

.ti 0
3.  McCauley, E. J., and P. J. Drongowski, \*(lqKSOS\-The Design of a Secure
Operating System,\*(rq \fIAFIPS Conference Proceedings\fR,
National Computer Conference,
Vol. 48, 1979, pp. 345-353.

.ti 0
4.  Crocker, David H., \fIFramework and Functions of the \*(lqMS\*(rq Personal
Message System\fR, The RAND Corporation, R-2134-ARPA, December 1977.

.ti 0
5.  Thompson, K., and D. M. Ritchie, \fIUNIX Programmer's Manual\fR, 6th ed.,
Western Electric Company, May 1975 (available only to UNIX licensees).

.ti 0
6. Crocker, D. H.,
\*(lqStandard for the Format of ARPA Internet Text Messages,\*(rq
\fIRFC822\fR,
August 1982.
.\" .he ''''
.fo ''''
.bp 2
.ce
.b \\s12CONTENTS\\s0
.sp 3
.xp y
.xp x