Folder Handling
***************

The operating system stores data permanently in named files.  We refer to files which contain mail messages as folders.  In general, the mail messages you process with af come from a folder which will need to be updated to reflect any changes you make.

Unlike most mail readers, af can read in and process several folders simultaneously, which makes it convenient to store messages in several folders rather than leaving them all in your incoming mailbox.  Af can actually be used quite conveniently as a small database by using folders to store related messages.

By default, af reads in your incoming mailbox when it starts.  You can also use command-line arguments to tell af to read a different folder (see Command Arguments).  Or you can tell an existing af to read another folder and prepare a buffer containing a copy of the folder's messages.  This is called visiting the folder.  Af commands apply to the messages in the buffer; that is, to the copy inside af.  Your changes appear in the folder itself only when you save the buffer back into the folder.

File Names
==========

Most af commands that operate on a file require you to specify the file name.  (Saving and reverting are exceptions; the buffer knows which file name to use for them.)  You enter the file name using the minibuffer (see Minibuffer).  Completion is available, to make it easier to specify long file names (see Completion).

Many people prefer to keep all their mail folders in one directory; any folders saved from Usenet news (news folders) in another, and so on.  To make this kind of operation more convenient, af interprets several characters specially if they appear at the start of the file name.

~USER
     USER's home directory, or your home directory if USER is not given.  For example ~/foo is the file foo in your home directory, while ~malc/foo is the file foo in malc's home directory.

%USER
     USER's incoming mailbox, or your incoming mailbox if USER is not given.  So % is the your incoming mailbox, while %malc is malc's incoming mailbox.  Note that you won't usually have the necessary permission to read other people's incoming mailboxes.

+
     Your folder directory, as specified by the variable folder. This is either extracted from the environment variable FOLDER, or defaulted to ~/Mail.  So +af will usually expand to ~/Mail/af.  You will need to create the directory yourself if you plan to use it; af won't create it for you.

=
     Your news folder directory, where saved news articles are stored, as specified by the variable news-folder.  This is either extracted from the environment variable SAVEDIR, or defaulted to ~/News.  So =Comp.mail.headers will usually expand to ~/News/Comp.mail.headers.  Normally your news-reader will have created this directory for you.

\
     A leading \ in a file name is ignored, but it prevents any special meaning being taken from the next character in the filename. To start a file name with a \, use \\.  For example \+af is the file +af in the current directory.

Af has a current directory, sometimes referred to as the working directory, which is normally the directory you were in when you ran af.  When you enter a folder name without a directory or a special prefix, the current directory is used.  If you specify a directory in a relative fashion, with a name that does not start with either a special prefix or a slash, it is interpreted with respect to the current directory.

For example, if the current directory is /home/malc/src/af and you type just foo, which does not specify a directory, it is short for /home/malc/src/af/foo.  ../../.afrc would stand for /home/malc/.afrc.  new/foo would stand for the file name /home/malc/src/af/new/foo.

The command M-x pwd prints af's current directory, and the command M-x cd sets it (to a value read using the minibuffer).  Af's current directory can only be changed by using the cd command.

Reading Folders Over a Network
==============================

Af supports a mail protocol called POP3, which allows you to read a folder over a network.  This allows people to read mail on a small machine which doesn't have a mail system itself; you simply connect to the POP server where your mail is stored, and read your mail over the network.

Your incoming mailbox may live on a POP server, or you may have a separate POP3 mailbox somewhere.  To access a POP3 folder use a filename beginning in a colon.  Two forms of POP3 folder name are acceptable: :SERVER or :USER@SERVER. The first form implies that the username to use on SERVER is the same one that you are currently logged in as; the second explicitly specifies the username to use to connect to the POP server.

Once af has opened a connection to the POP server, you are prompted for a password.  The password won't be echoed (for security reasons), and it won't be stored in the minibuffer history either.  If you don't know your password then you will need to check with your system administrator to find out what it is.  The password you use to log in is often worth trying.

