Added all of the MH sources, including RCS files, in

[mmh] / docs / historical / mh-6.8.5 / papers / bboards / 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/.

In particular, the UCI BBoards facility,
which was suggested by Einar Stefferud,
has been in place at the University of California, Irvine
(in one form or another) for the last two and one-half years.
The UCI BBoards facilities runs under both \MMDF/ and {\sf SendMail},
and, in a more restricted form, under stand-alone \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{Scope}
This document explains how to use the UCI BBoards facility to a user familiar
with \MH/ and the \unix/ operating system in general.
A large degree of expertise is not assumed.
This document does not attempt to introduce \MH/ to the novice user
(for that task, consult the \MH/ tutorial known as \cite{MH.TUT}).
Additional information on the programs discussed here
(particularly \pgm{bbc\/}) is to be found in \cite{MH}.

\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}

\section{Introduction}
\MH/ is a very powerful message handling system that runs under the \unix/
operating system.
One of the many features which \MH/ offers is an interface to the UCI BBoards
facility.
This facility permits the efficient distribution of interest group messages
on a single host, a group of hosts under a single administration, and the
ARPA Internet community.

Described simply, a interest group is composed of a number of subscribers
with a common interest.
These subscribers post mail to a single address, known as a
{\it distribution} address.
From this distribution address, a copy of the message is sent to each
subscriber.
Each group has a {\it moderator},
which is the person that runs the the group.
This moderator can usually be reached at a special address,
known as a {\it request} address.
Usually, the responsibilities of the moderator are quite simple,
since the mail system handles the distribution to subscribers automatically.
In some cases, the interest group,
instead of being distributed directly to its subscribers,
is put into a {\it digest} format by the moderator and then sent to the
subscribers.
Although this requires more work on the part of the moderator,
such groups tend to be better organized.

Unfortunately, there are a few problems with the scheme outlined above.
First, if two users on the same host subscribe to the same interest group,
two copies of the message get delivered.
This is wasteful of both processor and disk resources.

Second,
some of these groups carry a lot of traffic.
Although subscription to an group does indicate interest on the part of a
subscriber,
it is usually not interesting to get $50$ messages or so delivered to 
the user's private maildrop each day,
interspersed with {\it personal} mail,
that is likely to be of a much more important and timely nature.

Third, if a subscriber on the distribution list for a group becomes ``bad''
somehow,
the originator of the message and not the moderator of the group is notified.
It is not uncommon for a large list to have $10$ or so bogus addresses present.
This results in the originator being flooded with ``error messages'' from
mailers across the ARPA Internet stating that a given address on the list was
bad.
Needless to say,
the originator usually could not care less if the bogus addresses got a copy
of the message or not.
The originator is merely interested in posting a message to the group at large.
Furthermore, the moderator of the group does care if there are bogus
addresses on the list,
but ironically does not receive notification.

To solve all of these problems,
the UCI BBoards facility introduces a new entity into the picture:
all interest group mail is handled by a special component of the mail system.
The distribution address maps to a special {\it channel} that performs
several actions.
First, if local delivery is to be performed,
then a copy of the message is placed in a global maildrop for the interest
group with a timestamp and a unique number.
Local users can read messages posted for the interest group by reading the
file.
Second, if further distribution is to take place,
a copy of the message is sent to the distribution address in such a way that
if any of the addresses are bogus,
the failure notice is sent to the maintainer of the group and not the
originator.

This scheme has several advantages:
First, messages delivered to the host are processed and saved once
in a globally accessible area.
The UCI BBoards facility supports software which allows a user to query the
interest group for new messages and to read those messages in the \MH/-style.
Second, once a host subscribes to an interest group,
a user can add or remove him/herself from the list without contacting the
moderator.
Third, a hierarchical distribution scheme can be constructed to further
reduce the amount of message traffic.
Fourth, errors are prevented from propagating.
When an address on the distribution list goes bad,
the request address immediately responsible for the address is notified.
Usually, this is the local PostMaster and not the group moderator.

