Basic af Commands
*****************

We now give the basics of how to read, save, and delete messages, send mail to people and save your changes back to your mailbox.

Reading Messages
================

The most basic operation in af is to open the current message; to display it's contents via typeout (see Typeout), or some other pager.

RET or C-o
     Open the current message, using the pager named in the pager variable, usually typeout.  If the message is a MIME message, then use the pager named in the mime-pager variable instead if possible.

M-RET or C-M-o
     Open the current message, using the pager named in the PAGER environment variable.

Normally, only mail headers not listed in the headers-not-displayed variable will be displayed when you open a message.  A positive numeric argument makes af display all the message's headers.  A negative argument makes af skip all headers, and only display the body of the message.  See Arguments for more information on numeric arguments.

If your external pager doesn't need af to pause after displaying the message; then you can make reading messages more convenient by setting the variable pause-after-paging-message to true.

Changing the Location of Point
==============================

To do anything useful with af, you have to know how to move point (see Point).  There are several keys which move point within a buffer.

C-n or n
     Move down one line, vertically (next-line).

C-p or p
     Move up one line, vertically (previous-line).

M-.
     Move point to the vertical centre of the window. (move-to-window-line).  Text does not move on the screen.

     A numeric argument says which screen line to place point on.  It counts screen lines down from the top of the window (zero for the top line).  A negative argument counts lines from the bottom (-1 for the bottom line).

M-< or <
     Move to the top of the buffer (beginning-of-buffer).  With numeric argument N, move to N/10 of the way from the top. See Arguments, for more information on numeric arguments.

M-> or >
     Move to the end of the buffer (end-of-buffer).

C-g
     Read a number N and move point to line number N (goto-line).  Line 1 is the beginning of the buffer.

Scrolling
=========

Since only part of a large buffer fits in the window, af tries to show the part that is likely to be interesting.  The display control commands allow you to specify which part of the buffer you want to see.

C-l
     Clear screen and redisplay, scrolling the selected window to center point vertically within it (recenter).  A numeric argument N says to move point to screen line N.

C-v
     Scroll forward (a windowful or a specified number of lines) (scroll-up).

M-v
     Scroll backward (scroll-down).

The names of all scroll commands are based on the direction that the messages move in the window.  Thus, the command to scroll forward is called scroll-up, since the messages move up.

When scrolling a windowful at a time, af leaves two lines that were visible before you scrolled still visible afterwards, so that you can retain the context you were in before you scrolled.  The number of lines of overlap across a C-v or M-v is controlled by the variable next-screen-context-lines; by default, it is two.

Deleting Messages
=================

C-k or k
     Kill the current message, removing it from the folder (kill-line).  See Killing and Yanking.

M-x delete-message
     Mark the current message as deleted.  This doesn't actually delete the message until you save the buffer.  At that point any messages marked as deleted will be killed, and not written to the folder.

M-x undelete-message
     Remove the deleted marker from the current message; so that it will not be killed when you save the buffer.

Message and Position information
================================

Here are commands to get information about messages, and your position in the buffer.

M-=
     Print line number of point in the buffer (what-cursor-position).

C-x =
     Print a short summary of some of the message's details in the echo area (message-info).

C-t ?
     Print the message's tags in the echo area (message-tags). See Tags.

Quitting
========

At any time in af except when a command is running, you can type C-g (keyboard-quit) to quit from what you are doing.  If you have typed part of a command, or a numeric argument, then C-g will get rid of it.  If there isn't a partial command to get rid of, but you are in the minibuffer or typeout then typing C-g will exit back to the mail buffer, aborting the command you were running.

This means, that you can always get back to the top level of af by typing C-g C-g.  This is useful for aborting commands, or if you are unsure where you are in af.

Help
====

If you forget what a key does, you can find out with the Help character, which is C-h.  Type C-h k followed by the key you want to know about; for example, C-h k C-n tells you all about what C-n does.  C-h is a prefix key; C-h k is just one of its subcommands (the command describe-key).  The other subcommands of C-h provide different kinds of help.  Type C-h three times to get a description of all the help facilities. (see Help).