Once af has read the POP folder (which may like some time; network connections are often slow), it displays the buffer as normal.  However, the buffer containing the folder will have the POP3 minor mode set.  This disallows several af features, notably killing and yanking messages in the buffer.  The reason for this is that the POP3 protocol was designed to work well with existing mail readers, and it doesn't have the functionality to cope with af's method of folder management.   (This isn't really POP3's fault; the design of af and of other mailers is very different in several areas.  The IMAP protocol provides all the functionality that af needs to work normally, but since it is nothing like as widely supported as POP3, we decided that POP3 was the network protocol to support.  For now.)  One way of working around this is to use a pending folder (see Pending Folders).

Visiting Files
==============

C-x C-f
     Visit a folder (find-file).

C-x C-r
     Visit a folder for viewing, without allowing changes to it (find-file-read-only).

C-x C-v
     Visit a different folder instead of the one visited last (find-alternate-file).

C-x 4 C-f
     Visit a file, in another window (find-file-other-window).

Visiting a folder means reading its contents into an af buffer so you can process them.  Af makes a new buffer for each folder that you visit.  We say that this buffer is visiting the folder that it was created to hold.  Af constructs the buffer name from the folder name by throwing away the directory, keeping just the name proper.  For example, a file named /home/malc/Mail/af would get a buffer named af.  If there is already a buffer with that name, a unique name is constructed by appending <2>, <3>, or so on, using the lowest number that makes a name that is not already in use.

Each window's mode line shows the name of the buffer that is being displayed in that window, so you can always tell what buffer you are processing.

The changes you make with af commands are made in the af buffer.  They do not take effect in the folder that you visited, or any place permanent, until you save the buffer.  Saving the buffer means that af writes the current contents of the buffer into its visited folder.  See Saving.

If a buffer contains changes that have not been saved, we say the buffer is modified.  This is important because it implies that some changes will be lost if the buffer is not saved.  The mode line displays two stars near the left margin to indicate that the buffer is modified.

If the status of one or more messages in a buffer has changed (perhaps they were new before you read the folder), but no other changes have been made, then we say that the buffer is status modified.  This is not so important as being modified, but some information will be lost if the buffer is not changed.  The mode line displays two plus signs near the left margin to indicate that the buffer is status modified.

To visit a folder, use the command C-x C-f (find-file). Follow the command with the name of the folder you wish to visit, terminated by a RET.

The folder name is read using the minibuffer (see Minibuffer), with defaulting and completion in the standard manner (see File Names). While in the minibuffer, you can abort C-x C-f by typing C-g.

If the specified folder does not exist and could not be created, or cannot be read, then you get an error, with an error message displayed in the echo area.

While af is reading the folder, it reports on how many messages it has read, usually after every five messages read.  You can control how often af updates the count by setting the variable message-count-update. Once the folder has been read, af will print a message like this:

     (Read 15 messages)

This confirms that af has successfully read the folder into a buffer. The message may also sometimes look like this:

     (Read 15 messages; including 1 with bad headers)

This means that the folder was read successfully, but some of the messages in the folder had mail headers that af couldn't interpret properly.  This is not usually critical, but some people prefer to know about errors in their mailboxes.

If the variable first-unread-message is set to true; then af will move point to the first message in the buffer that you haven't read, if there are any.  Otherwise you will begin processing the buffer with point on the first message.

If you visit a file that is already in af, C-x C-f does not make another copy.  It selects the existing buffer containing that file.

What if you want to create a new folder?  Just visit it.  Af prints (New File) in the echo area, but in other respects behaves as if you had visited an existing empty file.  If you make any changes and save them, the file is created.

If you visit a file that the operating system won't let you modify, Af makes the buffer read-only, so that you won't go ahead and make changes that you'll have trouble saving afterward.  You can make the buffer writable with C-x C-q (toggle-read-only).

Occasionally you might want to visit a folder as read-only in order to protect yourself from entering changes accidentally; do so by visiting the file with the command C-x C-r (find-file-read-only).

If you accidentally visit the wrong folder (perhaps you mistyped the file name), use the C-x C-v command (find-alternate-file) to visit the file you really wanted.  C-x C-v is similar to C-x C-f, but it kills the current buffer (after first offering to save it if it is modified).

C-x 4 f (find-file-other-window) is like C-x C-f except that the buffer containing the specified file is selected in another window.  The window that was selected before C-x 4 f continues to show the same buffer it was already showing.  If this command is used when only one window is being displayed, that window is split in two, with one window showing the same buffer as before, and the other one showing the newly requested file.  See Windows.