In addition to solving the problems outlined above,
the UCI BBoards facility supports several other capabilities.
BBoards may be automatically archived in order to conserve disk space and
reduce processing time when reading them.

Special alias files may be generated which allow the \MH/ user to shorten
address type-in.
For example, instead of sending to \eg{SF-Lovers@Rutgers},
a user of \MH/ usually sends to \eg{SF-Lovers} and the \MH/ aliasing
facility automatically makes the appropriate expansion in the headers of the
outgoing message.
Hence, one need only know the name of a interest group and not its address.

Finally, the UCI BBoards facility supports {\it private} interest groups
using the \unix/ group access mechanism.
This allows a group of people on the same or different machines to conduct a
private discussion.

The practical upshot of all this is that the UCI BBoards facility automates
the vast majority of BBoards handling from the point of view of both the
PostMaster and the user.

\section{BBoard Handling}
Usually the term {\it BBoard} is used interchangeably with the terms
{\it discussion group} and {\it interest group}.
This is true of the discussion that follows.

The messages for a BBoard delivered locally are kept in the same format as
a maildrop.%
\nfootnote{Actually,
your site might be running with all BBoards kept on a single host.
\MH/ supports the remote access of BBoards using a modified version of the
ARPA Post Office Protocol (POP).
This has the advantage that it saves a lot of disk space,
and incurs only a modest performance penalty.}
Unlike the user's private maildrop however,
the \pgm{inc} program is not run to incorporate new BBoard messages into
the user's \MH/ \eg{+inbox} folder.
The programs which are used will be discussed momentarily.

Each message in a BBoard maildrop has a unique number and a timestamp.
The number, called the {\it BBoard-ID}, is always ascending.
The BBoard-ID of a message should {\bf NOT} be confused with the message
number of a message, which can change as messages are removed from the BBoard.
The BBoard-ID is a value which is unique for every message delivered locally
to the BBoard.

To read BBoards, the \MH/ user invokes \pgm{bbc}.
The \pgm{bbc} program has several switches to direct it's action.
The \switch{topics} switch to \pgm{bbc} tells the \MH/ user about the
status of a BBoard.
The \switch{check} switch to \pgm{bbc} lets the \MH/ user check on the
activity of a BBoard.
The \switch{read} switch to \pgm{bbc} invokes the \pgm{msh} program on the
BBoard.
\pgm{msh} is a monolithic program which contains most of the functionality of
\MH/ in a single program.
These commands are now discussed in greater detail.

\subsection{BBoard status}
The \switch{topics} option to the \pgm{bbc} program can be used to report
information about a BBoard that does not pertain to the user's reading habits.
If the \MH/ users types \example bbc\ -topics\endexample
then \pgm{bbc} will list the following information for all BBoards received
on the host:
\smallskip
{\advance\leftskip by\parindent
\item{$\bullet$} the official name of the BBoard
\item{$\bullet$} the number of messages delivered to the BBoard
(but not necessarily present)
\item{$\bullet$} the date and time of the last message delivered to the BBoard
\medskip}
\noindent
In addition to \switch{topics},
if the \switch{verbose} option is given to \pgm{bbc},
then more information is listed:
\smallskip
{\advance\leftskip by\parindent
\item{$\bullet$} any aliases the BBoard is known as
\item{$\bullet$} the local leaders of the BBoard
\item{$\bullet$} the file that the BBoard is locally delivered to
\item{$\bullet$} the ``global'' distribution address
\item{$\bullet$} the ``global'' request address
\item{$\bullet$} the host that distributes the BBoard to the local host
\item{$\bullet$} the addresses to which this host distributes
\item{$\bullet$} miscellaneous information (presently only archiving status)
\medskip}
\noindent
Naturally, \pgm{bbc} can be invoked with the \switch{topics} option and one or
more BBoard names listed on its command line.
For example \example bbc\ -topics\ unix-wizards\endexample is completely
acceptable~---~it tells \pgm{bbc} to report the status of the BBoard
\eg{unix-wizards}.

