PDP-10.its/doc/_info_/rmail.order

RMAIL is a program for reading and editing mail.
It can conveniently be used either to examine one
or more files of mail, or to copy several files
into one, optionally editing the combined contents.

There are two major modes: "perusal mode", and "update mode". 
Of perusal mode it is also said that "an rmail file has not
been specified".  In update mode, it is said that one has been.
Perusal mode is good for viewing other people's mail; update
mode, for one's own.  If RMAIL is run with a null command string,
it operates in updated mode on one's own mail, using the default
names for all the files.


Perusal mode:

To invoke RMAIL in perusal mode, supply it with a command
string containing the names of the files to be examined,
separated by commas.  The default for the first filespec is
DSK:<msname>;<xuname> MAIL.  The default for each other filespec
is the previous file.  If only one filename is specified, it
is the first filename.  Alternatively, to specify a user's
mail file, give JUST the user's name and use a "/" instead of
a comma - the file will be found on COM: or the user's
directory, as appropriate.

"^A" may be used at the beginning of a filespec to represent
the default first filename, in case it is desired to change only the second.
Thus, "COM:^ASENDS" will get the SENDS file for the user whose
name is the default at that moment.

All the files named are read in, concatenated together, in
the order they appear in the command string, and the first
message in the first newmail file is then displayed.

Editing may be done in perusal mode, but RMAIL will not
write the edited string into any file of its own accord.


Update mode:

For this mode, the command string should contain a list
of newmail files terminated by commas, and users' names
terminated by slashes, as for perusal mode,
followed by the name of the rmail file, followed by an
altmode.  If it is desired not to use any newmail files,
just the rmail file name and the altmode should be given.
When including a :RMAIL in an execute file, for best results
before every "<user>/", include "<user>;<user> OMAIL," so that
the user's omail file, if any, will be grabbed.  If a user's mail
file and omail file are both specified, the omail file should
come first, since otherwise it may be deleted when the spec of
the mail file is reached.
The default names for the rmail file are
DSK:<msname>;<xuname> RMAIL, rather than the names of the
last newmail file.

In update mode, RMAIL reads all the files, including the
rmail file, and concatenates them together, as in perusal
mode, except that if the rmail file starts with "*APPEND*<crlf>"
it goes at the front instead of at the end (this is good for
those who use the "APPEND" option in the mailer).
The result is then written back on top of the rmail
file (which is created if necessary), and then all user's
mail files specified with slashes are deleted.  When
RMAIL is exited via the X command, the result of
the user's editing will be again written out on top of
the rmail file.  At intermediate times, the S option may
be used to save the editing in that way.

Invoking RMAIL with a null command string is the same as
using "<xuname>;^A OMAIL,COMMON;,<xuname>/" as the command string.
It means, according to the above rules,
to concatenate <xuname>;<xuname> OMAIL, COM:<xuname> OMAIL,
and the user's mail file (either <xuname>;<xuname> MAIL
or COMMON;<xuname> MAIL) with <msname>;<xuname> RMAIL,
write the result back out on top of the file RMAIL, then
delete all the other files mentioned.  After editing, the result may again
be written out in <msname>;<msname> RMAIL.

The I option switches into update mode, asking the user to
specify the name of the new rmail file.  If RMAIL was already
in update mode, the old rmail file is written out (as by S).


Once RMAIL is running:

RMAIL is normally in option mode.  In that mode, several
single-character commands, called options, are available,
including escapes into other modes.
If an unrecognized option is typed, a statement to that effect
will be typed out.  The user then has another chance to type
an option, and is reminded that "?" types documentation.
Unless it says otherwise in the description of a particular
option, after any option is executed, the current message
will be displayed, and a new option will be awaited.  In other
words, options normally do not leave option mode.

The options are:

N	move to Next message (then display it and read an option)
	 When looking at the last message, N does nothing but
	 notify the user of that fact.
	 N may be preceded by a decimal integer, which will act
	 as a repeat count.  1000N is a good way to go to the last
	 message in the buffer.

D	Delete the message and move to the next.
	 The deleted message is appended to the end of Qreg 9.

U	Undelete the last message deleted, putting it before
	 the message which had been current, and moving back
	 to it.  Successive undeletes will undelete earlier
	 messages (the deleted messages live in a stack).

P	move to the Previous message.
	 When looking at the first message, P does nothing but
	 notify the user of that fact.
	 P may be preceded by a decimal integer repeat count.
	 10000P means "go to the first message" - it fails only
	 when starting out at the first message.

SPACE	move to the next screenful of a long message.
	 At the end of a message, space will go back to the
	 beginning.

.	move to the beginning of the current message.
	 In addition, if more than one message is being looked
	 at (as, after a W option), "." will select just the
	 message that the pointer is inside.  Thus, "."
	 is the "inverse" of W, in some ways.

R	Reply to message.  Usually, a :QMAIL addressed to the author
	 of the current message, along with all the recipients of
	 the message listed in the message (including the user who
	 is reading his mail, presumably) is displayed, and the reply may be
	 typed in, using all the facilities of ^R mode.
	 ^C ends the editing, causing the message to be sent as
	 specified in the buffer.
	 If you change your mind about the message, just clean out
	 the buffer and then ^C; no message will be sent.
	 In either case, RMAIL will return to option mode.

	 Subject headers and other 
	 QMAIL features may be used by putting the appropriate
	 QMAIL commands in the buffer.  For this purpose, when
	 ALTMODE is typed, it will prompt for the QMAIL command
	 to follow, and both will go in the buffer (^G quits).
	 If you really wish to put a stray altmode in the buffer,
	 you can use META-ALTMODE, but that will probably cause
	 nothing but trouble.
	 The R option will automatically specify a subject line
	 identical to that of the message being replied to.
	 It can be changed by editing, of course.

	 You should not put anything on the first line of the
	 :QMAIL in the buffer, except for recipient names.

	 While the reply is being edited, the character ^Y is set
	 up to insert the text of the message being replied to,
	 in case it is desirable to quote part of the message in
	 the reply.

	 Actually, RMAIL executes a QMAIL by writing the text of
	 the message into a file named COM:<uname> RMAIL and then
	 valretting the :QMAIL along with an altmode-G telling
	 QMAIL to snarf that file.  When QMAIL exits, RMAIL restarts
	 and deletes the temporary file.  If the :QMAIL is replaced
	 by anything else, it will be valretted to DDT.