Pending Folders
===============

If you are reading mail via POP3, you may prefer to store your mail on your local machine, rather than on a POP server.  You can do this conveniently with af by using a pending folder, a folder which contains two folders.  The simplest way of doing this is to set the variable pending-folder to the name of the folder where all your incoming mail should be stored; say +mailbox.  You must set the pending-folder variable in your .afrc file, or it will have no affect (see Startup Files).

Once the pending-folder variable is set, it changes the behaviour of af when you start without specifying folders to read or addresses to send mail to.  Instead of reading your incoming mailbox into its own buffer, it reads the folder specified in the pending-folder variable, and then appends the contents of your incoming mailbox to the buffer.

The buffer is considered to contain both the pending folder and your incoming mailbox; it will be resynchronised from both, and visiting either folder will switch to the buffer displaying the pending folder. When you save the pending folder your incoming mailbox will be cleared, ready for any new mail.  If you don't save the buffer, both folders are left untouched.

One advantage of pending folders is that they are normal disk folders. If your incoming mailbox is read via POP3, using a pending folder will allow you to avoid the limitations of buffers in POP3 mode, and use all of af's features in the buffer.  Once you've set it up, using a default pending folder is transparent enough that you'll probably never notice the difference.

You can also read a folder into an existing buffer, making the buffer pending on the folder you read.  To do this use the command M-x read-pending-file.  You will be prompted for the name of the file to make the buffer pending on.  This has exactly the same effect as using the pending-folder variable.

Resynchronizing Buffers
=======================

As we have discussed, buffers are copies of the contents of a folder. So what can we do to handle new mail arriving in the folder after we have read it?  The solution to this is resynchronizing the buffer, so that any new messages in the file on disk are incorporated into the buffer.

When a buffer is resynchronised, any new messages are appended to the buffer, and a message will appear in the echo area to let you know that new messages were read into the buffer.

Af will check for new messages whenever you try to save a buffer to disk.  If there are new messages then the buffer is resynchronised, and the save will fail.

Af also checks for new mail in each folder you are visiting on a regular basis.  If any buffers are out of date, then they are resynchronised.  How often af does this is controlled by the resync-time variable, normally it is done every 600 seconds (10 minutes).

To manually check for new messages in a buffer's folder, use C-x r (resync-buffer).  If the buffer needs to be resynchronised, then point will be set on the first new message.

Saving Files
============

Saving a buffer in af means writing its contents back into the folder that was visited in the buffer.

C-x C-s
     Save the current buffer in its visited file (save-buffer).

C-x s
     Save any or all buffers in their visited files (save-some-buffers).

M-x save-all-buffers
     Save all modified buffers in their visited files.

M-~
     Forget that the current buffer has been changed (not-modified).

C-x C-w
     Save the current buffer in a specified file (write-file).

When you wish to save the folder and make your changes permanent, type C-x C-s (save-buffer).  After saving is finished, C-x C-s displays a message like this:

     (Wrote 12 messages)

If the selected buffer is not modified or status modified (no changes have been made in it since the buffer was created or last saved), saving is not really done, because it would have no effect.  Instead, C-x C-s displays a message like this in the echo area:

     (No changes need to be written)

The command C-x s (save-some-buffers) offers to save any or all modified buffers.  It asks you what to do with each buffer. These questions are also asked if you exit af by typing C-x C-c. The buffer is automatically resynchronised before being saved, and if any new messages are found the save will be abandoned.

The command M-x save-all-buffers saves all modified buffers.  This can be dangerous if you have several buffers, since you may not want to save one of them, so be careful!