Numeric Arguments
=================

Any af command can be given a numeric argument (also called a prefix argument), although it may be ignored.  Some commands interpret the argument as a repetition count.  For example, C-n with an argument of ten moves down ten lines instead of one.  With these commands, no argument is equivalent to an argument of one.  Negative arguments tell most such commands to move or act in the opposite direction.

If your terminal keyboard has a META key, the easiest way to specify a numeric argument is to type digits and/or a minus sign while holding down the META key.  For example,

     M-5 C-n

would move down five lines.  The characters Meta-1, Meta-2, and so on, as well as Meta--, do this because they are keys bound to commands (digit-argument and negative-argument) that are defined to contribute to an argument for the next command.

Another way of specifying an argument is to use the C-u (universal-argument) command followed by the digits of the argument.  With C-u, you can type the argument digits without holding down modifier keys; C-u works on all terminals.  To type a negative argument, type a minus sign after C-u.  Just a minus sign without digits normally means -1.

C-u followed by a character which is neither a digit nor a minus sign has the special meaning of ``multiply by four''.  It multiplies the argument for the next command by four.  C-u twice multiplies it by sixteen.  Thus, C-u C-u C-n moves down sixteen lines.  This is a good way to move down ``fast'', since it moves about 2/3 of a screen in the usual size screen.  C-u is also a handy way of providing an argument when you don't care about the value.

Many commands care only about whether there is an argument, and not about its value.  Other commands care only about the sign of the argument.  For example, the command RET (open-message) with no argument shows only some of the message's headers; with a positive argument, it shows all the headers, and with a negative argument it shows no headers at all.  This may seem strange, but it is a convenient way of modifying the behaviour of a command.

We use the term ``prefix argument'' as well as ``numeric argument'' to emphasise that you type the argument before the command, and to distinguish these arguments from minibuffer arguments that come after the command.

Typeout
*******

Typeout is the mode af uses to display large amounts of text such as mail messages or help information.  When af uses typeout, the typeout window appears, covering the entire screen apart from the echo area. Once you exit typeout, the window disappears, ``uncovering'' the original windows.

If possible, each line of the text is displayed as a single line on the screen.  If a line is too long to fit on a single screen line, then it will be displayed on several screen lines, with a \ at the extreme right margin of all but the last of them.  The \ says that the following screen line is not really a distinct line in the text, but just the continuation of a line too long to fit the screen.  This is called line wrapping, and the lines after the first are often referred to as continuation lines.

When you are viewing typeout, the position indicator in the mode line will often say MOR.  This is because typeout does not wait to read the entire input before displaying the first page, and since af doesn't know how many lines there are in the text yet, it will give the position as MOR to indicate this.

Sometimes, the typeout window will appear, but you will still be able to carry on with some other operation (such as displaying the help options via C-h C-h C-h).  In these cases the typeout window will disappear when the operation is completed.

Within typeout, only the cursor motion commands, the scrolling commands and the text searching commands can be used.  To exit typeout, simply type C-g.  The other af commands are irrelevant when you are just viewing text.  Here is a brief summary of the commands available in typeout:

SPC
     Scroll the text up to show the next page of text.  If you are already at the end of the text, then exit typeout  (typeout-scroll). This is a convenient way of paging through short amounts of text.

C-v
     Scroll forward (a windowful, or a specified number of lines) (scroll-up).

M-v
     Scroll backward (a windowful, or a specified number of lines) (scroll-down).

C-n
     Scroll forward one line (next-line);

C-n
     Scroll backward one line (previous-line);

C-l
     Redraw the display (recenter).

C-s REGEX RET
     Search forward through the text for a line matching REGEX (search-forward).  See Searching.

C-r REGEX RET
     Search backward through the text for a line matching REGEX (search-forward).  See Searching.

The Minibuffer
**************

The minibuffer is the facility used by af commands to read arguments more complicated than a single number.  Minibuffer arguments can be file names, buffer names, af command names, address lists, and many other things, depending on the command reading the argument.  You can use many editing commands in the minibuffer to edit the argument.

