4. Entering Af

The usual way to invoke af is with the shell command `af'. Af clears the screen and then displays an initial help message and copyright notice while it processes any startup files (see section 21.2 The Startup File, `~/.afrc'), and then reads your incoming mailbox. (If your mailbox is small, you may not see the initial help message and copyright; it would be very inconvenient for experienced users if af were to pause long enough to let you read the message.) When af has finished reading the mailbox, it displays a final count of how many messages it read, and displays the buffer containing the messages.

Some operating systems discard all type-ahead when af starts up; they give af no way to prevent this. Therefore, it is advisable to wait until af clears the screen before typing your first command.

It is possible to specify folders to be visited, or details of a message you want to send, by giving af arguments in the shell command line (see section 4.1 Command Line Arguments). But you can do these things from within af too; whether you run af once and suspend it, or separately each time you want to read or send mail is simply a matter of taste.

Arguments starting with `-' are options. Other arguments specify addresses to send mail to. If you specify addresses (or use any of the `-c', `-b', or `-E' options), then af doesn't read any folders; it simply allows you to send a single mail message to the addresses you supplied, and then exits.

You can use options to specify various other things, such as which folders to read, the subject for mail you're sending, and so on. A few options support advanced usage, such as running afl functions in batch mode. The sections of this chapter describe the available options, arranged according to their purpose.

Most options specify how to initialise af, or set parameters for the af session. We call them initial options. A few options specify things to do: for example, read folders or load afl programs (see section 22. Afl). These are called action options. These and file names together are called action arguments. Af processes all the action arguments in the order they are written.

4.1 Command Line Arguments		The command line arguments af accepts
4.2 Command Line Examples		Examples of using command line arguments.
4.3 Environment Variables		Environment variables that af uses.

4.1 Command Line Arguments

Here is a table of the arguments and options that af accepts:

`address'

Send mail to address. See section 8. Composing and Sending Mail. If addresses are supplied, then many of the other arguments are disabled, since af will not be visiting any folders. If the standard input is not a terminal, then af will silently send the message as requested, rather than expecting you to edit the text of the message.

`-E'

This option has two effects. Firstly, it makes af start up to send a single mail message even if no addresses were given as arguments. Secondly, it forces af to allow you to edit the text of the message you send, even if the text is being obtained from the standard input. This doesn't really seem very useful, but occasionally it can be very handy in allowing you to write flexible scripts which send mail using af.

`-H'

Force af to present the user with the headers of an outgoing message when editing it, or to force translation of headers in mail sent from the standard input. In effect, it causes af's edit-initial-headers variable to be set to true regardless of the contents of the user's `.afrc' file (see section Variables).

`-c cc'

Specifies one or more addresses to send a carbon copy of a message to. If the addresses contain spaces then you should enclose them in double quotes.

`-b bcc'

Specifies one or more addresses to send a blind carbon copy of a message to. If the addresses contain spaces then you should enclose them in double quotes.

`-s subject'

Specifies the Subject: for an outgoing message. Only one `-s' option may be given, and it only takes effect if addresses (or the `-c', `-c', or `-E' option) were given on the command line. If the subject contains spaces then you should enclose it in double quotes.

`-C content-type'

Specifies the MIME Content-Type: for an outgoing message. Only one `-C' option may be given, and it only takes effect if addresses (or the `-E' option) were given on the command line.

`-f folder'

Read folder in place of your incoming mailbox. Multiple `-f' options may be given, in which case each folder is read into its own buffer. This option is ignored if addresses or the `-E' option were given.

`-u user'

Read user's incoming mailbox in place of your own. You must have permissions to read user's mailbox. Multiple `-u' options may be given, and they may be mixed with `-f' options. This option is ignored if addresses or the `-E' option were given.

`-F'

Interpret any arguments other than options as folders to be read in, rather than addresses to send mail to. This can be very useful if you want to read in a set of folders with `af -F *'.

`-w'

Create enough windows to display all the folders given with the `-f', `-u' or `-F' options, subject to the maximum number of windows that will fit on the screen (usually about four on a 24-line display). This option is ignored if addresses or the `-E' option were given.

`-e'

Check whether there is mail in your default mailbox (or, if `-f' or `-u' are given, any specified mailboxes) and then exit. The exit status is zero if there is mail in any of the mailboxes; one if not. This option is ignored if addresses or the `-E' option were given.

`-z'

Makes af terminate immediately with an exit status of 1 if your incoming mailbox (or, if `-f' or `-u' are given, any specified folders) is empty. Otherwise, af will start up normally. This option is ignored if addresses or the `-E' option were given.

`-n'

