More Ways to Handle Messages
****************************

You can use af to handle messages in more sophisticated ways than by simply displaying them; You can save messages to folders, print a hardcopy of them, pipe them into commands, and more.

Most commands that deal with a single message also have similar commands which deal with a set of messages, selected either by using the mark and region (see Mark and Region), or with tags (see Tags).  These similar commands will be covered later.

Saving Messages
===============

Af allows you to save messages by copying them to folders.  One way to save a message to a folder is to use M-+ (save-message).  Af will prompt you for the folder name, offering a default based on the sender's mail address (see Folders).  The message will be appended to the folder you specify, so any messages already in the folder will be left unchanged.

When the message is saved to a folder, the original copy is not deleted. an S will appear in the system tags of the message, so that you know you have saved it.

M-+ can take a numeric argument, in which case it only saves the body of the message, not the headers.  Obviously the file containing a saved copy of the message body shouldn't be read with af; it isn't a mail folder.  Saving the body of a message can be useful when the body is input for some other program (such as a patch file).

When you save message bodies, any MIME encoding is removed from the body parts.  Partial messages are rebuilt before they are saved.  Af will only save a rebuilt message once, no matter how many parts of the message are included in the messages to save.  This is convenient when you are saving a set of message bodies.

Printing Messages
=================

Af allows you to print a hardcopy of a message to a spooler.  The program to use to print hard copies of mail is defined by the print-command variable for textual body parts, or the mime-printer variable for non-textual body parts.

To print a hardcopy of a message, use C-p (print-message). Af will usually prompt you to confirm that you want a hardcopy of the message; this feature can be turned off by setting the variable confirm-print to false.  After you print the message, a P will appear in the system tags of the message, to remind you that you have printed it.

Normally, the mail headers listed in the headers-not-displayed variable will not be printed when you print a message.  A positive numeric argument makes af print all the message's headers, while a negative argument makes af skip all headers, and only print the body of the message.

When you print messages, any MIME encoding is removed from the body parts.  Partial messages are rebuilt before they are printed.  Af will only print a rebuilt message once, no matter how many parts of the message are included in the messages to print.  This is convenient when you are printing a set of message bodies.

If you print a non-text message, af will use an external program to print any non-text body parts.  For this reason, non-textual body parts may not appear in the correct sequence with textual body parts.  If you print a non-text body part, and af doesn't know how to handle it, it will assume that you know what you are doing, and print it anyway.  The results may well be less than ideal if you print an image or audio body part.

Piping Messages
===============

Af allows you to pipe a message into the standard input of a system command.  To do this use M-| (pipe-message).  Af will prompt for the command to pipe the message into, and then execute the command.  Any output from the command will be displayed on the screen.  Once the command has completed, af will wait for you to press a key before continuing; giving you a chance to read any output from the command.

Normally, the mail headers listed in the headers-not-displayed variable will not be piped into the command.  A positive numeric argument makes af pass all the message's headers to the command.  A negative argument makes af skip all headers, and only pass the body of the message to the command.

When you pipe messages into a command, any MIME encoding is removed from the body parts.  Partial messages are rebuilt before they are piped into the command.  Af will only pipe a rebuilt message once, no matter how many parts of the message are included in the messages to pipe. This is convenient when you are piping a set of messages into a command

Other Message-Handling Commands
===============================

C-x j
     Create a new buffer containing the body parts of the current message. (open-body-parts).

C-x 4 j
     Create a new buffer in the other window containing the body parts of the current message.  (open-body-parts-other window).

C-x C-e
     Edit the text of the current message.

If a message contains one or more body parts, or an encapsulated message, then af can create a buffer containing each body part as a separate message.  Similarly, af can rebuild the original message from a single part if all the parts are present in the current buffer.  Or if the message is an old, pre-MIME, mail digest, then af is still capable of extracting the parts of the message.

To extract or rebuild the parts of a message body use C-x j (open-body-parts) or C-x 4 j (open-body-parts-other-window).  This will create a new buffer containing the extracted or rebuilt messages, and switch to that buffer.  The buffer will not be visiting any folder, and so will not be saved to a folder when you exit af.

