Added sources to historical documents downloaded from

[mmh] / docs / historical / mh5 / text.tex

% begin text
\banner
\section{Acknowledgements}
The \MH/ system described herein is based on the original Rand \MH/ system.
It has been extensively developed (perhaps too much so) by Marshall Rose and
John Romine at the University of California, Irvine.
Einar Stefferud, Jerry Sweet, and Terry Domae provided numerous suggestions
to improve the UCI version of \MH/.

\section{Disclaimer}
The Regents of the University of California wish to make it known that:
\bigquote
Although 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.
\endbigquote

\section{Conventions}
In this document,
certain \TeX -formatting conventions are adhered to:
\smallskip
{\advance\leftskip by\parindent
\item{1.} The names of \unix/ commands, such as \pgm{comp},
are presented in {\it text italics}.
\item{2.} Arguments to programs, such as \arg{msgs},
are presented in {\tt typewriter style} and delimited by single-quotes.
\item{3.} \unix/ pathnames and envariables,
such as \file{/usr/uci/} and \file{\$SIGNATURE},
are presented in {\sl slanted roman}.
\item{4.} Text presenting an example, such as
\example comp\ -editor\ zz\endexample
is presented in {\tt typewriter style}.
\smallskip}

\bop\section{General Changes}
The author is pleased to announce that there are actually very few
user-visible changes to \mh5 from the \mh4 distribution.
The majority of \mh5 development was in the form of bug fixes and slight
generalizations.
In addition, \mh5 is somewhat faster than \mh4:
all programs have been speeded-up slightly,
a few, such as \pgm{msh}, have been speeded-up signficantly.

