18. 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 section 4.1 Command Line 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.

18.1 File Names		How to type and edit file name arguments.
18.2 Reading Folders Over a Network		Af can handle reading folders over a network.
18.3 Visiting Files		Visiting a folder prepares af to handle it.
18.4 Pending Folders		How an af buffer may contain two files.
18.5 Resynchronizing Buffers		Keeping buffers up-to-date with their folders.
18.6 Saving Files		Saving makes your changes permanent.
18.7 Reverting a Buffer		Reverting cancels all the changes not saved.
18.8 Inserting a Folder		You can insert a folder into the buffer.

18.1 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 section 7. The Minibuffer). Completion is available, to make it easier to specify long file names (see section 7.6 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.

18.2 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 user name to use on server is the same one that you are currently logged in as; the second explicitly specifies the user name 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. (3) One way of working around this is to use a pending folder (see section 18.4 Pending Folders).

18.3 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 section 18.6 Saving Files.

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 section 7. The Minibuffer), with defaulting and completion in the standard manner (see section 18.1 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 section 20. Multiple Windows.

18.4 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 section 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.

18.5 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.

18.6 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 section 18.7 Reverting a Buffer.

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.

18.7 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.

18.8 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.