The new buffer will be in Body Parts minor mode, which means that the body-part-line-format variable will be used to display each message in the buffer, rather than the header-line-format.  This allows you to show different details for body parts to those you show for messages.

Af will allow you to edit a message in a folder with C-x C-e (edit-message).  Af will save the message to a temporary file and execute an editor to edit the file.  When you finish editing, af will read back the temporary file, and update its internal copy of the message.  When you save the buffer, the modified message will be written to the folder.

With an argument, C-x C-e will only pass the body of the message to the editor, and will preserve the message header unchanged.

Running Shell Commands from Af
==============================

Af has commands for running inferior shell processes, displaying the result to typeout or letting the inferior process take control of the terminal.

M-! CMD RET
     Run the shell command line CMD and display the output to typeout (shell-command-to-typeout).

C-x ! CMD RET
     Start an inferior shell to run the command line CMD.  The inferior shell will take control of the terminal until it exits. (shell-command)

M-x shell
     Run an inferior shell interactively under af.  The inferior shell will take control of the terminal until it exits (shell).

The Mark and the Region
***********************

Many af commands operate on an arbitrary contiguous part of the current buffer.  To specify the text for such a command to operate on, you set the mark at one end of it, and move point to the other end.  The text between point and the mark is called the region.

You can move point or the mark to adjust the boundaries of the region. It doesn't matter which one is set first chronologically, or which one comes earlier in the buffer.  Once the mark has been set, it remains where you put it until you set it again at another place.  Each af buffer has its own mark, so that when you return to a buffer that had been selected previously, it has the same mark it had before.

Many commands that insert messages (or text in the minibuffer), such as C-y (yank) and C-x i (insert-file), position point and the mark at opposite ends of the inserted text, so that the region contains the text just inserted.

Setting the Mark
================

There are two commands to set the mark in a buffer.  These commands work identically in mail buffers, typeout, and the minibuffer.

C-SPC or C-@ or M-SPC
     Set the mark where point is (set-mark-command).

C-x C-x
     Interchange mark and point (exchange-point-and-mark).

For example, suppose you wish to save part of a mail buffer to a folder, using the C-x + (save-region) command, which operates on the messages in the region.  You can first go to the beginning of the messages to be saved, type C-SPC to put the mark there, move to the end, and then type C-x +.  Or, you can set the mark at the end of the text, move to the beginning, and then type C-x +.

The most common way to set the mark is with the C-SPC command (set-mark-command).  This sets the mark where point is.  Then you can move point away, leaving the mark behind.

Af doesn't show you where the mark is located.  You have to remember. The usual solution to this problem is to set the mark and then use it soon, before you forget where it is.  Alternatively, you can see where the mark is with the command C-x C-x (exchange-point-and-mark) which puts the mark where point was and point where the mark was.  The extent of the region is unchanged, but point is now at the previous position of the mark.

C-x C-x is also useful when you are satisfied with the position of point but want to move the mark; do C-x C-x to put point at that end of the region, and then move it.  A second use of C-x C-x, if necessary, puts the mark at the new position with point back at its original position.

There is no such character as C-SPC in ASCII; when you type SPC while holding down CTRL, what you get on most ordinary terminals is the character C-@.  This key is actually bound to set-mark-command.  But unless you are unlucky enough to have a terminal where typing C-SPC does not produce C-@, you might as well think of this character as C-SPC.  If you are on a terminal where C-SPC doesn't work, you could use M-SPC instead; it is also bound to set-mark-command.

Operating on the Region
=======================

Once you have a region in a mail buffer, here are some of the commands that operate on the region.  Note that these commands all have the word region in their names.

C-w
     Kill the messages in the region (kill-region). See Killing and Yanking.

M-w
     Copy the region into the kill buffer as if it had been killed (copy-region-as-kill). See Killing and Yanking.

C-x + FOLDER RET
     Save the messages in the region into FOLDER (save-region). This command handles the argument in the same way as M-+ (save-message). See Saving Messages.

C-x p
     Print a hardcopy of all the messages in the region (print-region).  This command handles the argument in the same way as M-p (print-message). See Printing Messages.

C-x | COMMAND RET
     Pipe the messages in the region into a single instance of the shell command COMMAND (pipe-region).  Again, this command handles the argument in the same way as M-| (pipe-message) see Piping Messages.