When the minibuffer is in use, it appears in the echo area, and the terminal's cursor moves there.  The beginning of the minibuffer line displays a prompt which says what kind of input you should supply and how it will be used.  Often this prompt is derived from the name of the command that the argument is for.  The prompt normally ends with a colon.

Sometimes a default argument appears in parentheses after the colon; it too is part of the prompt.  The default will be used as the argument value if you enter an empty argument (e.g., just type RET).  For example, commands that read buffer names always show a default, which is the name of the buffer that will be used if you type just RET.

The simplest way to enter a minibuffer argument is to type the text you want, terminated by RET which exits the minibuffer.  You can cancel the command that wants the argument, and get out of the minibuffer, by typing C-g.

Sometimes, a default response will already be in the minibuffer when you enter it.  If it is completely wrong, then you can type C-a C-k to remove it.  These default responses appear for convenience when you are prompted for a long value that you are likely to want to edit, rather then retype from scratch.

Most commands which use typeout allow you to redirect the output into a file, instead of viewing it.  The major exception to this is RET (open-message), since there are several ways to save a message to a file.  To redirect typeout to a file simply give the command a prefix argument of any value; you will be prompted for the file name using the minibuffer.

Echo Area Conflicts
===================

Since the minibuffer uses the screen space of the echo area, it can conflict with other ways af customarily uses the echo area.  Here is how af handles such conflicts:

  * If a command gets an error while you are in the minibuffer, this does not cancel the minibuffer.  However, the echo area is needed for the error message and therefore the minibuffer itself is hidden for a while.  It comes back after a few seconds, or as soon as you type anything.

  * If in the minibuffer you use a command whose purpose is to print a message in the echo area, such as C-x =, the message is printed normally, and the minibuffer is hidden for a while.  It comes back after a few seconds, or as soon as you type anything.

  * Echoing of keystrokes does not take place while the minibuffer is in use.

Inserting Text
==============

To insert printing characters into the minibuffer, just type them.  This inserts the characters you type into the buffer at the cursor (that is, at point; which has a different appearance in the minibuffer, but the same meaning).  The cursor moves forward, and any text after the cursor moves forward too.  If the text in the buffer is foobar, with the cursor before the b, then if you type xx, you get fooxxbar, with the cursor still before the b.  This all works because in the minibuffer all the printing characters run the command self-insert-command.

Direct insertion works for printing characters and SPC, but other characters act as editing commands and do not insert themselves.  If you need to insert a control character or a character whose code is above 200 octal, you must quote it by typing the character C-q (quoted-insert) first.  There are two ways to use C-q:

  * C-q followed by any non-graphic character (even C-g) inserts that character.

  * C-q followed by three octal digits inserts the character with the specified character code.

A numeric argument to C-q specifies how many copies of the quoted character should be inserted (see Arguments).

When you have finished entering the text, simply type RET (newline) to accept the argument and exit the minibuffer.

Deleting Text
=============

To delete a character you have inserted, use DEL (delete-backward-char).  DEL deletes the character before the cursor (not the one that the cursor is on top of or under; that is the character AFTER the cursor).  The cursor and all characters after it move backwards.  Therefore, if you type a printing character and then type DEL, they cancel out.

To delete the character that the cursor is under, use C-d (delete-char).  This deletes the character, moving all the characters after the cursor backwards.  The cursor is left in place. Therefore C-d is equivalent to C-f DEL.

To delete the text from the cursor to the end of the line, use C-k (kill-line).  This kills the characters from the one the cursor is under to the end of the line, leaving the cursor at the end of the line (see Minibuffer Kills).

Editing the Text
================

To edit the text in the minibuffer, you need to be able to move around in the text.  There are several commands available to do this:

C-a
     Move to the beginning of the line (beginning-of-line).

C-e
     Move to the end of the line (end-of-line).

C-f
     Move forward one character (forward-char).

C-b
     Move backward one character (backward-char).

C-t
     Transpose the two characters on either side of point, moving point forward one character (transpose-chars).

Dealing with Words
==================

