Pine Technical Notes Version 4.64, September 2005 _Pine_ and _Pico_ are trademarks of the University of Washington. No commercial use of these trademarks may be made without prior written permission of the University of Washington. Pine, Pico and Pilot Copyright 1989-2005 University of Washington. Additional legal notices are at the web URL http://www.washington.edu/pine/legal. Table of Contents Introduction * Design Goals * Pine Components Background Details * Domain Names * RFC 822 Compliance * SMTP and Sendmail * Internet Message Access Protocol (IMAP) * Multipurpose Internet Mail Extensions (MIME) * Folder Collections Building and Installation * Compile-time Options * Including LDAP Functionality * Including Kerberos 5 Functionality * Pine Compile-time Options * Pico Compile-time Options * OS Dependent Compile-time Settings * IMAPd Compile-time Options * Building the Pine Programs * Installing Pine and Pico on UNIX Platforms * Installing PC-Pine * Installing IMAPd * Support Files and Environment Variables: UNIX Pine * Support Files, Environment Variables, and Registry Values: PC-Pine Command Line Arguments * Pine * Pico * Pilot Configuration and Preferences * Pine Configuration * General Configuration Variables * Configuration Features * Hidden Config Variables and Features * Retired Variables * Tokens for Index and Replying * Conditional Inclusion of Text for Reply-Leadin, Signatures, and Templates * Per Server Directory Configuration * Color Configuration * Index Line Color Configuration * Role Configuration * Filtering Configuration * Scoring Configuration * Other Rules Configuration * Patterns * Configuring News Configuration Notes + Pine in Function Key Mode + Domain Settings + Syntax for Collections + Syntax for Folder Names + Server Name Syntax + Folder Namespaces + What is a Mail Drop? + Sorting a Folder + Alternate Editor + Signatures and Signature Placement + Feature List Variable + Configuration Inheritance + Using Environment Variables + SMTP Servers + MIME.Types file + Color Details + Additional Notes on PC-Pine Behind the Scenes * Address Books * Remote Configuration * Checkpointing * Debug Files * Filters * Folder Formats and Name Extensions * Folder Locking * INBOX and Special Folders * Internal Help Files * International Character Sets * Interrupted and Postponed Messages * Message Status * MIME: Reading a Message * MIME: Sending a Message * New Mail Notification * NFS * Printers and Printing * Save and Export * Sent Mail * Spell Checker * Terminal Emulation and Key Mapping Notes for Porting and Modification * Porting Pine to Other Platforms * Test Checklist Introduction Design Goals Throughout _Pine_ development, we have had to strike a balance between the need to include features which advanced users require and the need to keep things simple for beginning users. To strike this balance, we have tried to adhere to these design principles: - The model presented to the user has to be simple and clear. Underlying system operation is hidden as much as possible. - It's better to have a few easily understood commands that can be repeated than to have some more sophisticated command that will do the job all at once. - Whenever the user has to select a command, file name, address, etc., the user should be given (or can get) a menu from which to make the selection. Menus need to be complete, small, organized and well thought out. - _Pine_ must provide immediate feedback for the user with each operation. - _Pine_ must be very tolerant of user errors. Any time a user is about to perform an irreversible act (send a message, expunge messages from a folder), _Pine_ should ask for confirmation. - Users should be able to learn by exploration without fear of doing anything wrong. This is an important feature so the user can get started quickly without reading any manuals and so fewer manuals are required. - The core set of _Pine_ functions should be kept to a minimum so new users don't feel "lost" in seemingly extraneous commands and concepts. Just as there were goals relating to the look and feel of _Pine_, there were equally important goals having to do with _Pine_'s structure-the things that users never see but still rely on every time they use _Pine_. While _Pine_ can be used as a stand-alone mail user agent, one of its strongest assets is its use of the Internet Message Access Protocol (IMAP) for accessing remote email folders. In addition, _Pine_ was one of the first programs to support the Multipurpose Internet Mail Extensions (MIME) specification. With MIME, _Pine_ users can reliably send any binary file to any other person on the Internet who uses a MIME compliant email program. The decision to use IMAP and MIME reflects the importance of interoperability, standardization and robustness in _Pine_. As you work with _Pine_ more, you will see other features which reflect the same values. For example, _Pine_ enforces strict compliance with RFC 822, implements a strong mail folder locking mechanism and verifies a process before overwriting any files (e.g. addressbook, expunging messages). Pine Components If you have picked up the _Pine_ distribution, then you already know that _Pine_ comes in a few different pieces. They are: _Pine_ The main code from which the _Pine_ program is compiled. _Pico_ _Pico_ is the name for the _Pine_ composer. The _Pico_ code is used in two ways: (1) it is compiled on its own to be a stand-alone editor and, (2) it is compiled as a library for _Pine_ to support composition of messages within _Pine_. _Pico_ is _Pine_'s internal editor invoked when users need to fill in header lines or type the text of an email message. _Imap_ An API for IMAP. Includes the C-Client library, which is compiled into _Pine_, and the IMAP server _IMAPd_. C-Client implements the IMAP protocol and also negotiates all access between _Pine_ and the mail folders it operates on, even if the folders are local. The C-Client routines are used for email folder parsing and interpreting MIME messages. _IMAPd_ is a separate server that handles IMAP connections from any IMAP-compliant email program. When _Pine_ accesses a remote mailbox, the _Pine_ program is the IMAP client and the _IMAPd_ program is the IMAP server. Background Details Domain Names Domain names are used to uniquely name each host on the Internet. A domain name has a number of parts separated by periods. Each label represents a level in the hierarchy. An example of a name is: olive.cac.washington.edu In this domain name the top-level label is _edu_, indicating it is at an educational institution, the second-level label is _washington_, indicating the University of Washington. _cac_ is a specific department within the University of Washington, and _olive_ is the host name. The top-level names are assigned by Internet organizations, and other names are assigned at the appropriate level. The Domain Name Service, DNS, is the distributed database used to look up these names. _Pine_ relies on domain names in multiple places. A domain name is embedded into the message-id line generated for each piece of email. A domain name is needed to contact an IMAP server to get access to remote INBOXes and folders. Most importantly, domain names are needed to construct the From: line of your outgoing messages so that people on the Internet will be able to get email back to you. On UNIX systems, you can set the domain via the user-domain variable in the _Pine_ configuration file, or rely on the file /etc/hosts which usually sets the name of the local host. While _Pine_ can often deliver email without the domain name being properly configured, it is best to have this set correctly. Problems can usually be solved by adjusting the system's entry in the /etc/hosts file. The fully-qualified name should be listed before any abbreviations. 128.95.112.99 olive.cac.washington.edu olive is preferred over 128.95.112.99 olive olive.cac.washington.edu On PCs, the task of configuring the domain name is a bit different. Often times, PCs do not have domain names-they have _IP addresses_. IP addresses are the numbers which uniquely identify a computer on the network. The way you configure your IP address depends on the networking software which you use on the PC. You can refer to the documentation which came with your networking software or see the PC specific installation notes for help configuring the IP address with your network software. With PCs, it is vital that users set the variable user-domain in the _Pine_ configuration file (PINERC). Details on configuring _Pine_ with correct domain names can be found in the Domain Settings section of this document. _________________________________________________________________ RFC 822 Compliance _Pine_ tries to adhere to RFC 822 a little more strongly than some other mailers and uses the _"full name
"_ format rather than the older _"address (full name)"_ format. The intent of the standard is that parentheses should only be for comments. _Pine_ displays and generates the newer format, but will parse the old format and attempt to turn it into the new one. As far as outgoing email is concerned, _Pine_ fully-qualifies addresses whenever possible. They are even displayed in fully-qualified form on the terminal as the user composes a message. This makes addresses more clear and gives a hint to the user that the network extends beyond the local organization. _Pine_ implements fully-qualified domain names by tacking on the local domain to all unqualified addresses which a user types in. Any address which does not contain an "@" is considered unqualified. The newer format for addresses allows for spaces and special characters in the full name of an address. For this reason, commas are required to separate addresses. If any special characters as defined in RFC 822 appear in the full name, quotes are required around the address. _Pine_ will insert the quotes automatically. The common cases where this happens are with periods after initials and parentheses. Because _Pine_ fully complies with RFC 822, it is sometimes difficult to use non-Internet address formats such as UUCP's host!user or DECNet's USER::HOST with _Pine_. People who run _Pine_ on these systems have made local modifications to _Pine_ or to the mail transport agent (e.g. sendmail) to make things work for them. _Pine_ expects dates to be in the standard RFC 822 format which is something like: [www, ] dd mmm yy hh:mm[:ss] [timezone] It will attempt to parse dates that are not in this format. When an unparsable date is encountered it is displayed as _xxx xx_ when shown in the FOLDER INDEX screen. _________________________________________________________________ SMTP and Sendmail _Pine_ is a _user agent_ not a _message transfer agent._ In plain English, that means _Pine_ does not know how to interact with other computers on the Internet to deliver or receive email. What _Pine_ does know how to do is help users read, organize and create email. The "dirty work" of delivering and accepting email is handled by other programs. All outgoing email is delivered to a mail transfer program or to an SMTP server. The most common mail transfer program is sendmail. Pine 3.91 and earlier: When _Pine_ on a UNIX computer uses the local sendmail, it first writes the message to a temporary file in /tmp. Then _Pine_ runs a shell in the background that runs sendmail on the temporary file and then removes it. This is done with a shell in the background so the user doesn't have to wait for sendmail to finish. By default, sendmail is invoked with the -t flag to cause it to read and parse the header to determine the recipients; the -oem flag to cause errors to be mailed back; and the -oi flag to ignore dots in incoming messages. Systems administrators can choose to configure _Pine_ to use a different mail transfer program or even sendmail with different flags. See the section on UNIX Pine Compile-time Options for more details on this. _Pine_ can also operate as an SMTP client. SMTP stands for _Simple Mail Transfer Protocol_; it specifies the rules by which computers on the Internet pass email to one another. In this case, _Pine_ passes outgoing email messages to a designated SMTP server instead of to a mail transfer program on the local machine. A program on the server then takes care of delivering the message. To make _Pine_ operate as an SMTP client, the smtp-server variable must be set to the IP address or host name of the SMTP server within your organization. This variable accepts a comma separated list of servers, so you can specify multiple SMTP servers. _PC-Pine_ only runs as an SMTP client. Pine 3.92 and later: The selection of which MTA to use depends on the settings of sendmail-path, smtp-server, and compile-time options. The first MTA specified in the following list is used: 1. _sendmail-path_ in /usr/local/lib/pine.conf.fixed 2. _smtp-server_ in /usr/local/pine.conf.fixed 3. _sendmail-path_ specified on the command line. 4. _smtp-server_ specified on the command line. 5. _sendmail-path_ in the user's .pinerc file. 6. _smtp-server_ in the user's .pinerc file. 7. _sendmail-path_ in /usr/local/lib/pine.conf 8. _smtp-server_ in /usr/local/pine.conf 9. DF_SENDMAIL_PATH defined at compile time. 10. SENDMAIL and SENDMAILFLAGS defined at compile time. If the _sendmail-path_ form is used, a child process is forked, and the specified command is executed with the message passed on standard input. Standard output is then passed back and displayed for the user. _NOTE: The program MUST read the message to be posted on standard input, AND operate in the style of sendmail's "-t" option. _ If an _smtp-server_ is specified, a connection to the server is opened. If the message contains 8-bit text, ESMTP 8BITMIME negotiation is attempted. The message is then sent using SMTP commands. If none of the above are set, the default sendmail program is invoked with the "-bs -odb -oem" flags, ESMTP negotiation is attempted, and the message is sent. _________________________________________________________________ Internet Message Access Protocol (IMAP) IMAP is a remote access protocol for message stores. _Pine_ uses IMAP to get at messages and folders which reside on remote machines. With IMAP, all messages are kept on the server. An IMAP client (such as _Pine_) can request specific messages, headers, message structures, etc. The client can also issue commands which delete messages from folders on the server. IMAP's closest kin is POP, the Post Office Protocol, which works by transferring an entire mailbox to the client where all the mail is kept. For a comparison of IMAP and POP, see the paper "Comparing Two Approaches to Remote Mailbox Access: IMAP vs. POP" by Terry Gray. A more detailed exploration of message access may be found in the paper " Message Access Paradigms and Protocols." These papers may be found in the /mail directory of the anonymous FTP server at ftp.cac.washington.edu. IMAP Features: * Allows access to mail folders from more than one client computer. * Works well over low-bandwidth lines because information is sent in small pieces as needed by the user. For example, only header information is sent to build index lists, and if someone sends a 2MB audio file via MIME, you can choose when (or if) you want to get that part of the message. * Email can be delivered and stored on a well-maintained and reliable server which is "always-up". * Folders can be accessed and manipulated from anywhere on the Internet. * Users can get to messages stored in different folders within the same _Pine_ session. * Allows use of IMAP server for searching and parsing. * The latest revision of IMAP (IMAP4) also provides for disconnected operation, including resynchronization of message state between mail servers and message caches on clients. _Pine_ does not yet support this capability, however. IMAP2 is defined in RFC 1176. IMAP4rev1, the revision to IMAP2, is described in RFC 3501. Further information about IMAP may be obtained from the University of Washington's IMAP Information Center on the World Wide Web. _Pine_ 4.00 is an IMAP4rev1 client. _________________________________________________________________ Multipurpose Internet Mail Extensions (MIME) MIME is a way of encoding a multipart message structure into a standard Internet email message. The parts may be nested and may be of seven different types: Text, Audio, Image, Video, Message, Application and Multipart (nested). The MIME specification allows email programs such as _Pine_ to reliably and simply exchange binary data (images, spreadsheets, etc.). MIME includes support for international character sets, tagging each part of a message with the character set it is written in, and providing 7-bit encoding of 8-bit character sets. It also provides a simple rich text format for marking text as bold, underlined, and so on. There is a mechanism for splitting messages into multiple parts and reassembling them at the receiving end. The MIME standard was officially published in June of 1992 as RFC 1341 and subsequently revised in RFC 2045 when it became a full Internet Standard. _Pine_ 3.0 was one of the first email programs to Implement MIME. Now, there are dozens of commercial and freely available MIME-capable email programs. In addition, MIME is being added to newsreaders so MIME messages can be posted and read in USENET newsgroups. The MIME standard also includes support for non-ASCII text in message headers through the extensions described in RFC 1342 and subsequently revised in RFC 2047. Support for RFC 2047 was added in _Pine_ 3.92. An actual MIME message looks something like this: Date: Tue, 12 Mar 1996 15:39:35 -0800 (PST) From: David L Miller To: David L Miller Subject: =?iso-8859-1?Q?Test_MIME_message_with_RFC-1522_headers_=28=E1?= =?i so-8859-1?Q?=E2=E3=29?= Message-Id: Mime-Version: 1.0 Content-Type: MULTIPART/MIXED; BOUNDARY="0-1737669234-826673975=:21583" Content-Id: This message is in MIME format. The first part should be readable text, while the remaining parts are likely unreadable without MIME-aware tools. Send mail to mime@docserver.cac.washington.edu for more info. --0-1737669234-826673975=:21583 Content-Type: TEXT/PLAIN; CHARSET=US-ASCII Content-ID: The text of the message would go here. It is readable if one doesn't mind wading around a little bit of the MIME formatting. After this is a binary file in base 64 encoding. |\ | |\/| David L. Miller dlm@cac.washington.edu (206) 685-6240 |/ |_ | | Software Engineer, Pine Development Team (206) 685-4045 (FAX) University of Washington, Networks & Distributed Computing, JE-20 4545 15th Ave NE, Seattle WA 98105, USA --0-1737669234-826673975=:21583 Content-Type: APPLICATION/ZIP; NAME="test.zip" Content-Transfer-Encoding: BASE64 Content-ID: Content-Description: Test Attachment UEsDBBQAAAAIAGh8bCBbZKT4ygIAAHgFAAAEAAAAdGVzdIVUX2vbMBB/16c4 9rSBNyjsYX1UHSUROLInycv2qNhKI5ZYxlLa5dvvpDRLw6CFgJF09/t3Rxo3 WDBDD43rPJjJQpxMbw9m+h3AbyHuLLSDe7JTcPGUbtYm7NzwGP3wBYQnnT8c 7NQ5s4djsC8t4QbmYE6wsfjpLTy7uPPHCOPk/ATPk4vRDmS008GF4PzwPich zY3m4LfxOQlPNy4GcEO3P/a2h2j/xGyp9ONpco+7CHf33+4/393ff4XNibzL c1UVfXJXQIdIBRx877b4TYy9C3Fym2NEyzsX/pNDet8dD3aIJiagLbo2wwnG 4zT6cK66ZLK1NhH9J4tcZQEy7OxkNyd4nMwQbV9glP7JZb87E3O32fgnm7We XQ8+us4SM47WTCkgMPt9enc2ZAW5c+Pj7o32l0IXXk/r8pSRE3A4jqOfIqqF G+PFlSdRDOaQduXNESTwtDcYfJ8191gWXUjYmOJ43Oxdh11JTzRuSPcY37+B vNqmf0O5RB1G27mt64rLCp4X8pW1L6BvxunCeYHNk3F7s9lb+GAwyvAhOyNE Lxm0gv9gUnH9C+o5rKlacrHQtYAZV2VF+UoBrSp8kJIKzZkqgP1sJFMKagl8 1VSczQqy5noJki2onIGuQS+5AlXPNfaxArgoq3aGwJDq6lZDxVdcU82RKMG/ 4JArTVKzYrJc4pE+8CoJpGIGc65FIp8jO4WGSs3LtqISmlY2tUKyVMUFETWw H0xoUMvE8KbXB4aC6EPFzrDiF6iGlZxWBeFixiUrdXJb1kKx7y2C4hPM6Iou WI4hdVyO6yXVqkZqiXmottLJ9lzWK1LVKttqk8oZ1TS1NrJGS5jqeslQI0aK ieCvzNlgNZJqiccCc5WafLxmKdii4gsmSvYpISkteamzkRwXJiG5SoUpcERK 8xIE8QQ7o+eh5WAUy1qYRP8rioip/maI+OfyF1BLAQIUAxQAAAAIAGh8bCBb ZKT4ygIAAHgFAAAEAAAAAAAAAAEAAACkgQAAAAB0ZXN0UEsFBgAAAAABAAEA MgAAAOwCAAAAAA== --0-1737669234-826673975=:21583-- For details about _Pine_'s implementation of MIME, see the two MIME sections "MIME: Reading a Message" and "MIME: Sending a Message" later in this document. _________________________________________________________________ Folder Collections Folder Collections are _Pine_'s way of dealing with more than a single group of folders. With advent of _PC-Pine_ and the development of tools within IMAP to better manage remote folders, the time was ripe to provide a mechanism for defining a group of remote folders. _PC-Pine_ forced the issue in that many potential _PC-Pine_ users would be migrating from UNIX _Pine_ in a time-sharing environment and, thus, would have some investment in their archived messages on that host. For a more complete description of Folder Collections, see the section on "Syntax for Collections." The _Pine_ distribution is designed to require as little configuration and effort at compile time as possible. Still, there are some _Pine_ behaviors which are set at the time you compile _Pine_. For each of these, there is a reasonable (our opinion) default built into the code, so most systems administrators will have no need for these steps. Building and Installation Compile-time Options The files you may need to modify are ./{pico,pine}/makefile.xxx, ./{pico,pine}/osdep/os-xxx.h, and possibly ./{pico,pine}/osdep/os-xxx.ic, where _xxx_ is the 3-letter code for your platform. You can give the command build help to see the list of ports incorporated into _Pine_ and their associated 3-letter codes. The files ./{pico,pine}/makefile.xxx are where you would set compiler options. By default, _Pine_ will be compiled with debugging on, optimization and profiling off. Note that if you compile with DEBUG off, then _Pine_ will not create its normal debug files, no matter how the debug-level and debug command line flag are set. Some of these can only be set when you compile. Others, however, can be overridden by command-line flags to _Pine_ or settings in _Pine_'s user or system configuration files. Some of the options which can be set when compiling: Including LDAP Functionality In order to build _Pine_ with LDAP functionality included you need to supply the LDAP library and include files. _Pine_ has been successfully built with OpenLDAP 2.0.x, OpenLDAP 1.x, the University of Michigan LDAP library (ldap-3.3), and with the Netscape Directory SDK 1.0 LDAP library. Set up a symlink called ldap in the top-level pine directory (the directory where the _Pine_ build script is located). The build script will call contrib/ldap-setup to help figure out how to use the LDAP libraries. It expects to find directories ldap, ldap/include, ldap/libraries, and file ldap/include/ldap.h. There are at least two slightly different styles of LDAP libraries. One style uses two libraries, libldap and liblber, the other uses just libldap. The script is not very smart, but it attempts to figure out which of these two cases is being used. Modify the script to fit your situation if you need to. When using OpenLDAP as the library (or the older University of Michigan libary), set up the symlink so that it points to the base of the ldap source tree. The ldap-setup script looks for the directory ldap/libraries/liblber and the libraries ldap/libraries/libldap.a and ldap/libraries/liblber.a. To use the Netscape Directory SDK library, make a directory called ldap in the top-level pine directory (where the _Pine_ build script is located). That directory should contain two subdirectories, include and libraries. The include directory is where you should put the include files from the Netscape SDK. The libraries directory is where you should put the library, libldap.a. The build script will run the script contrib/ldap-setup if you have created an ldap symlink or directory. It tries to figure out if the setup is the Univ. of Michigan code or not. If it is Univ. of Michigan ldap-3.3 or the library from mozilla.org, then it will link against both libldap.a and liblber.a. If it isn't, it will link against only libldap.a. You may find you have to do some tweaking to get this to work with the libraries you are using. If you find that a change to contrib/ldap-setup works for you, you might think about sending that to us for inclusion in the next _Pine_ release. If there is no ldap symlink, there is still an attempt to automatically include LDAP support if certain conditions exist. At this point, the check includes a check for Solaris 8, otherwise the automatic inclusion is not done. You may override the automatic inclusion of LDAP with the build argument NOLDAP. _Pine_ uses LDAPv2 protocol. When using LDAPv3 protocol, the results are returned in the utf8 character set. _Pine_ is not yet ready to deal with that, so it tells the server to use the LDAPv2 protocol. Including Kerberos 5 Functionality In order to build _Pine_ with Kerberos functionality included you should place a symlink called krb5 to the directory where your Kerberos5 include files and libraries are located. That is, krb5/include and krb5/lib should exist. Place the symlink in the top-level pine directory (where the _Pine_ build script is located). See the comments in the script contrib/krb5-setup if you have trouble. Pine Compile-time Options USE_QUOTAS Determines whether quotas are checked on startup. Default is to not check the quota. ALLOW_CHANGING_FROM This is now a hidden runtime feature called allow-changing-from. Even with this feature turned on, users still have to include _From_ in their default-composer-hdrs or customized-hdrs in order to be able to edit the From line. Beginning with version 4.10, a user may also change their From address by using Roles. A system administrator may disallow editing of the From line by putting the feature _no-allow-changing-from_ in the system-wide _fixed_ configuration file. The paranoid system administrator can compile in this behavior by defining _NEVER_ALLOW_CHANGING_FROM_ in ./pine/osdep/os-xxx.h. DEFAULT_DEBUG Sets the level of debugging output created in _Pine_'s debug files. Default is level 2. The command-line flag -d may also be used to change the debug level. For example, -dverbose=7. NUMDEBUGFILES Sets the number of debug files kept per user. Default is 4. The command-line flag -d may also be used to change this. For example, -dverbose=3,numfiles=2. BACKGROUND_POST Define this if you want to allow users to turn on the feature that enables sending to take place in a fork()'d child. This may reduce the time on the user's wall clock it takes to post mail. NOTE: You'll also have to make sure the appropriate ./pine/osdep/postreap.* file is included in the ./pine/osdep/os-xxx.ic file for your system. NEW_MAIL_TIME Interval between new-mail checks. Default is 150 seconds. This is obsolete. This should be set in a configuration file by setting the variable mail-check-interval. OVERLAP Number of lines overlap when user views the next page of a message. Default is 2 lines. This is obsolete. This should be set in a configuration file by setting the variable viewer-overlap. PASSFILE _WARNING!_ Turning this on is very dangerous and should probably not be done, except on single user systems! For _PC-Pine_, this is turned on by default and set to the filename PINE.PWD. It may be overridden by the -passfile command-line argument. You may enable it for Unix systems by defining PASSFILE to be a filename which will be located in the same directory as the pinerc file, usually the home directory. The file is used to save passwords from one session to the next. Even if you define PASSFILE when you compile _Pine_, password saving will not be enabled by default, but requires the existence of the file (the name of which is the value of PASSFILE). Even with the existence of this file, the user must still acknowledge a prompt before the password is saved to the file. If _Pine_ is configured to access several different IMAP servers, each password entered will be kept (associated with the corresponding host name) in memory during the current session, and optionally, in the PASSFILE file for use in subsequent sessions. _WARNING_! Use this feature with caution! It effectively makes the user's mail no more secure than the physical security of the machine running _Pine_. What's more, while the password is cloaked by a mild (some might say, feeble) encryption scheme, it is nonetheless sitting in a file on the disk and subject to cracking by anyone with access to it. _BEWARE_! SENDMAIL SENDMAILFLAGS Sets the name and flags for the local program that will be called to handle outgoing email. Default is /usr/lib/sendmail -oi -oem -t. See the SMTP and Sendmail section for more details. SYSTEM_PINERC The name of the file which holds _Pine_ configuration information for all users on the system. Default on UNIX systems is /usr/local/lib/pine.conf. SYSTEM_PINERC_FIXED The name of the file which holds the same type of information as for SYSTEM_PINERC, but only for variables that the administrator wants to keep fixed. That is, users are not allowed to change variables that are specified in the FIXED file. Default on UNIX systems is /usr/local/lib/pine.conf.fixed. There are a couple of more obscure options which are in the source code because a few people have asked for them or because we changed our minds about them being a good idea in general. ENCODE_FROMS Use Quoted-printable encoding so that From's at the beginning of lines don't end up being escaped by >'s. Most people seem to dislike the Q-P encoding more than the > escapes so this is off by default. Once everyone has MIME mail readers, we'll turn this on by default. NO_KEYBOARD_LOCK Disable the keyboard locking function in the main menu. Keyboard locking is enabled by default. An easier way to turn off Keyboard locking is to add the feature disable-keyboard-lock-cmd to the feature list variable in the global pine.conf or pine.conf.fixed file. Pico Compile-time Options There is really only one option settable specifically for _Pico_. It is for the UNIX _Pico_ versions only. The file that may need some changing is ./pico/osdep/os_xxx.h.. Whatever is set will effect the behavior of the _Pico_ stand-alone program as well as the composer within _Pine_. SPELLER Names the program called to do "normal" spell-checking. This can be set in a configuration file instead by setting the speller configuration variable. OS Dependent Compile-time Settings Most of _Pine_'s (and _Pico_'s) operating system dependent behaviors are set in the files ./pico/osdep/os-xxx.h and ./pico/osdep/os-xxx.ic. The flags in the makefiles are also system dependent. See the comments in ./pico/osdep/os-xxx.h for more details. One that may come up is: USE_TERMINFO USE_TERMCAP Instructs _Pine_ to use the terminfo (or termcap) database. Default varies by system. This has been moved from ./pine/osdep/os-xxx.h to ./pico/osdep/os-xxx.h. If you change this you will also have to change the file ./pico/osdep/os-xxx.ic so that it includes the file term.inf instead of term.cap (or vice versa) and you will probably have to change the libraries included by the makefiles ./{pico,pine}/makefile-xxx. Hopefully, it is already set correctly for each system. IMAPd Compile-time Options There are no options or settings required for the version of IMAPd distributed with _Pine_. If you need to be doing more complex modifications to IMAP, then you should pick up the IMAP development package and work with that code. The developer's version of IMAP is available for anonymous ftp from ftp.cac.washington.edu in the directory mail. The file is called imap.tar.Z. _________________________________________________________________ Building the Pine Programs You may have already compiled _Pine_ and tried it out. If so, great! If not, you should be able to do it without too much trouble by following these step-by-step instructions: 1. Figure out what platform you're building for. You can give the command build help or look at the list in ./doc/pine-ports to see the list of ports incorporated into _Pine_. What you need is the three letter code for the platform. Some examples are a41 for the AIX 4.1 operating system, os4 for Digital Unix 4.0, and lnx for Linux. There are sometimes several variants for a single operating system (different compilers, shadow passwords or not, etc.) so look through the whole list in ./doc/pine-ports for the one you want. If your platform is not in the list of ports, then you might have some work ahead of you. First, check the file doc/pine-ports to see if there are others working on a port for your platform or to see if the port is included in the contrib section of the source code. Ports in the contrib directory were contributed by _Pine_ administrators from around the world, but the _Pine_ development team has not been able to test the code. Some of these ports are very old and are based on old versions of _Pine_. If _Pine_ has not yet been ported to your platform at all, read the section on Porting Pine in this document. 2. Make sure you're in the root of the _Pine_ source. When you type ls you should see the following files and directories (or something close to it): README build doc makefile pine bin contrib imap pico 3. Make sure you're getting a clean start by giving the command ./build clean. This should take only a few seconds to run. 4. Give the command ./build _xxx_ where _xxx_ is the three letter code you picked in step 1. The compiler should grind away for a few minutes. 5. When the compilation is complete the sizes of the binaries built will be displayed. The actual binaries are in the various source directories. In addition, the bin directory contains a link to each program compiled. You can just copy them out of bin or try them from there. The build command can be given some options which it passes on to the subordinate makes. Some that may be useful are EXTRACFLAGS, DEBUG, and EXTRALDFLAGS. There are also some SSL-related arguments: SSLDIR, SSLCERTS, SSLINCLUDE, and SSLLIB. You should also read the comments in the build script itself, which are possibly more up-to-date than this text. Here are some examples of options you may want to pass to build. This will turn off the debugging files that _Pine_ produces, while leaving the symbol table information. We believe a better way to do this is to have an alias for pine which executes pine -d0 instead. This turns off debugging at runtime while preserving the possibility of using the debugging if a problem turns up. But if you wanted to turn it off unconditionally you could use the build argument DEBUG=-g In other words, the command to build a _Pine_ with no debugging would be ./build DEBUG=-g target where target is one of the 3-letter port names found in doc/pine-ports. To also leave out the symbol table information you could pass: DEBUG= To turn on the optimizer DEBUG=-O It should be ok to move string constants into a read-only area. We don't think there are any instances where _Pine_ modifies a string constant. So you could pass a flag to your compiler that tells it to do this. This could cause several hundred K of strings to be moved from the data area of the program into the text area of the program, and that should allow that text to be shared among all instances of _Pine_. To do this, for example, with the AIX _a41_ port, you could pass this to build: EXTRACFLAGS=-qro If you are using OpenSSL but have decided to use a non-standard directory (standard one is /usr/local/ssl) for the location then you can cause _Pine_ to use that directory with SSLDIR=/some/other/dir The assumption is that the certs directory is in SSLDIR/certs, the include directory is SSLDIR/include, and the library directory is SSLDIR/lib. You can change those assumptions with SSLCERTS=certs_directory SSLINCLUDE=include_directory and SSLLIB=ssl_library_directory If you are having trouble with the SSL compilation you may explicitly exclude SSL code with NOSSL. NOSSL Similarly, NOLDAP The argument EXTRASPECIALS can be used to pass arguments to the c-client make which aren't provided for in the _Pine_ build script. For example, if you want to change the FRIZZLE parameter (a made up argument which the c-client make uses) you might be tempted to type something like ./build FRIZZLE=cruft target This does work with make on some platforms, but not on others. Some makes seem to pass the arguments on to sub-makes, others don't. If that doesn't work, then EXTRASPECIALS is for you. ./build EXTRASPECIALS="FRIZZLE=cruft" target An additional warning. There are some arguments which are overridden unconditionally in the sub-makes. Hopefully none of the arguments mentioned above falls in this category, but it is something to look out for if you are having trouble. _________________________________________________________________ Installing Pine and Pico on UNIX Platforms Installing _Pine_ and _Pico_ is remarkably simple. You take the program files which you have just transferred or built and you move them to the correct directory on your system. Most often the binaries go in /usr/local/bin though sometimes they are placed in /usr/bin. All the help text is compiled into _Pine_ so there are no _required_ auxiliary files. There are, however, three optional auxiliary files: /usr/local/lib/pine.info, /usr/local/lib/pine.conf, and /usr/local/lib/pine.conf.fixed. The file pine.info contains text on how to get further help on the local system. It is part of the help text for the main menu and should probably refer to the local help desk or the system administrator. If this file doesn't exist a generic version which suggests ``talking to the computer support staff at your site'' is shown. The file pine.conf is used to set system-wide default configurations for _Pine_. The file pine.conf.fixed is also used to set system-wide default configurations for _Pine_. The difference between these two files is that configuration variables set in the pine.conf.fixed file may not normally be over-ridden by a user. See the section on Pine Configuration later in this document for details about the pine.conf and pine.conf.fixed files. _________________________________________________________________ Installing PC-Pine The PC-Pine distribution comes as a .zip file. To install, unzip the files to a directory where you would like the program to reside. Modern Windows versions come with the capability of unzipping .zip files. Failing that, you can use one of the many .zip file extractors out there, or the pkunzip.exe program that resides on our FTP server. Following current Windows conventions, a common directory into which the files could be extracted would be C:\Program Files\PC-Pine\. Having extracted PC-Pine's .zip file to the directory of choice, you can now run that directory's pine.exe, which is the actual PC-Pine program. For convenience, you could place shortcuts to it on the task bar, start menu, etc. Upon first running PC-Pine, you may be asked where you would like to access your Configuration file (called the _pinerc_). This is useful in accessing already existing configuration files, and it does not matter where this file gets created. If you are connecting to an IMAP server to access your email, it is also possible to store this Configuration data on that server, which facilitates accessing the same configuration from multiple machines (in fact, your configuration may have already been set up this way for use with other pine programs). After having established the location of the configuration file, it may be necessary to specify a few configuration settings before reading or sending mail. You may be prompted for the following (which may also be edited from the (S)etup (C)onfig screen from the Main Menu): Folder to open as inbox (or _inbox-path_) - This can be an inbox residing on an IMAP or POP3 server, or one residing locally. An example of an INBOX for an IMAP server is: {server.example.com}INBOX. User-id, Personal name, and host/domain, which are to be used as your email address. SMTP server to forward message - You must enter your SMTP server before you can send any messages. At this point, you will be able to read and send email messages. There are, however, many more preferences that you can set in the Configuration screen. _________________________________________________________________ Installing IMAPd When the _Pine_ distribution is built on a UNIX system, the IMAP server binary, imapd, is compiled. Installing imapd requires placing the binary in the appropriate directory, usually /usr/etc, and adding entries to /etc/services and /etc/inetd.conf or their counterparts. The following line is appropriate for /etc/services: imap 143/tcp # Mail transfer and the next line is appropriate for /etc/inetd.conf: imap stream tcp nowait root /usr/etc/imapd imapd The /etc/inetd.conf file entry may vary on different versions of UNIX. Some have a slightly different set of fields. Also the pathname in /etc/inetd.conf must match the path where imapd is installed. With this configuration, the IMAP server runs without pre-authentication. Each new IMAP connection requires a correct username and password. IMAP can also be run with pre-authentication based on the standard _rsh_ mechanism. To enable this, the user account on the IMAP server must contain a valid file which grants access to the client machine. Enabling _rimap_ authentication is done by creating a link called /etc/rimapd to imapd. Basically, what is happening is that _Pine_ is taking advantage of the ability that rsh has to use privileged TCP ports so it doesn't have to run in privileged mode. If the rimap authentication fails it will drop back to plain password authentication. _PC-Pine_ cannot take advantage of _rimap_ authentication. Also, if your system uses a distributed configuration database, like NIS, Yellow Pages or Netinfo, be sure that appropriate steps are taken to ensure the above mentioned information is updated. _________________________________________________________________ Support Files and Environment Variables: UNIX Pine This section lists the various files which _Pine_ uses which are not email folders. All of these are the default names of files, they may vary based on _Pine_'s configuration. /usr/local/lib/pine.conf Pine's global configuration file. /usr/local/lib/pine.conf.fixed Non-overridable global configuration file. /usr/local/lib/pine.info Local pointer to system administrator. ~/.pinerc Personal configuration file for each user. ~/.pinercex Personal exceptions configuration file for each user. ~/.addressbook Personal addressbook ~/.addressbook.lu Personal address book lookup file (index file to speed up lookups). ~/.newsrc Personal USENET subscription list. This is shared with other newsreading programs. ~/.pine-debugX The files created for debugging _Pine_ problems. By default, there are 4 .pine-debug files kept at any time. ~/.signature A signature file which will be included in all outgoing email messages. ~/.pine-interrupted-mail The text of a message which was interrupted by some unexpected error which _Pine_ detected. ~/mail/postponed-msgs A folder of messages which the user chose to postpone. /etc/mailcap System-wide mail capabilities file. Only used if $MAILCAPS not set. ~/.mailcap Personal mail capabilities file. Combines with system-wide mailcap. Only used if $MAILCAPS not set. The location of the following support files may be controlled by variables in the personal or global _Pine_ configuration file: signature, addressbook and its index file, postponed messages, and newsrc. Unix _Pine_ uses the following environment variables: TERM Tells _Pine_ what kind of terminal is being used. DISPLAY Determines if _Pine_ will try to display IMAGE attachments. TMPDIR, TMP, or TEMP Specifies location of temporary storage area, first one set wins SHELL If not set, default is /bin/sh MAILCAPS A semicolon delimited list of path names to mailcap files. _________________________________________________________________ Support Files, Environment Variables, and Registry Settings: PC-Pine This section lists the various files which _PC-Pine_ uses which are not normal mail folders. All of these are the default names of files, they may vary based on _Pine_'s configuration. \PINE.HLP File containing _Pine_'s internal help text. \PINE.NDX Index of _Pine_'s help text used by _PC-Pine_ to locate entries. $PINERC or or $HOME\PINE\PINERC or \PINERC Path to (required) personal configuration file. $PINERCEX or $HOME\PINE\PINERCEX or \PINERCEX Path to personal exceptions configuration file. $PINECONF Path of optional global configuration file. \ADDRBOOK Personal addressbook \ADDRBOOK.LU Personal address book lookup file (index file to speed up lookups). \PINE.SIG A signature file which will be included in all outgoing email messages. \PINE.PWD A file containing encrypted password for remote mail server. \PINEDEBG.TXT Location of _Pine_ debug file. \MAILCAP and/or \MAILCAP These paths are only used if $MAILCAPS not set. $HOME\NEWSRC or \NEWSRC Personal USENET subscription list. This may be shared with other newsreading programs. $HOME\MAIL\INTRUPTD The text of a message which was interrupted by some unexpected error which _Pine_ detected. $HOME\MAIL\POSTPOND A folder of messages which the user chose to postpone. Registry Values: HKEY_LOCAL_MACHINE\Software\University of Washington\PC-Pine\4.0 _Pinedir_: The directory that contains the _Pine_ executable. _PineEXE_: The name of the _Pine_ executable (most commonly "pine.exe"). HKEY_CURRENT_USER\Software\University of Washington\PC-Pine\4.0 _PineRC_: The path that points to the default pinerc to use. HKEY_LOCAL_MACHINE\Software\Clients\Mail\PC-Pine _DLLPath_: The path that points to _Pine_'s pmapi32.dll. HKLM\Software\Clients\Mail\PC-Pine\shell\open\command _(Default)_: When set as the default mailer, this is the command that is run by external programs. HKLM\Software\Clients\Mail\PC-Pine\Protocols\Mailto\DefaultIcon _(Default)_: This points to the icon to display in relation to _Pine_'s mailto URL rendering. HKLM\Software\Clients\Mail\PC-Pine\Protocols\Mailto\shell\open\command _(Default)_: This value is the command that gets run by external programs when a mailto URL is run with _PC-Pine_ set as the default mailer. HKLM\Software\Clients\News\PC-Pine\shell\open\command _(Default)_: When set as the default newsreader, this is the command that is run by external programs. HKLM\Software\Clients\News\PC-Pine\Protocols\news\DefaultIcon _(Default)_: This points to the icon to display in relation to _Pine_'s news URL rendering. HKLM\Software\Clients\News\PC-Pine\Protocols\news\shell\open\command _(Default)_: This value is the command that gets run by external programs when a news URL is run with _PC-Pine_ set as the default newsreader. HKLM\Software\Clients\News\PC-Pine\Protocols\nntp\DefaultIcon _(Default)_: This points to the icon to display in relation to _Pine_'s nntp URL rendering. HKLM\Software\Clients\News\PC-Pine\Protocols\nntp\shell\open\command _(Default)_: This value is the command that gets run by external programs when a nntp URL is run with _PC-Pine_ set as the default newsreader. _PC-Pine_'s help text and help text index file are expected to reside in the same directory as the PINE.EXE executable, as they are essentially extensions of the executable. The personal configuration file may be in the same directory as the executable, or if that is inconvenient because the executable is on a shared or read-only drive, then it can be in a file named by the $PINERC environment variable, or in $HOME\PINE\PINERC, where if not set, $HOME defaults to the root of the current working drive. Most of the other support files key off of the location of the PINERC file. However, in the case of the NEWSRC file, the path $HOME\NEWSRC is checked first. Also, the postponed messages and interrupted message folders are placed in the default folder collection, normally in the directory $HOME\MAIL. The location of the following support files may be controlled by variables in the personal or global _Pine_ configuration file: signature, addressbook (and its index file), postponed messages, and newsrc. _PC-Pine_ uses the following environment variables: PINERC Overrides default path to pinerc file. PINERCEX Overrides default path to personal exceptions configuration file. PINECONF Optional path to global _Pine_ config file. HOME If not set, _Pine_ uses the root of the current drive, e.g. C: TMPDIR, TMP, or TEMP Specifies location of temporary storage area, first one set wins COMSPEC Specifies shell for external commands. MAILCAPS A semicolon delimited list of path names to mailcap files. Command Line Arguments Pine _Pine_ and _PC-Pine_ can accept quite a few command-line arguments. Many of these arguments overlap with variables in the _Pine_ configuration file. If there is a difference, then a flag set in the command line takes precedence. Both _Pine_ and _PC-Pine_ expect command line arguments (other than addresses) to be preceded by the "-" (dash) as normally used by UNIX programs. _[addresses]_ Send-to: If you give _Pine_ an argument or arguments which do not begin with a dash, _Pine_ treats them as email addresses. _Pine_ will startup in the composer with a message started to the addresses specified. Once the message is sent, the _Pine_ session closes. Standard input redirection is allowed. Separate multiple addresses with a space between them. Addresses are placed in the "To" field only. < _file_ _Pine_ will startup in the composer with _file_ read into the body of the message. Once the message is sent, the _Pine_ session closes. -attach _file_ Go directly into composer with given file attached. -attachlist _file-list_ Go directly into composer with given files attached. This must be the last option on the command line. -attach_and_delete _file_ Go directly into composer with given file attached, delete when finished. -aux _local_directory_ _PC-Pine_ only. This tells _PC-Pine_ the local directory to use for storing auxiliary files, like debug files, address books, and signature files. The pinerc may be local or remote. -nosplash _PC-Pine_ only. This tells _PC-Pine_ to not display the splash screen upon startup. This may be helpful for certain troubleshooting or terminal server scenarios. -bail If the personal configuration file doesn't already exist, exit. This might be useful if the configuration file is accessed using some remote filesystem protocol. If the remote mount is missing this will cause _Pine_ to quit instead of creating a new pinerc. -c _n_ When used with the -f option, apply the _n_th context. This is used when there are multiple folder collections (contexts) and you want to open a folder not in the primary collection. -conf Configuration: Prints a sample system configuration file to the screen or standard output. To generate an initial system configuration file, execute pine -conf > /usr/local/lib/pine.conf To generate a system configuration file using settings from an old system configuration file, execute pine -P old-pine.conf -conf > /usr/local/lib/pine.conf A system configuration file is not required. -convert_sigs _-p pinerc_ Convert signatures contained in signature files into literal signatures. -copy_abook _ _ Copy an address book file to a remote address book folder. If the remote folder doesn't exist, it will be created. If it exists but the first message in the folder isn't a remote address book header message, the copy will be aborted. This flag will not usually be used by a user. Instead, the user will create a remote address book from within _Pine_ and copy entries from the local address book by using aggregate Save in the address book screen. -copy_pinerc _ _ Copy a pinerc configuration file to a remote pinerc folder. If the remote folder doesn't exist, it will be created. If it exists but the first message in the folder isn't a remote pinerc header message, the copy will be aborted. This flag may be useful to users who already have a local pinerc file and would like to convert it to a remote pinerc folder and use that instead. This gives a way to bootstrap that conversion without having to manually reset all of the variables in the remote pinerc folder. -create_lu _addrbook sort-order_ Create auxiliary LookUp (index) file for _addrbook_ and sort _addrbook_ in _sort-order_, which may be _dont-sort_, _nickname_, _fullname_, _nickname-with-lists-last_, or _fullname-with-lists-last_. Only useful when creating global or shared address books. The settings of the features disable-setlocale-collate and enable-setlocale-ctype have no effect when using the create_lu command. See Address Book Lookup File for more information, especially the warning about copying the address book after creating the lookup file. -d _debug-level_ Debug Level: Sets the level of debugging information written by _Pine_. _Debug-level_ can be set to any integer 0-9. A debug level of 0 turns off debugging for the session. (Actually there are some levels higher than 9, but you probably don't want to see them. Sensitive authentication information is hidden at levels less than 10.) -d _keywords_ You may use a more detailed version of the debugging flag to set the debug level in separate parts of _Pine_. The possibilities are flush, timestamp, imap=0..4, tcp, numfiles=0..31, and verbose=0..9. _Flush_ causes debugging information to be flushed immediately to the debug file as it is written. _Verbose_ is the general debugging verbosity level. _Timestamp_ causes timestamps to be added to the debug file, which is useful when you are trying to figure out what is responsible for delays. _Numfiles_ sets the number of debug files saved. _Imap_ sets the debug level for the debugging statements related to the conversation with the IMAP server, and more generally, for the debugging related to _Pine_'s interaction with the C-Client library. If _imap_ is set higher than 4, sensitive authentication information will be included in the debug file. _Tcp_ adds more TCP/IP debugging information. -f _folder_ Startup folder: _Pine_ will open this folder in place of the standard INBOX. -F _file_ Open named text file for viewing and forwarding. -h Help: Prints the list of available command-line arguments to the screen. -i _Pine_ will start up in the FOLDER INDEX screen instead of the MAIN MENU. Configuration equivalent: _initial-keystroke-list=i_. -I _a,b,c,..._ Initial Keystrokes: _Pine_ will execute this comma-separated sequence of commands upon startup. This allows users to get _Pine_ to start in any of its menus/screens. You cannot include any input to the composer in the initial keystrokes. The key is represented by a ``CR'' in the keystroke list; the spacebar is designated by the letters ``SPACE''. Control keys are two character sequences beginning with ``^'', such as ``^I''. A tab character is ``TAB''. Function keys are ``F1'' - ``F12'' and the arrow keys are ``UP'', ``DOWN'', ``LEFT'', and ``RIGHT''. A restriction is that you can't mix function keys and character keys in this list even though you can, in some cases, mix them when running _Pine_. A user can always use only _character_ keys in the startup list even if he or she is using _function_ keys normally, or vice versa. If an element in this list is a string of characters surrounded by double quotes (") then it will be expanded into the individual characters in the string, excluding the double quotes. Configuration equivalent: _initial-keystroke-list_ -install For _PC-Pine_ only, this option prompts for some basic setup information, then exits. -k Function-Key Mode: When invoked in this way, _Pine_ expects the input of commands to be function-keys. Otherwise, commands are linked to the regular character keys. Configuration equivalent: _use-function-keys_ included in _feature-list_. -n _n_ Message-Number: When specified, _Pine_ starts up in the FOLDER INDEX screen with the current message being the specified message number. -nowrite_passfile This tells _Pine_ to use the passfile if there is one, but to never offer writing new passwords to the passfile. -o _folder_ Opens the INBOX (or a folder specified via the -f argument) ReadOnly. -p _pinerc_ Uses the named file as the personal configuration file instead of _~/.pinerc_ or the default PINERC search sequence _PC-Pine_ uses. Pinerc may be either a local file or a remote configuration folder. -P _pinerc_ Uses the named file as the system wide configuration file instead of _/usr/local/lib/pine.conf_ on UNIX, or nothing on _PC-Pine_. Pinerc may be either a local file or a remote configuration folder. -passfile _passfile_ This tells _Pine_ what file should be used as the password file. This should be a fully-qualified filename. -pinerc _file_ Output fresh pinerc configuration to _file_, preserving the settings of variables that the user has made. Use _file_ set to ``-'' to make output go to standard out. -r Restricted Mode: For UNIX _Pine_ only. _Pine_ in restricted mode can only send email to itself. Save and export are limited. -registry _cmd_ For _PC-Pine_ only, this option affects the values of _Pine_'s registry entries. Possible values for _cmd_ are set, noset, clear, clearsilent, and dump. _Set_ will always reset _Pine_'s registry entries according to its current settings. _NoSet_ will never set any values in the registry, but it will still use the values already set in the registry. _Clear_ will clear the registry values. _Clearsilent_ will silently clear the registry values. _Dump_ will display the values of current registry settings. Note that the dump command is currently disabled. Without the -registry option, _PC-Pine_ will write values into the registry only if there currently aren't any values set. -sort _key_ Sort-Key: Specifies the order messages will be displayed in for the FOLDER INDEX screen. _Key_ can have the following values: arrival, date, subject, orderedsubj, thread, from, size, score, to, cc, arrival/reverse, date/reverse, subject/reverse, orderedsubj/reverse, thread/reverse, from/reverse, size/reverse, score/reverse, to/reverse, and cc/reverse. The default value is "arrival". The _key_ value reverse is equivalent to arrival/reverse. Configuration equivalent: _sort-key_. -supported Some options may or may not be supported depending on how _Pine_ was compiled. This is a way to determine which options are supported in the particular copy of _Pine_ you are using. -url _url_ Open the given URL. -v Version: Print version information to the screen. -version Version: Print version information to the screen. -x _exceptions_config_ Configuration settings in the exceptions config override your normal default settings. _Exceptions_config_ may be either a local file or a remote pinerc folder. -z Enable Suspend: When run with this flag, the key sequence ctrl-z will suspend the _Pine_ session. Configuration equivalent: _enable-suspend_ included in _feature-list_. -_option_=_value_ Assign _value_ to the config option _option_. For example, _-signature-file=sig1_ or _-feature-list=signature-at-bottom_. (Note: feature-list values are additive and features may be preceded with no- to turn them off). Pico The following command line options are supported in _Pico_: +_n_ Causes _Pico_ to be started with the cursor located _n_ lines into the file. (Note: no space between "+" sign and number) -a Display all files and directories, including those beginning with a period (.). -b Enable the option to Replace text matches found using the "Where is" command. -d Rebind the "delete" key so the character the cursor is on is rubbed out rather than the character to its left. -e Enable file name completion. -f Use function keys for commands. _This option supported only in conjunction with UW Enhanced NCSA telnet._ -g Enable "Show Cursor" mode in file browser. Cause cursor to be positioned before the current selection rather than placed at the lower left of the display. -k Causes "Cut Text" command to remove characters from the cursor position to the end of the line rather than remove the entire line. -m Enable mouse functionality. This only works when _Pico_ is run from within an X Window System "xterm" window. -n_n_ The -n_n_ option enables new mail notification. The _n_ argument is optional, and specifies how often, in seconds, your mailbox is checked for new mail. For example, -n60 causes _Pico_ to check for new mail once every minute. The default interval is 180 seconds, while the minimum allowed is 30. (Note: no space between "n" and the number) -o _dir_ Sets operating directory. Only files within this directory are accessible. Likewise, the file browser is limited to the specified directory subtree. -p Preserve the "start" and "stop" characters, typically Ctrl-Q and Ctrl-S, which are sometimes used in communications paths to control data flow between devices that operate at different speeds. -q TermdefWins. Termcap or terminfo escape sequences are used in preference to default escape sequences. -Q _quotestr_ Set the quote string. Especially useful when composing email, setting this allows the quote string to be checked for when Justifying paragraphs. A common quote string is "> ". -r_n_ Sets column used to limit the "Justify" command's right margin. -t Enable "tool" mode. Intended for when _Pico_ is used as the editor within other tools (e.g., Elm, Pnews). _Pico_ will not prompt for save on exit, and will not rename the buffer during the "Write Out" command. -v View the file only, disallowing any editing. -version Print version information. -w Disable word wrap (thus allow editing of long lines). _Note: Pico will break any lines over 255 characters when reading a file, regardless of word wrapping._ -x Disable keymenu at the bottom of the screen. -z Enable ^Z suspension of _Pico_. Pilot The following command line options are supported in _Pilot_: -a Display all files including those beginning with a period (.). -f Use function keys for commands. _This option supported only in conjunction with UW Enhanced NCSA telnet._ -g Enable "Show Cursor" mode. Cause cursor to be positioned before the current selection rather than placed at the lower left of the display. -m Enable mouse functionality. This only works when _Pilot_ is run from within an X Window System "xterm" window. -n_n_ The -n_n_ option enables new mail notification. The _n_ argument is optional, and specifies how often, in seconds, your mailbox is checked for new mail. For example, -n60 causes _Pilot_ to check for new mail once every minute. The default interval is 180 seconds, while the minimum allowed is 30. (Note: no space between "n" and the number) -o _dir_ Sets operating directory. Only files within the specified directory are accessible and browsing is limited to the specified directory subtree. -v Enable single vertical column display. -x Disable keymenu at the bottom of the screen. -z Enable ^Z suspension of _Pilot_. Configuration and Preferences Pine Configuration There is very little in _Pine_ which _requires_ compile-time configuration. In most cases, the compiled-in preferences will suit users and administrators just fine. When running _Pine_ on a UNIX system, the default built-in configuration can be changed by setting variables in the system configuration files, /usr/local/lib/pine.conf or /usr/local/lib/pine.conf.fixed. (Actually, these files are whatever the definitions for SYSTEM_PINERC and SYSTEM_PINERC_FIXED in pine/osdep/os-xxx.h are set to.) The location of the pine.conf file can be changed with the -P command line argument. Both _Pine_ and _PC-Pine_ also use personal (user-based) configuration files. On UNIX machines, the personal configuration file is the file ~/.pinerc. For _PC-Pine_ systems, the personal configuration file is in $PINERC or or ${HOME}\PINE\PINERC or \PINERC. Or the personal configuration file can be specified with the -p command line argument. After the personal configuration, _Pine_ may optionally use a personal exceptions configuration file which is specified with the command line option "-x exceptions_config". "Exceptions_config" may be either a local file or a remote configuration folder. For Unix _Pine_, if you don't have a "-x" command line option, _Pine_ will look for the file ".pinercex" in the same local directory that the regular config file is located in. If the regular config file is remote then Unix _Pine_ looks in the home directory for ".pinercex". For _PC-Pine_, if you don't have a "-x" command line option, _PC-Pine_ will use the value of the environment variable $PINERCEX. If that is not set, _PC-Pine_ will look for the local file "PINERCEX" in the same local directory that the regular config file is located in. If the regular config file is remote then _PC-Pine_ looks in the local directory specfied by the "-aux local_directory" command line argument, or the directory ${HOME}\PINE, or in . The syntax of a non-list configuration variable is this: = If the value is absent then the variable is unset. To set a variable to the empty value the syntax is "". This is equivalent to an absent value except that it overrides any system-wide value that may be set. Quotes may be used around any value. All values are strings and end at the end of the line or the closing quote. Leading and trailing space is ignored unless it is included in the quotes. There is one variable, _use-only-domain-name_, for which the only appropriate values are _yes_ and _no_. That's because it is a variable from the early days of _Pine_ before features existed. There is also a second type of variable, lists. A list is a comma-separated list of values. The syntax for a list is: = [, , ... ] A list can be continued on subsequent lines by beginning the line with white-space. Both the per-user and global configuration files may contain comments which are lines beginning with a #. For UNIX _Pine_, there are five ways in which each variable can be set. In decreasing order of precedence they are: 1. the system-wide _fixed_ configuration file 2. a command line argument 3. the personal exceptions file 4. the personal configuration file 5. the system-wide configuration file. If the variable is not set in any of those places, there is a default setting in the source code. So, system-wide fixed settings always take precedence over command line flags, which take precedence over per-user exception settings, which take precedence over per-user settings, which take precedence over system-wide configuration settings. _PC-Pine_ has the same list, except that it does not use a system-wide _fixed_ configuration file. This can be modified slightly by using inheritance, which is covered below. You may get a sample/fresh copy of the system configuration file by running _Pine -conf._ The result will be printed on the standard output with short comments describing each variable. (The online help in the Setup screens provides longer comments.) If you need to fix some of the configuration variables, you would use the same template for the fixed configuration file as for the regular system-wide configuration file. (If it isn't clear, the purpose of the fixed configuration file is to allow system administrators to restrict the configurability of _Pine_. It is by no means a bullet-proof method.) _Pine_ will automatically create the personal configuration file the first time it is run, so there is no need to generate a sample. _Pine_ reads and writes the personal configuration file occasionally during normal operation. Users will not normally look at their personal configuration file, but will use the Setup screens from within _Pine_ to set the values in this file. If a user does add additional comments to the personal configuration file they will be retained. References to environment variables may be included in the _Pine_ configuration files. The format is $variable or ${variable}. The character ~ will be expanded to the $HOME environment variable. For a more complete explanation of how environment variables work, see the section Using Environment Variables. When environment variables are used for _Pine_ settings which take lists, you must have an environment variable set for each member of the list. That is, _Pine_ won't properly recognize an environment variable which is set equal to a comma-delimited list. It is OK to reference unset environment variables in the _Pine_ configuration file, which will expand to nothing. Remote and Local Configuration Beginning with _Pine_ 4.30 there are two types of storage for configuration information. _Local_ configuration files are used by default. These are just regular files on the UNIX system or on the PC. This is the only kind of configuration storage _Pine_ used prior to 4.30. _Remote_ configuration folders are stored on an IMAP server. The advantage of using a remote configuration is that the same information may be accessed from multiple platforms. For example, if you use one computer at work and another at home, the same configuration could be used from both places. A configuration change from one place would be seen in both places. Technical information about remote configuration is in Remote Configuration. Generic and Exceptional Configuration If you use _Pine_ from more than one platform it may be convenient to split your configuration information into two pieces, a generic piece and exceptions which apply to a particular platform. For example, suppose you use _Pine_ from home and from work. Most of your configuration settings are probably the same in both locations, so those settings belong in the generic settings configuration. However, you may use a different SMTP server and INBOX from home than you do from work. The "smtp-server" and "inbox-path" variables could be part of your exceptional configuration so that they could be different in the two places. Beginning with _Pine_ 4.30 you can use the command line option "-x config" to split your configuration into generic and exceptional pieces. Config may be either local or remote. For most people, splitting the configuration information into two pieces is only going to be useful if the generic information is accessed remotely. If you already have a local pinerc file with settings you like you may find that the command Setup/RemoteConfigSetup will be useful in helping you convert to a remote configuration. The command line flag copy_pinerc may also be useful. Configuration Inheritance Configuration inheritance is a power user feature. It is confusing and not completely supported by the configuration user interface. For configuration variables which are lists, like "smtp-server" or "incoming-folders", the inheritance mechanism makes it possible to _combine_ the values of options from different configuration locations instead of _replacing_ the value. Configuration Inheritance has more information about how inheritance is used. _________________________________________________________________ General Configuration Variables The following is a list of all _Pine_ configuration variables, in alphabetical order. Note that not all variables apply to all versions of _Pine_ and that some variables are only applicable in a system configuration file and some are only applicable in a personal configuration file. These are configuration _variables_. Configuration Features are in a separate section. _addrbook-sort-rule_ This variable sets up the default address book sorting. Currently, _Pine_ will accept the values _dont-sort_, _fullname-with-lists-last_, _fullname_, _nickname-with-lists-last_, and _nickname_. The default is to sort by fullname with lists last. _address-book_ A list of personal address books. Each entry in the list is an optional nickname followed by a pathname or file name relative to the home directory. The nickname is separated from the rest of the line with whitespace. Instead of a local pathname or file name, a remote folder name can be given. This causes the address book to be a Remote address book. Remote folder syntax is discussed in Syntax for Remote Folders. This list of address books will be combined with the global-address-book list to arrive at the complete set of address books. _addressbook-formats_ This option specifies the format that address books are displayed in. By default, address books are displayed with the nicknames in the first column, the fullnames in the second column, and addresses in the third column. The system figures out reasonable defaults for the widths of the columns. An address book may be given a different format by listing special tokens in the order you want them to display. The possible tokens are NICKNAME, FULLNAME, ADDRESS, FCC, and COMMENT. More details are included in the online help for this variable. _alt-addresses_ This option provides a place for you to list alternate email addresses you may have. If set, the option affects the behavior of the _Reply_ command and the _+_ symbol in the "Folder Index", which denotes that a message has been addressed specifically to you. In the default INDEX display the personal name (or email address) of the person listed in the message's "From:" header field is usually displayed except when that address is yours or one of your alternate addresses. In that case you will usually see the name of the first person specified in the message's "To:" header field with the prefix "To: " prepended. With respect to _Reply_, the _Reply to All_ option will exclude addresses listed here. _bugs-additional-data_ System-wide configuration files only. Program/Script used by _Report Bug_ command. Output from the program/script is captured and attached to the bug report. _bugs-fullname_, _bugs-address_, _local-fullname_, _local-address_, _suggest-fullname_, and _suggest-address_ System-wide configuration files only. These are used by the bug report commands which can be accessed from some of the Help screens. _character-set_ This sets the character set used by the terminal. Currently appropriate values are _US-ASCII_, _ISO-8859-1_ through _ISO-8859-9_ and _ISO-2022-JP_. See the section on International Character Sets for more details. The default is _US-ASCII_. _color-style_ UNIX _Pine_ only (color is automatically on with _PC-Pine_). If the terminal or terminal emulator you are using is capable of displaying colors, this variable controls whether or not color will be used in _Pine_. If you turn color on and things are set up correctly, you should see color appear on the screen immmediately. Modern terminal emulators are usually capable of displaying colors. This variable may be set to any of the following values: no-color Don't use color. use-termdef In order to decide if your terminal is capable of color, _Pine_ looks in the terminal capabilities database, TERMINFO or TERMCAP, depending on how _Pine_ was compiled. This is a good option to choose if you switch between a color and a non-color terminal with the same _Pine_ configuration. _Pine_ will know to use color on the color terminal because it is described in the termcap entry, and _Pine_ will know to use black and white on the non-color terminal. Color Details has more information about configuring a termcap entry for color. This is usually something a system administrator does. force-ansi-8color Because setting up a termcap entry is confusing and because the terminal capabilities database is often not correctly configured for color, this choice and the next may be easier for you to use. If your terminal emulator responds to ANSI color escape sequences, which many do, this option will cause _Pine_ to believe your terminal will respond to the escape sequences which produce eight different foreground and background colors. The escape sequences used to set the foreground colors are ESC [ 3 m where the color_number is an ASCII digit between 0 and 7. The numbers 0 through 7 should correspond to the colors black, red, green, yellow, blue, magenta, cyan, and white. Some terminal emulators use a pre-ANSI scheme which swaps the colors blue and red and the colors yellow and cyan. This will cause the default colors to be different, but other than that things should work fine. The escape sequences used to set the background colors are the same as for the foreground colors except a "4" replaces the "3". Note: With the Tera Term terminal emulator this setting works well. You should also have the Tera Term "Full color" option turned OFF. You may find the "Full color" option in Tera Term's "Setup" menu, in the "Window" submenu. force-ansi-16color Many terminal emulators know about the same eight colors above plus eight more. This option attempts to use all 16 colors. The same escape sequences as for the eight-color terminal are used for the first eight colors. The escape sequences used to set foreground colors 8-15 are the same as for 0-7 except the "3" is replaced with a "9". The background color sequences for colors 8-15 are the same as for 0-7 except the "4" is replaced with "10". You can tell if the 16 colors are working by turning on this option and then going into one of the color configuration screens, for example, the configuration screen for Normal Color. If you see 16 different colors to select from, it's working. The normal default is "no-color". Once you've turned on color you may set the colors of many objects on the screen individually. The Color Configuration section has more information, or you may just try it by running the "Setup" command and typing "K" for Kolor to enter the color configuration screen (Kolor instead of Color because C means Config). Most categories of color which _Pine_ supports are configurable there. Index line color is configured separately. Beginning with _Pine_ 4.41, the default names of some colors were changed in order to have better interoperability between _PC-Pine_ and Unix _Pine_ with both eight and 16-color terminals. Both _PC-Pine_ and 8-color Unix _Pine_ will interpret the colors named color008, color009, ..., color015 as black, red, ..., white. When changing a configuration color they will put the colors black, color009, color010, ..., color015 into the config file. That is, the colors red, green, ..., white will only appear in the config file if put there manually or if they were already there from an older version of _Pine_. The reason for this is because with 16-color xterm the colors red, green, ..., white are actually two-thirds intensity colors, and the colors color009, color010, ..., color015 (in pine terminology) are full intensity colors which better match the default eight of _PC-Pine_ or 8-color Unix terminal emulators. The idea is that you can use the eight colors of an 8-color terminal on a 16-color terminal and with _PC-Pine_. Those eight colors will be about the same in all three situations. In pre-4.41 _PC-Pine_ the three default grays offered were called color008, color009, and color010. Since this conflicts with three of the colors on 16-color terminals these three colors have been renamed colorlgr, colormgr, and colordgr. _PC-Pine_ will attempt to automatically change those color names the first time you run a version higher than 4.40. If that fails for some reason, you will see your old light grays displayed as black, your old medium grays displayed as red, and your old dark grays displayed as green. You may fix these from within the _PC-Pine_ color config screens. If you then go back to running a pre-4.41 version of _PC-Pine_ the colors with the new names (colorlgr...) will show up as Normally colored text. _composer-wrap-column_ This option specifies an aspect of _Pine_'s Composer. This gives the maximum width that auto-wrapped lines will have. It's also the maximum width of lines justified using the ^J Justify command. The normal default is _74_. The largest allowed setting is normally _80_ in order to prevent very long lines from being sent in outgoing mail. When the mail is actually sent, trailing spaces will be stripped off of each line. _current-indexline-style_ current-indexline-style. _customized-hdrs_ You may add your own custom headers to outgoing messages. Each header you specify here must include the header tag (Reply-To:, Approved:, etc.) and may optionally include a value for that header. If you want to see these custom headers each time you compose a message, you must add them to your default-composer-hdrs list, otherwise they become part of the rich header set which you only see when you press the rich header command. (If you are looking for a way to change which headers are _displayed_ when you view a message, take a look at the viewer-hdrs option instead.) Here's an example which shows how you might set your From address From: Full Name and another showing how you might set a Reply-To address Reply-To: user@example.com You may also set non-standard header values here. For example, you could add Organization: My Organization Name or even X-Favorite-Colors: Purple and Gold If you include a value after the colon then that header will be included in your outgoing messages unless you delete it before sending. If a header in the Customized-Headers list has only a tag but no value, then it will not be included in outgoing messages unless you edit a value in manually. For example, if Reply-To: is in the list, then the Reply-To header will be available for editing but won't be included unless a value is added while in the composer. It's actually a little more complicated than that. The values of headers that you set with the Customized-Headers option are defaults. If the message you are about to compose already has a value for a header, that value is used instead of a value from your Customized-Headers. For example, if you are Replying to a message the Subject field will already be filled in. In that case, if the Customized-Headers list contains a Subject line, the custom subject will _NOT_ be used. The subject derived from the subject of the message you are Replying to will be used instead. It is also possible to make header setting even more complicated and more automatic by using Roles, but if all you want to do is set a default value for a header, you don't need to think about Roles. If you change your From address you may also find it useful to add the changed From address to the alt-addresses configuration option. Because commas are used in the configuration file to separate the list of Customized-Hdrs, you need to quote the value if that value contains a comma. Use double quotes and place the quotes around the entire value part of the header, not including the name of the header. For example, you might have Organization: "My Organization Name, My City" as one of the Customized-Hdrs. _dead-letter-files_ This option affects _Pine_'s behavior when you cancel a message being composed. _Pine_'s usual behavior is to write the canceled message to a file named "dead.letter" in your home directory, or "DEADLETR" when using _PC-Pine_, overwriting any previous message. If you set this option to a value higher than one, then that many copies of dead letter files will be saved. For example, if you set this option to "3" then you may have files named "DEADLETR", "DEADLETR2", and "DEADLETR3"; or "dead.letter", "dead.letter2", and "dead.letter3". In this example, the most recently cancelled message will be in "dead.letter", and the third most recently cancelled message will be in "dead.letter3". The fourth most recently cancelled message will no longer be saved. If you set this option to zero, then NO record of canceled messages is maintained. If the feature Quell-Dead-Letter-On-Cancel is set, that overrides whatever you set for this option. If this option had existed at the time, then the Quell feature would not have been added, but it is still there for backwards compatibility. So, in order for this option to have the desired effect, make sure the Quell feature is turned off. _default-composer-hdrs_ You can control which headers you want visible when composing outgoing email using this option. You can specify any of the regular set, any Rich Header, or any Customized-Hdrs which you have already defined. If you use this setting at all, you must specify all the headers you want to see, you can't just add to the regular header set. The default set is To:, Cc:, Attchmnt:, and Subject:. Note that the "Newsgroups:" header will be abbreviated in the Composer display, but should be spelled out in full here. _default-fcc_ The name of the folder to which all outgoing mail goes is set here. The compiled-in default is _sent-mail_ (UNIX) or _sentmail_ (PC). It can be set to "" (two double quotes with nothing between them) to turn off saving copies of outgoing mail. If _default-fcc_ is a relative file name, then it is relative to your default collection for saves (see folder-collections). _default-saved-msg-folder_ This option determines the default folder name for _Saves_... If this is not a path name, it will be in the default collection for saves. Any valid folder specification, local or IMAP, is allowed. This default folder only applies when the saved-msg-name-rule doesn't override it. Unix _Pine_ default is normally _saved-messages_ in the default folder collection. _PC-Pine_ default is _SAVEMAIL_ (normally stored as _SAVEMAIL.MTX_). _disable-setlocale-collate_ This is a hard to understand feature that should only be used in rare cases. Normally, the C function call setlocale(LC_COLLATE, "") is used by _Pine_. If you want to try turning it off, setting this feature will turn it off. This part of the locale has to do with the sort order of characters in your locale. A related feature is enable-setlocale-ctype. _disable-these-drivers_ This variable is a list of mail drivers which will be disabled. The candidates for disabling are listed below. There may be more in the future if you compile _Pine_ with a newer version of the c-client library. + mbox + mbx + mh + mmdf + mtx + mx + news + phile + tenex + unix The _mbox_ driver enables the following behavior: if there is a file called mbox in your home directory, and if that file is either empty or in Unix mailbox format, then every time you open _INBOX_ the _mbox_ driver will automatically transfer mail from the system mail spool directory into the mbox file and delete it from the spool directory. If you disable the _mbox_ driver, this will not happen. It is not recommended to disable the driver which supports the system default mailbox format. On most non-SCO systems, that driver is the _unix_ driver. On most SCO systems, it is the _mmdf_ driver. The system default driver may be configured to something else on your system; check with your system manager for additional information. It is most likely not very useful for you to disable any of the drivers other than possibly _mbox_. You could disable some of the others if you know for certain that you don't need them but the performance gain in doing so is very modest. _disable-these-authenticators_ This variable is a list of SASL (Simple Authentication and Security Layer) authenticators which will be disabled. SASL is a mechanism for authenticating to IMAP, POP3, SMTP, and other network servers. _Pine_ matches its list of supported authenticators with the server to determine the most secure authenticator that is supported by both. If no matching authenticators are found, _Pine_ will revert to plaintext login (or, in the case of SMTP, will be unable to authenticate at all). The candidates for disabling are listed below. There may be more if you compile _Pine_ with additional authenticators and/or a newer version of the c-client library. + GSSAPI + CRAM-MD5 + PLAIN + LOGIN Normally, you will not disable any authenticators. There are two exceptions: 1. You use a broken server that advertises an authenticator, but does not actually implement it. 2. You have a Kerberos-capable version of _Pine_ and the server is also Kerberos-capable, but you can not obtain Kerberos credentials on the server machine, thus you desire to disable GSSAPI (which in turn disables _Pine_'s Kerberos support). It is never necessary to disable authenticators, since _Pine_ will try other authenticators before giving up. However, disabling the relevant authenticator avoids annoying error messages. _display-filters_ This option defines a list of text-filtering commands (programs or scripts) that may be used to filter text portions of received messages prior to their use (e.g., presentation in the "Message Text" display screen). For security reasons, the full path name of the filter command must be specified. Display filters do not work with _PC-Pine_. The command is executed and the message is piped into its standard input. The standard output of the command is read back by _Pine_. The __TMPFILE__ token (see below) overrides this default behavior. The filter's use is based on the configured _trigger_ string. The format of a filter definition is: You can specify as many filters as you wish, separating them with a comma. Each filter can have only one trigger and command. Thus, two trigger strings which invoke the same command require separate filter specifications. The _trigger_ is simply text that, if found in the message, will invoke the associated command. If the trigger contains any space characters, it must be placed within quotes. Likewise, should you wish a filter to be invoked unconditionally, define the trigger as the null string, "" (two consecutive double-quote characters). If the trigger string is found anywhere in the text of the message the filter is invoked. Placing the trigger text within the tokens defined below changes where within the text the trigger must be before considering it a match. Trigger Modifying Tokens: __CHARSET(string)__ This token tells _Pine_ to invoke the supplied command if the text is in a character set matching string (e.g., ISO-8859-2 or ISO-2022-JP). __LEADING(string)__ This token tells _Pine_ to invoke the supplied command if the enclosed string is found to be the first non-whitespace text. NOTE: Quotes are necessary if string contains the space character. __BEGINNING(string)__ This token tells _Pine_ to invoke the supplied command if the enclosed string is found at the beginning of any line in the text. NOTE: Quotes are necessary if string contains the space character. The "command" and "arguments" portion is simply the command line to be invoked if the trigger string is found. Below are tokens that _Pine_ will recognize and replace with special values when the command is actually invoked. Command Modifying Tokens: __TMPFILE__ When the command is executed, this token is replaced with the path and name of the temporary file containing the text to be filtered. _Pine_ expects the filter to replace this data with the filter's result. NOTE: Use of this token implies that the text to be filtered is not piped into standard input of the executed command and its standard output is ignored. _Pine_ restores the tty modes before invoking the filter in case the filter interacts with the user via its own standard input and output. __RESULTFILE__ When the command is executed, this token is replaced with the path and name of a temporary file intended to contain a status message from the filter. _Pine_ displays this in the message status field. __DATAFILE__ When the command is executed, this token is replaced with the path and name of a temporary file that _Pine_ creates once per session and deletes upon exit. The file is intended to be used by the filter to store state information between instances of the filter. __PREPENDKEY__ When the command is executed, this token indicates that a random number will be passed down the input stream before the message text. This number could be used as a session key. It does not appear as a command-line argument. It is sent in this way to improve security. The number is unique to the current _Pine_ session and is only generated once per session. The feature disable-terminal-reset-for-display-filters is related. Performance caveat/considerations: Testing for the trigger and invoking the filter doesn't come for free. There is overhead associated with searching for the trigger string, testing for the filter's existence and actually piping the text through the filter. The impact can be reduced if the Trigger Modifying Tokens above are employed. Limitation: If Header Colors are being used, the sequences of bytes which indicate color changes will be contained in the text which is passed to the display-filter. If this causes problems you'll need to turn off Header Colors. The thirteen bytes which indicate a color change are the character \377 followed by \010 for a foreground color or \011 for a background color. Then comes eleven characters of RGB data which looks something like 255, 0,255, depending on the particular color, of course. _download-command_ This option affects the behavior of the _Export_ command. It specifies a Unix program name, and any necessary command line arguments, that _Pine_ can use to transfer the exported message to your personal computer's disk. _download-command-prefix_ This option is used in conjunction with the _download-command_ option. It defines text to be written to the terminal emulator (via standard output) immediately prior to starting the download command. This is useful for integrated serial line file transfer agents that permit command passing (e.g., Kermit's APC method). _editor_ UNIX _Pine_ only. Sets the name of the alternate editor for composing mail (message text only, not headers). It will be invoked with the "^_" command or it will be invoked automatically if the enable-alternate-editor-implicitly feature is set. _empty-header-message_ When sending, if all of the To, Cc, and Newsgroups fields are empty, _Pine_ will put a special address in the To line. The default value is "undisclosed-recipients: ;". The reason for this is to avoid embarrassment caused by some Internet mail transfer software that interprets a "missing" To: header as an error and replaces it with an Apparently-to: header that may contain the addresses you entered on the Bcc: line, defeating the purpose of the Bcc. You may change the part of this message that comes before the ": ;" by setting the _empty-header-message_ variable to something else. _fcc-name-rule_ Determines default folder name for fcc when composing. Currently, _Pine_ will accept the values _default-fcc_, _by-recipient_, or _last-fcc-used_. If set to _default-fcc_, then _Pine_ will use the value defined in the default-fcc variable (which itself has a default) for the Fcc header field. If set to _by-recipient_, then _Pine_ will use the name of the recipient as a folder name for the fcc. The relevant recipient is the first address in the To field. If set to "last-fcc-used", then _Pine_ will offer to Fcc to whatever folder you used previously. In all cases, the field can still be edited after it is initially assigned. If the fcc field in the address book is set for the first To address, that value over-rides any value derived from this rule. _feature-list_ This is a list of the many features (options) which may be turned on or off. There is a separate section titled Configuration Features which explains each of the features. There is some additional explanation about the _feature-list_ variable itself in Feature List Variable. _file-directory_ _PC-Pine_ only. This value affects the Composer's "^J Attach" command, the Attachment Index Screen's "S Save" command, and the Message Index's "E Export" command. Normally, when a filename is supplied that lacks a leading "path" component, _Pine_ assumes the file exists in the user's home directory. Under Windows operating systems, this definition isn't always clear. This feature allows you to explictly set where _Pine_ should look for files without a leading path. NOTE: this feature's value is ignored if either use-current-dir feature is set or the PINERC has a value for the operating-dir variable. _folder-collections_ This is a list of one or more collections where saved mail is stored. See the sections describing folder collections and collection syntax for more information. The first collection in this list is the default collection for _Save_s, including default-fcc's. _folder-extension_ _PC-Pine_ only. File extension used for local folder names. This is .MTX by default. _folder-reopen-rule_ _Pine_ normally checks for new mail in the currently open folder and in the INBOX every few minutes. There are some situations where automatic new-mail checking does not work. For example, if a mail folder is opened using the POP protocol or a newsgroup is being read using the NNTP protocol, then new-mail checking is disabled. It may be possible to check for new mail in these cases by reopening the folder. _Pine_ does not do this for you automatically, but you may do the commands manually to cause this to happen. You reopen by going back to the folder list screen from the message index screen with the "<" command, and then going back into the message index screen with the ">" command. (Actually, any method you would normally use to open a folder will work the same as the "<" followed by ">" method. For example, the GoTo Folder command will work, or you may use L to go to the Folder List screen and Carriage Return to reopen the folder.) There are some cases where _Pine_ knows that reopening the folder should be useful as a way to discover new mail. At the time of this writing, connections made using the POP protocol, news reading using the NNTP protocol, local news reading, and local ReadOnly folders which are in the traditional UNIX or the MMDF format all fall into this category. There are other cases where it _may_ be a way to discover new mail, but _Pine_ has no way of knowing, so it might also just be an exercise in futility. All remote, ReadOnly folders other than those listed just above fall into this category. The setting of this option together with the type of folder controls how _Pine_ will react to the apparent attempt to reopen a folder. If you don't reopen, then you will just be back in the message index with no change. You left the index and came back, but the folder remained "open" the whole time. However, if you do reopen the folder, the folder is closed and then reopened. In this case, the current state of the open folder is lost. The New status, Important and Answered flags, selected state, Zoom state, collapsed or expanded state of threads, current message number, and any other temporary state is all lost when the reopen happens. For POP folders (but not NNTP newsgroups) the Deleted flags are also lost. In the possibilities listed below, the text says "POP/NNTP" in several places. That really implies the case where _Pine_ knows it is a good way to discover new mail, which is more than just POP and NNTP, but POP and NNTP are the cases of most interest. This option probably has more possible values than it deserves. They are: Always reopen _Pine_ will not ask whether you want to reopen but will just do the reopen whenever you type a command that implies a reopen, regardless of the access method. In other words, it is assumed you would always answer Yes if asked about reopening. Yes for POP/NNTP, Ask about other remote [Yes] _Pine_ will assume a Yes answer if the access method is POP or NNTP, but will ask you whether to reopen other remote folders, with a default answer of Yes. Yes for POP/NNTP, Ask about other remote [No] _Pine_ will assume a Yes answer if the access method is POP or NNTP, but will ask you whether to reopen other remote folders, with a default answer of No. Yes for POP/NNTP, No for other remote _Pine_ will assume a Yes answer if the access method is POP or NNTP, and will assume a No answer for all other remote folders. Always ask [Yes] _Pine_ will not differentiate based on access method. It will always ask for all remote folders, with a default answer of Yes. Always ask [No] _Pine_ will not differentiate based on access method. It will always ask for all remote folders, with a default answer of No. Ask about POP/NNTP [Yes], No for other remote _Pine_ will ask if the access method is POP or NNTP, with a default answer of Yes. It will never attempt to reopen other remote folders. Ask about POP/NNTP [No], No for other remote This is the default. _Pine_ will ask if the access method is POP or NNTP, with a default answer of No. It will never attempt to reopen other remote folders. Never reopen _Pine_ will never attempt to reopen already open folders. Remember, wherever it says POP or NNTP above it really means POP or NNTP or any of the other situations where it is likely that reopening is a good way to discover new mail. There is an alternative that may be of useful in some situations. Instead of manually checking for new mail you can set up a Mail Drop and automatically check for new mail. _folder-sort-rule_ This option controls the order in which folder list entries will be presented in the FOLDER LIST screen. Choose one of the following: _Alphabetical_ sort by alphabetical name independent of type _Alpha-with-dirs-last_ sort by alphabetical name grouping directory entries to the end of the list _Alpha-with-dirs-first_ sort by alphabetical name grouping directory entries to the start of the list The normal default is _Alphabetical_. _font-name_ Winsock version of _PC-Pine_ only. _font-size_ Winsock version of _PC-Pine_ only. _font-style_ Winsock version of _PC-Pine_ only. _forced-abook-entry_ System-wide _Pine_ configuration files only. Force these address book entries into all writable personal address books. This is a list variable. Each item in the list has the form: Nickname | Fullname | Address with optional whitespace in all the obvious places. _form-letter-folder_ A Form Letter Folder is a mail folder that is intended to contain messages that you have composed and that are intended to be sent in their original form repeatedly. Setting this variable will alter _Pine_'s usual behavior when you execute the Compose command. Normally, _Pine_ offers a chance to continue a postponed or interrupted message should one or the other exist. When this variable is set to a folder name that exists, _Pine_ will also offer the chance to select a message from the folder to insert into the composer, much like when continuing a postponed message. The difference, however, is that _Pine_ will not automatically delete the selected message from the Form Letter Folder. Setting this variable will also affect _Pine_'s behavior when you Postpone a message from the composer. Normally, _Pine_ simply stashes the message away in your Postponed-Folder. Regardless of the specified folder's existence, _Pine_ will ask which folder you intend the message to be stored in. Choose the "F" option to store the message in your Form Letter Folder. This is the most common way to add a message to the folder. Another method of adding messages to the folder is via the _Pine_ composer's Fcc: field. If you are sending a message that you expect to send in the same form again, you can enter the Form Letter Folder's name in this field. _Pine_, as usual, will copy the message as it's sent. Note, when you later select this message from your Form Letter Folder, it will have the same recipients as the original message. To delete a message from the Form Letter Folder, you can either select the folder from a suitable FOLDER LIST screen, or use the Delete command in the MESSAGE INDEX offered when selecting from the folder as part of the Compose command. You can delete a Form Letter Folder just as any other folder from a suitable FOLDER LIST screen. You may find that the Roles facility introduced in _Pine_ 4.10 can be used to replace the Form Letter Folder. _global-address-book_ A list of shared address books. Each entry in the list is an optional nickname followed by a pathname or file name relative to the home directory. A SPACE character separates the nickname from the rest of the line. Instead of a local pathname or file name, a remote folder name can be given. This causes the address book to be a Remote address book. Remote folder syntax is discussed in Syntax for Remote Folders. This list will be added to the address-book list to arrive at the complete set of address books. Global address books are defined to be ReadOnly. _goto-default-rule_ This value affects _Pine_'s behavior when using the _Goto_ command. There are five possible values for this option: _folder-in-first-collection_ _Pine_ will offer the most recently visited folder in the default collection found in the "Collection List" screen as the default. _inbox-or-folder-in-first-collection_ If the current folder is _INBOX_, _Pine_ will offer the most recently visited folder in the default collection found in the "Collection List" screen. If the current folder is other than _INBOX_, _INBOX_ is offered as the default. _inbox-or-folder-in-recent-collection_ This is _Pine_'s default behavior. If the current folder is _INBOX_, _Pine_ will offer the last open folder as the default. If the current folder is other than _INBOX_, _INBOX_ is offered as the default. _first-collection-with-inbox-default_ Instead of offering the most recently visited folder in the default collection, the default collection is offered but with _INBOX_ as the default folder. If you type in a folder name it will be in the default collection. If you simply accept the default, however, your _INBOX_ will be opened. _most-recent-folder_ The last accepted value simply causes the most recently opened folder to be offered as the default regardless of the currently opened folder. NOTE: The default while a newsgroup is open remains the same; the last open newsgroup. _image-viewer_ This variable names the program to call for displaying parts of a MIME message that are of type IMAGE. If your system supports the _mailcap_ system, you don't need to set this variable. _inbox-path_ This specifies the name of the folder to use for the _INBOX_. By default this is unset and the system's default is used. The most common reason for setting this is to open an IMAP mailbox for the _INBOX_. For example, _{imap5.u.example.edu}inbox_ will open the user's standard _INBOX_ on the mail server, _imap5_. _incoming-archive-folders_ This is like read-message-folder, only more general. This is a list of folder pairs, with the first separated from the second in the pair by a space. The first folder in a pair is the folder you want to archive, and the second folder is the folder that read messages from the first should be moved to. Depending on how you define the auto-move-read-msgs feature, you may or may not be asked when you leave the first folder if you want read messages to be moved to the second folder. In either case, moving the messages means they will be deleted from the first folder. If these are not path names, they will be in the default collection for _Save_s. Any valid folder specification, local or remote (via IMAP), is allowed. There is no default. _incoming-folders_ This is a list of one or more folders other than _INBOX_ that may receive new messages. This list is slightly special in that it is always expanded in the folder lister. In the future, it may become more special. For example, it would be nice if _Pine_ would monitor the folders in this list for new mail. _incoming-startup-rule_ This rule affects _Pine_'s behavior when opening the _INBOX_ or another folder from the "INCOMING MESSAGE FOLDERS". This rule tells _Pine_ which message to make the current message when an incoming folder is opened. There are seven possible values for this option: _first-unseen_ The current message will be the first unseen message which has not been marked deleted, or the last message if all of the messages have been seen. This is the default setting. _first-recent_ This is similar to _first-unseen_. Instead of first unseen it is the first recent message. A message is considered to be recent if it arrived since the last time the folder was open (by any mail client, not just the current one). So this option causes the current message to be set to the first undeleted-recent message, or the last message if none is both undeleted and recent. _first-important_ This will result in the current message being set to the first message marked Important (but not Deleted). If no messages are marked Important, then it will be the last message. _first-important-or-unseen_ This selects the minimum of the first unseen and the first important messages. _first-important-or-recent_ This selects the first of the first recent and the first important messages. _first_ Set the current message to the first undeleted message unless all are deleted. In that case set it to the last message. _last_ Set the current message to the last undeleted message unless all are deleted. In that case set it to the last message. _index-answered-background-color_ _index-answered-foreground-color_ _index-deleted-background-color_ _index-deleted-foreground-color_ _index-important-background-color_ _index-important-foreground-color_ _index-new-background-color_ _index-new-foreground-color_ _index-recent-background-color_ _index-recent-foreground-color_ _index-to-me-background-color_ _index-to-me-foreground-color_ _index-unseen-background-color_ _index-unseen-foreground-color_ Index Colors. _index-format_ This option is used to customize the content of lines in the MESSAGE INDEX screen. Each line is intended to convey some amount of immediately relevant information about each message in the current folder. _Pine_ provides a pre-defined set of informational fields with reasonable column widths automatically computed. You can, however, replace this default set by listing special tokens in the order you want them displayed. The list of available tokens is here. Spaces are used to separate listed tokens. Additionally, you can specify how much of the screen's width the taken's associated data should occupy on the index line by appending the token with a pair of parentheses encl