Using the Region in Typeout
===========================

Typeout is only used to display text, and not to edit or delete anything. For that reason, there are no commands which operate on the region available in typeout.  It is still possible to set the mark in the typeout buffer; but the only thing you can do with it is to use C-x C-x (exchange-point-and-mark) to move back to the mark.

Using the Region in the Minibuffer
==================================

The minibuffer supports the mark and region, but only a subset of the commands which are available in a mail buffer to process the region. Since the minibuffer deals with text rather than messages, the region delimits a block of text in the minibuffer.

Just like any other buffer, the minibuffer has its own mark.  The mark is not preserved between uses of the minibuffer, or when you move between minibuffer history entries, so you will usually need to set the mark in the minibuffer before you use it.

There are two commands which operate on the region in the minibuffer:

C-w
     Delete the text in the region (kill-region). See Minibuffer Kills.

M-w
     Copy the text in the region into the kill buffer as if it had been killed (copy-region-as-kill).  See Minibuffer Kills.

Tags
****

The region allows you to conveniently process blocks of messages, but what if you want to handle an arbitrary set of messages?  Af uses tags to let you mark a set of messages and process them quickly.

Tags are only available in mail buffers; they wouldn't make any sense in the minibuffer or the mail buffer.

Tag Concepts
============

A tag is a single-character mark which is set on a message.  A message can have any number of tags set on it.  There are two types of tags: system tags which are automatically set by af for various reasons, and user tags which you can set and unset yourself.  You cannot set or remove system tags, but you can use them in exactly the same ways as you can user tags.

There are many commands which operate on tagged messages; and you can use either single tags or a combination of them to specify a set of messages to operate on.  Tags are central to advanced use of af; they provide a way for you to easily set up a set of messages, which you can then work with in several ways.

System Tags
-----------

The system tags are all upper-case letters, which give information on the status of messages.  The possible system tags are:

D
     The message has been marked for deletion with M-x delete-message.

E
     Af found an error in the message's headers when the folder was visited. This is not normally critical, but you may not be able to reply to the message; or it may even (rarely) indicate a corrupted folder.

F
     You have forwarded or bounced the message (see Sending Mail).

M
     The message is in MIME format; and isn't text that you can display on your terminal.  When you read the message, af will display each body part separately if there are more that one, and will use external commands to display any non-textual body parts.  If af doesn't know how to display a given body part then it will ask you what to do.

T
     The message is in MIME format, and is textual, but is either not plain text, or is in a character set not listed in the viewable-charsets variable.  When you read the message then it will be displayed as usual, which may not be ideal.

N
     The message is new; the message has arrived since last time you visited the folder and hasn't yet been read.

O
     The message is old but unread.  The message was present last time you visited the folder, but you haven't read it yet.

P
     A hardcopy of the message has been printed to a spooler.

R
     You have replied to the message (see Sending Mail).

S
     The message has been saved to a folder.

User Tags
---------

The user tags you can use are the lower case letters, and +. + is sometimes called the default tag, since it is the default whenever you are asked about tags.

Normally, the user tags are considered transient, and are lost when you exit af.  If you would like to keep some or all of the tags across mail reading sessions, then you can set the variable persistent-tags to the tags you would like to be preserved.  For example, setting the value of persistent-tags to aeiou, would mean that the user tags a, e, i, o, and u will be preserved whenever you save a folder, but the other tags will be lost. You cannot make the default tag (+) persistent.

Tag Lists
---------

Whenever you are setting or removing tags, af will expect you to enter a tag list.  Tag lists consist of one or more user tags, which may be separated by spaces.  For example, abcd and a b c d, both specify a list of four tags, a, b, c, and d.

Whenever you are prompted for a tag list, you can just hit return to use the default tag (+).

Tag Expressions
---------------

When you are using tags to define a set of messages to apply some command to, you will be expected to enter a tag expression.  That tag expression is then compared to the tags of each message in the buffer, and the command will operate on the message if the expression is true for that message.  We often refer to the messages which match a tag expression as the tagset.