The minibuffer includes several commands for dealing with words rather than characters.  Often these take the usual command for moving point, but use a Meta key rather then a control key:

M-f
     Move forward one word (forward-word).

M-b
     Move backward one word (backward-word).

M-DEL
     Delete the next word (backward-kill-word).

M-d
     Delete the previous word (kill-word).

M-l
     Convert the next word to lower case (downcase-word).

M-u
     Convert the next word to upper case (upcase-word).

M-c
     Capitalise the next word (capitalize-word).

Completion
==========

For certain kinds of arguments, you can use completion to enter the argument value.  Completion means that you type part of the argument, then af visibly fills in the rest, or as much as can be determined from the part you have typed.

When completion is available, certain keys---TAB, RET, and SPC---are rebound to complete the text present in the minibuffer into a longer string that it stands for, by matching it against a set of completion alternatives provided by the command reading the argument.  ? is defined to display a list of possible completions of what you have inserted.

For example, when M-x uses the minibuffer to read the name of a command, it provides a list of all available af command names to complete against.  The completion keys match the text in the minibuffer against all the command names, find any additional name characters implied by the ones already present in the minibuffer, and add those characters to the ones you have given.  This is what makes it possible to type M-x del SPC m RET instead of M-x delete-message RET (for example).

Case is often significant in completion, because it is significant in many of the names that you can complete (buffer names and file names). Thus, fo often does not complete to Foo.  Completion does ignore case distinctions for certain arguments in which case does not matter (such as af command or configuration variable names).

Completion Example
------------------

A concrete example may help here.  If you type M-x co TAB, the TAB looks for alternatives (in this case, command names) that start with co.  There are only two: copy-region-as-kill and copy-tagset-as-kill.  These are the same as far as copy-, so the co in the minibuffer changes to copy-.

If you type TAB again immediately, there are multiple possibilities for the very next character---it could be r or t---so no more characters are added; instead, TAB just produces a beep.  If you now type ?, af will produce a list of all possible completions to typeout; when you exit typeout, the minibuffer is still waiting for the next character.

If you go on to type r TAB, this TAB sees copy-r.  The only command name starting this way is copy-region-as-kill, so completion fills in the rest of that. You now have copy-region-as-kill in the minibuffer after typing just co TAB r TAB.  Note that TAB has this effect because in the minibuffer it is bound to the command minibuffer-complete when completion is available.

Completion Commands
-------------------

Here is a list of the completion commands defined in the minibuffer when completion is available.

TAB
     Complete the text in the minibuffer as much as possible (minibuffer-complete).

SPC
     Complete the minibuffer text, but don't go beyond one word (minibuffer-complete-word).

RET
     Submit the text in the minibuffer as the argument, possibly completing first as described below (minibuffer-complete-and-exit).

?
     Print a list of all possible completions of the text in the minibuffer (minibuffer-list-completions).

SPC completes much like TAB, but never goes beyond the next hyphen or space.  If you have copy-r in the minibuffer and type SPC, it finds that the completion is copy-region-as-kill, but it stops completing after region-.  This gives copy-region-.  Another SPC at this point completes to copy-region-as-.

Strict Completion
-----------------

There are three different ways that RET can work in completing the minibuffer, depending on how the argument will be used.

  * Strict completion is used when it is meaningless to give any argument except one of the known alternatives.  For example, when M-x reads the name of a command to run, it is meaningless to give anything but the name of an existing command or macro.  In strict completion, RET refuses to exit if the text in the minibuffer does not complete to an exact match.

  * Cautious completion is similar to strict completion, except that RET exits only if the text was an exact match already, not needing completion.  If the text is not an exact match, RET does not exit, but it does complete the text.  If it completes to an exact match, a second RET will exit.

     Cautious completion is used for reading file names for files that must already exist.

  * Permissive completion is used when any string whatever is meaningful, and the list of completion alternatives is just a guide. For example, when C-x C-f reads the name of a folder to visit, any folder name is allowed, in case you want to create a folder.  In permissive completion, RET takes the text in the minibuffer exactly as given, without completing it.

Minibuffer History
==================