M	Mail a message.  Like R, except for its default,
	 which is to set up an empty :QMAIL command, in which
	 the user may insert recipients, text, subject, etc.

O	Output the message to a file - good for forwarding a
	 message to someone else's mail file;  also good
	 for filing messages according to topics.
	 The default for the file to be used is displayed,
	 and the user may type in and
	 edit an explicit specification to override it.
	 In such a specification, a lone filename is used as the
	 second filename of the file to be written.
	 An altmode tells RMAIL to proceed, appending the
	 current message to the front of the specified file,
	 which will be created if necessary.  However, if the
	 file starts with "*APPEND*<crlf>", the new message
	 will go at the end instead of the front.
	 To abort the O command, clear out the filenames
	 in the buffer with ^A^K (leaving the buffer empty)
	 and then type the altmode.

X	eXit: kill the job and return control to DDT.
	 If an rmail file was specified, the current buffer
	 is written out into the rmail file first.

S	Save: write the rmail file.
	 Does nothing if no rmail file was specified.
	 The RMAIL is NOT killed, so further editing may be
	 done.

I	Inputs a new rmail file, and enters update mode.
	 If RMAIL was already in update mode, the old rmail
	 file is written out, as if the S option had been typed.
	 Then ^R-mode is used to enter the name of the new
	 rmail file, with the name of the old one shown
	 as the default.  An altmode tells RMAIL to go ahead.
	 To abort the I command, clear out the filenames
	 in the buffer with ^A^K (leaving the buffer empty)
	 and then type the altmode.

^C	just as in TECO;  returns to DDT.  When RMAIL is
	 proceeded, it will redisplay the screen.

^R	escape into ^R mode to edit the message.
	 An altmode will return to option mode.

ALTMODE
	escape to the TECO interpreter.  The next attempt
	 by the TECO interpreter to display the buffer
	 will return to option mode.

L	Show a List of all messages.  This command puts on the
	 screen text that resembles the mail file except that
	 every message is truncated to 100 characters at most.
	 RMAIL then invokes ^R mode, which allows the user to
	 move the cursor to any message he desires.  On exiting
	 from ^R, RMAIL will show and point at the message
	 which was selected in that manner.

W	show the Whole buffer.  Normally, virtual buffer
	 boundaries are set up to restrict editing to a
	 single message.  This option flushes them.
	 After doing a W, the option "." will
	 go back to the single message that the pointer
	 is in.  P or N will do that and then move back
	 or forward.  A D option is unwise after a W, but
	 one can recover from it using "$G9$$".
	 The W option is especially useful before a
	 ^R or altmode.

F	reads in a string (using ^R mode), and then searches
	 through all the remaining messages for the string.
	 It stops on the first message that contains the
	 string.  To find the same string as last time, give
	 the null string as the argument.
	 If the current message itself contains the string,
	 F will not move to a later message, so if
	 you want to find the next message after the current
	 one, do an N before the F.  If the string is not found,
	 F will stay at the current message, also.  Note that
	 case is ignored while searching (since FSBOTHCASE$
	 is set nonzero by RMAIL).  While the string is being
	 read in, the word "FIND" will appear at the bottom
	 of the screen to remind the user of what is happening.

^L	clears the screen and redisplays.

?	shows a brief description of all available options.
	 The display will remain until a character is typed
	 in; that character will be used as an option.


Random information:

RMAIL keeps data in Q-registers ..B, ..L, 6, 7, 8, 9, X and Z.
6 holds the default filenames for the O option.
7 holds the names of the newmail files, followed by the
  name of the rmail file.  In perusal mode, Q7 holds 0.
8 holds the last string specified in an "F".
9 holds all messages deleted with "D".

The input and output files are not clobbered by RMAIL but the
default filenames are clobbered by the S, M, X and O options.
Some options may clobber Q-regs 0 and 1, but I hope by now
those qregs are always saved and restored.

The sources for RMAIL are .TECO.;RMAILX >,  .TECO.;RMAILZ >,
and .TECO.;RMAILL >.
RMAILX is the macro that implements option execution,
while RMAILZ processes the command string and the input files.
While in RMAIL they normally live in Qregs X and Z, they do
not depend on that.  They are designed to be able to be used
independently, in macro packages - see the comments at the
front of each file for how to call them and what they do
with and to various qregs.
RMAILL is a macro to load up and dump out an RMAIL.
It reads RMAILX and RMAILZ; also it sets up a driver routine
in Q..L to call them with approriate interfacing.
When using RMAILX and RMAILZ from a macro package, copying the
structure of that driver routine should be useful.

SYS1;TS RMAIL is actually just a simple bootstrap program
to load TECO (through SYS1;RMAIL TS) and tell it to run
RMAIL (found in SYS1;RMAIL TECO).

To create a new RMAIL, do ":TECO RMAIL;", if you have a macro
package that will take that to mean "run (INIT);RMAIL .TECO."
(as ALL macro packages morally should). This will write a file
.TECO.;RMAIL TECO which should be copied to SYS1.
Also, SYS1;RMAIL TS should be a link to the version of TECO
used to create RMAIL TECO.