\subsection{BBoard checking}
The \switch{check} option to the \pgm{bbc} program can be used to check for
new BBoard messages in a synchronous fashion
(i.e., when you specifically ask for it).
The \MH/ users types \example bbc\ -check\endexample and \pgm{bbc} consults
the profile entry for \eg{bboards:} in the user's \profile/ file.
For each BBoard listed,
\pgm{bbc} prints one of several messages depending on the status of both the
BBoard and the user's reading habits
(for example, in the case of the mythical BBoard \eg{foo\/}):
\smallskip
{\advance\leftskip by\parindent
\item{1.} \eg{foo -- n items unseen}\hbreak
This message indicates items in the BBoard have not been seen by the user.
When \pgm{bbc} is invoked with the \eg{quiet} switch,
this is the only informative message that \pgm{bbc} will print out.
Users of \MH/ usually put \example bbc\ -check\ -quiet\endexample
in their \file{\$HOME/.login} file.

\item{2.} \eg{foo -- empty}\hbreak
The BBoard is empty.

\item{3.} \eg{foo -- n items (none seen)}\hbreak
The BBoard has $n$ items in it, but the user hasn't seen any.

\item{4.} \eg{foo -- n items (all seen)}\hbreak
The BBoard is non-empty, and the user has seen everything in it.

\item{5.} \eg{foo -- n items seen out of m}\hbreak
The BBoard has at most $m-n$ items that the user has not seen.
\medskip}
\noindent
It is important to note that \pgm{bbc} performs its calculations on
BBoard-ID:s and not the messages actually present in a BBoard.
This means that the numbers given by \pgm{bbc} are maximal end-points.
When \pgm{bbc} says $n$, \pgm{bbc} means ``at most $n$''.

Naturally, \pgm{bbc} can be invoked with the \switch{check} option and one or
more BBoards listed on its command line.
For example \example bbc\ -check\ info-c\ poli-sci\endexample is completely
acceptable~---~it tells \pgm{bbc} to check on the BBoards \eg{info-c} and
\eg{poli-sci} only.

There are two ways to check for new BBoard messages in an asynchronous fashion:
using the \pgm{CShell} variable \file{\$mail} and running the \pgm{useto}
program.

\subsubsection{Asynchronous Checking with the CShell}
The \pgm{CShell} has a variable called \file{\$mail}.
This variable can contain one or more words.
Each word should be a filename where the shell should check for new mail.
The check is performed after a specified time interval has elapsed just
before the shell would prompt the user.

If the first word of \file{\$mail} is a number,
then this number specifies a different checking interval, in seconds,
than the default, which is 10 minutes.

Whenever the time interval elapses and the shell is ready to prompt the user,
the shell looks at the file and decides if new messages have arrived.
If so, it says \example You have new mail.\endexample
if only one file is present in \file{\$mail}.
Otherwise,
if more than one file is present in \file{\$mail},
then the shell says \example New mail in foo.\endexample whenever there is new
mail in the file called \eg{foo}.

To find out what file is associated with a BBoard, say \eg{info-unix},
the \MH/ user types \example bbc\ -topics\ -verbose\ info-unix\endexample
Usually the local file for a BBoard has an extension of \file{.mbox}.

\subsubsection{Asynchronous Checking with Useto}
In contrast to using the \file{\$mail} variable in the \pgm{CShell},
the \MH/ user might employ \pgm{useto} instead.%
\nfootnote{Not all sites have \pgm{useto};
contact the same people who supplied \MH/ to get a copy.}
The \pgm{useto} program is a continuous update display that prints information
on the status line of your terminal.
Needless to say,
your terminal must support a status line in order to run \pgm{useto}.
Not all terminals have this capability,
but for those that do it's usually well worth the effort to run \pgm{useto}.

For example, users of \MH/  could put
\example
    useto\ -bepf\ \'tcp-ip\ sftp\'\ %
        \'\%D\ \%M\ \%d\ \%h:\%m\%z\%b\ \%n.tty\%t:\%l1\'%