Every argument that you enter with the minibuffer is saved on a minibuffer history list so that you can use it again later in another argument.  You can think of the minibuffer history as a buffer which you can move through displaying a line at a time.

C-p
     Move to the next earlier argument string saved in the minibuffer history (previous-line).

C-n
     Move to the next later argument string saved in the minibuffer history (next-line).

M-<
     Move to the first argument string saved in the minibuffer history (beginning-of-buffer).

M->
     Move to the last argument string saved in the minibuffer history (end-of-buffer).  This will always move you to the text you were editing before using the minibuffer history.

C-r
     Move to an earlier saved argument in the minibuffer history that matches the current text (search-backward).

C-s
     Move to a later saved argument in the minibuffer history that matches the current text (search-forward)..

The simplest way to reuse the saved arguments in the history list is to move through the history list one element at a time.  While in the minibuffer, type C-p to ``move to'' the previous minibuffer input, and use C-n to ``move to'' the next input.  Similarly, you can use C-< and C-> to ``move to'' the first and last elements in the history list.

When you move to a new history line, any text you had typed is stored for you as the last history element, so you can return to it by typing M->.  To use a history element as the argument, exit the minibuffer as usual with RET.  You can also edit the text before you reuse it; this does not change the history element that you ``moved'' to, but your new argument does go at the end of the history list in its own right.

There are also commands to search forward or backward through the history.  At the moment they search for a history element that starts with the text you have typed in the minibuffer, up to the position of the cursor; so typing list- C-r will search for a history element that begins with list-.  If a matching history element is found then the cursor will stay in the same column, so that typing C-r again will search for another history element beginning with list-.

Composing and Sending Mail
**************************

Af allows you to compose and send mail as well as read it.  There are several different commands to send mail, each of which sends mail in a slightly different way.

Af composes messages in three stages.  First you are prompted for any details needed for the message, such as the addresses to send it to. Then af starts an editor, so that you can edit the message.  Finally, you are prompted for what to do with the message (its disposition).

Commands for Sending Mail
=========================

There are five commands for sending mail in af.  These commands are all similar in use, but conceptually different.

M-m or M-s
     Send a message to one or more people.  This allows you to compose and send a mail message (send-mail).

M-r
     Reply to the current message.  This lets you compose and send mail to whoever the current message is from (send-reply).

C-M-r
     Group reply to the current message.  This lets you compose and send mail to whoever the message is from, and all the addresses listed in the To: header.  Copies are sent to the addresses listed in the Cc: header (group-reply-to-message).

M-f
     Forwarding allows you to compose an annotated copy of the current message and send it to one or more people.  (forward-message).

M-b
     Bouncing means sending an exact copy of the current message to one or more addresses, making it appear that the copy you send them is from the person who sent the message to you (bounce-message). You will not normally edit the text of the message.

Initial Details for Composing Mail
==================================

Depending on how you are sending mail, and how you have configured af, you will be prompted for several things when you begin composing a mail message.  Normally af will only prompt for To: and Subject:, but here are all the possible questions:

To:
     The addresses you want send the mail to.

Subject:
     A brief description of what the message is about.

Cc:
     Any mail addresses to send additional copies of the message to.

Bcc:
     Any mail addresses to send blind copies of the mail to.  These addresses will not be listed in the headers of the message when it is sent.

Signature file
     Which signature file (see Signatures) do you want to include at the end of the message.

Copy message (y/n)
     If you are replying to a message, you can copy the text of of the original message into the initial text of the reply.  This is called quoting.

Editing the Mail Message
========================

When you first edit a message you will normally see either a blank file or the text of the original message with each line prefixed with > .  You can then use your editor as usual to compose the text of the message.  When you save the message, your .signature file will be appended to the message, separated by a line containing --.

When you edit a message for the second time (or if you have configured af to do so), the headers of the message are inserted into the file you edit, separated by a blank line, and your signature will be visible at the end of the file.  You can edit the headers with your editor, and af will process the changes when you exit the editor; reporting any problems to typeout.  You can create headers by adding them into the header section of the file, or delete them by deleting them from the file.

