NOTE: The remote address book capability does not allow you to access an existing local address book from a remote system! That is, you can't set the remote address book to something like{remote.host}.addressbookand expect to access the existing.addressbookfile on remote.host. Instead, you need to create a new remote address book in a new, previously unused remote mail folder. Then you can use the Select and Apply Save commands in the address book screen to Save all of the entries from an existing local address book to the new remote address book.
A remote address book is stored in a mail folder on an IMAP server. An Alpine remote address book is just like an Alpine local address book in that it is not interoperable with other email clients. The folder is a regular folder containing mail messages but those messages are special. The first message must be an alpine remote address book header message which contains the header x-pine-addrbook. The last message in the folder contains the address book data. In between the first and the last message are old versions of the address book data. The address book data is simply stored in the message as it would be on disk, with no MIME encoding. When it is used the data from the last message in the folder is copied to a local file and then that file is used exactly like a local address book file is used. When a change is made the modified local file is appended to the remote folder in a new message. In other words, the local file is just a cache copy of the data in the remote folder. Each client which uses the remote address book will have its own cache copy of the data. Whenever a copy is done the entire address book is copied, not just the entries which have changed.
Alpine can tell that the remote data has changed by one of several methods. If the date contained in the Date header of the last message has changed then it knows it has changed. If the UID of the last message has changed, or the number of messages in the folder has changed, it knows that it has changed. When Alpine discovers the folder has changed it gets a new copy and puts it in the local cache file.
There is a configuration file variable for remote address books called remote-abook-metafile. The variable is the name of a file in which information about remote address books is stored. There is one line in the metafile for each remote address book. The information stored there is the name of the cache file and information to help figure out when the remote folder was last changed. If the metafile or any of the cache files is deleted then Alpine will rebuild them the next time it runs.
Remote address books have names that look just like regular remote mail folder names. For example:
{host.domain}foldernameAlpine decides whether or not an address book is remote simply by looking at the first character of the address book name and comparing it to '{'.
.addressbook in the
user's Unix home directory, or in the case of PC-Alpine,
ADDRBOOK, in the same directory as the PINERC file.
There may be more than
one address book, and the default name can be overridden via an entry in
any of the Alpine configuration files. The two configuration variables
address-book
and global-address-book
are used to specify the names of the address books.
Each of these variables is a list
variable. The total set of address books for a user is the combination of
all the address books specified in these two lists. Each entry in the
list is an optional nickname followed by an address book name. The nickname is
everything up to the last space before the file name. The
global-address-book list will typically be configured in the
system-wide configuration file, though a user may override it like most
other variables. Address books which are listed in the
global-address-book variable are forced read-only, and are
typically shared among multiple users. Local address books (or local cache files for remote address books) are simple text files with lines in the format:
<nickname>TAB<fullname>TAB<address>TAB<fcc>TAB<comments>The last two fields are optional. A "line" may be made up of multiple actual lines in the file by using continuation lines, which are lines beginning with SPACE characters. The line breaks may be after TABs or in between addresses in a distribution list. Each actual line in the file must be less than 1000 characters in length.
Nicknames (the first field) are short names that the user types instead of typing in the full address. There are several characters which aren't allowed in nicknames in order to avoid ambiguity when parsing the address (SPACE, COMMA, @, ", ;, :, (, ), [, ], <, >, \). Nicknames aren't required. In fact, none of the fields is required.
The fullname field is usually stored as Last_name, First_name, in order that a sort on the fullname field comes out sorted by Last_name. If there is an unquoted comma in the fullname, Alpine will flip the first and last name around and get rid of the comma when using the entry in a composition. It isn't required that there be a comma, that's only useful if the user wants the entries to sort on last names.
The address field takes one of two forms, depending on whether the entry is a single (simple) address or a distribution list. For a simple entry, the address field is an RFC 2822 address. This could be either the email-address part of the address, i.e., the part that goes inside the brackets (<>), or it could be a full RFC 2822 address. The phrase part of the address (the fullname) is used unless there is a fullname present in the fullname field of the address book entry. In that case, the fullname of the address book entry replaces the fullname of the address. For a distribution list, the <address> is in the format:
"(" <address>, <address>, <address>, ... ")"
The only purpose for the parentheses around the list of addresses is to make it easier for the parsing routines to tell that it is a simple entry instead of a list. The two are displayed differently and treated slightly differently in some cases, though most of the distinction has disappeared. Each of the addresses in a list can be a full RFC 2822 address with fullname included, or it may be just the simple email-address part of the address. This allows the user to have a list which includes the fullnames of all the list members. In both the simple and list cases, addresses may also be other nicknames which appear in this address book or in one of the other address books. (Those nicknames are searched for by looking through the address books in the order they appear in the address book screen, with the first match winning.) Lists may be nested. If addresses refer to each other in a loop (for example, list A includes list B which includes list A again) this is detected and flagged. In that case, the address will be changed to "**** address loop ****".
The optional fcc field is a folder name, just like the fcc field in the composer headers. If the first address in the To field of a composition comes from an address book entry with an fcc field, then that fcc is placed in the fcc header in the composer.
The comments field is just a free text field for storing comments about an entry. By default, neither the fcc nor the comments field is shown on the screen in the address book screen. You may make those fields visible by configuring the variable addressbook-formats. They are also searched when you use the WhereIs command in the address book screen and are visible when you View or Update an entry.
The address book is displayed in the order that it is stored. When the user chooses a different sorting criterion, the data is actually sorted and stored, as opposed to showing a sorted view of the data.
When the address book is written out, it is first written to a temporary file and if that write is successful it is renamed. This guards against errors writing the file that might destroy the whole address book. The address book is re-written after each change. If the address book is a remote address book, the file is then appended to the remote mail folder using IMAP.
The end-of-line character(s) in the address book file are those native to the system writing it. So it is <LF> on Unix and <CR><LF> on PC's. However, both Unix and PC versions of Alpine can read either format, so it should be possible to share a read-only address book among the two populations (using NFS, for example).
There is an automatic, behind-the-scene check that happens every so often, also. For example, if someone else changes one of the address books that you have configured, your Alpine's copy of the address book will usually be updated automatically without you noticing. This checking happens at the same time as new mail checking takes place, unless you are actively using the address book, in which case it happens more frequently.
Remote configuration folders are very similar to remote address book folders. They both consist of a header message, which serves to identify the type of folder; the last message, which contains the data; and intermediate messages, which contain old versions of the data. The first message must contain the header x-pine-pinerc.
When a remote configuration is being used, the folder is checked to make sure it is a remote configuration folder, then the data contained in the last message is copied to a temporary file. That file is treated just like any regular local configuration file from that point on. Whenever a configuration change is made, the entire file is copied back to the IMAP server and is appended to the folder as a new message.
Because remote configuration folders are so similar to remote address books, the configuration variable remote-abook-metafile is used by both.
Remote configuration folders have names that look just like regular remote mail folder names. For example:
{host.domain}mypinercAlpine decides whether or not a configuration file is remote simply by looking at the first character of the name and comparing it to '{'.
The exact algorithm given below is no longer correct. It has gotten more complicated over time. However, this gives the general idea Alpine uses when deciding whether or not to do a checkpoint.
.pine-debugX in the user's home directory where
X goes from 1 to 4. Number 1 is always the most recent session
and 4 the oldest. Four are saved because often the user has gone in and
out of Alpine a few times after a problem has occurred before the expert
actually gets to look at it. The amount of output in the debug files
varies with the debug level set when Alpine is
compiled and/or as a command
line flag. The default is level 2. This shows very general things and
records errors. Level 9 produces copious amounts of output for each
keystroke.
Similarly, PC-Alpine creates debug files
named pinedebg.txtX in the
same directory as the PINERC file.
The folders for sent mail and saved messages folders are also somewhat special. They are automatically created if they are absent and recreated if they are deleted.
pine.hlp in the alpine subdirectory of the
distribution contains all the help text for Alpine.
It is compiled right into the Alpine binary as strings.
This is done to simplify installation and configuration.
The pine.hlp file is in a
special format that is documented at the beginning of the file.
It is divided into sections, each with a name that winds up being referenced as
a global variable. This file is processed during the build process and
turned into a C file that is compiled into Alpine.
Alpine recognizes some local character sets which are right-to-left (Arabic, Hebrew, and Thai) or not representable in a fixed-width font (Arabic) and properly converts texts in these character sets to/from Unicode; however, there are known display bugs with these character sets.
There are three possible configuration character settings and some environment variable settings which can affect how Alpine handles international characters. The first two of these are only available in UNIX Alpine. The three configuration options are display-character-set, keyboard-character-set, and posting-character-set. The keyboard-character-set defaults to being the same value as the display-character-set, and that is usually correct, because the keyboard almost always produces characters in the same character set as the display displays. The display-character-set is the character set that Alpine will attempt to use when sending characters to the display.
Besides those variables there is also use-system-translation which can be used instead of these. That usage is only lightly tested and is not recommended.
By default, the display-character-set variable is not set and UNIX Alpine
will attempt to get this information from the environment.
In particular, the nl_langinfo(CODESET) call is used.
This usually depends on the setting of the environment variables LANG or LC_CTYPE.
An explicit configuration setting for display-character-set will,
of course, override any default setting.
For PC-Alpine the display-character-set
and the keyboard-character-set
are always equivalent to UTF-8 and this is not settable.
It is probably best to use UNIX Alpine in a terminal emulator capable of displaying UTF-8 characters, since that will allow you to view just about any received text that is correctly formatted (note, however, the above comments about known index display bugs with certain character sets). You'll need to have an emulator which uses a UTF-8 font and you'll need to set up your environment to use a UTF-8 charmap. For example, on a Linux system you might include
setenv LANG en_US.UTF-8 or something similar in your UNIX startup files. You'd also have to select a UTF-8 font in your terminal emulator.
The types of values that the character set variables may be set to are
UTF-8, ISO-8859-1, or EUC-JP.
The ISO-2022 character sets are not supported for input or
for display, but as a special case, ISO-2022-JP is supported
for use only as a posting-character-set.
In the Setup/Config screen you may choose from a list of all the
character sets Alpine knows about by using the "T" ToCharsets command.
Here is a list of many of the possible character sets:
| UTF-8 | Unicode |
| US-ASCII | 7 bit American English characters |
| ISO-8859-1 | 8 bit European "Latin 1" character set |
| ISO-8859-2 | 8 bit European "Latin 2" character set |
| ISO-8859-3 | 8 bit European "Latin 3" character set |
| ISO-8859-4 | 8 bit European "Latin 4" character set |
| ISO-8859-5 | 8 bit Latin and Cyrillic |
| ISO-8859-6 | 8 bit Latin and Arabic |
| ISO-8859-7 | 8 bit Latin and Greek |
| ISO-8859-8 | 8 bit Latin and Hebrew |
| ISO-8859-9 | 8 bit European "Latin 5" character set |
| ISO-8859-10 | 8 bit European "Latin 6" character set |
| ISO-8859-11 | Latin and Thai |
| ISO-8859-12 | Reserved |
| ISO-8859-13 | 8 bit European "Latin 7" character set |
| ISO-8859-14 | 8 bit European "Latin 8" character set |
| ISO-8859-15 | 8 bit European "Latin 9" character set |
| ISO-8859-16 | 8 bit European "Latin 10" character set |
| KOI8-R | 8 bit Latin and Russian |
| KOI8-U | 8 bit Latin and Ukranian |
| WINDOWS-1251 | 8 bit Latin and Russian |
| TIS-620 | 8 bit Latin and Thai |
| VISCII | 8 bit Latin and Vietnamese |
| GBK | Latin and Chinese Simplified |
| GB2312 | Latin and Chinese Simplified |
| CN-GB | Latin and Chinese Simplified |
| BIG5 | Latin and Chinese Traditional |
| BIG-5 | Latin and Chinese Traditional |
| EUC-JP | Latin and Japanese |
| SHIFT-JIS | Latin and Japanese |
| EUC-KR | Latin and Korean |
| KSC5601 | Latin and Korean |
When reading incoming email, Alpine understands many different character sets and is able to convert the incoming mail into Unicode. The Unicode will be converted to the display-character-set for display on your terminal. Characters typed at the keyboard will be converted from the keyboard-character-set to Unicode for Alpine's internal use. You may find that you can read some malformed messages that do not contain a character set label by setting the option unknown-character-set.
The posting-character-set is used when sending messages. The default behavior obtained by leaving this variable unset is usually what is wanted. In that default case, Alpine will attempt to label the message with the most specific character set from the rather arbitrary set
US-ASCII, ISO-8859-15, ISO-8859-1, ISO-8859-2, VISCII, KOI8-R, KOI8-U, ISO-8859-7, ISO-8859-6, ISO-8859-8, TIS-620, ISO-2022-JP, GB2312, BIG5, EUC-KR, and UTF-8.
For example, if the message is made up of only US-ASCII characters, it will be labeled US-ASCII. Otherwise, if it is all ISO-8859-15 characters, that will be the label. If that doesn't work the same is tried for the remaining members of the list.
It might make sense to set posting-character-set to an explicit value instead. For example, if you usually send messages in Greek, setting this option to ISO-8859-7 will result in messages being labeled as US-ASCII if there are no non-ascii characters, ISO-8859-7 if there are only Greek characters, or UTF-8 if there are some characters which aren't representable in ISO-8859-7. Another possibility is to set this option explicitly to UTF-8. In that case Alpine labels only ascii messages as US-ASCII and all other messages as UTF-8.
Composition of half-done messages may be postponed to a later time by giving the ^O command. Other messages can be composed while postponed messages wait. All of the postponed messages are kept in a single folder. Postponing is a good way to quickly reference other messages while composing.
N in Alpine's
FOLDER INDEX means that a
message is unseen-it has not been read from this folder yet. The D
means that a message is marked for deletion.
Messages marked with D are
removed when the user Expunges the folder (which usually happens
when the folder is closed or the user quits Alpine).
The A in Alpine's
FOLDER INDEX means that the message has been replied-to. The * in
Alpine's FOLDER INDEX means that the message has been ``flagged'' as
important. That is, the user used the Flag command to turn the
FLAGGED flag on. This flag can mean whatever the user wants it to mean.
It is just a way to mark some messages as being different from others. It
will usually probably be used to mark a message as somehow being
``important''. For Berkeley format folders, the message status is written
into the email folder itself on the header lines marked Status:
and X-Status.
It is also possible for a user to define their own flags in addition to the standard system flags above. In Alpine these user defined flags are called Keywords.
Alpine honors the "mailcap" configuration system for specifying external programs for handling attachments. The mailcap file maps MIME attachment types to the external programs loaded on your system which can display and/or print the file. A sample mailcap file comes bundled with the Alpine distribution. It includes comments which explain the syntax you need to use for mailcap. With the mailcap file, any program (mail readers, newsreaders, WWW clients) can use the same configuration for handling MIME-encoded data.
If a MAILCAPS environment variable is defined,
Alpine will use that to look
for one or more mailcap files, which are combined. In the absence of
MAILCAPS, Unix Alpine will look for
a personal mailcap file in ~/.mailcap
and combine that with a system-wide file in /etc/mailcap.
PC-Alpine will look for a file named MAILCAP in the
same directory as the PINERC file,
and/or the directory containing the ALPINE.EXE executable.
Messages which include rich text or enriched text in the main body will be displayed in a very limited way (it will show bold and underlining).
If Alpine sees a MIME message part tagged as type IMAGE,
and Alpine's
image-viewer
configuration variable is set, Alpine will attempt to
send that attachment to the named image viewing program. In the case of
UNIX Alpine, the DISPLAY environment variable is
checked to see if an X-terminal is being used (which can handle the images).
If the image-viewer variable is not set,
Alpine uses the mailcap
system to determine what to do with IMAGE types, just as it does for any
other non-TEXT type, e.g. type APPLICATION. For MIME's generic "catch
all" type, APPLICATION/OCTET-STREAM, the mailcap file will
probably not specify any action, but Alpine users may always
Save any MIME attachment to a file.
MIME type "text/plain" is handled a little bit differently than the other types. If you are viewing the main body part in the MESSAGE TEXT viewing screen, then Alpine will use its internal viewer to display it. This happens even if there is a mailcap description which matches this particular type. However, if you view a part of type "text/plain" from the ATTACHMENT INDEX screen, then Alpine will check the mailcap database for a matching entry and use it in preference to its internal viewer.
Some text attachments, specifically those which are just other email messages forwarded as MIME messages, are displayed as part of the main body of the message. This distinction allows easy display when possible (the forward as MIME case) and use of an attachment viewer when that is desirable (the plain text file attachment case).
If the parts of a multipart message are alternate versions of the same thing Alpine will select and display the one best suited. For parts of type "message/external-body", the parameters showing the retrieval method will be displayed, and the retrieval process is automated. Messages of type "message/partial" are not supported.
MIME has two ways of encoding data-Quoted-Printable and Base64. Quoted-Printable leaves the ASCII text alone and only changes 8-bit characters to "=" followed by the hex digits. For example, "=09" is a tab. It has the advantage that it is mostly readable and that it allows for end of line conversions between unlike systems. Base64 encoding is similar to uuencode or btoa and just encodes a raw bit stream. This encoding is designed to get text and binary files through even the most improperly implemented and configured gateways intact, even those that distort uuencoded data.
All attachments are encoded using Base64 encoding. This is so that the attachment will arrive at the other end looking exactly like it did when it was sent. Since Base64 is completely unreadable except by MIME-capable mailers or programs, there is an obvious tradeoff being made here. We chose to ensure absolutely reliable transport of attachments at the cost of requiring a MIME-capable mailer to read them. If the user doesn't want absolute integrity he or she may always include text (with the ^R command) in the body of a message instead of attaching it. With this policy, the only time quoted-printable encoding is used is when the main body of a message includes special foreign language characters.
When an attachment is to be sent, Alpine sniffs through it to try to set the right label (content-type and subtype). An attachment with any lines longer than 500 characters in it or more than 10% of the characters are 8-bit it will be considered binary data. Alpine will recognize (and correctly label) a few special types including GIF, JPEG, PostScript, and some audio formats. Another method which can be more robust and flexible for determining the content-type and subtype is to base it on the file extension. This method uses a MIME.Types File.
If it is not binary data (has only a small proportion of 8-bit characters in it,) the attachment is considered 8-bit text. 8-bit text attachments are labeled "text/plain" with charset set to the value of the user's keyboard-character-set variable. If an attachment is ASCII (no 8-bit characters) and contains no control characters then it is considered plain ASCII text. Such attachments are given the MIME label "text/plain; charset=US-ASCII", regardless of the setting of the user's keyboard-character-set variable.
All other attachments are unrecognized and therefore given the generic MIME label "application/octet-stream".
When there is new mail, the message(s) will appear in the index, the screen will beep, and a notice showing the sender and subject will be displayed. If there has been more than one new message since you last issued a command to Alpine, the notice will show the count of new messages and the sender of the most recent one.
The implementation of the standard UNIX ".lock" file locking has been modified to work with NFS as follows. Standard hitching post locking is used so first a uniquely named file is created, usually something like xxxx.host.time.pid. Then a link to it is created named xxxx.lock where the folder being locked is xxxx. This file constitutes the lock. This is a standard UNIX locking scheme. After the link returns, a stat(2) is done on the file. If the file has two links, it is concluded that the lock succeeded and it is safe to proceed.
In order to minimize the risks of locking failures via NFS, we strongly recommend using IMAP rather than NFS to access remote incoming message folders, e.g. your INBOX. However, it is generally safe to access personal saved-message folders via NFS since it is unlikely that more than one process will be updating those folders at any given time. Still, some problems may occur when two Alpine sessions try to access the same mail folder from different hosts without using IMAP. Imagine the scenario: Alpine-A performs a write that changes the folder. Alpine-B then attempts to perform a write on the same folder. Alpine-B will get upset that the file has been changed from underneath it and abort operations on the folder. Alpine-B will continue to display mail from the folder that it has in its internal cache, but it will not read or write any further data. The only thing that will be lost out of the Alpine-B session when this happens is the last few status changes.
If other mail readers besides Alpine are involved, all bets are off. Typically, mailers don't take any precautions against a user opening a mailbox more than once and no special precautions are taken to prevent NFS problems.
The first setting, attached-to-ansi, makes use of escape sequences on ANSI/VT100 terminals. It uses "<ESC>[5i" to begin directing all output sent to the terminal to the printer and then "<ESC>[4i" to return to normal. Alpine will send these escape sequences if the printer is set to attached-to-ansi. This works with most ANSI/VT100 emulators on Macs and PCs such as kermit, NCSA telnet, VersaTerm Pro, and WinQVT. Various terminal emulators implement the print feature differently. There is also a closely related method called attached-to-ansi-no-formfeed which is the same except for the lack of formfeed character at the end of the print job.
Attached-to-wyse and attached-to-wyse-no-formfeed are very similar to "attached-to-ansi". The only difference is in the control characters sent to turn the printer on and off. The Wyse version uses Ctrl-R for on, and Ctrl-T for off.
The second selection is the standard UNIX print command. The default is
lpr, but it can be changed on a system basis to anything so
desired in /usr/local/lib/pine.conf.
The third selection is the user's personal choice for a UNIX print command. The text to be printed is piped into the command. Enscript or lpr with options are popular choices. The actual command is retained even if one of the other print selections is used for a while.
Both the second and third sections are actually lists of possible commands rather than single commands.
If you have a PostScript printer attached to a PC or Macintosh, then you
will need to use a utility called ansiprt to get printouts on
your printer. Ansiprt source code and details can be found in
the ./contrib directory of the Alpine distribution.
SENTMAIL,
which is syntax for a DOS file. However, if the default collection
for Saves is
remote, then the default-fcc needs to be sent-mail
to match the UNIX syntax. The configuration variable fcc-name-rule also plays a role in selecting the folder to save sent mail in.
A danger here is that the sent mail could grow without bound. For this reason, we thought it useful to encourage the users to periodically prune their sent mail folder. The first time Alpine is used each month it will offer to archive all messages sent from the month before. Alpine also offers to delete all the sent mail archive folders which are more than 1 month old. If the user or system has disabled sent mail archiving (by setting the configuration variable default-fcc="") there will be no pruning question.
Lines beginning with ">" (usually messages included in replies) are not checked. The message text to be checked is on the standard input and the incorrect words are expected on the standard output.
The default spell checker is UNIX spell. You can replace this by setting the speller configuration variable. A common choice for a superior replacement is ispell.
PC-Alpine relies on the aspell library being installed. Aspell is independent of Alpine. The Windows version has traditionally been available at http://aspell.net/win32/. You'll need to download and install both Aspell and a precompiled dictionary. Aspell is provided in an installer package. Dictionaries, to be installed after Aspell, are in '.exe' files to download and run.
Alpine handles screens of most any size and resizing on the fly. It catches SIGWINCH and does the appropriate thing.
On the input side of things, Alpine uses all the standard keys, most of the control keys and (in function-key mode) the function keys. Alpine avoids certain control keys, specifically ^S, ^Q, ^H, and ^\ because they have other meanings outside of Alpine (they control data flow, etc.) ^H is treated the same as the delete key, so the backspace or delete keys always work regardless of any configuration. There is a feature compose-maps-delete-key-to-ctrl-d which makes the delete key behave like ^D rather than ^H (deletes current character instead of previous character).
Sometimes a communications program or communications server in between you and the other end will eat certain control characters. There is a work-around when you need it. If you type two escape characters followed by a character that will be interpreted as the character with the control key depressed. For example, ESC ESC T is equivalent to ^T.
When a function key is pressed and Alpine is in regular (non-function key) mode, Alpine traps escape sequences for a number of common function keys so users don't get an error message or have an unexpected command executed for each character in the function key's escape sequence. Alpine expects the following escape sequences from terminals defined as VT100:
ANSI/VT100
F1: <ESC>OP
F2: <ESC>OQ
F3: <ESC>OR
F4: <ESC>OS
F5: <ESC>Op
F6: <ESC>Oq
F7: <ESC>Or
F8: <ESC>Os
F9: <ESC>Ot
F10: <ESC>Ou
F11: <ESC>Ov
Arrow keys are a special case. Alpine has the escape sequences for a number of conventions for arrow keys hard coded and does not use termcap to discover them. This is because termcap is sometimes incorrect, and because many users have PC's running terminal emulators that don't conform exactly to what they claim to emulate. There is a feature called termdef-takes-precedence which can be set to cause the termcap or terminfo definitions to be used instead of the built in definitions. Some arrow keys on old terminals send single control characters like ^K (one even sends ^\). These arrow keys will not work with Alpine. The most popular escape sequences for arrow keys are:
Up: <ESC>[A <ESC>?x <ESC>A <ESC>OA
Down: <ESC>[B <ESC>?r <ESC>B <ESC>OB
Right: <ESC>[C <ESC>?v <ESC>C <ESC>OC
Left: <ESC>[D <ESC>?t <ESC>D <ESC>OD