Tag expressions are made up of sub-expressions, which may be system or user tags.  You can use operators to combine subexpressions, and build arbitrarily complex expressions.  Any tag will evaluate to true if the message being checked has that tag set, false otherwise.  The possible operators are, in decreasing precedence:

( ... )
     Override any precedence, and force the contents of the parentheses to be evaluated as a unit.  (a) is equivalent to a.

!
     Logical not; true if the expression it precedes is false.  !a is true if a is not set.

&
     Logical and; true if both sides of the expression are true. a & b is true if both a and b are set.

^
     Logical exclusive-or; true if only one side of the expression is true. a ^ b is true if either a or b is set, but not both.

|
     Logical or; true if either side of the expression is true.  a | b is true if either a or b is set, or if both are set.

Here are some examples of tag expressions, with their meanings.

     a & b | c & d

True if a and b are both set, or c and d are both set.

     a & (b | c) & d

True if a, d, and either b or c are set.

     a & !b

True if a is set and b is not set.

     a & !(b | c)

True if a is set and neither of b or c are set.

Setting and Removing Tags
=========================

C-t t TAGS RET
     Set TAGS on the current message (tag-message).

C-t u TAGS RET
     Remove TAGS from the current message (untag-message).

C-t r TAGS RET
     Remove TAGS from all the messages in the buffer (remove-tag).

M-x tag-thread TAGS RET

To tag the current message, use C-t t.  You will be prompted for the tags to set; simply type in the tag list to set.  The tags in the list will be added to those already set on the message.

To remove one or more tags from the current message use C-t u. You will be prompted for the tags to remove.  The tags you specify will be removed from the message's tags.

To remove one or more tags from all the messages in the buffer, use C-t r.  You will be prompted for the tags to remove.  The tags you specify will be removed from all the messages in the buffer.

The experimental command M-x tag-thread TAGS RET tags all the messages in a thread of conversation, a set of messages which are all sent as replies to other related messages.  (This is similar to the concept of threading found in most news readers.)  This command works, but at the moment there are too many mail composers which don't include references to messages when they generate a reply, so that the threads are often broken by replies which af can't detect as a part of the thread.  It is probably best not to use this command for the moment, unless you can be sure that all the participants are using a mail composer that does include references to messages in replies.

There is also a command to set tags on messages which match search criteria.  See Search and Tag.

Using Tags
==========

Once you have tagged messages in the region, you can use single tags or tag expressions to operate on them.  Here are some of the ways in which you can operate on tagged messages:

C-t C-k TAG-EXPR RET
     Kill the messages in the tagset defined by TAG-EXPR (kill-tagset).  See Killing and Yanking.

C-t w TAG-EXPR RET
     Copy the messages in the tagset into the kill buffer as if they had been killed (copy-tagset-as-kill). See Killing and Yanking.

C-t + TAG-EXPR RET FOLDER RET
     Save the messages in the tagset into FOLDER (save-tagset). This command handles the argument in the same way as M-+ (save-message). See Saving Messages.

C-t p TAG-EXPR RET
     Print a hardcopy of all the messages in the tagset (print-tagset).  This command handles the argument in the same way as M-p (print-message). See Printing Messages.

C-t | TAG-EXPR RET FOLDER RET
     Pipe the messages in the tagset into a single instance of the shell command COMMAND (pipe-tagset).  Again, this command handles the argument in the same way as M-| (pipe-message) see Piping Messages.

Killing and Yanking
*******************

Killing means erasing messages (or text in the minibuffer) and copying them into the kill ring, from which it can be retrieved by yanking it.  Some systems use the terms ``cutting'' and ``pasting'' for these operations.

The commonest way of moving or copying messages within af is to kill them, and later yank them elsewhere one or more times.  This is very safe because af remembers several recent kills, not just the last one. It is versatile, because the many commands for killing messages can also be used for moving them.

Af has only one kill ring for all mail buffers, so you can kill messages in one buffer and yank them in another buffer.  The minibuffer has a separate kill ring for storing text.

All commands which delete messages from the buffer save it in the kill ring (even delete-message when you save the folder) so that you can move or copy it to other parts of the buffer.  These commands are known as kill commands.

Killing Messages
================