Ignore the file `.afrc' in the user's home directory. See section 21.2 The Startup File, `~/.afrc'.

`-v'

Prints the version of af and then exit. Ignores the effect of any other options.

`-l loadfile'

Specifies a file which should be read and executed on startup before any buffers are created. Used with the `-n' option, this allows the user to specify an alternate startup file, rather than the default of `.afrc' in their home directory.

`-S file'

Names a file of commands in af's internal language afl. The commands in the file are read and executed exactly as if af had been started up interactively and then the af command load-file had been executed. When all the commands in file have been executed, or if an error is encountered in the file, then af terminates. If the `-S' option is given, then af will not display the screen; only messages will be printed to the standard output. Only one `-S' option may be given, it is ignored if destinations or the `-E' option were specified.

4.2 Command Line Examples

Here are a few examples of af command line usage, with brief explanations.

Read two folders `foo' and `bar' into separate windows:

af -f foo -f bar -w

Check if there is any mail in folders foo and bar:

af -e -f foo -f bar

Send mail to `fred' on the local system with subject `Hi':

af -s Hi fred

Take a current directory listing, and use it as a base for some mail to user `fred@foobar.co.uk':

ls -l | af -E fred@foobar.co.uk

Run the afl script in file `script.afl' with folder `foobar' as the default buffer:

af -S script.afl -f foobar

4.3 Environment Variables

Af uses several environment variables. An environment variable is a string passed from the operating system to af, and the collection of environment variables is known as the environment. Environment variable names are case sensitive and it is conventional to use upper case letters only.

Because environment variables come from the operating system there is no general way to set them; it depends on the operating system and especially the shell that you are using. For example, here's how to set the environment variable ORGANIZATION to `Utter Chaos' using bash:

export ORGANIZATION="Utter Chaos"

and here's how to do it in csh or tcsh:

setenv ORGANIZATION "Utter Chaos"

It should be noted that the environment variables are used to customise af, not to configure it. None of these variables are required; and af should work correctly without them. They simply serve to tailor af to your taste.

Here is a list of the environment variables af uses, with a brief description of what they are used for.

MAIL

The full path to your incoming mailbox.

HOME

Your home directory.

FOLDER

The directory where your mail folders are stored. Defaults to `~/Mail'.

SAVEDIR

The directory where your news folders are stored. Defaults to `~/News'.

TMPDIR

The directory where temporary files should be created.

VISUAL, EDITOR

The editor to use for editing outgoing mail (or messages if you choose to edit them). VISUAL overrides EDITOR if they are set to different values.

PAGER

The program to use when you ask af to display a message via an external pager.

NAME

Your real name. Used for generating the headers on the messages you send.

ORGANIZATION

your organisational affiliation. If set, af will generate an Organization: header on the messages you send.

4.4 Exiting af

There are two commands for exiting af because there are two kinds of exiting: suspending af and killing af.

Suspending means stopping af temporarily and returning control to its parent process (usually a shell), allowing you to resume reading mail later in the same af job, with the same buffers, same kill ring, and so on.

Killing af means destroying the af job. You can run af again later, but you will get a fresh af; there is no way to resume the same mail reading session after it has been killed.

C-z

Suspend af (suspend-af)

C-x C-c

Kill af (save-buffers-kill-af).

M-z

Kill af, automatically saving any changed buffers (save-all-kill-af).

To suspend af, type C-z (suspend-af). This takes you back to the shell from which you invoked af. You can resume af with the shell command `%af' in most common shells.

On systems that do not support suspending programs, C-z starts an inferior shell that communicates directly with the terminal (shell). Af waits until you exit the inferior shell. (The way to do that is probably with C-d or `exit', but it depends on which shell you use). The only way on these systems to get back to the shell from which af was run (to log out, for example) is to kill af.

To kill af, type C-x C-c (save-buffers-kill-af). A two-character key is used for this to make it harder to type. This command first offers to save any modified file-visiting buffers. If you do not save them all, it asks for confirmation with yes before killing af, since any changes not saved will be lost forever.

To kill af, saving all modified file-visiting buffers, type M-z (save-all-kill-af). We don't recommend using this, since you might accidentally save changes you didn't mean to, but you can use M-z to exit if you prefer.

The operating system usually listens for certain special characters whose meaning is to kill or suspend the program you are running. This operating system feature is turned off while you are in af. The meanings of C-z and C-x C-c as keys in af were inspired by the use of C-z and C-c on several operating systems as the characters for stopping or killing a program, but that is their only relationship with the operating system. You can customise these keys to run any commands of your choice (see section 21.6 Customising Key Bindings).