\endexample
in their \file{\$HOME/.login} file.
This command line to \pgm{useto} says to inform the user of
\smallskip
{\advance\leftskip by\parindent
\item{$\bullet$} the current date and time
\item{$\bullet$} new mail for the user
\item{$\bullet$} new messages for the BBoards \eg{tcp-ip} and \eg{sftp}
\item{$\bullet$} the name of the host and tty that the user is logged in on
\item{$\bullet$} the 5--minute load average of that host
\smallskip}

The \pgm{useto} program is really quite amusing and useful.%
\nfootnote{To be honest,
the author considers computing environments without \pgm{useto}
to be less than adequate.}

\subsection{BBoard reading}
If \pgm{bbc} is not given either the \switch{check} or \switch{topics} option,
the \pgm{bbc} program reads BBoard messages.
For each BBoard listed in the \MH/ user's profile entry for \eg{bboards:},
\pgm{bbc} checks to see if there is unread mail.
If so, \pgm{bbc} starts \pgm{msh} on the BBoard,
telling \pgm{msh} which messages haven't been seen.%
\nfootnote{If the \switch{verbose} option is given to \pgm{bbc},
then \pgm{bbc} will start \pgm{msh} on the BBoard regardless of whether there
are unseen messages there.}

When \pgm{msh} starts it identifies the BBoard being read and indicates how
many messages are present and how many the user has read.
Usually, in the user's \MH/ profile,
the user has the entry \example msh:\ -scan\endexample
This says that when \pgm{msh} starts,
it should print a {\it scan listing} of the messages which the user
hasn't seen yet.

The \pgm{msh} program now prompts the user for \MH/ commands.
The user may type most of the normal \MH/ command.
The syntax and semantics of the commands typed to \pgm{msh} are identical
to their \MH/ counterparts.
For example, to reply to a message on the BBoard,
the \MH/ user types \eg{repl};
other \MH/ commands likewise may be applied to BBoard messages.
In cases where the nature of \pgm{msh} would be inconsistent
(e.g., specifying a \arg{+folder} with some commands),
\pgm{msh} will duly inform the user.
In addition to supporting most \MH/ commands,
\pgm{msh} also has a \eg{help} command which gives a brief overview.

The only command that behaves entirely differently in \pgm{msh} is the
\eg{mark} command when given no arguments.
The \pgm{msh} program maintains a special sequence, \eg{unseen},
which it uses to keep track of the messages you've seen.
If the \eg{mark} command is given without any arguments,
then \pgm{msh} will interpret it as
\example mark\ -sequence\ unseen\ -delete\ -nozero\ all\endexample
Hence, to discard all of the messages in the current BBoard being read,
the \MH/ user types \eg{mark} which says to remove all messages from sequence
called \eg{unseen}.

To leave \pgm{msh} use the \eg{quit} command.
This tells \pgm{msh} to terminate and \pgm{bbc} to go to the next BBoard.
Instead, if the user types EOT (usually CTRL-D),
then \pgm{bbc} will exit as well,
updating whatever information was appropriate.