There are two ways to add messages to the kill ring; killing and copying.  Killing means deleting messages and adding them to the kill ring, while copying means copying messages to the kill ring without deleting them.

There are commands to kill a single message (see Deleting Messages), commands to kill or copy the region (see Using the Region), and commands to kill or copy a tagset (see Using Tags).

Yanking Messages
================

All killed messages are recorded in the kill ring, a list of blocks of messages that have been killed.  There is only one kill ring, shared by all mail buffers, so you can kill messages in one buffer and yank them in another buffer.  This is the usual way to move messages from one folder to another (see Saving Messages, for another way).

The command C-y (yank) reinserts the most recently killed messages.  It leaves the cursor at the end of the text.  It sets the mark at the beginning of the text (see Mark and Region).

C-y can take a numeric argument, in which case it select an earlier kill to yank, rather than the last (see Earlier Kills).

Appending Kills
===============

Normally, each kill command pushes a new entry onto the kill ring. However, two or more kill commands in a row combine their messages into a single entry, so that a single C-y yanks all the messages as a unit, just as they were before they were killed.

Thus, if you want to yank messages as a unit, you need not kill all of them with one command; you can keep killing line after line, until you have killed them all, and you can still get them all back at once.

Commands that kill forward from point add the messages onto the end of the previous killed messages.  Commands that kill backward from point add them onto the beginning.  This way, any sequence of mixed forward and backward kill commands puts all the killed messages into one entry without rearrangement.  Numeric arguments do not break the sequence of appending kills.

Yanking Earlier Kills
=====================

To recover killed messages that are no longer the most recent kill, use the M-y command (yank-pop).  It takes the messages previously yanked and replaces them with the messages from an earlier kill.  So, to recover the messages of the next-to-the-last kill, first use C-y to yank the last kill, and then use M-y to replace it with the previous kill.  M-y is allowed only after a C-y or another M-y.

You can understand M-y in terms of a ``last yank'' pointer which points at an entry in the kill ring.  Each time you kill, the ``last yank'' pointer moves to the newly made entry at the front of the ring. C-y yanks the entry which the ``last yank'' pointer points to. M-y moves the ``last yank'' pointer to a different entry, and the text in the buffer changes to match.  Enough M-y commands can move the pointer to any entry in the ring, so you can get any entry into the buffer.  Eventually the pointer reaches the end of the ring; the next M-y moves it to the first entry again.

M-y moves the ``last yank'' pointer around the ring, but it does not change the order of the entries in the ring, which always runs from the most recent kill at the front to the oldest one still remembered.

M-y can take a numeric argument, which tells it how many entries to advance the ``last yank'' pointer by.  A negative argument moves the pointer toward the front of the ring; from the front of the ring, it moves ``around'' to the last entry and continues forward from there.

Once the messages you are looking for are brought into the buffer, you can stop doing M-y commands and it will stay there.  They are a copy of the kill ring entry, so altering them in the buffer does not change what's in the ring.  As long as no new killing is done, the ``last yank'' pointer remains at the same place in the kill ring, so repeating C-y will yank another copy of the same previous kill.

If you know how many M-y commands it would take to find the messages you want, you can yank those messages in one step using C-y with a numeric argument.  C-y with an argument restores the text the specified number of entries back in the kill ring.  Thus, C-u 2 C-y gets the next to the last block of killed messages.  It is equivalent to C-y M-y.  C-y with a numeric argument starts counting from the ``last yank'' pointer, and sets the ``last yank'' pointer to the entry that it yanks.

The length of the kill ring is controlled by the variable kill-ring-max; no more than that many blocks of killed messages are saved.

Killing and Yanking in the Minibuffer
=====================================

The minibuffer is used for editing text rather than handling mail, so it has it's own kill ring.  Any command which kills more than one character at a time (the word and line killing commands) will store the killed text in the minibuffer kill ring.  You can yank the killed text back in exactly the same way as killed messages using C-y.

The minibuffer kill commands will append successive kills to the kill ring, just like the mail buffer kill commands do.  If you use M-d (delete-word) three times, then the three words you kill will all be stored in a single kill ring entry; and a single yank will insert them into the text at point.

