Walnut is under active development. This document describes how to obtain and use the latest version of Walnut released on the Cedar directory.
How to Use Walnut: Contents
0. Introduction
1. Database structure
2. User interface
3. The log
4. Becoming a user
5. Coping with releases and crashes
6. User profile options
7. Shortfalls and wishes
1. Database Structure
We begin with a user's model of Walnut's database. This model suppresses many details whose understanding would be required in writing a new application on Walnut's database, but are irrelevant for accessing the database through Walnut's user interface.
Walnut's database contains two entity types:
message and
message set.
A message entity corresponds to a message retrieved from the Grapevine mail transport system. Like all database entities it has a name, consisting of the sender's RName concatenated with a unique message ID provided by Grapevine. A message also has several immutable properties: its sender, its subject, and so on. Its unread property is a BOOL whose value is TRUE when the message is first stored in the database, and is set to FALSE when the message is first displayed.
A message entity is also a member of one or more message sets. A message set entity is named by a text string containing no embedded blanks. There are two distinguished message sets: Active and Deleted. A newly-retrieved message is made a member of Active. A message that is removed from all other message sets is added to Deleted. Using the Active and Deleted message sets in this way ensures that each message belongs to at least one message set.
Each user will generally have one private Walnut database for reading mail (this database is the one specified in the user profile for the logged-in user). Additionally, there are public Walnut databases (residing on Alpine servers) that any Walnut user can browse. (Switching from private to public databases is descrided in Section 4.) You may have either readonly or write access to a public database; if you have write access, then it is possible to move messages among message sets and to delete unwanted messages from the database (by doing an Expunge, as described below).
2. User Interface
Walnut implements four viewer types: the Walnut control viewer, the message set display viewer, the message display viewer, and the message composition viewer. When Walnut is running there is one Walnut control viewer, and any number of instances of the other viewer types. The iconic form of the Walnut control viewer is a mailbox. Anything that can be done with Walnut can be done by starting from the control viewer (sometimes by creating other viewers).
Walnut's user interface attempts to be consistent with conventions used elsewhere in Cedar. Clicking LEFT on a button representing a Walnut entity (a message or a message set) "selects" the entity (makes it an implied parameter to other operations); clicking MIDDLE on such a button opens the entity (displays more information somehow). This is analogous to the behavior of icons in Cedar.
Unless otherwise specified, hereafter "click" means "click with the LEFT mouse button".
2.1 Message sets
The message sets in a Walnut database are represented by buttons in the Walnut control viewer. The Active and Deleted message set buttons always appear first; other message set buttons appear in alphabetical order. There may be several rows of these buttons.
To create a new message set (containing no messages) type its name into the MessageSet: field of the control viewer, then click Create. A message set button with this name will appear and be selected. The remaining operations on message sets can be performed by using menu items on the second line of the Walnut control window; the MessageSetOps menu item in the first menu line will "open" the second line up for use. All of these buttons use the selected messages sets as implied arguments for the operations. To delete one or more existing message sets, select the message sets and click Delete. Note that you cannot delete the Deleted message set this way; you must click Expunge to do that. Walnut requests confirmation if any message set contains any messages. If you delete a message set containing messages, the messages are deleted from the set (as if clicking each message with CTRL-LEFT as described below) before the set is destroyed. To find out how many messages are currently in the selected message sets, click SizeOf; the sizes are printed in the typescript at the bottom of the control window. Clicking Print will print the messages in the selected message sets, loading the TSetter if necessary (see section 6 for printing options).
To create a message set display viewer, click MIDDLE on the corresponding message set button of the control viewer. The iconic form of a message set displayer is a stack of envelopes.
The message set displayer contains a one-line button for each message in the set. Each message button looks much like a line in the top window of Laurel: it shows the date of the message, the name of the sender (or To: field if the sender is the current user), and the message subject. At most one of the message buttons in a set is selected (shown with a grey background). To select a message, click LEFT on it; to select and display a message, click MIDDLE on it. To delete a message from the message set, click CTRL-LEFT on it; its button will disappear. (Note that if this message belonged to no other message set, it is added to the Deleted set, and hence is still accessible.)
A message set displayer also contains several command buttons that operate on the selected message.
Categories lists (in the Walnut control window) the message sets in which the selected message appears (a message can simultaneously be in several message sets).
MoveTo adds the message from the message set to all of the message sets selected in the control window, after first deleting it from the message set.
Display displays the selected message.
Delete deletes the message from the message set; if it thus becomes a member of no other message sets, then it is moved to the Deleted message set.
AddTo adds the messages to the selected sets without first doing the deletion.
Print prints all the messages in the message set (see section 6 for options).
PrintSelected prints the one selected message (see section 6 for options).
Finally, the Active message set includes a NewMail button that reads new mail and adds the messages read to this message set.
For the MoveTo, Delete, and AddTo buttons, LEFT-clicking simply performs the operation described above, while RIGHT- or MIDDLE- clicking performs the operation and displays the next message in the set. (Note that if you have readonly access to a public database, then the MoveTo, Delete and AddTo buttons will not appear in message set displayers.)
2.2 Messages
As described above, a message can be displayed by clicking MIDDLE on a message button of a message set displayer. This creates a message display viewer, whose iconic form is an envelope (clicking SHIFT-MIDDLE on a message button causes the created viewer to fill the entire column). The message within such a viewer is not editable. This viewer is associated with the message set that created it, so clicking MIDDLE on another message of the same message set shows this new message in the same message displayer. This is designed to avoid a proliferation of message displayers. Of course, there are times when you really want to create viewers on several different messages in one set. Clicking a message displayer's Freeze button (which then disappears) permanently binds the message to the message displayer. If all message displayers for a given message set are frozen, then MIDDLE clicking in the message set creates a new displayer. A frozen message displayer cannot be unfrozen, but can be destroyed.
A message displayer has several other buttons. The Categories button is the same as that on message set displayers. Answer and Forward create a Walnut Send viewer initialized either with a proper heading for an answer to the message or a copy of the message for forwarding. The Print button uses the TSetter to print the message -- it will load the TSetter if necessary. And the remaining Split, Places and Levels buttons are from Tioga.
2.3 Sending mail
To create a Walnut Sender, left-click NewForm in the Walnut control viewer, or use the Answer or the Forward button on a message viewer, or type WalnutSend to the User Exec. A Walnut Sender is a Tioga viewer for typing in the header fields and body of a message you want to send.
The Sender menu:
Send is well named. StopSending! pops up during part of the sending process; clicking it gives you a last-minute chance to change your mind about sending a message. Right-clicking Send makes the Walnut Sender become iconic after syntax checking. (In iconic form a Walnut Sender is the back of an envelope.) A Walnut Sender will not allow itself to be destroyed while sending is in progress.
Get is similar Tioga Get -- Will load a local or remote file and allow editting
Store is like Tioga Store.
Save is like Tioga Save.
Forms shows the
Forms menu line. All the items on this line are guarded while the Sender is dirty.
NewForm might better be called DefaultForm; it replaces the current Sender with the default. (You can specify a non-standard default in your User.profile.)
PrevMsg restores the last message successfully sent from the current Sender.
And you can also add your own forms (see below).
Get and Store change the name of the Sender to be the file name. Clicking the Forms items will cause any backing file association for the Sender to be cleared and the caption will revert to Walnut Sender.
New creates another Sender.
Split is like Tioga Split.
Places is like Tioga Places.
Levels is like Tioga Levels.
The default Sender form now has node structure and uses a small bold font for the header fields. But added header fields use standard Roman; to get added fields to use the small font, include in your User.profile the line:
WalnutSend.labelFont: "sb"
If you want to change the default forms, you can create your own and specify them in your User.profile with the entries:
WalnutSend.DefaultForm: filename
WalnutSend.AnswerForm: filename
WalnutSend.ForwardForm: filename
The answer form must have header lines in the same order as the standard form and provide placeholders in the appropriate header positions. The forward form must have a node with the contents "ForwardedMessage"; Forward replaces this node with the message being forwarded. (See Jim Donahue for further details.) These private defaults can be local or remote.
If you need additional sending forms, you can specify them in your User.profile with the entry:
Walnut.MsgForms: {list of file names}
These additional forms will then appear in the pop-up Forms menu. Like private defaults, these additional forms can be local or remote. (You might, for instance, want to specify remote forms from /Indigo/Cedar/Forms.) Only the short name pops up; the default extension is .form, and only non-default extensions pop up. At the moment, there is no way to create additional answer or forward forms.
A message to a public distribution list or to more than twenty individuals probably needs a Reply-to: field. If your message doesn't contain one, Send will pop up a menu with the items
Self,
All, and
Cancel. Self means insert the Reply-to:
field and fill in my name
; All means do not insert a
Reply-to: field (replies then go to the full list)
; Cancel means whoops, don't send the message yet. To get Reply-to: sender when appropriate, without being asked, insert the entry
Walnut.ReplyToSelf: TRUE
in your User.profile. (With this entry, if at some point you want Reply-to: all you have to insert it by hand.)
Watch the Walnut control window for errors in transmission. If the transmission is successful, the message is saved and a new default form appears.
2.4 Retrieving mail
Walnut polls the mail servers at regular intervals. If there is new mail for the logged-in user and the database being read is the user's private database, the Walnut control viewer displays a message like
You have new mail at 27-Sep-82 14:28:45 PDT
(if you are reading a public database, the message will simply be
Cannot retrieve mail using this database (if you have write access) or
You only have Read access to this database).
Clicking the NewMail button (which will not be present if you're browsing a public database) in either the control viewer or the Active message set viewer retrieves all the new mail. You can "button ahead" during message retrieval. The new messages appear as buttons at the bottom of the Active message set viewer, with a "?" in the leftmost column of each new message button to show that the message is unread. If the control window is iconic and there is new mail, the flag on the icon is raised; for convenience, there is a NewMail button in the Active Messages displayer, which will retrieve the waiting mail.
Walnut will now automatically retrieve new mail for you, when it knows that your mailbox is not empty. To enable this feature, include:
Walnut.AutoNewMail: TRUE
in your profile. During startup or restart, Walnut may not immediately notice that there is new mail, even though the status line says there is; it will take Walnut at most 5 minutes to do the automatic retrieve. You can, of course, still use the NewMail buttons.
2.5 Global operations
The Walnut control viewer has a few more buttons that will now be described. Clicking Commit commits all changes that you have made to Walnut's database. The only other operations that automatically commit database changes are Destroy and CloseAll. If you perform a Walnut operation that updates the database and then boot or rollback without doing a Commit, the effects of that operation are in the log and will be performed on the database and then committed when you next run Walnut.
The CloseAll button furnishes a quick way of ending a session with Walnut. CloseAll destroys all message displayers, and closes all message set displayers. Then it executes a Commit and closes the Walnut control viewer.
The Archive operation provides a way to copy a set of messages into a file that can later be read by either Walnut or Laurel. Type a filename into the OnFile: field and click Archive. All messages in the currently selected message sets are copied to the named file (if the file name has no extension, ".ArchiveLog" is assumed). If Append is clicked, the messages are appended to the named file.
Clicking the (guarded) Expunge button (in the second control window menu line) expunges the Walnut database: all messages in the Deleted set disappear without a trace. (Laurel purges deleted messages every time you Quit or change mail files.) Without the Expunge operation, Walnut's database and log would grow without bound. The Expunge operation may fail if your disk is nearly full; this is a motivation for regular Expunges. Section 4 contains more information on this topic.
Walnut registers several infrequently-used commands with the Cedar Executive. All of the command names contain the prefix "Walnut", so typing Walnut*? to the Executive enumerates them. The Walnut command creates a Walnut control viewer if you should happen to Destroy yours; to open a public database on Alpine provide the Alpine directory name as an argument (eg., Walnut CSL-Notebook opens up the database stored on [Luther.Alpine]<CSL-Notebook>Walnut.segment). The WalnutExpunge command has the same effect as RIGHT-clicking Expunge. WalnutDump writes on expunged version of the log on the file "Walnut.TempLog", but makes no database changes. The WalnutOldMailReader command is described in Section 3, and the WalnutScavenge command is described in Section 4. WalnutNewMail simulates clicking the NewMail button. The WalnutSend command is like clicking NewForm. WalnutScavenge is discussed in Section 5.
3. The log
Walnut keeps a record of all retrieved messages and all database updates for a single user in a Walnut log file. This is a text file with a very simple format (an extension of the .mail format used by Laurel and Hardy); load your Walnut log into a Tioga viewer to see this. (Since your Walnut log be a large file, you may wish to use the OpenHuge command to load it into a Tioga viewer.)
The important point is that the truth about your Walnut mail resides in a Walnut log file; the Cypress database that Walnut uses for query processing can always be reconstructed by replaying a Walnut log file. The Walnut log mechanism is robust, making Walnut's mail storage reliable even if Walnut (or some other part of Cedar) crashes.
Walnut locates the log file for a particular user by consulting the Walnut.WalnutLogFile entry of the user profile. If there is no such entry, the name Walnut.DBLog is assumed. If you use a public Dorado, it is strongly urged that you store your log file on Alpine (see section 4.2). If you do not, each time you use Walnut, you must copy the log to the Dorado from a file server, then start Walnut (Walnut command to the Executive). At the end of a public Dorado session you must stop Walnut (Destroy button), then copy the log to a file server.
A Walnut log grows with each retrieved message and database update until an Expunge command is given to the Executive. This command writes a new Walnut log that only contains information about the messages that have not been deleted, and updates the database to be consistent with this. (Note that this requires disk space for two copies of the log, or one copy if your log is remote.) Because the cost of a full Expunge is proportional to the size of your Walnut log (which can grow to be quite large, if you are a "pack rat"), there is a "short cut" Expunge that only deletes messages from the point in the log of the previous Expunge; it is enabled by setting the Walnut.EnableTailRewrite user profile option. When enabled, LEFT-clicking Expunge causes the short-cut expunge to be performed, while RIGHT-clicking performs the full expunge. Note that with the tail-rewrite expunge any quite old messages that you delete (which appear before the expunge cut-off point) will not be removed from the log or database; thus, once in a while you will still need to do a full expunge.
Jim Morris's advice concerning files on the local disk is to "keep your bags packed". A prudent individual will apply this philosophy to his Walnut log. Include this (local) file in a personal .df file (such as the one that contains your user profile), and make it a habit to SModel it every few days.
4. Becoming a User
First, bring over the latest Walnut by typing
Bringover /a /p <Cedar>Top>Walnut
to the Executive; this will also retrieve WalnutSend, Cypress, AlpineUserImpls, and TSetter. These latter files will be also loaded by Walnut.
Before you can run Walnut, you will also need an account on the Alpine server "Luther.alpine" to store your Walnut database. Contact Karen Kolling to obtain an Alpine account. You can also store your log on Alpine which reduces the cost of using Walnut on a public machine (you can just retrieve your user profile from a server, login and type Walnut). If your log is to be stored on Alpine, tell Karen so that it will be backed up for you.
Edit your personal profile to contain all of the entries specified in WalnutDefault.profile (public in Walnut.df). The only profile entry that most users will want to experiment with is "InitialActiveRight: TRUE"; making it FALSE causes the Active message set displayer to create itself in the left viewer column, like all other message set displayers.
To start Walnut, type
Walnut
to the Executive. This will spend a long time loading, but finally a Walnut control viewer will appear.
You can include Walnut in a checkpoint. Be sure not to click checkpoint until the message "...Ready" appears in the Walnut control viewer typescript. Message and Message set displayers get updated after each rollback; if a displayed message or message set has since been deleted, the viewer will be destroyed.
To read a Laurel or Hardy mail file, or a file created by Walnut's Archive operation, first run Walnut as just described. Then type
WalnutOldMailReader <complete mail file name> {optional message set name}
to the Executive. If you fail to specify a message set name, the messages will be placed in Active. If the specified message set does not exist, it will be created. Using WalnutOldMailReader to read a Walnut archive log will put the messages back into the message sets they were in when archived.
6. User profile options
Below is a complete list of all of the current Walnut user profile options (copied from UserProfileDoc.tioga):
Walnut.ReplyToSelf:
BOOL ←
FALSE;
if TRUE, causes walnut to automatically supply a Reply-To: field, if appropriate.
Walnut.DestroyAfterSend:
BOOL ←
FALSE;
if TRUE, causes sender to be destroyed after a successful delivery, if Send was clicked with RIGHT
Walnut.AlwaysOpenSender:
BOOL ←
FALSE;
if TRUE, the first time WalnutSend is typed to the exec, the sender will be opened and grab the input focus.
Walnut.InitialActiveRight:
BOOL ←
TRUE;
true says to bring up the active message set on the right column, false on left.
Walnut.InitialActiveOpen:
BOOL ←
FALSE;
true says open a message set viewer on Active.
Walnut.InitialActiveIconic:
BOOL ←
FALSE;
if true and InitialActiveOpen = TRUE, then the Active message set viewer is opened as an icon.
Walnut.AutoNewMail:
BOOL ←
FALSE;
if TRUE, then automatically retrieves new mail when the mail box is nonempty.
Walnut.MsgSetButtonBorders:
BOOL ←
FALSE;
if TRUE, puts borders around the MsgSet buttons in the control window.
Walnut.EnableTailRewrite:
BOOL ←
FALSE;
if TRUE, performs "tail rewrite" on Expunge.
Walnut.WalnutSegmentFile:
TOKEN ← "[Luther.Alpine]<UserName>Walnut.Segment";
value is the name of the file to be used for the walnut data base.
Walnut.WalnutLogFile:
TOKEN ← "Walnut.DBLog;
Name of log file.
Walnut.AutoScrollMsgSets:
BOOL ←
TRUE;
if TRUE, automatically scrolls a msgset (when first displayed) to the first unread message (if any) or to the end.
Walnut.NewPageEveryMsg:
BOOL ←
FALSE;
if TRUE, when printing a msgset, every message will begin on a new page.
Walnut.PrintSmallHeaders:
BOOL ←
TRUE;
if TRUE, the headers sections of msgs get printed in a smaller font. This is NOT used for the print button on a message displayer.
Walnut.MsgForms:
LIST OF TOKEN ←
"";
A list of file names to be used as Walnut message forms (buttons for each file listed are added to WalnutSend viewers).
WalnutSend.DefaultForm:
TOKEN ←
"";
The file name of the default WalnutSend form (used when NewForm is clicked in a Sender).
WalnutSend.ForwardForm:
TOKEN ←
"";
The file name of the forwarding WalnutSend form (used when Forward is clicked in a message viewer).
WalnutSend.AnswerForm:
TOKEN ←
"";
The file name of the answering WalnutSend form (used when Answer is clicked in a message viewer).
WalnutSend.LabelFont:
TOKEN ←
"";
The font to be used for the labels on message the headers of sent messages
7. Shortfalls and Wishes
What follows is a listing of known deficiencies and contemplated extensions to Walnut. Nobody guarantees that everything listed below will be implemented. But the list does indicate some directions for future work, and may provide context for your own Walnut wishes. Send both bug reports and wishes to WalnutSupport^.
7.1 Message sets
It would be nice to allow selection of more than one message in a message set (perhaps even spanning message sets).
7.2 Retrieving mail
It seems desirable to make mail retrieval a continuous background activity. This would tend to insulate users from the response time of Grapevine.
Once mail retrieval is implemented in the background, a natural next step is to provide some means for a user procedure to classify incoming mail according to its significance, file it in sets other than Active, let the user know the status of his new mail ("You have important new mail").
The procedure that stores new mail in the database should understand the In-Reply-To relationship. Eventually, users should be able to write queries or other commands that exploit this relationship.
7.3 Sending mail
It should be possible to forward or answer multiple messages. This seems to require the ability to select multiple messages.
Feedback from mail parse errors can be improved. When displaying a message containing a parse error or bad a recipient, the point of error in the message header should be highlighted.
When sending a sequence of messages with the message composition viewer, you tend to click Send, wait for the feedback "sending ...", then make the viewer iconic (to reclaim the screen area) and finally click NewForm to create a new viewer. It would be smoother to reuse the same message composition viewer, but without waiting for the message to be sent (since this can take quite awhile). Since it is quite unusual to have two messages in transit (as contrasted with two messages being composed) at the same time, this can be achieved by passing responsibility for the message from the message composition viewer to the Walnut control viewer when message parsing is complete, and clearing the composition viewer for reuse. Any errors in transmission would be reported in the control viewer rather than the composition viewer.
7.4 Global operations
Walnut needs a way to make queries. (This is what databases are all about!) For starters, we'd like to have something analogous to Laurel's SearchMail program for performing text pattern matching in the messages of a message set.
The Walnut Expunge operation currently requires more resources (such as disk space) than Walnut requires to perform other operations on the same database. This is unfortunate, since it means that a user can get stuck in a situation where he must hand-edit his Walnut.DBLog in order to recover.