The text-graphics interface is reminiscent of the vi visual editor. This interface does not require graphics capabilities of the computer or the terminal on which it is run, but the terminal must have the minimum capabilities required by any visual screen editor.
The default interface is the conventional tty-based line mode similar to command line interpreters such as csh as well as other mailers, such as University of California, Berkeley's, Mail and Bell Lab's System V mailx interface. This mode requires nothing from the terminal in cursor optimization and may be run on many different version of UNIX running on various architectures such as VAX and MicroVax (4.2, 4.3 BSD), IBM-PC AT's running system V (XENIX), IBM-RT's, and pyramids.
See the correpsonding subheadings for more information on the user interface desired. Most of this manual deals with commands, variables and actions which are usually common to all three interfaces although some attention is paid to individual characteristics of each interface.
The following command line arguments are understood by Mush:
The following features are common to all user interfaces that Mush provides. Interface-specific features are listed separately under the subheading for that interface. Commands and user definable variables are described under the appropriate subheadings.
New Mail.
If during a Mush session, new mail arrives for you, it is automatically incorporated into your system mailbox and you are told that new mail has arrived.
In the default line mode, new mail is checked between each command issued. In the tool based graphics mode, new mail is checked approximately every minute or by the number of seconds specified by the -T option on the command line. In the curses mode, new mail is checked on each command and is displayed in the bottom line of the screen.
If you are using your system mailbox as your "current folder," then the new mail is added immediately to your current list of messages and this information is displayed telling you whom the mail is from:
New mail: (#15) island!argv@Sun.Com
If you are not in your system mailbox, then the new mail will not be added to your list of messages, but you will instead be informed of the new arrival.
If you are using the tool based mode and Mush is closed to an iconic state, then the number of messages in the current folder is displayed on the mailbox icon and the flag on the mailbox will go up.
Aliases.
Mail aliases are shorthand names for long mail addresses. These are supported in the same manner as UCB Mail supports them. Because Mush has command line history reminiscent of csh, commands which use uucp's `!' character for user-host and host-host separation should be escaped (preceded by a backslash). This is not necessary in the initialization file (.mushrc) because history referencing is ignored while these files are being sourced. See the subheading, INITIALIZATION and the line-mode interface for more information on initialization file format and the history mechanism.
Aliases reference normal mailing addresses as well as other aliases. If a loop is detected, then the user will be notified and a dead.letter will be forced into the file dead.letter in the user's home directory. The command, unalias, is used to reverse the effects of the alias command.
Help.
Mush was designed so that each command or action should not be a mystery. Helping the user understand what to do and how to do whatever he wishes is the goal behind the help facility. For this reason, the command, help gives information on both general usage and specific help categories.
In text mode, most help is gotten by typing `-?' as an argument to a command. Virtually all commands have the -? option. When this option is specified, most commands will attempt to read from a help file the necessary information explaining the functionality of the command in executed. If necessary, a pointer to other sources of information will be given to fully explain a concept.
In the tool/graphics mode, this is also possible, but more extensive help is provided in the pop-up menus. Pop-up menus can be gotten from virtually anywhere on the screen; press the RIGHT mouse button (the "menu button") and a number of items will appear in a menu. The last command in the menu list will be one labelled "help." Selecting this menu item will display a "help box" in the center of the console and wait for input to remove the box.
In the curses mode, the `?' key will display a list of the current command-to-key bindings; a keystroke or set of keystrokes correspond directly to a command.
Sorting mail.
Mush allows you to sort your mail according to various constraints such as time, status (new, unread, deleted, etc), by author and subject. See the sort command in the subheading COMMANDS for more information on sorting.
Picking specific messages.
You can select messages that contain unique information, or from messages that have special attributes. You have the option of restricting your search to messages between dates, message numbers, author names and other constraints.
Upon startup, before any command line arguments are parsed, and before the current folder's messages are read (thus, there are no messages to speak of, yet), Mush will initialize itself with basic variable settings and values. If the -n option is given, initialization is not done. If no -n option is given, it will source an initializing file which contains commands that [typically] set variable values, aliases, command line aliases, and so forth. The file it reads from is determined by first looking for the environment variable, MAILRC. If that file isn't found, then the file .mushrc is search from the home directory of the user. If that file cannot be found, it will attempt to read the file, .mailrc from the same directory. If that file isn't found, then the default initialization file setup by the administrator is attempted. Finally, if that file cannot be read, then nothing is done about initialization and the default values will be in effect.
If the user has no home directory, or permissions prevent read/write access to $HOME, /tmp is used as the home directory. See the home variable under the VARIABLES heading.
You may specify a filename to source if you want to source a specific file other than the default. You may use the command saveopts to save all variable settings, aliases, and all other Mush settable attributes. If no filename is given on the command line, saveopts chooses a file in the same manner that source does. Using saveopts is highly discouraged since it overwrites files without warning and saves settable variables only. ``if'' expressions are not saved and session-dependent settings may be invalid upon next invocation.
Initialization File Format. When reading the initialization file, Mush will recognize the `#' character as a comment character. It may be anywhere on a line in the file. When that character is encountered, processing of that line is discontinued to the end of the line. If the `#' is encased in quotes (single or double), then it is not considered a comment.
set shell = /bin/csh # set the shell variable
# this entire line has been commented out.
set prompt = "Message #%m: " # The `#' is within quotes
The exit command has special meaning in the initialization file. If the command is found, Mush will not exit, but rather, discontinue reading from the file immediately.
There may be ``if'' expressions within the initialization file to determine certain runtime states of Mush. There are no parentheses allowed and only one boolean expression may be evaluated per line; that is, no ``&&'' or ``||'' may be used in expressions. There is currently no support for multiple levels of if-else expressions and embedded ``if'' expressions are ignored (they are evaluated to TRUE). There must always be an ``endif'' accompanying all ``if'' expressions. The statements associated with an ``if'' expression are never on the same line with the conditional.
Understood conditional expressions include the internal variables, istool, iscurses, hdrs_only, and redirect. If istool is true, the program is going to start in the tool mode. If iscurses is true, the program is in or is going to start in the curses mode even though the screen package may not have already been started. If hdrs_only is true, then the -H flag on the command line has been given. If redirect is true, then input to the program is redirected. The -i option on the command line is required to run the shell if redirect is on. If the flag is specified, the value for redirect will be set to false. These are internal variables whose values can not be referenced using the ``$variable'' method of variable expansion.
The `!' operator may be used to negate expressions, thus,
if !istool
exit
else
set autoprint
endif
means that if you are not running as a tool, stop reading commands from this file. Otherwise, set the autoprint variable. The test for redirection may be done to determine whether or not input, not output, has been redirected to the program.
set hdr_format = "%S %25f %7d (%l/%c) %25s"
if (hdrs_only)
exit
endif
This tells the program to set the hdr_format variable and check to see if we're running the program to read headers only. If so, stop reading this file (exit) and continue on with the program. This speeds up runtime quite a bit for those who have lengthy initialization files because no other shell variables are necessary.
if !iscurses
set crt = 24 screen = 18
endif
This segment checks to see if we're not running in curses mode and if not it will set our crt and screen sizes. This is mostly because the curses mode will set those values for us by looking at the size of our screen for us. The curses command itself should never be called from an initialization file. Doing so will cause terminal settings to be set incorrectly and unpredictable results from there. In fact, no interactive commands should be called from any initialization file. These commands are not prevented because it is impossible to trace which commands are aliased to interactive commands and which might even be shell commands that are interactive. The responsibility of not running interactive commands is left to the user. See the section on curses under THE CURSES INTERFACE for configuring your environment so you enter the curses interface each time you runs the shell.
When initialization files are being read, no history expansion is done, so the `!' need not be escaped for address aliasing. String evaluation is allowed and the operators, "==" and "!=" may be used to determine their equality. Usually, variables are compared with constants for evaluation.
if $TERM == adm3a
set pager = /usr/ucb/more
else
set pager = /usr/local/less
endif
This segment tests to see if the user's terminal type is "adm3a". If it is, then it sets the pager variable to be the "more" program. Note that the variable TERM will be gotten from the user's environment if a shell variable is not set already. Otherwise, the pager variable is set to "less". This example exemplifies the fact that "less" normally fails to function correctly for the terminal type ``adm3a'' so we don't use it.
After sourcing the initialization file, Mush reads all the mail out of the specified folder (the system spool directory if no folder is given) and creates a list of messages. The current maximum number of messages the user can load is set to 1000 by default. The system administrator who configures the program can reset this value higher or lower if you ask nicely. If the user has the sort variable set, then when the current folder's messages are finally read, the messages are sorted according to the value of the variable (see the sort entry under the VARIABLES heading for more information). Each message has a number of message headers which contain information about whom the mail is from, the subject of the message, the date it was received, and other information about the letter. This information is then compiled into a one line summary and is printed out sequentially in the appropriate manner depending on the interface you're using.
At this point, commands may be input by the user. The initialization file is read before any messages are read into the program. Message filtering commands should not be placed in this file unless you know you're going to resource the file later as a command. For example, a filtering file, "filter", might contain:
pick -f Mailer-Daemon | save mail_errors pick -f yukko | delete pick -s -i thesis | save +thesis_mail pick -t unix-wizards | +wizmail update sort d
The first command the user could type might be source filter and the following would happen. First, all messages that have Mailer-Daemon in the from line will be saved in the file "mail_errors". Then, all mail from the user "yukko" will simply be deleted. Next, all mail that has in the subject field "thesis" (case ignored, so "Thesis" would also match) would be saved in the file $folder/thesis. The next command would find all messages that were addressed to the group "unix-wizards" (of which the user is an elite member of) and save them in the file $folder/wizmail. The folder will be updated, removing all deleted mail (saved mail may be marked as deleted), and the folder is reread and sorted according to the date of the messages.
When a command line has been determined and placed in an argument vector, the first argument in the vector (the `command') is searched for in a list of legal Mush commands. If found, the function associated with that command is called and the rest of the line is passed to that function as command line arguments.
Before commands are called, however, the input the user gives is preprocessed
in a style reminiscent of
csh. Mush
also supports a subset from each of the following aspects of
csh.
* Command history.
* Command line aliasing.
* A `piping' mechanism to redirect "input" and "output" of commands.
Command history.
The history mechanism remembers commands up to the value of the history variable. To reference previously typed commands, the `!' character is used in the same manner as csh.
Examples:
!-2:$ two commands ago, last argument. !3:2-4 the third command, arguments two through four. !! the last command in its entirety.There is a limited implementation of history modification. Supported is the argument selector which references command line arguments and 'p' (echo, but don't execute the command).
During the sourcing of initialization files (.mushrc), history is not in effect and therefore the ``!'' character does not cause history expansion. This includes startup of the program and when the command source is issued. Uucp style addresses that contain the ``!'' character may be given without the need to be preceded by a backslash in the initialization file. However, ``!'' does need to be escaped if cmd's are used to reference command line arguments.
Command line aliasing.
This feature enables command substitution similar to csh. To be backwards compatible with UCB's Mail, the alias command is used for address aliasing. Thus, the command cmd is introduced in place of alias.
Examples:
cmd d delete cmd t type cmd dt 'd ; t' cmd - previous cmd r 'replysender \!* -e -i'
In the last example, if the user types `r 5', Mush will reply to sender of the fifth message and pass all the other arguments along to the reply command. Note the escaping of the ! character. This must also be done if set in the initialization file (.mushrc). Had the user not specified a message number on the command line (`r'), respond would reply to the "current message" rather than the fifth message.
Piping commands.
"Output" from a command is a message list, not the text in a message. A message list is defined as the set of messages which the user specifies in a command or the messages a command affects after it is through executing. When one command is piped to another, the effect is that the second command will "consider only those messages the affected by first command." In most cases, Mush is smart enough to know when piping is occurring and may suppress text output that a command might produce.
Examples:
pick -f fred | save fred_mail
This will find all the messages from "fred" and save them all in the file named "fred_mail".
lpr 4-8 | delete
This will send messages 4, 5, 6, 7, and 8 to the printer and then delete them.
headers :o | delete
Delete's all old (already read) mail.
Because action is taken on mail messages, not files, metacharacters such as `*' and `?' are not expanded to file names as csh would do. Instead, Mush commands take as arguments, message lists (a list references one or messages) to take action upon. To reference message numbers, there is a special syntax that Mush will understand.
* All messages. ^ The first message. $ The last message. N-M A range of messages between N and M.In the last case, N and M may be * ^ $ . or digits referencing explicit message numbers. The range must be in ascending order.
You can also negate messages by placing the message list inside braces, `{' `}' -- thus, the expression "2-19 {11-14}" references messages 2 through 19 except for those between 11 through 14.
Note that message lists are parsed left to right. Indicating negated
messages may be reset by turning them on again later in the argument list.
A common error new users have is to specify a negated list without
specifying any beginning messages.
delete { 6 }
In this example, the user attempted to delete all messages except for number 6. He should have specified the * before hand.
preserve ^-. { 3 }
Here, the user specifies a valid message list and causes
mush
to preserve all messages from the beginning of the list (message 1)
to the current message excluding message 3.
As discussed, the command line is parsed and the command given is called and the rest of the arguments on the command line are passed to it. If no command has been found for the one given, then the variable unix is checked. If set, the command line given is attempted to be run as a regular UNIX command.
If it is not set, or if the command cannot be found in the user's PATH environment, a message will be printed indicating that the command was not found.
Since no `messages' are affected by UNIX commands, piping is disallowed either to or from such commands. If the user wishes to execute UNIX commands which are to be piped to one another (or use any sort of redirection), the command, sh is provided for such purposes. Since Mush will parse the entire command line, caution should be taken by enclosing quotes around questionable shell variables or metacharacters. See the COMMANDS heading below for more detail.
This shell-like quality is for the convenience of the user and is not intended to replace the functionality of sh, csh, or any other command interpreter.
Many users who prefer the curses interface might want to always start all their mail sessions in the curses interface. Putting the curses command in your initialization file is a no-no, so you can alias your login shell mail command to include the -C option. If you use the Bourne Shell, you're going to have to type it out all the time. Mush is going to attempt to know not to run a shell if you're just sending mail to someone, so the command line sequences:
% alias mail 'mush -C' % mail fred
will mail to fred and not enter the shell. However, if you just said, "mail" with no arguments, you'll enter the shell in curses mode if you have mail. If you don't, you'll be told so. If you want to enter curses mode even if you don't have mail, use the -S option on the command line.
In curses mode, the user's terminal has it's "echo" turned off so commands that are issued are not echoed on the screen. Certain commands cause the mode to return to normal for typing purposes (sending mail, for example). In normal operation, the screen will display the current set of message headers, the current message number is in the top left corner, the mail status on the top line, and the cursor will be placed on the current message. The number of message headers displayed is set by the variable, screen. If the user does not have that variable set, the baud rate is checked and the size of the screen is set according to optimal refresh time. Usually, 300 baud gives 7 lines, 1200 gives 14, 2400 gives 22 lines, and all higher baud rates give the size of the screen, whatever that may be. Note that the top line is reserved for "status" and the bottom line is for user interaction should it be required.
The user may now type commands via key sequences which are not echoed to the screen. Thus, function keys may be bound to "commands" by using the bind command. A list of key-to-command bindings can be found at runtime by typing `?' in curses mode or by using the bind command.
The commands which you can map sequences to are intended to be as self explanatory as possible, but admittedly, it's easier to figure out via trial and error than to try to wade through this documentation. A list of the legal curses commands can be obtained when executing the bind command. Regular tty line-mode commands are not issued from the curses interface; only special curses mode commands are understood. The current list of valid curses commands is:
goto msg write write list save save list copy copy list delete delete list undelete undelete list reverse video redraw next msg back msg first msg last msg top page bottom page screen next screen back show hdr source saveopts search up search down search cont preserve sort sort reverse quit! quit exit! exit update folder shell escape line mode lpr chdir variable ignore alias my hdrs version mail flags mail reply reply all display top display next bind unbind help
The following is a list of default key-command bindings. If you specify bind commands in your initialization file that conflict with these defaults, your settings will override the defaults. The default settings given here use the ^-character method to indicate control characters. Thus, `^X' would mean control-X even though you'd have to type "\CX" to set the binding and actually use the control key and the `X' key simultaneously to really do a Control-X. This is mostly because nroff makes printing the backslash character so amazingly difficult.
When setting new key sequences to be bound to commands, the user may use control keys and the ESCAPE character for extended commands. Exceptions are control-C, control-\, and possibly other control characters depending on your system's configuration or your current tty interrupt character settings. The spacebar may not be bound since it is the only obvious way to return to the top level curses mode from the "...continue..." prompt.
When assigning key sequences to commands, the user enters the bind command and prompting is done. If the user wishes to have control characters or the escape character in a key sequence, he must use special notation since control characters are not echoed visibly on the screen. This same sequence is used if the user wants to bind sequences in the initialization file.
To bind control characters, the sequence, "\Cc" is used where ``c'' is the character which the control key will translate to and must be in upper case. The sequence, "\CP" would map to control-P. If the user wishes to indicate the RETURN key, this is specified with the string, "\n" and the tab key is specified by the string "\t". On a Wyse-50 terminal, the 8th function key outputs the three characters: Control-A, H, line-feed. To map this function key to a command, the user would have to enter the sequence, "\CAH\n" as the key sequence, then follow up with a valid curses command. From then on, if the user uses that function key, then the command mapped to it will be executed.
The ESCAPE key is signified by the sequence, "\E". On a Sun-3 workstation, the R1 key outputs the character sequence: ESC, [, 2, 0, 8, z. The corresponding key sequence would be "\E[208z". Restrictions are that key sequences may not contain the space key or begin with a digit. Unfortunately, this makes mapping the spacebar to a command impossible.
Whenever a command is entered, if the command causes the screen to scroll or be refreshed in anyway, the mode is left in the continue mode. When in this mode, the user is given his line-mode prompt followed by "...continue..." indicating that he may issue a new command or return to the top level where the current message headers are displayed on the screen. Remember that this is still the curses mode, but much time is saved by avoiding to redraw the screen after each command. The user may move up and down messages using the appropriate commands (j/k by default) or anything else the curses mode allows. Unknown commands do not return to the top level, only the spacebar, and the exit and quit commands will return to the top level. Because the exit and quit commands are used to do this, there are 2 additional ways to "quit" in the program and return to the login shell. The two commands, "exit" and "quit" commands will quit from the top level, but the commands, exit! and quit! are used to exit from the "continue" level in the curses interface as well as from the top level.
Note that the best way to understand the curses interface is to just use it. In line mode, the command "curses" puts you into curses mode.
The panel items have labels describing their functionality. Selecting a panel item with the LEFT mouse button causes the action to be executed. The RIGHT mouse button displays a menu of options that the command may branch to. For example, the save panel item by default will save messages to the file "mbox", but if the RIGHT mouse button causes a menu to be displayed the choices of where to save the message increases to include the items in the menu. These typically include the files in the user's folder directory (see the folder variable below).
At the end of each list of menu entries for panel items is an item labelled "help." When this item is chosen, help with that command is displayed in the center of the console.
When composing letters, the interface is the same for the tool mode, the line mode and the curses mode. Tilde escapes are recognized by all the interfaces, but the tool interface allows the user to use the menu mouse button to select the tilde escape desired.
If the user wishes to review a mail message while in edit-mode, he may do as the other interfaces and enter the tilde escape command, ``~:print''. This will cause the current message (or message number if given) to be displayed in the window. Editing is temporarily put on hold till the user enters a `q' in the message window to indicate that he is done reading the message and input is to be directed again to the letter being composed.
Because there are three different interfaces available to the user, the tty characteristics (backspace, kill-word, kill-line, redraw line) are simulated identically to all routines. When the user has to type something, the 4.2BSD style of tty driver interface is simulated whether you're in the window system, the curses mode, the tty-line mode, and even on System-V machines. This means that backspacing causes a backspace-space-backspace effect (erasing the character backspaced over). The user may reset his tty characteristics using the stty command.
Displaying messages.
Depending on the interface you use, you can display any message in your list of messages as long as the message is not marked for deletion. If the message is marked as deleted, then use the undelete command supplied by the interface you are using. To display a message in line mode, specify a message to be displayed using print, type, p, t, or by typing the message number, that message will be printed on the screen.
In the graphics mode, you move the mouse over the message you wish to be displayed and select the LEFT mouse button. If the message you want is not visible (in the header subwindow), you may type in the message subwindow the number of the message and hit return. That message number will be displayed.
In curses mode, you can move the cursor over the message you want and type a `t' or `p' to read the message. The user may "bind" other keys to call the function which displays messages if `t' or `p' are uncomfortable.
In the line or curses mode, if the message has more lines than the variable crt, then a pager will be invoked to allow the user to page through the message without having it race by the screen. The pager used is determined by the variable, pager. If that variable is unset, the a default pager will be used. Note that if pager is set, but not to a value, then nothing will be printed.
In the tool mode, if a message is larger than the size of the message subwindow, the amount of the message viewed is displayed and the user may page through the message via `+' (forward by lines), `-' (backwards by lines), LEFT mouse button (forward by pages), or RIGHT mouse button (backwards by pages). The user may precede the `+' and the `-' keystrokes with a numerical count to specify how many lines to scroll.
An alternative to displaying messages is the top command. This command will print just the top few lines of a message. The number of lines is determined by the variable, toplines. If this variable isn't set, ``top'' will print the value of the variable, crt, number of lines.
Sending mail. You can send mail using the mail command or by responding to other mail. In either case, when you are sending mail, you are in a mode where everything you type is added to the contents of the message. When you are done typing your message, you can type ^D to signify the end of the message. If you have the variable, dot set, then you can end a message with a "." on a line by itself.
While you are composing a message, Mush treats lines beginning with the character `~' specially. This is called a tilde escape. For instance, typing ``~i'' (alone on a line) will place a copy of the "current message" into your message body. It will not include the message headers of the message, just the body of text. Each line of the message will be preceded by "> " to indicate that it is an included message. You can set the variable string indent_str to a string if you want to precede those lines with something other than "> ".
Available tilde escapes: [OPTIONAL arguments in square brackets]