.\" This file is automatically generated. Do not edit! .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 .+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 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 \*(<\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 /Mail/draft (where 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 (usually ). 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' 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\-next:\0\*(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':\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 ^Msg\-Protect:\0644~^\fIinc\fR ^Folder\-Protect:\0711~^\fIinc, pick, refile\fR ^:\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 . (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'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 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/new/lib/mh/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 .. .po -.50i .so ali.me .so anno.me .so burst.me .so comp.me .so dist.me .so folder.me .so forw.me .so inc.me .so mark.me .so mhl.me .so mhmail.me .so mhook.me .so mhpath.me .so msgchk.me .so msh.me .so next.me .so packf.me .so pick.me .so prev.me .so prompter.me .so rcvstore.me .so refile.me .so repl.me .so rmf.me .so rmm.me .so scan.me .so send.me .so show.me .so sortm.me .so vmh.me .so whatnow.me .so whom.me .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'UCI version' .po -.50i .so mh-alias.me .so mh-format.me .so mh-mail.me .so mh-profile.me .so ap.me .so conflict.me .so dp.me .so install-mh.me .so post.me .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@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. 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 `\-private' 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 issue integer issue number volume 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/new/lib/mh/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/new/lib/mh/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'signed-number 'u +\w':= 'u +\w'user-defined-sequence 'u msgs := msgspec | msgs msgspec msgspec := msg | msg-range | msg-sequence | user-defined-sequence msg := msg-name | 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 | \*(lq-\*(rq | .re .fi .sp .lp Where 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 of messages, beginning with \*(lqmsg\*(rq (in the case of first, cur, next, or ), or ending with \*(lqmsg\*(rq (in the case of prev or last). + forces \*(lqstarting with msg\*(rq, and \- 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. .de $c .ce .b "\\s12\\$1\\s0" \" 12 Point Bold Header .(x y .sp \\$1 .)x .sp 3 .. .++ P .bp 1 .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@UCI.EDU\fR (in the ARPA Internet), and \fB...!ucbvax!ucivax!bug\-mh\fR (UUCP). Presently, there are two Internet discussion groups, \fBMH\-Users@UCI.EDU\fR and \fBMH\-Workers@UCI.EDU\fR. If there is sufficient interest, corresponding Usenet news groups may be established along with the appropriate gateways. .+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. 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 \MH/ 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. .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. .he '''' .fo '''' .bp .ce .b \\s12CONTENTS\\s0 .sp 3 .xp y .xp x .bp .\" 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