For simplicity, the minibuffer kill ring only has one entry, so you can't use M-y in the minibuffer.  If many people find this a problem, then it may change at some point in the future.

Searching Mail Folders
**********************

Af has search commands, which allow you to search through the messages in a buffer and find those which match a regular expression.  You can also search for messages which match a tag expression.

Searching for Regular Expressions
=================================

C-s REGEX RET
     Search for REGEX (search-forward).

C-r REGEX RET
     Search backward for REGEX (search-backward).

To do a search on a buffer (whether typeout or a mail buffer), use C-s or C-r.  Af will prompt you for the regular expression to search for, and then the search takes place.  If no messages match the regular expression then the search will fail with an error.

A second search immediately after the first, will not match the current message, so repeated searches will move through all the messages which match the regular expression.  To make this more convenient, the search expression is defaulted to the last one you entered.

The search commands with a numeric argument will only search the headers of the messages.  This is often convenient when (for example) looking for messages which are from a particular person.

With a negative numeric argument the search commands will only search the bodies of the messages.  This can be useful when (for example) looking for messages which mention your machine's host name (which is included in the headers of all messages).

Searching for Tagged Messages
=============================

C-t C-s TAGEXPR RET
     Search for messages matching TAGEXPR (tag-search-forward).

C-t C-r TAGEXPR RET
     Search backward for messages matching TAGEXPR (tag-search-backward).

To search for a message matching a tag expression use C-t C-s or C-t C-r.  Af will prompt you for the tag expression (see Tag Expressions) to search for; and then the search takes place.  If no messages match the tag expression then the search will fail with an error.

Just as with regular expression searches, a second search immediately after the first, will not match the current message, so repeated searches will move through all the messages which match the tag expression.  To make this more convenient, the search expression is defaulted to the last one you entered.

Tagging Matching Messages
=========================

As well as just searching for a regular expression and moving point to the first matching message, af can tag all the messages which match a regular expression.  To do this use C-t s (search-and-tag). You will be prompted for the regular expression to search for, and the tags to set on the matching messages (see Setting Tags).  Once the search has finished, af will report how many messages were tagged.

With a numeric argument this command will only search the headers of the messages.  This is often convenient when (for example) looking for messages which are from a particular person or mailing list.

Syntax of Regular Expressions
=============================

Regular expressions have a syntax in which a few characters are special constructs and the rest are ordinary.  An ordinary character is a simple regular expression which matches that same character and nothing else.  The special characters are $, ^, ., *, +, ?, [, ] and \.  Any other character appearing in a regular expression is ordinary, unless a \ precedes it.

For example, f is not a special character, so it is ordinary, and therefore f is a regular expression that matches the string f and no other string.  (It does not match the string ff.)  Likewise, o is a regular expression that matches only o.  (When case distinctions are being ignored, these regular expressions also match F and O, but we consider this a generalization of ``the same string'', rather than an exception.)

Any two regular expressions A and B can be concatenated. The result is a regular expression which matches a string if A matches some amount of the beginning of that string and B matches the rest of the string.

As a simple example, we can concatenate the regular expressions f and o to get the regular expression fo, which matches only the string fo.  Still trivial.  To do something nontrivial, you need to use one of the special characters.  Here is a list of them.

. (Full stop)
     is a special character that matches any single character except a newline. Using concatenation, we can make regular expressions like a.b which matches any three-character string which begins with a and ends with b.

*
     is not a construct by itself; it is a postfix operator, which means to match the preceding regular expression repetitively as many times as possible.  Thus, o* matches any number of os (including no os).

     * always applies to the smallest possible preceding expression.  Thus, fo* has a repeating o, not a repeating fo.  It matches f, fo, foo, and so on.

+
     is a postfix character, similar to * except that it must match the preceding expression at least once.  So, for example, ca+r matches the strings car and caaaar but not the string cr, whereas ca*r matches all three strings.

?
     is a postfix character, similar to * except that it can match the preceding expression either once or not at all.  For example, ca?r matches car or cr; nothing else.