You should be very careful when editing a message's headers.  If you accidentally insert a blank line before the headers, then af will not find them when you exit the editor, and will therefore think that you have deleted them all.  This can normally be fixed by editing the file again, and removing the offending text from the start of the file.

Options After Editing the Message
=================================

When you finish editing a message and exit the editor, af will display a summary of the message's headers and prompt you with

     Send, Edit, Check spelling, List or Forget?

It is a very good idea to check the headers that af displays, to make sure that you are sending the message to the people you think you are, that the subject is appropriate, and so on.  Your options at this point are:

Send
     Confirm the message, and give it to the system for delivery.

Edit
     Edit the message again, this time inserting the headers and any signature into the text for you to edit.

Check spelling
     Run an interactive spelling checker on the body of the message (but not the headers).  This option may not be available on systems where there isn't an interactive spelling checker installed.

List
     List the message to typeout, exactly as it will be given to the system for delivery.  This can be useful for checking a message, as it is much quicker than starting up an editor.

Forget
     Cancel the message and exit mail composition.  There is no way to recover a message that you have ``forgotten''.

Variables Related to Composing Mail
===================================

There are a number of configuration variables related to composing and sending mail.  Here is a summary of each variable and its effects:

addresses-to-ignore
     Contains mail addresses which are to be ignored in group replies, typically your mail addresses on this and other machines.  Default is unset.

ask-bcc
     If set to true, then af will prompt for addresses to send blind copies to whenever you send mail.  Default is false.

ask-cc
     If set to true, then af will prompt for addresses to send copies to whenever you send mail.  Default is false.

auto-fold-headers
     If set to false, then af will not automagically fold long header lines onto several lines.  Default is true.

copy-on-reply
     If set to false, af will never quote the text of the original message in the initial text of a reply.  If set to true af will always quote the original message.  If set to ask then you will be asked each time you reply to a message.  Defaults to ask.

copy-preface
     If set, the value is inserted before any text copied into the body of a replying or forwarding message.  Any conversion characters in the value are expanded to their full value.  A good value for this variable might be On %D, %o wrote:.  Default is unset.

copy-prefix
     The prefix for lines of text copied into an outgoing message when replying or forwarding a message.  Defaults to > .

edit-initial-headers
     It set to true, headers will be placed into the file to edit the first time you edit a message.  When set to accept, headers will not be displayed for editing, but any valid headers typed at the start of the message will be accepted.  Defaults to false.

edit-initial-signature
     When set to true, any signature will be placed into the editor the first time you edit a message.  Defaults to false.

edit-reply-address
     When set to true, allows editing of the destination address when replying to mail.  It is intended for use by people at sites with inadequate mail configurations.  Defaults to false.

editor
     The program to use to edit messages.  Defaults to the value of the VISUAL or EDITOR environment variable.

headers-to-copy
     A colon separated list of header names which should be included in text copied into an outgoing message when replying to or forwarding a message.  Default is unset (no headers are copied).

multiple-reply-warning
     If set to true, then af will prompt for confirmation if you try to reply to a message that you have already replied to.  Defaults to false.

organization
     If set, the the value is inserted into an Organization: header in the outgoing message.  Defaults to the value of the ORGANIZATION environment variable.