\section{Current BBoards}
There are many, many active interest groups.
Consult the BBoard called \eg{list-of-lists} for a comprehensive description.
Here are a few of the more popular:
\smallskip
{\advance\leftskip by\parindent
\item{\tx system}
Important announcements for the local system are posted here.

\item{\tx mh-users}
A discussion group for users of \MH/.

\item{\tx arpanet-bboards}
Redistribution address for all known BBoards on the ARPAnet.

\item{\tx editor-people}
Discussion of topics related to computerized text editing, display editors, 
and human factors in man/machine interaction.
The theoretical discussion is catholic,
but practical discussion focuses particularly on \tops20/ and \unix/.

\item{\tx franz-friends}
Discusses the Franz Lisp language.

\item{\tx header-people}
Interest specifically in the format of message headers and related issues 
such as inter-network mail formats/standards, etc.

\item{\tx human-nets}
{\sf Human-Nets} has discussed many topics,
all of them related in some way to the theme of a world-wide computer and
telecommunications network usually called WorldNet.
The topics have ranged very widely, from something like tutorials,
to state of the art discussions,
to rampant speculation about technology and its impact.

\item{\tx info-micro}
Information/discussion list on the general interest topic of microcomputers.

\item{\tx info-unix}
{\sf Info-UNIX} is intended for question/answer discussion,
where ``novice'' system administrators can pose questions.

\item{\tx msggroup}
Interest in electronic mail, message formats, message systems, and the 
sociological implications of the above.

\item{\tx poli-sci}
A permanent distributed political ``bull'' session.

\item{\tx sf-lovers}
Science Fiction lovers.
{\sf SF-Lovers} has discussed many topics,
all of them related in some way to the theme of science fiction or fantasy.  

\item{\tx space}
Discussions (daily digest) on space-related topics.

\item{\tx telecom}
A broad spectrum moderated-digest-format discussion on telecommunictions 
technology: the telephone system, modems, and other more technical aspects 
of telecommunications systems.  

\item{\tx unix-emacs}
Used for new release announcements and general discussions of Gosling's
\EMACS/.

\item{\tx unix-wizards}
Distribution list for people maintaining machines running the \unix/ operating
system.
\medskip}
\noindent
As discussed earlier,
to find out about all of the BBoards that the local host subscribes to,
the \MH/ users types \example bbc\ -topics\endexample

\section{More on BBoards}
Finally, here are a few more operational details:

\subsection{Creating a BBoard}
Contact the PostMaster at your host to have a BBoard created.
Be sure to indicate its status (public or private)
and scope (where distribution should occur).

\subsection{Subscribing to a BBoard}
If your local host already receives an interest group,
then simply add the name of the BBoard to the \eg{bboards:} entry in your
\MH/ profile.
If not, ask the PostMaster to create the BBoard and contact the global
request address for you.

\subsection{BBoard Archives}
BBoard messages are automatically archived on a weekly basis.
Usually, this results in messages older than 12 days being moved to an
{\it archive} area.
To read the archives for a BBoard, the \switch{archive} option is used.
For example, \example bbc\ -archive\ telecom\endexample
tells \pgm{bbc} to invoke \pgm{msh} on the archives for the \eg{telecom}
BBoard.

Note that the archives may not be present for all BBoards on a given host;
also note that the archives may be periodically moved to tape and expunged
from the system.
Contact your local PostMaster for the details.

\subsection{BBoard Addresses}
Each BBoard has associated with it 4 addresses
(for example, in the case of the mythical BBoard \eg{foo\/}):
\smallskip
{\advance\leftskip by\parindent
\item{\tx foo} The global distribution list\hbreak
If you post a message addressed to {\tx foo} then the message is distributed
to everyone who subscribes to \eg{foo}.

\item{\tx dist-foo} The local distribution list\hbreak
If you post a message addressed to {\tx dist-foo} then the message is
distributed to the local BBoard for \eg{foo}
and to any sites which the local system distributes to.

\item{\tx foo-request} The global moderator\hbreak
If you post a message addressed to {\tx foo-request} then the message is
sent to the moderator for the entire interest group called \eg{foo}.

\item{\tx local-foo-request} The local moderator\hbreak
If you post a message addressed to {\tx local-foo-request} then the message is
sent to the person responsible for the BBoard \eg{foo} on the local system.
\medskip}
\noindent
These addresses are defined by the \MH/ alias facility.
Users of the BBoards facility who do not use \MH/ may not be able to make use
of them.

\subsection{Leading a BBoard}
Except for special circumstances, this task is wholly automated.
For more information though,
see the manual entries for \man bbl(1) and \man bbleaders(8).

\section{Extra for Experts}
Some clever \MH/ users might ask why BBoards aren't kept as folders instead
of \pgm{pack}'d files.
This is a good question.
Perhaps some future release of \MH/ and the UCI BBoards facility will treat
BBoards as a variant of read-only folders.

The problem with \pgm{msh}, of course, is that it's a monolithic program,
and although it does support input/output redirection and a few other
primitive shell-like properties, it's still not the \pgm{CShell}.