\subsection{Library Paths}
When a filter or form file argument is given to an \MH/ program,
and the name specified is not absolute (doesn't start with a \file{/\/}),
then the \MH/ program will first check in the user's \MH/ directory.
If the file is not present,
then program will consult the standard \MH/ library for the file.
This convention allows the PostMaster to make available system-wide
templates and skeletons.

\subsection{MH Directory}
If the \MH/ directory of a user doesn't exist,
then \MH/ will query the user if it should be created.
This is primarily useful when copying a \profile/ from one host to another,
or when the site administrator creates a \profile/ for a user when creating
the associated login.

\subsection{Documentation}
Two new documents have been prepared for the \mh5 distribution:
{\sl The Rand MH Message Handling System: Tutorial},
which is cited as \cite{MH.TUT};
and,
{\sl The Rand MH Message Handling System: The UCI BBoards Facility},
which is cited as \cite{MH.BB}.
The former is a useful tutorial for novice users of \MH/.
The latter describes BBoard handling and \MH/.

\section{Draft Handling}
This section discusses how the handling of drafts has been changed in \mh5.

The most important change is that the {\it draft-folder} notation
and the {\it push} option at \whatnow/ level have been explicitly made
visible in the \MH/ system.
There's a new profile entry called \eg{Draft-Folder} which defines the
default draft-folder for the \MH/ user.
By using this entry, such as \example Draft-Folder:\ +drafts\endexample
the \MH/ user needn't add \switch{draftfolder\ drafts} to the entries
for \pgm{comp}, \pgm{dist}, \pgm{forw}, and \pgm{repl} in the user's
\profile/ file.

\subsection{What Happens if the Draft Exists}
A new option has been added to \pgm{comp}, \pgm{dist}, \pgm{forw}, and
\pgm{repl} when the draft already exists: \eg{refile\ +folder}.
This allows you to \pgm{refile} the draft into another folder and then get a
fresh draft.

\subsection{Editing Environment}
In previous versions of \MH/,
when \pgm{comp}, \pgm{dist}, \pgm{forw}, and \pgm{repl} allowed the user to
edit the draft,
the \MH/ user's current working directory was somewhere inside of the user's
\MH/ directory.
This often lead to confusing results.
In \mh5,
when the user edits a draft,
the current working directory is unchanged.
Furthermore, two envariables are defined during the editing session for
\pgm{dist} and \pgm{forw}:
\file{\$editalt},
which is the name of the message (\unix/ file) being distributed or replied-to;
and,
\file{\$mhfolder},
which is the name of the folder (\unix/ directory) containing the message
being distributed or replied-to.

\subsection{Rapid Composition}
The \pgm{prompter} command has two new switches \switch{rapid} and
\switch{norapid}.
If the \switch{rapid} option is given then \pgm{repl} won't display an
existing body of the draft being edited.
This is useful for using \pgm{forw} with a slow terminal.

\subsection{Ultra Rapid Composition}
The \pgm{comp}, \pgm{dist}, \pgm{forw}, and \pgm{repl} commands have a new
option, \switch{noedit}.
If \switch{noedit} is given,
then the initial edit is supressed.
This is useful for various canned applications
(and perhaps more graceful than \switch{-editor /bin/true\/}).

\subsection{Digest Generation}
The \pgm{forw} command has the beginnings of a digest-composition facility,
with the \switch{digest\ list}, \switch{issue\ number},
and \switch{volume\ number} switches.

If \pgm{forw} is given the argument \eg{list} to the \switch{digest} switch,
and the \switch{issue\ number} switch is not given,
then \pgm{forw} looks for a profile entry called
\eg{digest-issue-list:} and increments its value to use as the issue
number.
Similarly,
if the \switch{volume\ number} switch is not given,
then \pgm{forw} looks for \eg{digest-volume-list:}
(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,
\pgm{forw} will look for a profile entry called \eg{sedproc:}
(which defaults to \pgm{/bin/sed\/})and filter the components file
(as specified with the \switch{form\ formfile} switch)
with the following definitions:
\eg{@(digest)}, \eg{@(issue)}, \eg{@(volume)}, and \eg{@(date)}.

\tagdiagram{1}{Sample skeleton for digest composition}{digestcomps}
A good components file to use, (which might be called \file{digestcomps\/}) is
shown in Figure~\digestcomps.

\pgm{Forw} will now compose the draft,
using the standard digest encapsulation algorithm
(even putting a \eg{End of list Digest} trailer in the draft).
Once the draft is composed by \pgm{forw},
it writes out the volume and issue profile entries for the digest,
and then invokes the editor.

\tagdiagram{2}{Sample template for digest messages}{mhldigest}
Naturally, when composing the draft,
the \pgm{forw} program will honor the\hbreak
\switch{filter\ filterfile} switch,
which is given to \pgm{mhl} to filter each message being forwarded prior to
encapsulation in the draft.
A good filter file to use, (which might be called \file{mhl.digest\/})
is shown in Figure~\mhldigest.

\subsection{Replies}
The \pgm{repl} command has two new switches \switch{query} and
\switch{noquery}.
If the \switch{query} option is given then for each address that would go in
the \eg{cc:} field of the reply,
\pgm{repl} asks the user if the address should be included.
This is sometimes useful for replying to mail sent to a large number of people.
(Obviously, one could simply edit the draft produced by \pgm{repl},
but the \switch{query} option is useful if \pgm{prompter} is the editor used
by \pgm{repl} and one doesn't want to invoke a second editor.)

Previous versions of \pgm{repl} would terminate if a \eg{From:} or
\eg{Sender:} field was not found or could not be parsed.
The \pgm{repl} program in \mh5 will continue to compose the reply draft,
after advising you of this anomaly.

\subsection{Blind Carbon Copies}
After much experimentation, \MH/ has finally stabilized on the format of
blind-carbon-copies.
As in \mh4, when \pgm{post} generates a draft for blind recipients,
a new draft is composed with a minimal set of headers.
In \mh5 however, the \eg{BCC-Disclaimer:} field is no longer used.
Instead, the draft for the blind recipients contains the original message as a
forwarded message.
This more clearly identifies a blind-carbon-copy to the blind recipient.

\subsection{File Carbon Copies}
A message draft can now have more than one folder listed in a \eg{Fcc:} field.
Each folder should be separated by a comma, just like the addresses in a
\eg{cc:} field.
In addition, the folders listed in a \eg{Fcc:} field may use the
relative-folder addressing notation
(though this latter activity is not recommended).

\subsection{Refiling the Draft}
At \whatnow/ level, there is a new option, \eg{refile}.
This options takes any arguments acceptable to the \pgm{refile} program,
and \pgm{refile\/}'s the message draft into the named folder(s).

\subsection{Annotations}
If the \switch{annotate} switch is given to \pgm{dist}, \pgm{forw}, or
\pgm{repl}, and the message is (re)moved by the user prior to the successful
posting of the draft, the \MH/ program will not complain as before.
Hence, users of the \eg{push} option at \whatnow/ level need not worry about
asynchronous error messages.

\section{Other Changes}
This last section describes the other more program-specific changes made to
\MH/.

\subsection{Bursting}
The bursting mechanism in \MH/ has been made sufficiently general to allow
\pgm{burst} to work on forwarded messages and blind-carbon-copies in addition
to digests.
Although \pgm{burst} can not always successfully decapsulate messages
encapsulated by sites not running \MH/,
it handles forwarded messages and blind-carbon-copies,
as constructed by \pgm{forw} and \pgm{send}, easily.

In addition, the \pgm{send} program has two new switches,
\switch{forward}, and \switch{noforward}.
If the \switch{forward} option is given,
then if a \pgm{send} which has been \pgm{push\/}'d in the background fails,
in addition to containing the reasons for the failure,
the failure notice contains the draft as a forwarded message.
This means one can simply \pgm{burst} the failure notice to get the draft
back,
instead of hunting around for it.

\subsection{Incorporation of Mail}
There's a new profile entry called \eg{MailDrop} which can be used to define
the default maildrop that \pgm{inc} should use.
In addition, if the envariable \file{\$MAILDROP} is defined,
then \pgm{inc} will use its value as the default maildrop.

The \pgm{inc} program also has a new option:
\switch{truncate} and \switch{notruncate},
which indicates if the maildrop should be truncated.
By default, \switch{truncate} is used defualt maildrop is used,
otherwise \switch{notruncate} is used.

\subsection{Clearing the Display}
The \switch{ff} and \switch{noff} switches have been removed from the
\pgm{scan} and \pgm{mhl} programs.
Instead, the \pgm{scan} has been given two switches,
\switch{clear} and \switch{noclear}
(\pgm{mhl} already has these switches).
The action of the \switch{clear} option is simple:
if the standard output to the \MH/ program is a terminal,
then the program will output the correct ``escape sequence'' to clear the
terminal's screen;
if the standard output is not a terminal,
then the program will output a formfeed.

In addition,
both \pgm{scan} and \pgm{mhl} consult the \file{\$TERM} envariable to
determine such things as the length and width of your terminal.
The \pgm{scan} program uses this to determine how long each line of the scan
listing should be.
The \pgm{mhl} program uses this to determine the default length and width
of your terminal (instead of the $40$ by $80\/$),
prior to reading the template or consulting command line options.

\subsection{Folder Handling}
If the \pgm{folder} command is given the name of a folder that does not exist,
\pgm{folder} will query the user if the folder should be created.
This is useful for creating a folder that the \MH/ user intends to access
later.

In previous releases of \MH/,
the \pgm{rmf} program would consider a folder writable if it was writable by
the user.
Since \pgm{rmf} ultimately removes the folder itself,
\pgm{rmf} considers a folder writable if the folder and its parent are
writable by the user.
If not, the folder is treated as a read-only folder by \pgm{rmf}.

\subsection{MailDrops}
The name of the \pgm{pack} program has been changed to \pgm{packf}.
The author didn't want to do this.
Some people don't know when to leave well enough alone.

\subsection{Refiling}
The \pgm{refile} program now has a \switch{draft} switch saying to file the
current draft.

\subsection{RcvMail Support}
In addition to the standard \pgm{rcvpack} and \pgm{rcvtty} receive mail hooks,
and the \pgm{rcvtrip} shell script,
there's a new rcvmail hook called \pgm{rcvdist}.
The \pgm{rcvdist} hook allows a user of \MH/ to have his/her mail forwarded
without the intervention of the PostMaster.
(By the way, the \pgm{rcvpack} hook used to be called \pgm{rcvcron\/}.)

\subsection{Reading BBoards}
The \pgm{msh} program (which used to be called \pgm{bbr\/})
implements an \MH/ shell.
In addition to the commands that the old \pgm{bbr} program had,
\pgm{msh} also has the
\pgm{inc}, \pgm{mhmail}, \pgm{pack}, \pgm{rmm} and \pgm{sortm} commands.

In addition, \pgm{msh} uses a ``maildrop mapping'' mechanism to
significantly speed-up its start-up time compared to the old \pgm{bbr}.
The \pgm{pack} program supports this mechanism as well,
so \pgm{msh} starts quickly on ordinary \pgm{pack\/}'d files as well.

Finally, \pgm{mhl} is now built-in to \pgm{msh},
so with a \eg{showproc} of \pgm{mhl},
the \pgm{msh} user gets speedy response in listing messages.