[ ... ]
     is a character set, which begins with [ and is terminated by ].  In the simplest case, the characters between the two brackets are what this set can match.

     Thus, [ad] matches either one a or one d, and [ad]* matches any string composed of just as and ds (including the empty string), from which it follows that c[ad]*r matches cr, car, cdr, caddaar, etc.

     You can also include character ranges in a character set, by writing two characters with a - between them.  Thus, [a-z] matches any lower-case letter.  Ranges may be intermixed freely with individual characters, as in [a-z$%.], which matches any lower case letter or $, % or ..

     Note that the usual regex special characters are not special inside a character set.  A completely different set of special characters exists inside character sets: ], - and ^.

     To include a ] in a character set, you must make it the first character.  For example, []a] matches ] or a.  To include a -, write - as the first or last character of the set.  Thus, []-] matches both ] and -.

     To include ^, make it other than the first character in the set.

[^ ... ]
     [^ begins a complemented character set, which matches any character except the ones specified.  Thus, [^a-z0-9A-Z] matches all characters except letters and digits.

     ^ is not special in a character set unless it is the first character.  The character following the ^ is treated as if it were first (- and ] are not special there).

^
     is a special character that matches the empty string, but only at the beginning of a line in the text being matched.  Otherwise it fails to match anything.  Thus, ^foo matches a foo which occurs at the beginning of a line.

$
     is similar to ^ but matches only at the end of a line.  Thus, xx*$ matches a string of one x or more at the end of a line.