If you have changed a buffer but you do not want to save the changes, you should take some action to prevent it.  Otherwise, each time you use C-x s or C-x C-c, you are liable to save this buffer by mistake.  One thing you can do is type M-~ (not-modified), which clears out the indication that the buffer is modified.  If you do this, none of the save commands will believe that the buffer needs to be saved.  (~ is often used as a mathematical symbol for `not'; thus M-~ is `not', metafied.)  Alternatively, you can cancel all the changes made since the file was visited or saved, by reading the text from the file again.  This is called reverting.  See Reverting.

If you wish to mark the buffer as visiting a different folder and save it right away, use C-x C-w (write-file).  It prompts for the new folder, marks the buffer as visiting that folder, and saves the buffer.  If the folder already exists, af will ask for confirmation that it is ok to overwrite the file with the buffer.

Reverting a Buffer
==================

If you have made extensive changes to a folder and then change your mind about them, you can get rid of them by reading in the previous version of the folder.  To do this, use M-x revert-buffer, which operates on the current buffer.  Since reverting a buffer unintentionally could lose a lot of work, you must confirm this command with yes.

Reverting marks the buffer as ``not modified'' until another change is made.

Inserting a Folder
==================

Sometimes you may want to merge two folders.  An easy way to do this is to use C-x i (insert-file), which inserts the contents of the specified folder into the buffer at point, leaving mark at the start of the inserted contents and point after them.  The buffer will not be visiting the folder you inserted, and so will be saved to its original folder.

Using Multiple Buffers
**********************

The messages you are processing in af reside in an object called a buffer.  Each time you visit a folder, a buffer is created to hold the messages in the folder.

At any time, one and only one buffer is selected.  It is also called the current buffer.  Often we say that a command operates on ``the buffer'' as if there were only one; but really this means that the command operates on the selected buffer (most commands do).

When af has multiple windows, each window has a chosen buffer which is displayed there, but at any time only one of the windows is selected and its chosen buffer is the selected buffer.  Each window's mode line displays the name of the buffer that the window is displaying (see Windows).

Each buffer has a name, which can be of any length, and you can select any buffer by giving its name.  Most buffers are made by visiting files, and their names are derived from the files' names.  But you can also create an empty buffer with any name you want.  A newly started af has a buffer named *scratch* which can be used as a temporary place to store messages.  The distinction between upper and lower case matters in buffer names.

Each buffer records individually what folder it is visiting, whether it is modified, and what major mode and minor modes are in effect in it (see Major Modes).

Creating and Selecting Buffers
==============================

C-x b BUFFER RET
     Select or create a buffer named BUFFER (switch-to-buffer).

C-x 4 b BUFFER RET
     Similar, but select BUFFER in another window (switch-to-buffer-other-window).

To select the buffer named BUFNAME, type C-x b BUFNAME RET.  This runs the command switch-to-buffer with argument BUFNAME.  You can use completion on an abbreviation for the buffer name you want (see Completion).  An empty argument to C-x b specifies the most recently selected buffer that is not displayed in any window.

Most buffers are created by visiting files, but you can also create a buffer explicitly by typing C-x b BUFNAME RET.  This makes a new, empty buffer which is not visiting any file, and selects it.  If you try and save a buffer created in this way, you are asked for the file name to use.

Note that C-x C-f, and any other command for visiting a file, can also be used to switch to an existing file-visiting buffer. See Visiting.

Listing Existing Buffers
========================

To display a list of all the buffers that exist, type C-x C-b.  Each line in the list shows one buffer's name, major mode and visited file.  The buffers are listed in the order, most recently visited first.

* or + at the beginning of a line indicates the buffer is modified or status modified.  If several buffers are modified, it may be time to save some with C-x s (see Saving).  % indicates a read-only buffer.  . marks the selected buffer.  Here is an example of a buffer list:

      MR Buffer         Size  Mode           File
      -- ------         ----  ----           ----
     .*  malc             12  Mail           /var/spool/mail/malc
      +  af               21  Mail           /home/malc/Mail/af
         *scratch*         0  Mail

Killing Buffers
===============

If you continue an af session for a while, you may accumulate a large number of buffers.  You may then find it convenient to kill the buffers you no longer need.  On most operating systems, killing a buffer releases its space back to the operating system so that other programs can use it.  Here are some commands for killing buffers:

C-x k BUFNAME RET
     Kill buffer BUFNAME (kill-buffer).

M-x kill-some-buffers
     Offer to kill each buffer, one by one.

C-x k (kill-buffer) kills one buffer, whose name you specify in the minibuffer.  The default, used if you type just RET in the minibuffer, is to kill the current buffer.  If you kill the current buffer, another buffer is selected; one that has been selected recently but does not appear in any window now.  If you ask to kill a file-visiting buffer that is modified, then you must confirm with yes before the buffer is killed.

The command M-x kill-some-buffers asks about each buffer, one by one.  An answer of y means to kill the buffer.  Killing the current buffer or a buffer containing unsaved changes selects a new buffer or asks for confirmation just like kill-buffer.

Multiple Windows
****************

Af can split the screen into two or many windows.  Multiple windows can display parts of different buffers, or different parts of one buffer.

Concepts of Af Windows
======================

Each Af window displays one Af buffer at any time.  A single buffer may appear in more than one window; if it does, any changes in its text are displayed in all the windows where it appears.  But the windows showing the same buffer can show different parts of it, because each window has its own value of point.

At any time, one of the windows is the selected window; the buffer this window is displaying is the current buffer.  The arrow cursor shows the location of point in this window, but is not visible in any other window.

Commands to move point affect the value of point for the selected af window only.  They do not change the value of point in any other af window, even one showing the same buffer.  The same is true for commands such as C-x b to change the selected buffer in the selected window; they do not affect other windows at all.  However, there are other commands such as C-x 4 b that select a different window and switch buffers in it.

When multiple windows show the same buffer, they can have different regions, because they can have different values of point and mark.

Each window has its own mode line, which displays the buffer name, modification status, size in messages, and major and minor modes of the buffer that is displayed in the window.  See Mode Line, for full details on the mode line.

Creating and Using Windows
==========================

C-x 2
     Split the current window vertically, creating a new window (split-window-vertically).

C-x o
     Select the ``other'' window (other-window).  That is o, not zero.

M-x previous-window RET
     Select the previous window.

C-M-v
     Scroll the next window (scroll-other-window).

The command C-x 2 (split-window-vertically) breaks the selected window into two windows, one above the other.  Both windows start out displaying the same buffer, with the same value of point.  By default the two windows each get half the height of the window that was split; a numeric argument specifies how many lines to give to the top window.

To select a different window, type C-x o (other-window). That is an o, for `other', not a zero.  When there are more than two windows, this command moves through all the windows from top to bottom.  After the bottommost window, it goes back to the one at the top.  A numeric argument means to move several steps in the cyclic order of windows.  A negative argument moves around the cycle in the opposite order.

You can also select a different window with M-x previous window. When there are more than two windows, this command moves through all the windows from bottom to top.  After the topmost window, it goes back to the one at the bottom.  A numeric argument means to move several steps in the cyclic order of windows.  A negative argument moves around the cycle in the opposite order.

The usual scrolling commands (see Scrolling) apply to the selected window only, but there is one command to scroll the next window. C-M-v (scroll-other-window) scrolls the window that C-x o would select.  It takes arguments, positive and negative, like C-v.

Deleting and Rearranging Windows
================================

C-x 0
     Delete the selected window (delete-window).  That is a zero.

C-x 1
     Delete all windows except the selected window (delete-other-windows).

C-x ^
     Make the selected window taller (enlarge-window).

M-x shrink-window
     Make the selected window smaller.

To delete a window, type C-x 0 (delete-window).  (That is a zero.)  The space occupied by the deleted window is given to an adjacent window.  Once a window is deleted, its attributes are forgotten; only restoring a window configuration can bring it back.  Deleting the window has no effect on the buffer it used to display; the buffer continues to exist, and you can select it in any window with C-x b.

C-x 1 (delete-other-windows) is more powerful than C-x 0; it deletes all the windows except the selected one; the selected window expands to use the whole screen except for the echo area.

To readjust the division of space among vertically adjacent windows, use C-x ^ (enlarge-window).  It makes the currently selected window get one line bigger, or as many lines as is specified with a numeric argument.  With a negative argument, it makes the selected window smaller.  The extra screen space given to a window comes from one of its neighbors.  You cannot enlarge the window if it would make a neighbouring window less than two lines tall.

You can also readjust the size of the selected window with M-x shrink-window.  It makes the currently selected window get one line smaller, or as many lines as is specified with a numeric argument. With a negative argument, it makes the selected window bigger.  The extra screen space released by a window is given to of its neighbors. You cannot shrink the window if it would make the window less than two lines tall.