outbound-folder
     Gives the name of a folder in which to store a copy of all messages sent with af.  The messages are stored with headers (except for a Message-ID:) in the named folder, immediately after being sent. Default is unset (don't save messages).

outbound-threshold
     Gives the maximum number of lines in a message body which should be silently saved to the outbound-folder.  Af will prompt for confirmation that a message longer than this limit is to be saved.  If set to 0 then all outbound messages will be saved regardless of length. Default is 100 lines.

preserve-cc-in-group-reply
     If set to true, any Cc: header on a message is duplicated in an outgoing group-reply to that message, so that recipients of a carbon-copy will also receive the reply.  Default is true.

real-name
     Your real name, for inclusion in From: headers.  Defaults to the value of the NAME environment variable, or your details stored in the file /etc/passwd.

reply-address
     Contains a mail address which forms a Reply-To: header in all messages you send, so that replies to those messages will be sent to the address you specify.  Default is unset.

signature-file
     The name of your signature file.  If the value begins with ask:, then you will be prompted for the signature file to use, with any value after the ask: being used as a default.  Defaults to .signature in your home directory.

signature-separator
     A string which will be printed on a line between the body of an outgoing message and any automatically-included signature.  If not set, then no separator line is printed.  Defaults to --.

spell-checker
     The program to use to interactively spell-check the body of a message before you send it.  Defaults to ispell -x if ispell is installed on your system, or unset otherwise.

Defining and Using Mail Aliases
===============================

Af will let you set mail aliases.  These are short mnemonic names which stand for mail addresses or groups of mail addresses.  Like many other mail programs, af expands aliases when they occur in the To:, From:, Cc:, Bcc:, and Reply-to: headers.

The easiest way to define a mail alias within af is with C-x C-a (set-alias).  Af will prompt for the alias and then the real name and the full address of the alias, defaulted from the From: header of the current message.  If the alias already exists, af will prompt for confirmation that you want to change the alias.   (If you edit your .afalias file, you will find that the old version of the alias will be commented out rather than deleted when you change it. This can be useful if you accidentally overwrite an important alias.)

C-x C-a sets the alias internally; but it also writes the alias to the file .afalias in your home directory.  This file is read whenever af starts up, so your aliases will be available next time you run af.  You can also edit your .afalias file directly; each line should either be blank, be a comment beginning with ;, or look like:

     ALIAS:REAL NAME:ADDRESSES

ALIAS is the name of the alias; REAL NAME is the real name of the person or group the alias represents, and ADDRESSES stands for one or more mail addresses for ALIAS to expand into.  Separate multiple addresses with spaces or (preferably) commas.  You can make an address list span more than one line by starting the second and subsequent lines with a space or tab, in the same way as mail headers are split over several lines of text.

For instance, to make afbugs stand for af-bug@csv.warwick.ac.uk put in the these lines:

     ; Set up the af-bug mailing list as an alias
     afbug:Af Bug Mailing List:af-bug@csv.warwick.ac.uk

Af expands aliases as soon as you finish editing the mail file, so you can check that the alias expanded properly by looking at the list of headers that af shows you when it prompts for the disposition of the mail.

Running Commands by Name
************************

The af commands that are used often or that must be quick to type are bound to keys---short sequences of characters---for convenient use. Other af commands that do not need to be brief are not bound to keys; to run them, you must refer to them by name.

A command name is, by convention, made up of one or more words, separated by hyphens; for example, af-version or list-commands.  The use of English words makes the command name easier to remember than a key made up of obscure characters, even though it is more characters to type.

The way to run a command by name is to start with M-x, type the command name, and finish it with RET.  M-x uses the minibuffer to read the command name.  RET exits the minibuffer and runs the command.  The string M-x appears at the beginning of the minibuffer as a prompt to remind you to enter the name of a command to be run.  See Minibuffer, for full information on the features of the minibuffer.

Note that next-line is the same command that you invoke with the key C-n.  You can run any af command by name using M-x, whether or not any keys are bound to it.

If you type C-g while the command name is being read, you cancel the M-x command and get out of the minibuffer, ending up at top level.

To pass a numeric argument to the command you are invoking with M-x, specify the numeric argument before the M-x.  M-x passes the argument along to the command it runs.  The argument value appears in the prompt while the command name is being read.

Normally, when describing a command that is run by name, we omit the RET that is needed to terminate the name.  Thus we might speak of M-x af-version rather than M-x af-version RET.  We mention the RET only when there is a need to emphasise its presence, such as when we show the command together with following arguments.

M-x works by running the command execute-extended-command, which is responsible for reading the name of another command and invoking it.

Help
****

Af provides extensive help features accessible through the command C-h (help-command).  C-h is a prefix key that is used only for documentation-printing commands.  The characters that you can type after C-h are called help options.  One help option is C-h; that is how you ask for help about using C-h.  To cancel, type C-g.

C-h C-h displays a list of the possible help options.  Typing C-h again displays a longer list of the options, each with a brief description.

Documentation for a Key
=======================

The most basic C-h options are C-h c (describe-key-briefly) and C-h k (describe-key). C-h c KEY prints in the echo area the name of the command that KEY is bound to.  For example, C-h c C-n prints next-line.  Since command names are chosen to describe what the commands do, this is a good way to get a very brief description of what KEY does.

C-h k KEY is similar but gives more information: it displays the documentation string of the command as well as its name. This is too big for the echo area, so typeout is used for the display.

Help by Command, Mode or Variable Name
======================================

C-h f (describe-function) reads the name of an af command, keyboard macro or afl function using the minibuffer, then displays that function's documentation string to typeout.  For example,

     C-h f delete-message RET

displays the documentation of delete-message.  This is the only way to get the documentation of a command that is not bound to any key (one which you would normally run using M-x).

C-h v (describe-variable) is like C-h f but describes configuration variables instead of commands and functions (see Variables).

C-h m (describe-mode) is also like C-h f but describes major and minor modes rather than commands and functions (see Major Modes).

Help for Lists of Things
========================

C-h b (list-bindings) displays the current key bindings active in af to typeout.  The global bindings are shown first, and then those for each of the major modes.  This be quite a long list, but might be useful as a wall chart.

C-h d (list-commands) lists all of af's commands, with their bindings, to typeout.  Bindings which only take effect in mail mode are listed in square brackets (eg [M-s]).  Bindings for typeout mode only are listed in braces (eg {C-f}). Bindings that are minibuffer-specific are listed in parentheses (eg (SPC)).

C-h C-f lists all of the afl functions to typeout.  Only those functions which are not also commands are listed.  This is quite a short list at present (see Afl).

C-h C-k list-kbd-macros lists all of the named keyboard macros, with their values, to typeout (see Keyboard Macros).

C-h C-v lists all of the af configuration variables, with their values, to typeout (see Variables).

C-h C-a (list-aliases) lists all the mail aliases you have defined to typeout, along with their values (see Aliases).

Apropos
=======

A more sophisticated sort of question to ask is, ``What is relevant for working with messages?''  To ask this question, type C-h a message RET, which displays a list of all command, function, keyboard macro and variable names that contain message, including open-message, print-message, and so on.  The bindings for each command is listed with that command, in the same format as list-bindings (see List Help).  Similarly the values of keyboard macros and variables are listed.  The a in C-h a stands for `Apropos'; C-h a runs the command command-apropos.

Because C-h a looks only for things whose names contain the string which you specify, you must use ingenuity in choosing the string.  If you are looking for commands for reading messages and C-h a read-message RET doesn't reveal any, don't give up.  Try just read, or just message.  Be persistent.  Also note that you can use a regular expression as the argument, for more flexibility (see Regex Syntax).

Here is a set of arguments to give to C-h a that covers many classes of af commands, since there are strong conventions for naming the standard af commands.  By giving you a feel for the naming conventions, this set should also serve to aid you in developing a technique for picking apropos strings.

     char, line, word, region, list, buffer, window, file, mode, beginning, end, forward, backward, next, previous, up, down, search, goto, kill, delete, mark, insert, yank, case, set, what, view, describe, default, print, page, message, send.

Other Help Commands
===================

C-h i (info) runs the Info program, which is used for browsing through structured documentation files.  The entire af manual is available within Info.  Type h after entering Info to run a tutorial on using Info.

If something surprising happens, and you are not sure what commands you typed, use C-h l (view-lossage).  C-h l prints the last 100 command characters you typed in.  If you see commands that you don't know, you can use C-h c to find out what they do.

Af has numerous major modes, each of which redefines keys and alters the behaviour of some commands.  C-h j (describe-major-mode) prints documentation on the current major mode to typeout.

The other C-h options display assorted useful information. C-h n (view-af-news) displays information on recent changes to af.  C-h C-w (display-no-warranty) displays details on the complete absence of warranty for af.  C-h C-c (describe-copying) displays the conditions you must obey in distributing copies of af.