\
     has two functions: it quotes the special characters (including \), and it introduces additional special constructs.

     Because \ quotes special characters, \$ is a regular expression which matches only $, and \[ is a regular expression which matches only [, etc.

     For the most part, \ followed by any character matches only that character.  However, there are several exceptions: two-character sequences starting with \ which have special meanings.  The second character in the sequence is always an ordinary character on its own.  Here is a table of `\' constructs.

     \{ ... \}
          is a postfix construct, similar to * except that it allows you to specify the number of times the preceding expression must be matched. So, for example, ca\{3\}r will match only the string caaar.

          If you add a comma after the number of times the expression must be matched, then the expression must be matched at least as many times as you specified.  So ca\{2,\}r will match the strings caar, caaar, caaaar, and so on.

          You can also add a maximum value after the comma, to specify a range of values.  So ca\{1,3\}r will match only the strings car, caar and caaar.

     \|
          specifies an alternative.  Two regular expressions A and B with \| in between form an expression that matches anything that either A or B matches.

          Thus, foo\|bar matches either foo or bar but no other string.

          \| applies to the largest possible surrounding expressions.  Only a surrounding \( ... \) grouping can limit the scope of \|.

     \( ... \)
          is a grouping construct that serves three purposes:

           1. To enclose a set of \| alternatives for other operations. Thus, \(foo\|bar\)x matches either foox or barx.

           2. To enclose a complicated expression for the postfix operators *, + and ? to operate on.  Thus, ba\(na\)* matches bananana, etc., with any (zero or more) number of na strings.

           3. To mark a matched substring for later reference with \N.

     \N
          When you use \( ... \) in an expression, you can look for another match for the exact same text that was matched inside the \( ... \).  The two-character sequence \N will match the same text as was matched by the Nth use of \( ... \).  The first nine uses are remembered, and are assigned the numbers 1 to 9.  So \1 matches the text that was matched by the first use of \( ... \).

          For example, \([a-z]\)\1 matches any two consecutive lower case characters.  The \([a-z]\) matches any lower case character, while the \1 must match the same character.

          If a use of \( ... \) matches more than once, which often happens if it is followed by * or +, only the last match is stored for use with \N.

Here is a moderately complicated regex, which you might use to find messages from the af-bug or af-user mailing lists.

     ^From:.*af-\(bug\|user\)@csv.warwick.ac.uk

Searching and Case
==================

Searches in af normally ignore the case of the text they are searching through.  Thus, if you specify searching for foo, then Foo and foo are also considered a match.  Regular expressions, and in particular character sets, are included: [ab] would match a or A or b or B.

If you set the variable case-fold-search to false, then all letters must match exactly, including case.

Sorting Messages
****************

Af provides commands for sorting some or all of the messages in a mail buffer.  Each command prompts for a sort order, and then sorts the selected messages into that order.

M-x sort-buffer ORDER RET
     Sort all of the messages in the buffer into ORDER order.

M-x sort-region ORDER RET
     Sort the messages in the region into ORDER order.

M-x sort-tagset ORDER RET
     Sort the messages in the tagset into ORDER order.  The messages in the tagset are sorted correctly, but messages which are not in the tagset are not moved at all.

The sort orders which af understands are:

(reverse-)address
     The address of the sender of the message, sorted case-independent. Any full name or routing information in the address is ignored.

(reverse-)date
     The date the message was sent (or received if the date sent isn't known), from oldest to newest (newest to oldest).  The variable show-dates-in-local-time indicates whether dates should be compared as they are, or converted to your local time before they are compared (the default).

(reverse-)lines
     The number of lines in the message, from smallest to largest (largest to smallest).

(reverse-)mailbox
     The (reverse) order of the messages in the folder when it was read. Messages which were yanked into the buffer after it was read may appear anywhere in the buffer.

(reverse-)sender
     The full name of the sender of the message, sorted case-independent.

(reverse-)status
     The system tags of the message (see System Tags).  Messages with no system tags are sorted after those that have them.

(reverse-)subject
     The subject of the message, sorted alphabetically and case-independent. The prefix 'Re: ' is handled specially in subject lines, so that replies to a message will sort immediately after (before) the original message.

(reverse-)tags
     The user tags of the message (see User Tags).  Messages with no user tags are sorted after those that have them.

When you sort, messages which sort identically will remain in their original order, so sorting a buffer by date and then subject will result in the messages being in date order within each subject.  This is often a good approximation to the ``threading'' that news readers such as trn do, and is handy for reading mailing lists.

Af does not sort your folders by default when it reads them.  If you have a preference for reading buffers in a certain order, then you can set the configuration variable initial-buffer-sort to the sort ordering you prefer.

If you are familiar with other mail readers it is worth noting that af, unlike most other mail readers, saves the messages back to the folders in whatever order you sort them into.  This can often be convenient when managing large folders.

Narrowing
*********

Narrowing means focusing in on some portion of the buffer, making the rest temporarily inaccessible.  The portion which you can still get to is called the accessible part.  Canceling the narrowing, which makes the entire buffer once again accessible, is called widening. The amount of narrowing in effect in a buffer at any time is called the buffer's restriction.

Narrowing can make it easier to concentrate on a set of messages by eliminating clutter.  It can also be used to restrict the range of operation of a search command or repeating keyboard macro.

C-x n
     Narrow down to between point and mark (narrow-to-region).

C-t n EXPRESSION RET
     Narrow to the tagset defined by tag-expression (narrow-to-tagset).

C-x w
     Widen to make the entire buffer accessible again (widen).

When you have narrowed down to a part of the buffer, that part appears to be all there is.  You can't see the rest, you can't move into it (motion commands won't go outside the accessible part), you can't change it in any way.  However, it is not gone, and if you save the folder all the inaccessible messages will be saved.  The word Narrow appears in the mode line whenever narrowing is in effect.

One narrowing command is C-x n (narrow-to-region).  It sets the current buffer's restrictions so that the messages in the region remain accessible but all messages before or after the region are inaccessible.  Point and mark do not change.

Another narrowing command is C-t n (narrow-to-tagset).  It prompts for a tag expression, and then set the current buffer's restrictions so that the messages in the tagset remain accessible but all the other messages are inaccessible.

The way to cancel narrowing is to widen with C-x w (widen). This makes all the messages in the buffer accessible again.

Narrowing can be very useful if you have a set of messages that you want to deal with independently of any others; such as all the messages from a mailing list, or from a certain user.  Use C-t s (search-and-tag) to tag the messages you are interested in, and then use C-t n to narrow the buffer to only the tagged messages. When you are done with the messages, use C-x w to widen to buffer.

Another use for narrowing is when you are using tags to kill messages. You can use C-t n to narrow to the messages you intend to kill, and then conveniently scan the messages to make sure that you are happy to kill them all; using C-t u to untag any messages that you decide you want to keep.  Finally you can either kill the tagset with C-t C-k (kill-tagset), or set the mark and point at opposite ends of the buffer and use C-w (kill-region). When you have finished, use C-x w to widen the buffer.