diff options
| author | Eduardo Chappa <echappa@gmx.com> | 2013-02-03 00:59:38 -0700 |
|---|---|---|
| committer | Eduardo Chappa <echappa@gmx.com> | 2013-02-03 00:59:38 -0700 |
| commit | 094ca96844842928810f14844413109fc6cdd890 (patch) | |
| tree | e60efbb980f38ba9308ccb4fb2b77b87bbc115f3 /doc/tech-notes | |
| download | alpine-094ca96844842928810f14844413109fc6cdd890.tar.xz | |
Initial Alpine Version
Diffstat (limited to 'doc/tech-notes')
| -rw-r--r-- | doc/tech-notes/Makefile | 70 | ||||
| -rw-r--r-- | doc/tech-notes/background.html | 350 | ||||
| -rw-r--r-- | doc/tech-notes/cmd-line.html | 553 | ||||
| -rw-r--r-- | doc/tech-notes/config-notes.html | 1681 | ||||
| -rw-r--r-- | doc/tech-notes/config.html | 12523 | ||||
| -rw-r--r-- | doc/tech-notes/for.pnuts | 9 | ||||
| -rw-r--r-- | doc/tech-notes/index.html | 122 | ||||
| -rw-r--r-- | doc/tech-notes/installation.html | 577 | ||||
| -rw-r--r-- | doc/tech-notes/introduction.html | 122 | ||||
| -rw-r--r-- | doc/tech-notes/low-level.html | 975 | ||||
| -rwxr-xr-x | doc/tech-notes/pn4tn | 7 | ||||
| -rwxr-xr-x | doc/tech-notes/pnuts.4tech-notes | 134 | ||||
| -rw-r--r-- | doc/tech-notes/porting.html | 336 |
13 files changed, 17459 insertions, 0 deletions
diff --git a/doc/tech-notes/Makefile b/doc/tech-notes/Makefile new file mode 100644 index 00000000..ea7d19ef --- /dev/null +++ b/doc/tech-notes/Makefile @@ -0,0 +1,70 @@ +# $Id: Makefile,v 1.6 1998/05/11 18:33:22 skramer Exp $ +# +# T H E P I N E M A I L S Y S T E M +# +# Laurence Lundblade and Mike Seibel +# Networks and Distributed Computing +# Computing and Communications +# University of Washington +# Administration Building, AG-44 +# Seattle, Washington, 98195, USA +# Internet: lgl@CAC.Washington.EDU +# mikes@CAC.Washington.EDU +# +# Please address all bugs and comments to "pine-bugs@cac.washington.edu" +# +# +# Pine and Pico are registered 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 software and its included text are Copyright +# 1989-1996 by the University of Washington. +# +# The full text of our legal notices is contained in the file called +# CPYRIGHT, included with this distribution. +# +# +# Pine is in part based on The Elm Mail System: +# *********************************************************************** +# * The Elm Mail System - Revision: 2.13 * +# * * +# * Copyright (c) 1986, 1987 Dave Taylor * +# * Copyright (c) 1988, 1989 USENET Community Trust * +# *********************************************************************** +# +# +# These variables are specific to the University of Washington's +# WWW server environment -- modify as needed for your own: +# WWWDIR: location for HTML files on WWW server +# PNUTS: script to run pnuts navigation bar generator; for details on PNUTS, +# see: http://hopf.math.nwu.edu/docs/utility.html +# If you do not have the PNUTS program, set variable to /bin/true + +SOURCES= index.html introduction.html background.html installation.html \ + cmd-line.html config.html config-notes.html low-level.html + +ALLSRC= $(SOURCES) for.pnuts + +TXTS= index.txt introduction.txt background.txt installation.txt \ + cmd-line.txt config.txt config-notes.txt low-level.txt + +HTML2TXT= lynx -underscore -nolist -dump + +WWWDIR= /usr/local/wwwdev/world/pine/tech-notes + +PNUTS= $(WWWDIR)/pn4tn + +.SUFFIXES: .html .txt + +tech-notes.txt: $(TXTS) + cat $(TXTS) > tech-notes.txt + rm $(TXTS) + +www: $(ALLSRC) + cp $(ALLSRC) $(WWWDIR) + ( cd $(WWWDIR) ; $(PNUTS) ) + +.html.txt: + $(HTML2TXT) $< > $@ + diff --git a/doc/tech-notes/background.html b/doc/tech-notes/background.html new file mode 100644 index 00000000..ac4d91af --- /dev/null +++ b/doc/tech-notes/background.html @@ -0,0 +1,350 @@ +<HTML><HEAD><TITLE>Alpine Technical Notes: Background Details</TITLE></HEAD><BODY> +<H1>Background Details</H1> + +<H2><A NAME="DNS">Domain Names</A></H2> + +<BR><P> + +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: + +<BLOCKQUOTE><CODE> +olive.cac.washington.edu +</CODE></BLOCKQUOTE> + +In this domain name the top-level label is <EM>edu</EM>, indicating it is +at an educational institution, the second-level label is +<EM>washington</EM>, indicating the University of Washington. +<EM>cac</EM> is a specific department within the University of Washington, +and <EM>olive</EM> 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. <P> + +<EM>Alpine</EM> 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. <P> + +On UNIX systems, you can set the domain via the <A +HREF="config.html#user-domain"><EM>user-domain</EM></A> +variable in the <EM>Alpine</EM> configuration file, or rely on the file +<CODE>/etc/hosts</CODE> which usually sets the name of the local host. +While <EM>Alpine</EM> 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 <CODE>/etc/hosts</CODE> +file. The fully-qualified name should be listed before any abbreviations. +For example, + +<BLOCKQUOTE><CODE> +128.95.112.99 olive.cac.washington.edu olive +</CODE></BLOCKQUOTE> + +is preferred over + +<BLOCKQUOTE><CODE> +128.95.112.99 olive olive.cac.washington.edu +</CODE></BLOCKQUOTE> +<P> + +On PCs, the task of configuring the domain name is a bit different. Often +times PCs do not have domain names-they have <EM>IP addresses</EM>. 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 <A +HREF="installation.html#install-pc">PC specific installation notes</A> for +help configuring the IP address with your network software. <P> + +With PCs, it is vital that users set the variable <A +HREF="config.html#user-domain"><EM>user-domain</EM></A> in the <EM>Alpine</EM> +configuration file (<CODE>PINERC</CODE>). <P> + +Details on configuring <EM>Alpine</EM> with correct domain names can be +found in the <A HREF="config-notes.html#domain">Domain Settings</A> +section of this document. <P> + +<HR> + +<H2><A NAME="rfc2822">RFC 2822 Compliance</A></H2> + +<EM>Alpine</EM> tries to adhere +to <A HREF="ftp://ftp.isi.edu/in-notes/rfc2822.txt">RFC 2822</A> +fairly strictly. <P> + +As far as outgoing email is concerned, <EM>Alpine</EM> 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. +<EM>Alpine</EM> 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. <P> + +The 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 2822 +appear in the full name, quotes are required around the address. <EM>Alpine</EM> +will insert the quotes automatically if needed. The common cases where this happens +are with periods after initials and parentheses. <P> + +<EM>Alpine</EM> expects dates to be in the standard RFC 822 format +which is something like: + +<PRE> + [www, ] dd mmm yy hh:mm[:ss] [timezone] +</PRE> + +It will attempt to parse dates that are not in this format. When an +unparsable date is encountered it is shown as question marks +in the FOLDER INDEX screen. <P> + +<HR> + +<H2><A NAME="SMTP">SMTP and Sendmail</A></H2> + +<EM>Alpine</EM> is a <EM>user agent</EM> not a <EM>message transfer agent</EM> (MTA). In +plain English, that means <EM>Alpine</EM> does not know how to interact with other +computers on the Internet to deliver or receive email. What <EM>Alpine</EM> 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. <P> + +All outgoing email is delivered to an SMTP server +or to a mail transfer agent. +A common mail transfer agent is <CODE>sendmail</CODE>. +The usual method of delivery used by <EM>Alpine</EM> is to use either a +local or a remote SMTP server. + +<P> The selection of which MTA to use depends on the settings of +<A HREF="config.html#smtp-server"><EM>smtp-server</EM></A>, +<A HREF="config.html#sendmail-path"><EM>sendmail-path</EM></A>, +and compile-time options. +The first MTA specified in the following list is used: + +<OL> + +<LI><EM>sendmail-path</EM> in +<CODE>/usr/local/lib/pine.conf.fixed</CODE> + +<LI><EM>smtp-server</EM> in <CODE>/usr/local/pine.conf.fixed</CODE> + +<LI><EM>sendmail-path</EM> specified on the command line. + +<LI><EM>smtp-server</EM> specified on the command line. + +<LI><EM>sendmail-path</EM> in the user's <CODE>.pinerc</CODE> file. + +<LI><EM>smtp-server</EM> in the user's <CODE>.pinerc</CODE> file. + +<LI><EM>sendmail-path</EM> in <CODE>/usr/local/lib/pine.conf</CODE> + +<LI><EM>smtp-server</EM> in <CODE>/usr/local/pine.conf</CODE> + +<LI><CODE>DF_SENDMAIL_PATH</CODE> defined at compile time. + +<LI><CODE>SENDMAIL</CODE> and <CODE>SENDMAILFLAGS</CODE> defined at +compile time. + +</OL><P> + +If the <EM>sendmail-path</EM> 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. +<EM>NOTE: The program MUST read the message to be posted on standard +input, AND operate in the style of sendmail's "-t" option. This +method is not recommended unless there are special reasons you +want to do this. </EM><P> + +If an <EM>smtp-server</EM> is specified, +<EM>Alpine</EM> operates as an SMTP client. SMTP stands for <EM>Simple Mail +Transfer Protocol</EM>; it specifies the rules by which computers on the +Internet pass email to one another. In this case, <EM>Alpine</EM> 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 <EM>Alpine</EM> operate as an SMTP client, the +<A HREF="config.html#smtp-server"><EM>smtp-server</EM></A> 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 alternate SMTP servers. +<EM>PC-Alpine</EM> only runs as an SMTP client so the <EM>smtp-server</EM> +option is mandatory. <P> + +For UNIX <EM>Alpine</EM>, +if neither <EM>smtp-server</EM> or <EM>sendmail-path</EM> is set, +the default <CODE>sendmail</CODE> program is +invoked with the "<CODE>-bs -odb -oem</CODE>" flags, and the message +is sent using the SMTP protocol. +<P> + +<HR> + +<H2><A NAME="IMAP">Internet Message Access Protocol (IMAP)</A></H2> + +IMAP is a remote access protocol for message stores. <EM>Alpine</EM> uses IMAP to get +at messages and folders which reside on remote machines. With IMAP, +messages are kept on the server. An IMAP client (such as <EM>Alpine</EM>) can +request specific messages, headers, message structures, message parts, 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 "<A +HREF="http://www.imap.org/imap.vs.pop.brief.html">Comparing Two Approaches +to Remote Mailbox Access: IMAP vs. POP</A>" by Terry Gray. A more +detailed exploration of message access may be found in the paper "<A +HREF="http://www.imap.org/imap.vs.pop.html"> Message Access Paradigms and +Protocols</A>." +<P> + +IMAP Features: + +<UL> + +<LI> Allows access to mail folders from more than one client computer. + +<LI> 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 large audio file via +MIME, you can choose when (or if) you want to get that part of the +message. + +<LI> Email can be delivered and stored on a well-maintained and reliable +server which is "always-up". + +<LI> Folders can be accessed and manipulated from anywhere on the +Internet. + +<LI> Users can get to messages stored in different folders within the same +<EM>Alpine</EM> session. + +<LI> Allows use of IMAP server for searching and parsing. + +<LI> The latest revision of IMAP (IMAP4) also provides for disconnected +operation, including resynchronization of message state between mail +servers and message caches on clients. <EM>Alpine</EM> does not support this +capability, however. + +</UL> + +IMAP4rev1 is described in <A +HREF="ftp://ftp.isi.edu/in-notes/rfc3501.txt">RFC 3501</A>. Further +information about IMAP may be obtained from the University of Washington's +<A HREF="http://www.washington.edu/imap/">IMAP Information Center</A>.<P> + +<EM>Alpine</EM> is an IMAP4rev1 client. +<P> + +<HR> + +<H2><A NAME="MIME">Multipurpose Internet Mail Extensions (MIME)</A></H2> + +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 +<EM>Alpine</EM> 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. <P> + +The MIME standard was officially published in June of 1992 as <A +HREF="ftp://ftp.isi.edu/in-notes/rfc1341.txt">RFC 1341</A> and subsequently +revised in <A HREF="ftp://ftp.isi.edu/in-notes/rfc2045.txt">RFC 2045</A> +when it became a full Internet Standard. <EM>Pine</EM> 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. <P> + +The MIME standard also includes support for non-ASCII text in message +headers through the extensions described in <A +HREF="ftp://ftp.isi.edu/in-notes/rfc1342.txt">RFC 1342</A> and subsequently +revised in <A HREF="ftp://ftp.isi.edu/in-notes/rfc2047.txt">RFC 2047</A>. <P> + +An actual MIME message looks something like this: + +<PRE> +Date: Tue, 12 Mar 1996 15:39:35 -0800 (PST) +From: David L Miller <dlm@cac.washington.edu> +To: David L Miller <dlm@cac.washington.edu> +Subject: =?iso-8859-1?Q?Test_MIME_message_with_RFC-1522_headers_=28=E1?= =?iso-8859-1?Q?=E2=E3=29?= +Message-Id: <Pine.ULT.3.92.960312150851.21583I-101000@shiva2.cac.washington.edu> +Mime-Version: 1.0 +Content-Type: MULTIPART/MIXED; BOUNDARY="0-1737669234-826673975=:21583" +Content-Id: <Pine.ULT.3.92.960312153928.21583O@shiva2.cac.washington.edu> + + 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: <Pine.ULT.3.92.960312153104.21583L@shiva2.cac.washington.edu> + +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: <Pine.ULT.3.92.960312153638.21583N@shiva2.cac.washington.edu> +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-- + +</PRE> + +For details about <EM>Alpine</EM>'s implementation of MIME, see the two MIME sections +"<A HREF="low-level.html#MIME-read">MIME: Reading a Message</A>" and +"<A HREF="low-level.html#MIME-send">MIME: Sending a Message</A>" later +in this document. <P> + +<HR> + +<H2><A NAME="collections">Folder Collections</A></H2> + +Folder Collections are <EM>Alpine</EM>'s way of dealing with more than a single group +of folders. <P> + +For a more complete description of Folder Collections, see the section on +"<A HREF="config-notes.html#collections">Syntax for Collections</A>." <P> + +The <EM>Alpine</EM> distribution is designed to require as little configuration and +effort at compile time as possible. Still, there are some <EM>Alpine</EM> behaviors +which are set at the time you compile <EM>Alpine</EM>. 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. <P> + +<!-- pnuts --> +</BODY> +</HTML> diff --git a/doc/tech-notes/cmd-line.html b/doc/tech-notes/cmd-line.html new file mode 100644 index 00000000..cb6d1efb --- /dev/null +++ b/doc/tech-notes/cmd-line.html @@ -0,0 +1,553 @@ +<HTML><HEAD><TITLE>Alpine Technical Notes: Command Line Arguments</TITLE></HEAD><BODY> +<H1>Command Line Arguments</H1> + +<H2><A NAME="alpine">Alpine</A></H2> + +<EM>Alpine</EM> and <EM>PC-Alpine</EM> can accept quite a few +command-line arguments. +Many of these arguments overlap with variables +in the <EM>Alpine</EM> configuration file. +If there is a difference, then a flag set in the command line takes precedence. +Both <EM>Alpine</EM> and <EM>PC-Alpine</EM> expect command line arguments (other +than addresses) to be +preceded by the "-" (dash) as normally used by UNIX programs. +<P> + +<DL COMPACT> + +<DT> <EM>[addresses]</EM> + +<DD> Send-to: If you give <EM>Alpine</EM> an argument or arguments which +do not begin with a dash, <EM>Alpine</EM> treats them as email addresses. +<EM>Alpine</EM> will startup in +the composer with a message started to the addresses specified. +Once the message is sent, the <EM>Alpine</EM> session closes. +Standard input redirection is allowed. +Separate multiple addresses with a space between them. +Addresses are placed in the "To" field only. +<P> + +<DT> < <EM>file</EM> + +<DD> <EM>Alpine</EM> will startup in the composer with <EM>file</EM> read +into the body of the message. +Once the message is sent, the <EM>Alpine</EM> session closes. +<P> + +<DT> -attach <EM>file</EM> + +<DD> Go directly into composer with given file attached. +<P> + +<DT> -attachlist <EM>file-list</EM> + +<DD> Go directly into composer with given files attached. +This must be the last option on the command line. +<P> + +<DT> -attach_and_delete <EM>file</EM> + +<DD> Go directly into composer with given file attached, delete when finished. +<P> + +<DT> -aux <EM>local_directory</EM> + +<DD> <EM>PC-Alpine</EM> only. +This tells <EM>PC-Alpine</EM> the local directory to use for storing auxiliary +files, like debug files, address books, and signature files. The pinerc may +be local or remote. +<P> + +<DT> -nosplash + +<DD> <EM>PC-Alpine</EM> only. +This tells <EM>PC-Alpine</EM> to not display the splash screen upon startup. +This may be helpful for certain troubleshooting or terminal server scenarios. +<P> + +<DT> -bail + +<DD> 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 +<EM>Alpine</EM> to quit instead of creating a new pinerc. +<P> + +<DT> -c <EM>n</EM> + +<DD> When used with the <CODE>-f</CODE> option, apply the <EM>n</EM>th context. +This is used when there are multiple folder collections (contexts) and you +want to open a folder not in the primary collection. +<P> + +<DT> -conf + +<DD> Configuration: Prints a sample system configuration file to the +screen or standard output. To generate an initial system configuration +file, execute + +<PRE><CODE> + alpine -conf > /usr/local/lib/pine.conf +</CODE></PRE> +<P> + +To generate a system configuration file using settings from an old +system configuration file, execute + +<PRE><CODE> + alpine -P old-pine.conf -conf > /usr/local/lib/pine.conf +</CODE></PRE> +<P> +A system configuration file is not required. +<P> + +<DT> -convert_sigs <EM>-p pinerc</EM> + +<DD> Convert signatures contained in signature files into literal signatures. +<P> + +<DT> <A NAME="copy_abook">-copy_abook <EM><local_abook_file> <remote_abook_folder></EM> + +<DD> 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 <EM>Alpine</EM> +and copy entries from the local address book by using aggregate Save in +the address book screen. +<P> + +<DT> <A NAME="copy_pinerc">-copy_pinerc <EM><local_pinerc_file> <remote_pinerc_folder></EM> + +<DD> 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. +<P> + +<DT> -d <EM>debug-level</EM> + +<DD> Debug Level: Sets the level of debugging information written by +<EM>Alpine</EM>. +<EM>Debug-level</EM> 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.) +<P> + +<DT> -d <EM>keywords</EM> + +<DD> You may use a more detailed version of the debugging flag to set +the debug level in separate parts of <EM>Alpine</EM>. +The possibilities are flush, timestamp, imap=0..4, tcp, numfiles=0..31, and +verbose=0..9. +<EM>Flush</EM> causes debugging information to be flushed immediately to +the debug file as it is written. +<EM>Verbose</EM> is the general debugging verbosity level. +<EM>Timestamp</EM> causes timestamps to be added to the debug file, which +is useful when you are trying to figure out what is responsible for delays. +<EM>Numfiles</EM> sets the number of debug files saved. +<EM>Imap</EM> sets the debug level for the debugging statements related +to the conversation with the IMAP server, and more generally, for the +debugging related to <EM>Alpine</EM>'s interaction with the C-Client library. +If <EM>imap</EM> is set higher than 4, sensitive authentication information +will be included in the debug file. +<EM>Tcp</EM> adds more TCP/IP debugging information. +<P> + +<DT> -f <EM>folder</EM> + +<DD> Startup folder: <EM>Alpine</EM> will open this folder in place +of the standard INBOX. +<P> + +<DT> -F <EM>file</EM> + +<DD> Open named text file for viewing and forwarding. +<P> + +<DT> -h + +<DD> Help: Prints the list of available command-line arguments to the +screen. +<P> + +<DT> -i + +<DD> <EM>Alpine</EM> will start up in the FOLDER INDEX +screen instead of the MAIN MENU. +<P> + +Configuration equivalent: <EM>initial-keystroke-list=i</EM>. +<P> + +<DT> -I <EM>a,b,c,...</EM> + +<DD> Initial Keystrokes: <EM>Alpine</EM> will execute this comma-separated +sequence of commands upon startup. +This allows users to get <EM>Alpine</EM> to start in any +of its menus/screens. +You cannot include any input to the composer in the initial keystrokes. +The key <Return> 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 <EM>Alpine</EM>. +A user can always use only <EM>character</EM> keys in the startup list even +if he or she is using <EM>function</EM> 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. +<P> + +Configuration equivalent: <EM>initial-keystroke-list</EM> +<P> + +<DT> -install + +<DD> For <EM>PC-Alpine</EM> only, this option prompts for some basic +setup information, then exits. +<P> + +<DT> -k + +<DD> Function-Key Mode: When invoked in this way, <EM>Alpine</EM> expects +the input of commands to be function-keys. +Otherwise, commands are linked to the regular character keys. +<P> + +Configuration equivalent: <EM>use-function-keys</EM> included in +<EM>feature-list</EM>. +<P> + +<DT> -n <EM>n</EM> + +<DD> Message-Number: When specified, <EM>Alpine</EM> starts up in the +FOLDER INDEX screen with the current message being the specified +message number. +<P> + +<DT> -nowrite_password_cache + +<DD> This tells <EM>Alpine</EM> to use the local password cache if there is one, but to +never offer writing new passwords to the cache. +<P> + +<DT> -o <EM>folder</EM> + +<DD> Opens the INBOX (or a folder specified via the -f argument) ReadOnly. +<P> + +<DT> -p <EM>pinerc</EM> + +<DD> Uses the named file as the personal configuration file instead of +<EM>~/.pinerc</EM> or the default PINERC search sequence <EM>PC-Alpine</EM> uses. +Pinerc may be either a local file or a remote configuration folder. +<P> + +<DT> -P <EM>pinerc</EM> + +<DD> Uses the named file as the system wide configuration file instead of +<EM>/usr/local/lib/pine.conf</EM> on UNIX, or nothing on <EM>PC-Alpine</EM>. +Pinerc may be either a local file or a remote configuration folder. +<P> + +<DT> -passfile <EM>passfile</EM> + +<DD> This tells <EM>Alpine</EM> what file should be used as the password file. +This should be a fully-qualified filename. +<P> + +<DT> -pinerc <EM>file</EM> + +<DD> Output fresh pinerc configuration to <EM>file</EM>, preserving the +settings of variables that the user has made. +Use <EM>file</EM> set to ``-'' to make output go to standard out. +<P> + +<DT> -r + +<DD> Restricted Mode: For UNIX <EM>Alpine</EM> only. +<EM>Alpine</EM> in restricted mode can only send email to itself. +Save and export are limited. +<P> + +<DT> -registry <EM>cmd</EM> + +<DD> For <EM>PC-Alpine</EM> only, this option affects the values of +<EM>Alpine</EM>'s registry entries. +Possible values for <EM>cmd</EM> are set, noset, clear, clearsilent, and dump. +<EM>Set</EM> will always reset <EM>Alpine</EM>'s registry +entries according to its current settings. +<EM>NoSet</EM> will never set any values in the registry, but it will +still use the values already set in the registry. +<EM>Clear</EM> will clear the registry values. +<EM>Clearsilent</EM> will silently clear the registry values. +<EM>Dump</EM> will display the values of current registry settings. +Note that the dump command is currently disabled. +Without the -registry option, <EM>PC-Alpine</EM> will write values into +the registry only if there currently aren't any values set. +<P> + +<DT> -sort <EM>key</EM> + +<DD> Sort-Key: Specifies the order messages will be displayed in for the +FOLDER INDEX screen. +<EM>Key</EM> 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 <EM>key</EM> value reverse is equivalent to arrival/reverse. +<P> + +Configuration equivalent: <EM>sort-key</EM>. +<P> + +<DT> -supported + +<DD> Some options may or may not be supported depending on how <EM>Alpine</EM> +was compiled. +This is a way to determine which options are supported in the particular +copy of <EM>Alpine</EM> you are using. +<P> + +<DT> -install + +<DD> For <EM>PC-Alpine</EM> only, this option removes references to Alpine +in Windows settings. The registry settings are removed and +the password cache is cleared. +<P> + +<DT> -url <EM>url</EM> + +<DD> Open the given URL. +<P> + +<DT> -v + +<DD> Version: Print version information to the screen. +<P> + +<DT> -version + +<DD> Version: Print version information to the screen. +<P> + +<DT> -x <EM>exceptions_config</EM> + +<DD> Configuration settings in the exceptions config override your normal +default settings. +<EM>Exceptions_config</EM> may be either a local file or a remote pinerc folder. +<P> + +<DT> -z + +<DD> Enable Suspend: When run with this flag, the key sequence ctrl-z +will suspend the <EM>Alpine</EM> session. +<P> + +Configuration equivalent: <EM>enable-suspend</EM> included in +<EM>feature-list</EM>. +<P> + +<DT> -<EM>option</EM>=<EM>value</EM> + +<DD> Assign <EM>value</EM> to the config option <EM>option</EM>. +For example, <EM>-signature-file=sig1</EM> or +<EM>-feature-list=signature-at-bottom</EM>. +(Note: feature-list values are +additive and features may be preceded with no- to turn them off). +<P> + +</DL> +<P> + +<H2><A NAME="pico">Pico</A></H2> + +The following command line options are supported in <EM>Pico</EM>: + +<DL> + +<DT> +<EM>n</EM> + +<DD> Causes <EM>Pico</EM> to be started with the cursor located <EM>n</EM> +lines into the file. (Note: no space between "+" sign and number) <P> + +<DT> -a + +<DD> Display all files and directories, including those beginning +with a period (.). <P> + +<DT> -b + +<DD> Enable the option to Replace text matches found using the +"Where is" command. This now does nothing. Instead, the option is +always turned on (as if the -b flag had been specified). <P> + +<DT> -d + +<DD> Rebind the "delete" key so the character the cursor is on is rubbed +out rather than the character to its left. <P> + +<DT> -e + +<DD>Enable file name completion. <P> + +<DT> -f + +<DD> Use function keys for commands. <I>This option supported only in +conjunction with UW Enhanced NCSA telnet.</I> <P> + +<DT> -g + +<DD> 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. <P> + +<DT> -k + +<DD>Causes "Cut Text" command to remove characters from the cursor +position to the end of the line rather than remove the entire line. <P> + +<DT> -m + +<DD> Enable mouse functionality. This only works when <EM>Pico</EM> is +run from within an X Window System "xterm" window. <P> + +<DT>-n<EM>n</EM> + +<DD> The -n<EM>n</EM> option enables new mail notification. The +<EM>n</EM> argument is optional, and specifies how often, in seconds, your +mailbox is checked for new mail. For example, -n60 causes <EM>Pico</EM> +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) <P> + +<DT> -o <EM>dir</EM> + +<DD> Sets operating directory. Only files within this directory are +accessible. Likewise, the file browser is limited to the specified +directory subtree. <P> + +<DT> -p + +<DD> 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.<P> + +<DT> -q + +<DD> TermdefWins. Termcap or terminfo escape sequences are used in preference +to default escape sequences.<P> + +<DT> -Q <EM>quotestr</EM> + +<DD> 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 "> ".<P> + +<DT> -r<EM>n</EM> + +<DD> Sets column used to limit the "Justify" command's right margin. <P> + +<DT> -t + +<DD> Enable "tool" mode. Intended for when <EM>Pico</EM> is used as the +editor within other tools (e.g., Elm, Pnews). <EM>Pico</EM> will not +prompt for save on exit, and will not rename the buffer during the "Write +Out" command. <P> + +<DT> -v + +<DD> View the file only, disallowing any editing. <P> + +<DT> -version + +<DD> Print version information. <P> + +<DT> -w + +<DD> Disable word wrap (thus allow editing of long lines). <P> + +<I>Note: <EM>Pico</EM> will break any lines over 255 characters when reading a +file, regardless of word wrapping.</I> <P> + +<DT> -x + +<DD> Disable keymenu at the bottom of the screen. <P> + +<DT> -z + +<DD> Enable ^Z suspension of <EM>Pico</EM>. <P> + +</DL> + +<H2><A NAME="pilot">Pilot</A></H2> + +The following command line options are supported in <EM>Pilot</EM>: + +<DL> + +<DT> -a + +<DD> Display all files including those beginning with a period (.). <P> + +<DT> -f + +<DD> Use function keys for commands. <I>This option supported only in +conjunction with UW Enhanced NCSA telnet.</I> <P> + +<DT> -g + +<DD> Enable "Show Cursor" mode. Cause cursor to be positioned before the +current selection rather than placed at the lower left of the display. <P> + +<DT> -m + +<DD> Enable mouse functionality. This only works when <EM>Pilot</EM> is +run from within an X Window System "xterm" window. <P> + +<DT> -n<EM>n</EM> + +<DD> The -n<EM>n</EM> option enables new mail notification. The +<EM>n</EM> argument is optional, and specifies how often, in seconds, your +mailbox is checked for new mail. For example, -n60 causes <EM>Pilot</EM> +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) <P> + +<DT> -o <EM>dir</EM> + +<DD>Sets operating directory. Only files within the specified directory +are accessible and browsing is limited to the specified directory subtree. +<P> + +<DT> -v + +<DD> Enable single vertical column display. <P> + +<DT> -x + +<DD> Disable keymenu at the bottom of the screen. <P> + +<DT> -z + +<DD> Enable ^Z suspension of <EM>Pilot</EM>. + +</DL> + +<!-- pnuts --> + +</BODY> +</HTML> diff --git a/doc/tech-notes/config-notes.html b/doc/tech-notes/config-notes.html new file mode 100644 index 00000000..bc8e7459 --- /dev/null +++ b/doc/tech-notes/config-notes.html @@ -0,0 +1,1681 @@ +<HTML><HEAD><TITLE>Alpine Technical Notes: Notes on Configuration and +Preferences</TITLE></HEAD><BODY> +<H1>Notes on Configuration and Preferences</H1> + +<H2><A NAME="fkey">Alpine in Function Key Mode</A></H2> + +The standard <EM>Alpine</EM> uses alphabetic keys for most commands, and control keys +in the composer. Despite possible appearances, the current bindings are +the result of much discussion and thought. All the commands in the +composer are single control characters. This keeps things very neat and +simple for users. Two character commands in the composer are a +possibility, but we're trying to avoid them because of the added +complexity for the user. <P> + +<EM>Alpine</EM> can also operate in a function-key mode. To go into this mode invoke +<EM>alpine -k</EM> or (on some UNIX systems) <EM>alpinef.</EM> On a UNIX +system, you can link or copy the <EM>Alpine</EM> executable to +<EM>alpinef</EM> to install <EM>alpinef.</EM> Alternatively, users and systems +administrators can set the <EM>use-function-keys</EM> feature in the +personal or system-wide <EM>Alpine</EM> configuration file. +The command menus at the +bottom of the screen will show <EM>F1-F12 </EM>instead of the alphabetic +commands. In addition, the help screens will be written in terms of +function keys and not alphabetic keys. <P> + +One of the results of using <EM>Alpine</EM> in function-key mode is that users can +only choose from twelve commands at any given time. In alphabetic-key +mode, a user can press a key for a command (say, q to quit) and that +command can be fulfilled. In function-key mode, the command must be +visible on the bottom key-menu in order to be used. There are some +screens where four screens of commands are operational; +function-key users can get to all of them, just not all at once. <P> + +<HR> + +<H2><A NAME="domain">Domain Settings</A></H2> + +<EM>Alpine</EM> uses the default domain for a few different tasks. First, it is +tacked onto the user-id for outgoing email. Second, it is tacked onto all +"local" (unqualified) addresses in the "To:" or "Cc:" fields of messages +being composed (unless they are found in the address book or on an +LDAP server). The domain +name is also used to generate message-id lines for each outgoing message +and to allow <EM>Alpine</EM> to check if an address is that of the current <EM>Alpine</EM> user. +<P> + +<EM>Alpine</EM> determines the domain name according +to whichever of these it finds. +The list here is in decreasing order of precedence. + +<OL> + +<LI> Value of the variable +<A HREF="config.html#user-domain"><EM>user-domain</EM></A> +in the system fixed configuration file + +<LI> Value of the variable <EM>user-domain</EM> in the personal +configuration file + +<LI> Value of the variable <EM>user-domain</EM> in the system-wide +configuration file + +<LI> Value from an external database (DNS, <CODE>/etc/hosts</CODE>, NIS) as +modified by a system fixed configuration file if +<A HREF="config.html#use-only"><EM>use-only-domain-name</EM></A> +set to <EM>yes</EM> + +<LI> Value from an external database (DNS, <CODE>/etc/hosts</CODE>, NIS) as +modified by a personal configuration file if <EM>use-only-domain-name</EM> +set to <EM>yes</EM> + +<LI> Value from an external database (DNS, <CODE>/etc/hosts</CODE>, NIS) as +modified by a system configuration file if <EM>use-only-domain-name</EM> +set to <EM>yes</EM> + +<LI> Unmodified value (host name) from an external database <P> + +</OL> + +<P> The easiest way for this system to work is for <EM>PC-Alpine</EM> +users and UNIX <EM>Alpine</EM> system administrators to +set the <EM>user-domain</EM> variable. The +variable <EM>use-only-domain-name</EM> is helpful if your site +supports/requires hostless addressing, but for some reason you don't want +to use the <EM>user-domain</EM> variable. <P> + +<HR> + +<H2><A NAME="collections">Syntax for Collections</A></H2> + +In many environments, it is quite common to have collections of archived +mail on various hosts around the network. Using the folder collections +facility in <EM>Alpine</EM>, access to these archives is just as simple as access to +folders on <EM>Alpine</EM>'s local disk. <P> + +"Collection" is the word we use in <EM>Alpine</EM> to describe a set of folders. A +collection corresponds loosely to a "directory" containing mail folders. +Folders within a defined collection can be manipulated (opened, saved-to, +etc) using just their simple name. Any number of folder collections can +be defined, and <EM>Alpine</EM> will adjust its menus and prompts to help navigate +them. <P> + +The way collections are defined in <EM>Alpine</EM> is with the +<A HREF="config.html#fold-coll"><EM>folder-collections</EM></A> +variable in the <EM>Alpine</EM> configuration file. +<EM>Folder-collections</EM> takes a list of one or more collections, each +(optionally) preceded by a user-defined logical name (label). Once +collections are defined, <EM>Alpine</EM> adjusts its menus and behavior to allow +choosing files by their simple name within the collection. +<P> + +Consider the following: + +<PRE> + folder-collections= Local-Mail C:\MAIL\[], + Remote-Mail {imap.u.example.edu}mail/[] +</PRE> +<P> + +The example shows two collections defined (a comma separated list; +newlines in the list are OK if there's one or more spaces before the next +entry), one local and one remote. Each collection is a space-delimited +pair of elements-first an optional logical-name and second the collection +specifier. The logical-name can have spaces if it has quotes around it +(but keeping the logical name short and descriptive works best). <EM>Alpine</EM> +will use the logical-name (if provided) to reference all folders in the +collection, so the user never has to see the ugliness of the collection +specifier. <P> + +The collection specifier can be thought of as an extended IMAP format (see +the <A HREF="#remote-folders"><EM>Remote Folders</EM></A> section +for a description of IMAP format names). +Basically, a pair of square-brackets are placed in the fully qualified +IMAP path where the simple folder name (the part without the host name and +path) would appear. Like IMAP, the path can be either fully qualified +(i.e., with a leading '/') or relative to your home directory. <P> + +An advanced feature of this notation is that a pattern within the square +brackets allows the user to define a collection to be a subset of a +directory. For example, a collection defined with the specifier: + +<PRE> + M-Mail C:MAIL/[m*]<BR> +</PRE> + +will provide a view in the folder lister of all folders in the PC's +"C:MAIL" directory that start with the letter 'm' (case insensitive under +DOS, of course). Further, the wildcard matching will honor characters +trailing the '*' in the pattern. <P> + +From within <EM>Alpine</EM>, the "Folder List" display will be adjusted to allow +browsing of the folders in any defined collection. Even more, you'll +notice in the <EM>Goto</EM> and <EM>Save</EM> commands a pair of +sub-commands to rotate +through the list of logical collection names, so only a simple name need +be input in order to operate on a folder in any collection. <P> + +The first collection specified in the <EM>folder-collections</EM> has +special significance. That folder is the "default collection for saves". +By default, in cases where the user does not specify which +collection should be used to <EM>Save</EM> a message, +the default collection for saves will be used. +Also, if the <A HREF="config.html#def-fcc"><EM>default-fcc</EM></A> +is a relative file name, then it is relative +to the default collection for saves. (See also +<A HREF="config.html#saved-msg-name"><EM>saved-msg-name-rule</EM></A>. <P> + +The notion of collections encompasses both email folders and news reading. +The variable <A HREF="config.html#news-coll"><EM>news-collections</EM></A> +uses nearly the same format as <EM>folder-collections</EM>. +Newsgroups can be defined for convenient +access via either IMAP or NNTP. There are advantages and disadvantages to +both access methods. In the IMAP case, your news environment state is +maintained on the server and, thus, will be seen by any client. The +downside is that, at the moment, you must have an account on the server. +In the NNTP case, server access is mostly anonymous and no +state/accounting need be maintained on it. The downside is that each +client, for now, must individually maintain news environment state. <P> + +An example pinerc entry might be: + +<PRE> + news-collections= Remote-State {news.u.example.edu}#news.[], + Local-State {news.u.example.edu/nntp}#news.[] +</PRE> + +Only newsgroups to which you are subscribed are included in the collection. <P> + +The pattern matching facility can be applied so as to define a news +collection which is a subset of all the newsgroups you subscribe to. For +example, this could be a valid collection: + +<PRE> + Newsfeed-News {news.u.example.edu/nntp}#news.[clari.*] +</PRE> +<P> + +Collection handling is a tough problem to solve in a general way, and the +explanation of the syntax is a bit ugly. The upside is, hopefully, that +for a little complexity in the <EM>Alpine</EM> configuration file you get simple +management of multiple folders in diverse locations. <P> + +Collection setup is handled by the +<EM>Setup/collectionList</EM> screen. <P> + +<HR> + +<H2><A NAME="remote-folders">Syntax for Folder Names</A></H2> + +Remote folders are distinguished from local folders by a leading host name +bracketed by '{' and '}'. The path and folder name immediately following +the closing bracket, '}', is interpreted by the remote server and is in a +form compatible with that server (i.e., path delimiters and naming syntax +relative to that server). +<P> + +The full syntax for a <EM>Alpine</EM> folder name looks like + +<P> +<CENTER><SAMP>[{<remote-specification>}][#<namespace>]<namespace-specific-part></SAMP></CENTER> +<P> + +The square brackets ([]) mean that the part is optional. +<P> + +If there is no remote-specification, then the folder name is interpreted +locally on the computer running <EM>Alpine</EM>. +Local folder names depend on the operating system used by the computer +running <EM>Alpine</EM>, as well as the configuration of that system. For example, +"C:\ALPINE\FOLDERS\OCT-94" might exist on a PC, and +"~/mail/september-1994" might be a reasonable folder name on a +system running Unix. + +<P> +<EM>Alpine</EM> users have the option of using folders which are stored on some other +computer. <EM>Alpine</EM> accesses remote folders via IMAP (the Internet Message +Access Protocol), or in the case of news, via NNTP (the Network News +Transport Protocol). To be able to access remote folders in <EM>Alpine</EM>, the +remote host must be running the appropriate server software (imapd or +nntpd) and you must correctly specify the name of the folder to <EM>Alpine</EM>, +including the domain name of the remote machine. For example, +<P> +<CENTER><SAMP>{monet.art.example.com}INBOX</SAMP></CENTER> +<P> +could be a remote folder specification, and so could +<P> +<CENTER><SAMP>{unixhost.art.example.com}~/mail/september-1994</SAMP></CENTER> +and +<P> +<CENTER><SAMP>{winhost.art.example.com}\mymail\SEP-94</SAMP></CENTER> +<P> +Note that in the case of remote folders, the directory/file path in the specification is +determined by the operating system of the remote computer, <B>not</B> by +the operating system of the computer on which you are running <EM>Alpine</EM>. +<P> +As you can tell, the name of the computer is in {} brackets +followed immediately by the name of the folder. (In each of these cases the +optional namespace is missing.) If, as in these +examples, there is no remote access protocol specified, then IMAP is +assumed. Check +<A HREF="#server-name-syntax"><EM>Server Name Syntax</EM></A> +for a more detailed look at what options can be placed between the brackets. +If there are no brackets at all, then the folder name is interpreted locally +on the computer on which you are running <EM>Alpine</EM>. + +<P> +To the right of the brackets when a server name is present, or at the +start of the foldername if no server is present, the sharp sign, +"#", holds special meaning. It indicates a folder name +outside the area reserved for your personal folders. In fact, it's +used to indicate both the name of the folder, and a special phrase +telling <EM>Alpine</EM> how to interpret the name that follows. + +<P> +So, for example, <EM>Alpine</EM> can be used to access a newsgroup that might be +available on your computer using: +<P> +<CENTER><SAMP>#news.comp.mail.pine</SAMP></CENTER> +<P> +The sharp sign indicates the folder name is outside your personal +folder area. The "news." phrase after it tells <EM>Alpine</EM> to +interpret the remainder of the name as a newsgroup. + +<P> +Similarly, to access a newsgroup on your IMAP server, you might +use something like: +<P> +<CENTER><SAMP>{wharhol.art.example.com}#news.comp.mail.misc</SAMP></CENTER> + +<P> +There are a number of such special phrases (or "namespaces") +available. For a more detailed explanation read about +<A HREF="#folder-namespaces"><EM>Namespaces</EM></A>. + +<P> +Note that "INBOX" has special meaning in both local and remote folder +names. The name INBOX refers to your "principal incoming +message folder" and will be mapped to the actual file name used for your +INBOX on any given host. Therefore, a name like +"{xxx.art.example.com}INBOX" refers to whatever file is used to +store incoming mail for you on that particular host. +<P> + +<HR> + +<H2><A NAME="server-name-syntax">Server Name Syntax</A></H2> + +This section describes the syntax which may be used for server names +which may be associated with remote folders or SMTP servers. + +<P> +A server name is the hostname of the server. +It's a good idea to use the host's fully-qualified network name. + +<P> +<CENTER><SAMP>foo.example.com</SAMP></CENTER> +<P> + +However, IP addresses are allowed if surrounded +with square-brackets. + +<P> +<CENTER><SAMP>[127.0.0.1]</SAMP></CENTER> +<P> + +An optional network port number may be supplied by appending +a colon (:) followed by the port number +to the server name. +By default, the IMAP port number, 143, is used. + +<P> +<CENTER><SAMP>foo.example.com:port</SAMP></CENTER> +<P> + +Besides server name and optional port number, various other optional +parameters may be supplied that alter <EM>Alpine</EM>'s interaction with the server. +A parameter is supplied by appending a slash (/) character followed by +the parameter's name and, +depending on the particular parameter, the value assigned to that +name, to the server name (and optional port number). +Parameter names are <EM>not</EM> case sensitive. +Currently supported parameters include: + +<DL> + +<DT>User</DT> +<DD>This parameter requires an associated value, and is intended to +provide the username identifier with which to establish the server +connection. +If your SMTP server offers SMTP AUTH authentication, adding this +parameter to the +<A HREF="config.html#smtp-server"><EM>SMTP-Server</EM></A> +option will cause <EM>Alpine</EM> to attempt to authenticate to the server using the +supplied username. +Similarly, if your NNTP server offers NNTP "AUTHINFO SASL" +or "AUTHINFO USER" authentication, adding this parameter to the +<A HREF="config.html#nntp-server"><EM>NNTP-Server</EM></A> +option (or to the server name for any folder collection using NNTP) +will cause <EM>Alpine</EM> to attempt +to authenticate to the server using the supplied username. +An example might be: + +<P> +<CENTER><SAMP>/user=katie</SAMP></CENTER> +<P> + +</DD> + +<DT>TLS</DT> +<DD> +Normally, when a new connection is made an attempt is made to +negotiate a secure (encrypted) session using Transport Layer Security (TLS). +If that fails then a non-encrypted connection will be attempted instead. +This is a unary parameter indicating communication with the server must +take place over a TLS connection. If the attempt to use TLS fails then +this parameter will cause the connection to fail instead of falling +back to an unsecure connection. + +<P> +<CENTER><SAMP>/tls</SAMP></CENTER> +<P> + +</DD> + +<DT>SSL</DT> +<DD> +This is a unary parameter indicating communication with the server should +take place over a Secure Socket Layer connection. The server must support +this method, and be prepared to accept connections on the appropriate +port (993 by default). +<EM>Alpine</EM> must be linked with an SSL library for this option to be operational. + +<P> +<CENTER><SAMP>/ssl</SAMP></CENTER> +<P> + +</DD> + +<DT>NoValidate-Cert</DT> +<DD>Do not validate certificates (for TLS or SSL connections) from the server. +This is needed if the server uses self-signed certificates or if <EM>Alpine</EM> +cannot validate the certificate for some other known reason. +<P> +</DD> + +<DT>Anonymous</DT> +<DD>This is a unary parameter (that means it does not have a value) +indicating that the connection be logged in as +"anonymous" rather than a specific user. +Not all servers offer anonymous +access; those which do generally only offer read-only access to certain +"public" folders. + +<P> +<CENTER><SAMP>/anonymous</SAMP></CENTER> +<P> + +</DD> + +<DT>Secure</DT> +<DD>This is a unary parameter indicating that the connection use the +most secure authentication method mutually supported by <EM>Alpine</EM> and the +server. +<EM>Alpine</EM> is capable of authenticating connections to +the server using several methods. +By default, <EM>Alpine</EM> will attempt each +method until either a connection is established or the +list of methods is exhausted. +This parameter causes <EM>Alpine</EM> to instead fail +the connection if the first (generally most "secure") method fails. + +<P> +<CENTER><SAMP>/secure</SAMP></CENTER> +<P> + +</DD> + +<DT>Submit</DT> +<DD>This is a unary parameter for use with the +"SMTP-Server" option. +It indicates that the connection should be made to the Submit server +(<A HREF="http://www.ietf.org/rfc/rfc2476.txt">RFC 3676</A>) +(port 587) instead of the SMTP port (25). +At the time this help was written the submit option was equivalent to +specifying port 587. + +<P> +<CENTER><SAMP>/submit</SAMP></CENTER> +<P> +or +<P> +<CENTER><SAMP>host:587</SAMP></CENTER> +<P> + +</DD> + +<DT>Debug</DT> +<DD>This is a unary parameter indicating that the connection be established +in a verbose mode. Basically, it causes <EM>Alpine</EM> to log the communication with +the server in <EM>Alpine</EM>'s debug file. +Normally, the alpine -d command-line flag would be used instead. +<P> +</DD> + +<DT>NoRsh</DT> +<DD>By default, <EM>Alpine</EM> attempts to login using "rsh", +the UNIX remote shell program. +Including "NoRsh" will cause connections to this server to skip +the "rsh" attempt. +This might be useful to avoid long timeouts caused by rsh firewalls, for +example. +<P> +</DD> + +<DT>Service</DT> +<DD>This parameter requires an associated value. The default value is +"IMAP" which indicates communication with the server based +on the IMAP4rev1 protocol (defined in RFC 3501 -- see +<A HREF="http://www.imap.org/docs/rfc3501.html">http://www.imap.org/docs/rfc3501.html</A>).</DD> + +Other service values include: + <DL> + <DT>NNTP</DT> + <DD>This value indicates communication with the server takes place via +the Network News Transfer Protocol. Use this to define a collection +of newsgroups on a remote news server. So + +<P> +<CENTER><SAMP>/service=NNTP</SAMP></CENTER> +<P> +or just +<P> +<CENTER><SAMP>/NNTP</SAMP></CENTER> +<P> + +is the way to specify NNTP access. +<P> + </DD> + + <DT>POP3</DT> + <DD>This value indicates communication with the server takes place via the +Post Office Protocol 3 protocol. + +<P> +<CENTER><SAMP>/service=POP3</SAMP></CENTER> +<P> +or just +<P> +<CENTER><SAMP>/POP3</SAMP></CENTER> +<P> + +Note that there are several important issues +to consider when selecting this option: +<OL> + <LI> POP3 provides access to only your INBOX. In other words, +secondary folders such as your "saved-messages" are inaccessible. + <LI> <EM>Alpine</EM>'s implementation of POP3 does not follow the traditional POP +model and will leave your mail on the server. Refer to the +<A HREF="#maildrop"><EM>Mail Drop</EM></A> +functionality for a possible way around this problem. + <LI> See the discussion about new-mail checking in <A HREF="config.html#reopen-rule"><EM>Folder-Reopen-Rule</EM></A>. +</OL> +</DD> +</DL> +</DL> + +<P> +Note that it is possible to include more than one parameter in a server +specification by concatenating the parameters. For example: + +<P> +<CENTER><SAMP>foo.example.com:port/user=katie/novalidate-cert/debug</SAMP></CENTER> +<P> + +<HR> + +<H2><A NAME="folder-namespaces">Folder Namespaces</A></H2> + +A <EM>Alpine</EM> folder name looks like + +<P> +<CENTER><SAMP>[{<remote-specification>}][#<namespace>][<namespace-specific-part>]</SAMP></CENTER> +<P> + +The local part of a folder name has an optional "Namespace" which +tells <EM>Alpine</EM> how to interpret the rest of the name. + +<P> +By default the folder name is interpreted as defining a section of your personal +folder area. This area and how you specify it are defined by the +server, if one is specified, or, typically, the home +directory, if no server is defined. + +<P> +If a namespace is specified, it begins with the +sharp, "#", character followed by the name of the namespace +and then the namespace's path-element-delimiter. Aside from the +path's format, namespaces can also imply access rights, content +policy, audience, location, and, occasionally, access methods. + +<P> +Each server exports its own set (possibly of size one) of +namespaces. Hence, it's likely communication with your server's +administrator will be required for specific configurations. Some of +the more common namespaces, however, include: + +<DL> +<DT>#news.</DT> +<DD>This specifies a set of folders in the newsgroup namespace. Newsgroup +names are hierarchically defined with each level delimited by a period. +<P> +<CENTER><SAMP>#news.comp.mail.pine</SAMP></CENTER> +<P> +</DD> +<DT>#public/</DT> +<DD>This specifies a folder area that the server may export to the general +public. +</DD> +<DT>#shared/</DT> +<DD>This specifies a folder area that the folder may export to groups +of users. +</DD> +<DT>#ftp/</DT> +<DD>This specifies a folder area that is the same as that it may have +exported via the "File Transfer Protocol". +</DD> +<DT>#mh/</DT> +<DD>This specifies the personal folder area associated with folders +and directories that were created using the MH message handling system. +</DD> +<DT>#move/</DT> +<DD>This namespace is interpreted locally by <EM>Alpine</EM>. It has an unusual interpretation and format. +<P> +<CENTER><SAMP>#move<DELIM><MailDropFolder><DELIM><DestinationFolder></SAMP></CENTER> +<P> +The <CODE>#move</CODE> namespace is followed by two folder names separated by a delimiter +character. +The delimiter character may be any character which does not appear in +the <CODE>MailDropFolder</CODE> name. +The meaning of <CODE>#move</CODE> is that mail will be copied from the <CODE>MailDropFolder</CODE> to +the <CODE>DestinationFolder</CODE> and then deleted (if possible) from the <CODE>MailDropFolder</CODE>. +Periodic checks at frequency +<A HREF="config.html#mail-check"><EM>Mail-Check-Interval</EM></A>, but with a minimum time between checks set by +<A HREF="config.html#maildrop-check-minimum"><EM>MailDrop-Check-Minimum</EM></A>, +are made for new mail arriving in the <CODE>MailDropFolder</CODE>. +An example which copies mail from a POP inbox to a local folder follows +<P> +<CENTER><SAMP>#move+{popserver.example.com/pop3/ssl}inbox+local folder</SAMP></CENTER> +<P> +To you it appears that mail is being delivered to the local folder when it +is copied from the <CODE>MailDropFolder</CODE>, and you read mail from the local folder. +<P> +Note that if the <CODE>DestinationFolder</CODE> does not exist then the messages are not +copied from the <CODE>MailDropFolder</CODE>. +A <CODE>#move</CODE> folder may only be used as an +<A HREF="config.html#enable-incoming-folders"><EM>Incoming folder</EM></A> or +an Inbox. +When you are in the FOLDER LIST of Incoming Message Folders (after turning +on the enable-incoming-folders option) +the Add command has a subcommand "Use Mail Drop" +which may be helpful for defining the folder in your <EM>Alpine</EM> configuration. +The same is true when you edit the +<A HREF="config.html#inbox-path"><EM>Inbox-Path</EM></A> +option in Setup/Config. +Each of these configuration methods will also create the <CODE>DestinationFolder</CODE> +if it doesn't already exist. +If you are having problems, make sure the <CODE>DestinationFolder</CODE> exists. +</DD> +</DL> +<P> + +In addition, the server may support access to other user's folders, +provided you have suitable permissions. Common methods use a prefix +of either "~<VAR>user</VAR>/", or "/<VAR>user</VAR>/" to +indicate the root of the other user's folder area. +<P> + +<HR> + +<H2><A NAME="maildrop">What is a Mail Drop?</A></H2> + +In some situaions it may make sense to have your mail delivered to one +folder (the Mail Drop) and then when you want to read mail that has been +delivered to the Mail Drop folder <EM>Alpine</EM> will move it to another +destination folder. +Often the Mail Drop will be a remote folder and messages will be moved from +there to a local destination folder. + +<P> +One example where this might make sense is if the Mail Drop folder is accessible +only with the POP protocol. +You could designate your POP inbox as the Mail Drop folder and have <EM>Alpine</EM> move +mail from there to a local (on the same machine <EM>Alpine</EM> is running on) +destination folder, where you'll read it. + +<P> +A Mail Drop may only be used as your Inbox or as an +<A HREF="config.html#enable-incoming-folders"><EM>Incoming folder</EM></A>. + +<P> +There is no attempt to synchronize the contents of the destination folder +with the contents of the Mail Drop folder. +All that happens is that all of the messages in the Mail Drop folder are +copied to the destination folder and then they are deleted and expunged (if possible) +from the Mail Drop folder. +The next time a check for new mail is made, any messages in the Mail +Drop folder are once again copied to the destination folder and deleted +and expunged from the Mail Drop folder. +(If the Mail Drop folder is a news group, then the messages can't be +expunged from the newsgroup. Instead, only Recent messages are copied from +the newsgroup to the destination folder.) + +<P> +Configuration of a Mail Drop is a little different from configuration of +a folder which does not use a Mail Drop because you have to specify two +folder names instead of one. +The two folders may be any types of folders that <EM>Alpine</EM> can normally use. +They don't have to be a remote folder and a local folder, that is +simply the most common usage. +When you use a Mail Drop folder <EM>Alpine</EM> will periodically re-open the Mail +Drop to check for new mail. +The new-mail checks will happen at the frequency set with the +<A HREF="config.html#mail-check"><EM>Mail-Check-Interval</EM></A> option, +but with a minimum time +(<A HREF="config.html#maildrop-check-minimum"><EM>MailDrop-Check-Minimum</EM></A>) +between checks. +Because of this minimum you may notice that new mail does not +appear promptly when you expect it. +The reason for this is to protect the server from over-zealous opening and +closing of the Mail Drop folder. +If the user initiates the check by typing ^L (Ctrl-L) or the Next command when at +the end of the folder index, then the check will happen, regardless of how +long it has been since the previous check. +<P> +If there is new mail, that mail will be copied to the destination folder +and then will be deleted from the Mail Drop. +Note that using a Mail Drop with a local destination folder does not make +sense if you read mail from more than one machine, because the mail is +downloaded to the destination folder (which is accessible from only one +machine) and deleted from the Mail Drop. +<P> +The feature <A HREF="config.html#maildrops-preserve-state"><EM>Maildrops-Preserve-State</EM></A> +modifies the operation of Mail Drops. + +<P> +The actual syntax used by <EM>Alpine</EM> for a folder that uses a Mail Drop is: + +<P> +<CENTER><SAMP>#move<DELIM><MailDropFolder><DELIM><DestinationFolder></SAMP></CENTER> +<P> +The brackets are not literal. +<P> +<CENTER><SAMP><DELIM></SAMP></CENTER> +<P> +is a single character which does not appear in the <CODE>MailDropFolder</CODE> name. +If the name doesn't contain spaces then it can be a space character. +The two folder names are full technical +<A HREF="#server-name-syntax"><EM>folder names</EM></A> +as used by <EM>Alpine</EM>. +Here are a couple examples to give you an idea what is being talked about: + +<P> +<CENTER><SAMP>#move {popserver.example.com/pop3}inbox localfolder</SAMP></CENTER> +<P> +<CENTER><SAMP>#move+{nntpserver.example.com/nntp}#news.comp.mail.pine+local folder</SAMP></CENTER> +<P> + +A #move folder may only be used as an +<A HREF="config.html#enable-incoming-folders"><EM>Incoming folder</EM></A> or +an Inbox. +When you are in the FOLDER LIST of Incoming Message Folders (after turning +on the Enable-Incoming-Folders option) +the Add command has a subcommand "Use Mail Drop" +which may be helpful for defining the folder in your <EM>Alpine</EM> configuration. +The same is true when you edit the +<A HREF="config.html#inbox-path"><EM>Inbox-Path</EM></A> +option in Setup/Config. +</CODE> +if it doesn't already exist. +If you are having problems, make sure the <CODE>DestinationFolder</CODE> exists. +<P> + +<HR> + +<H2><A NAME="sorting">Sorting a Folder</A></H2> + +The mail index may be sorted by arrival, date, subject, +from, size, score, to, or cc order. +Each sort order can also be reversed. The <EM>$</EM> command will +prompt the user for the sort order. The sort order can also be specified +on the command line with the <EM>-sort</EM> flag or (equivalently) with +the <A HREF="config.html#sort-key"><EM>sort-key</EM></A> variable in +the <EM>pinerc</EM> file. +When a user changes folders, the sort order will go back to the original +sort order. +The command line (<EM>-sort</EM>) or configuration file sort specification +(<EM>sort-key</EM>) changes the original sort order. <P> + +When a folder is sorted and new mail arrives in the folder it will be +inserted in its properly sorted place. This can be a little odd when the +folder is sorted by something like the subject. It can also be a little +slow if you are viewing a large, sorted <EM>INBOX</EM>, +since the <EM>INBOX</EM> will have +to be re-sorted whenever new mail arrives. <P> + +The sorts are all independent of case and ignore leading or trailing white +space. There are actually two forms of subject sort. One called +<EM>Subject</EM> and the other called <EM>OrderedSubj</EM>. +They both ignore "Re:" at +the beginning and "(fwd)" at the end of the subjects. +<EM>Subject</EM> sorts all the subjects alphabetically. +<EM>OrderedSubj</EM> sorts by subjects alphabetically, +groups messages with the same subject (pseudo-threads), +then sorts the groups by the date of the first message of the group. +Sorting by <EM>Thread</EM> was added after <EM>OrderedSubj</EM> +and is usually a better method. +Thread sorting uses information in the message headers References, +Message-ID, and Subject. +It is possible the sort will be slightly slower with a Thread sort than +with an OrderedSubj sort. +The +sort by sender sorts by the user-id (part before the "@"), not the full name. +The arrival sort is no sort at all and the date +sort depends on the format of the date. +Some dates are in strange formats and are unparsable. +The time zone is also taken into account. <P> + +Sorting large mail folders can be very slow since it requires fetching all +the headers of the mail messages. +With UNIX <EM>Alpine</EM>, only the first sort is slow since <EM>Alpine</EM> +keeps a copy of all the headers. One exception is sorting +in reverse arrival order. This is fast because no headers have to be +examined. <EM>Alpine</EM> will show progress as it is sorting. <P> + +<HR> + +<H2><A NAME="alt-ed">Alternate Editor</A></H2> + +In the <EM>Alpine</EM> composer you can use any text editor, +such as <EM>vi</EM> or <EM>emacs,</EM> for composing the message text. +The addresses and subject still must be edited using the standard +<EM>Alpine</EM> composer. +If you include the feature +<A HREF="config.html#enable-alt-ed"><EM>enable-alternate-editor-cmd</EM></A> +in your <EM>pinerc</EM> you can type <EM>^_</EM> while in the body of +the message in the composer and be prompted for the editor. +If you also set the <A HREF="config.html#editor"><EM>editor</EM></A> variable +in your <EM>pinerc</EM> then <EM>^_</EM> will invoke the configured +editor when you type it. <P> + +Turning on the feature +<A HREF="config.html#enable-alt-imp"><EM>enable-alternate-editor-implicitly</EM></A> +will automatically invoke the editor you have defined with the <EM>editor</EM> +variable whenever you enter the body of a message you are composing. For +example, when you move out of the last header line and into the body of +the message, the alternate editor will be automatically invoked. <P> + +We know that many people would like to use the alternate editor to edit +the mail header as well. We considered several designs for this and +didn't come up with one that we liked and that was easy to implement. One +of the main problems is that you lose access to the address book. <P> + +<HR> + +<H2><A NAME="signature">Signatures and Signature Placement</A></H2> + +If the file <EM>~/.signature</EM> (UNIX) or +<EM><PINERC</EM>directory>\PINE.SIG (PC) exists, it will be included +in all outgoing messages. It is included before composition starts so +that the user has a chance to edit it out if he or she likes. The file +name for the signature can be changed by setting the +<A HREF="config.html#sig-file"><EM>signature-file</EM></A> +variable in the <EM>pinerc</EM>. +If the feature <A HREF="config.html#sig-dash"><EM>enable-sigdashes</EM></A> +is turned on then the line consisting of the +three characters "<CODE>-- "</CODE> is prepended to the signature file. +When Replying or Forwarding a message different signatures my be automatically +included by configuring them in the +<A HREF="config.html#role-config"><EM>Roles</EM></A> +setup screen. +It's easy to include different signatures by hand, by having multiple +signature files (<EM>.sig1, .sig2, .sig3, etc</EM>) and choosing to +include (^R in the composer) the correct one for the message being sent. +<P> + +<EM>Alpine</EM>'s default behavior encourages +a user to put his or her contribution +before the inclusion of the original text of the message being forwarded +or replied to, This is contrary to some conventions, but makes the +conversation more readable when a long original message is included in a +reply for context. The reader doesn't have to scroll through the original +text that he or she has probably already seen to find the new text. If +the reader wishes to see the old message(s), the reader can scroll further +into the message. Users who prefer to add their input at the end of a +message should set +the <A HREF="config.html#sig-at-bot"><EM>signature-at-bottom</EM></A> feature. +The signature will then be appended to the end of +the message after any included text. +This feature applies when <EM>Reply</EM>ing, not when <EM>Forward</EM>ing. <P> + +<HR> + +<H2><A NAME="feature-list">Feature List Variable</A></H2> + +<EM>Alpine</EM> used to have <EM>feature levels</EM> for +users with different amounts of experience. +We found that this was too restrictive. <EM>Alpine</EM> now has a +<A HREF="config.html#feat-list"><EM>feature-list</EM></A> instead. +Each user may pick and choose which +features they would like enabled (simple to do in the <EM>Setup/Config</EM> +screen). There is a short description of each in <A HREF="config.html#features-conf"><EM>Configuration Features</EM></A>. There is also a short on-line +help explaining the effect of each of +the features in the <EM>Setup/Config</EM> screen. +When the cursor is highlighting +a feature, the <EM>?</EM> command will show the help text for that feature. +Features don't have values, they are just turned on or off. They are all +off by default. <P> + +The <EM>feature-list</EM> variable is different from all other +configuration variables in that its value is additive. That is, the +system-wide configuration file can have some features turned on by +default. The user can select other features in their personal +configuration file and those features will be <STRONG>added</STRONG> to +the set of features turned on in the system-wide configuration file. +(With all other configuration variables, the user's values +<STRONG>replace</STRONG> the system-wide values.) Likewise, additional +features may be set on the command-line with the argument +"-feature-list=". These will be added to the others. <P> + +The treatment of <EM>feature-list</EM> in the system-wide <EM>fixed</EM> +configuration file is also different from other variables. The system +management can fix the value of individual features by placing them in the +fixed configuration file. Users will not be able to alter those features, +but will still be able to set the other non-restricted features the way +they like. <P> + +Because <EM>feature-list</EM> is additive, there is a way to turn features +off as well as on. Prepending the prefix "no-" to any feature sets it to +off. This is useful for over-riding the system-wide default in the +personal configuration file or for over-riding the system-wide default or +the personal configuration value on the command line. For example, if the +system-wide default configuration has the <EM>quit-without-confirm</EM> +feature set, the user can over-ride that (and turn it off) by including +<EM>no-quit-without-confirm</EM> in the personal configuration file or by +giving the command line argument +<EM>-feature-list=no-quit-without-confirm.</EM> More features (options) +will no doubt continue to be added. <P> + +<HR> + +<H2><A NAME="config-inheritance">Configuration Inheritance</A></H2> + +We start with an explanation of how configuration works in hopes of making +it easier to describe how inheritance works. +<P> +<EM>Alpine</EM> uses a hierarchy of configuration values from different locations. +There are five ways in which each configuration option (configuration +variable) can be set. +In increasing order of precedence they are: +<P> +<OL> +<LI> the system-wide configuration file. + +<LI> the personal configuration file + +<LI> the personal exceptions file + +<LI> a command line argument + +<LI> the system-wide <EM>fixed</EM> configuration file (Unix <EM>Alpine</EM> only) +</OL> +<P> +The fixed configuration file is normally +<CODE>/usr/local/lib/pine.conf.fixed</CODE>. +<P> +The system-wide configuration file is normally +<CODE>/usr/local/lib/pine.conf</CODE> for Unix <EM>Alpine</EM> and is normally not +set for <EM>PC-Alpine</EM>. +For <EM>PC-Alpine</EM>, if the environment variable <EM>$PINECONF</EM> is set, that +is used for the system-wide configuration. +This location can be set or changed on the command line with the -P flag. +The system-wide configuration file can be either a local file or a +remote configuration folder. +<P> +For Unix <EM>Alpine</EM>, the personal configuration file is normally the file +<CODE>.pinerc</CODE> in the user's home directory. +This can be changed with the -p command line flag. +For <EM>PC-Alpine</EM>, the personal configuration file is in +<CODE>$PINERC</CODE> or <CODE><PineRC registry value></CODE> or +<CODE>${HOME}\ALPINE\PINERC</CODE> or +<CODE><ALPINE.EXE </CODE>dir<CODE>>\PINERC</CODE>. +This can be changed with the -p command line flag. +If -p or <CODE>$PINERC</CODE> is used, the configuration data may be in +a local file or a remote config folder. +<P> +For Unix <EM>Alpine</EM>, the personal exceptions configuration file is +specified with the "-x exceptions_config" command line argument. +"Exceptions_config" may be either a local file or a remote +configuration folder. +If there is no "-x" command line option, +<EM>Alpine</EM> will look for the file "<CODE>.pinercex</CODE>" +in the same local directory that the regular config file is located in. +If the regular config file is remote then Unix <EM>Alpine</EM> looks in the home +directory for "<CODE>.pinercex</CODE>". +<P> +For <EM>PC-Alpine</EM>, the personal exceptions configuration file is +specified with the "-x exceptions_config" command line argument. +If there is no "-x" command line argument the environment +variable <CODE>$PINERCEX</CODE> may be set to the name of the +"exceptions_config" instead. +"Exceptions_config" may be either a local file or a remote +configuration folder. +If there is no "-x" command line option and <CODE>$PINERCEX</CODE> +is not set, +<EM>PC-Alpine</EM> will look for the file "<CODE>PINERCEX</CODE>" +in the same local directory that the regular config file is located in. +If the regular config file is remote then <EM>PC-Alpine</EM> looks in the +local directory specified by the "-aux local_directory" command +line argument, or the directory <CODE>${HOME}\ALPINE</CODE>, or +in <CODE><ALPINE.EXE </CODE>directory<CODE>></CODE> for a file named +"<CODE>PINERCEX</CODE>". +<P> +To reiterate, the value of a configuration option is taken from the +last location in the list above in which it is set. +Or, thinking about it slightly differently, a default value for an option +is established in the system-wide configuration file (or in the source +code if there is no value in the system-wide file). +That default remains in effect until and unless it is overridden by a value in a +location further down the list, in which case a new "default" +value is established. +As we continue down the list of locations we either retain the +value at each step or establish a new value. +The value that is still set after going through the whole list of +configuration locations is the one that is used. +<P> +So, for example, if an option is set in the system-wide configuration +file and in the personal configuration file, but is not set in the +exceptions, on the command line, or in the fixed file; then the value +from the personal configuration file is the one that is used. +Or, if it is set in the system-wide config, in the personal config, not +in the exceptions, but is set on the command line; then the value +on the command line is used. +<P> +Finally we get to inheritance. +For configuration options which are lists, like "smtp-server" or +"incoming-folders", +the inheritance mechanism makes it possible to <EM>combine</EM> +the values from different locations instead of <EM>replacing</EM> the value. +This is true of all configuration lists other than the "feature-list", +for which you may already set whatever you want at +any configuration location (by using the "no-" prefix if +necessary). +<P> +To use inheritance, set the first item in a configuration list to the +token "INHERIT". +If the first item is "INHERIT", +then instead of replacing the default value established so far, the rest of +the list is appended to the default value established so far and that is +the new value. +<P> +Here is an example which may make it clearer. Suppose we have: +<P> +<PRE> + System-wide config : smtp-server = smtp1.corp.com, smtp2.corp.com + Personal config : smtp-server = INHERIT, mysmtp.home + Exceptions config : smtp-server = <No Value Set> + Command line : smtp-server = <No Value Set> + Fixed config : smtp-server = <No Value Set> +</PRE> +<P> + +This would result in an effective smtp-server option of +<P> +<PRE> + smtp-server = smtp1.corp.com, smtp2.corp.com, mysmtp.home +</PRE> +<P> +The "INHERIT" token can be used in any of the configuration files +and the effect cascades. +For example, if we change the above example to: +<P> +<PRE> + System-wide config : smtp-server = smtp1.corp.com, smtp2.corp.com + Personal config : smtp-server = INHERIT, mysmtp.home + Exceptions config : smtp-server = INHERIT, yoursmtp.org + Command line : smtp-server = <No Value Set> + Fixed config : smtp-server = <No Value Set> +</PRE> +<P> + +This would result in: +<P> +<PRE> + smtp-server = smtp1.corp.com, smtp2.corp.com, mysmtp.home, yoursmtp.org +</PRE> +<P> +Unset variables are skipped over (the default value is carried forward) so +that, for example: +<P> +<PRE> + System-wide config : smtp-server = smtp1.corp.com, smtp2.corp.com + Personal config : smtp-server = <No Value Set> + Exceptions config : smtp-server = INHERIT, yoursmtp.org + Command line : smtp-server = <No Value Set> + Fixed config : smtp-server = <No Value Set> +</PRE> +<P> + +produces: +<P> +<PRE> + smtp-server = smtp1.corp.com, smtp2.corp.com, yoursmtp.org +</PRE> +<P> + +If any later configuration location has a value set (for a particular list +option) which does <EM>not</EM> begin with "INHERIT", +then that value replaces whatever value has been defined up to that point. +In other words, that cancels out any previous inheritance. +<P> +<PRE> + System-wide config : smtp-server = smtp1.corp.com, smtp2.corp.com + Personal config : smtp-server = INHERIT, mysmtp.org + Exceptions config : smtp-server = yoursmtp.org + Command line : smtp-server = <No Value Set> + Fixed config : smtp-server = <No Value Set> +</PRE> +<P> + +results in: +<P> +<PRE> + smtp-server = yoursmtp.org +</PRE> +<P> + +For some configuration options, like "viewer-hdr-colors" or +"patterns-roles", it is +difficult to insert the value "INHERIT" into the list of values +for the option using the normal Setup tools. +In other words, the color setting screen (for example) does not +provide a way to input the text "INHERIT" as the first +item in the viewer-hdr-colors option. +The way to do this is to either edit the pinerc file directly and manually +insert it, or turn on the "expose-hidden-config" feature and insert it +using the Setup/Config screen. +<P> + +<HR> + +<H2><A NAME="env-variables">Using Environment Variables</A></H2> + +The values of <EM>Alpine</EM> configuration options may include environment variables +which are replaced by the value of the variable at the time <EM>Alpine</EM> is run +(and also at the time the config option is changed). +The syntax to use environment variables is a subset of the common Unix +shell dollar-syntax. +For example, if + +<P><CENTER><SAMP>$VAR</SAMP></CENTER><P> + +appears in the value of a <EM>Alpine</EM> configuration option it is looked up in the +environent (using getenv("VAR")) and its +looked-up value replaces the <SAMP>$VAR</SAMP> part of the option value. +To include a literal dollar sign you may precede the dollar sign with another +dollar sign. +In other words, if the text + +<P><CENTER><SAMP>$$text</SAMP></CENTER><P> + +is the value of a configuration option, it will be expanded to + +<P><CENTER><SAMP>$text</SAMP></CENTER><P> + +and no environment lookup will be done. +For Unix <EM>Alpine</EM> it will also work to use a backslash character to +escape the special meaning of the dollar sign, but $$ is preferable since +it works for both <EM>PC-Alpine</EM> and Unix <EM>Alpine</EM>, allowing the configuration option +to be in a shared configuration file. +<P> + +This all sounds more complicated than it actually is. +An example may make it clearer. +Unfortunately, the way in which environment variables are set is OS-dependent +and command shell-dependent. +In some Unix command shells you may use + +<P><CENTER><SAMP>PERSNAME="Fred Flintstone"</SAMP></CENTER><P> + <CENTER><SAMP>export PERSNAME</SAMP></CENTER><P> + +Now, if you use <EM>Alpine</EM>'s Setup/Config screen to set + +<P><CENTER><SAMP>personal-name=$PERSNAME</SAMP></CENTER><P> + +the <SAMP>$PERSNAME</SAMP> would be replaced by <SAMP>Fred Flintstone</SAMP> +so that this would be equivalent to + +<P><CENTER><SAMP>personal-name=Fred Flintstone</SAMP></CENTER><P> + +Note, environment variable substitution happens after configuration +options which are lists are split into the separate elements of the list, +so a single environment variable can't contain a list of values. + +<P> +The environment variable doesn't have to be the only thing +after the equal sign. +However, if the name of the variable is not at the end of the line or +followed by a space (so that you can tell where the variable name ends), +it must be enclosed in curly braces like + +<P><CENTER><SAMP>${VAR}</SAMP></CENTER><P> + +It is always ok to use the braces even if you don't need to. +<P> +It is also possible to set a default value for an environment variable. +This default value will be used if the environment variable is not +set (that is, if getenv("VAR") returns NULL). +The syntax used to set a default value is + +<P><CENTER><SAMP>${VAR:-default value}</SAMP></CENTER><P> + +If the config file contains + +<P><CENTER><SAMP>personal-name=${VAR:-Fred Flintstone}</SAMP></CENTER><P> + +then when <EM>Alpine</EM> is run <SAMP>VAR</SAMP> will be looked up in the environment. +If <SAMP>VAR</SAMP> is found then <SAMP>personal-name</SAMP> will have +the value that <SAMP>VAR</SAMP> was set to, otherwise, +<SAMP>personal-name</SAMP> will be set to <SAMP>Fred Flintstone</SAMP>, +the default value. + +<P> +An example where an environment variable might be useful is the +variable <SAMP>inbox-path</SAMP> in the global configuration file. +Suppose most users used the server + +<P><CENTER><SAMP>imapserver.example.com</SAMP></CENTER><P> + +but that there were some exceptions who used + +<P><CENTER><SAMP>altimapserver.example.com</SAMP></CENTER><P> + +In this case, the system manager might include the following line in +the systemwide default <EM>Alpine</EM> configuration file + +<P><CENTER><SAMP>inbox-path=${IMAPSERVER:-imapserver.example.com}</SAMP></CENTER><P> + +For the exceptional users adding + +<P><CENTER><SAMP>IMAPSERVER=altimapserver.example.com</SAMP></CENTER><P> + +to their environment should work. +<P> +Another example might be the case where a user has to use a different +SMTP server from work and from home. +The setup might be something as simple as + +<P><CENTER><SAMP>smtp-server=$SMTP</SAMP></CENTER><P> + +or perhaps a default value could be given. +Note that, as mentioned above, the variable <SAMP>SMTP</SAMP> cannot contain +a list of SMTP servers. +<P> + +<HR> + +<H2><A NAME="smtp-server">SMTP Servers</A></H2> + +It is sometimes desirable to set <CODE>smtp-server=localhost</CODE> +instead of setting +<A HREF="config.html#sendmail-path"><EM>sendmail-path</EM></A> +to overcome the inability to +negotiate ESMTP options when <EM>sendmail</EM> is invoked with the +<EM>-t</EM> option. Sendmail can also be subject to unacceptable delays +due to slow DNS lookups and other problems. <P> + +It is sometimes desirable to configure an SMTP server on a port other +than the default port 25. This may be used to provide an alternate +service that is optimized for a particular environment or provides +different features from the port 25 server. An example would be a program +that negotiates ESMTP options and queues a message, but does not attempt +to deliver messages. This would avoid delays frequently encountered when +invoking <EM>sendmail</EM> directly. <P> + +A typical configuration would consist of + +<UL> + +<LI> A program that implements the SMTP or ESMTP protocol via stdio. + +<LI> An entry in <CODE>/etc/services</CODE> for the alternate service. + +<LI> An entry in <CODE>/etc/inetd.conf</CODE> for the alternate service. + +<LI> An entry in <CODE>/usr/local/lib/pine.conf</CODE>, +<CODE>/usr/local/lib/pine.conf.fixed</CODE> or <CODE>~/.pinerc</CODE>. + +</UL> + +<HR> + +<H2><A NAME="mime.types">MIME.Types file</A></H2> + +<EM>Alpine</EM>'s MIME-TYPE support is based on code contributed by Hans Drexler +<drexler@mpi.nl>. <EM>Alpine</EM> assigns MIME Content-Types according +to file name extensions found in the system-wide files +<CODE>/usr/local/lib/mime.types</CODE> and <CODE>/etc/mime.types</CODE>, +and a user specific <CODE>~/.mime.types</CODE> file. <P> + +In Windows, +<EM>Alpine</EM> looks in the same directory as the PINERC file and +the same dir as ALPINE.EXE. This is similar to the UNIX situation with +personal config info coming before potentially shared config data. An +alternate search path can be specified by setting the +<A HREF="config.html#mimetype-search-path"><EM>mimetype-search-path</EM></A> +variable in the user or system-wide +configuration or by setting the <CODE>MIMETYPES</CODE> environment +variable. <P> + +These files specify file extensions that will be connected to a mime type. +Lines beginning with a '<CODE>#</CODE>' character are treated as comments +and ignored. All other lines are treated as a mime type definition. The +first word is a <EM>type/subtype</EM> specification. All following words +are file <EM>extensions</EM> belonging to that type/subtype. Words are +separated by whitespace characters. If a file extension occurs more than +once, then the first definition determines the file type and subtype. +A couple sample lines from a mime.types file follow: <P> + +<PRE> +image/gif gif +text/html html htm +video/mpeg mpeg mpg mpe<BR> +</PRE> + +<HR> + +<H2><A NAME="color-config-notes">Color Details</A></H2> + +UNIX <EM>Alpine</EM> may display color if the terminal or terminal emulator you +are using is capable of displaying colors. +If the terminal supports ANSI color escape sequences you will be able to +turn color on using the <A HREF="config.html#color-style">color-style</A> +option and setting it to the value <EM>force-ansi-8color</EM> or +<EM>force-ansi-16color</EM>. +If instead you'd like <EM>Alpine</EM> to automatically detect whether or not +you are on a color terminal, set <EM>color-style</EM> to <EM>use-termdef</EM> +<EM>and</EM> configure the termcap entry to describe your terminal's +color capabilities. +<P> + +If the <EM>color-style</EM> option is set to <EM>use-termdef</EM>, +<EM>Alpine</EM> looks in +the terminal capabilities database, TERMINFO or TERMCAP, depending on +how <EM>Alpine</EM> was compiled, to decide whether or not your terminal is +capable of color. +For TERMINFO compiled <EM>Alpine</EM>s, the capabilities that are used for +color are +"colors", "setaf", "setab", +"op", and "bce". +If you have a terminal with color capabilities described by +the "scp" capability, <EM>Alpine</EM> does not support it. +The capabilities +"setf" and "setb" may be used instead of +"setaf" and "setab". +The capability "bce" is optional and is used as an optimization, +the other capabilities are required. +For TERMCAP compiled <EM>Alpine</EM>s, the capabilities that are used for +color are +"Co", "AF", "AB", "op", +and "ut". +The capabilities +"Sf" and "Sb" may be used instead of +"AF" and "AB", though this isn't a useful feature. +<P> + +Here are some short descriptions of the capabilities listed +above. +The TERMINFO name is listed, followed by the TERMCAP name in parentheses. +<DL COMPACT> + +<DT> <EM>colors</EM> (<EM>Co</EM>) + +<DD> The number of different colors. +<P> + +<DT> <EM>setaf</EM> (<EM>AF</EM>) + +<DD> Set ANSI foreground color. +<P> + +<DT> <EM>setab</EM> (<EM>AB</EM>) + +<DD> Set ANSI background color. +<P> + +<DT> <EM>setf</EM> (<EM>Sf</EM>) + +<DD> Set foreground color. Alternate form of <EM>setaf</EM>. +<P> + +<DT> <EM>setb</EM> (<EM>Sb</EM>) + +<DD> Set background color. Alternate form of <EM>setab</EM>. +<P> + +<DT> <EM>op</EM> (<EM>op</EM>) + +<DD> Set default pair to its original value. +<P> + +<DT> <EM>bce</EM> (<EM>ut</EM>) + +<DD> Screen is erased with current background color instead +of default background. +<P> + +<P> +</DL> +<P> +A standard ANSI terminal which supports color will have +a TERMINFO entry which contains: +<PRE> + colors#8 + setaf=\E[3%p1%dm + setab=\E[4%p1%dm + op=\E[39;49m + bce +</PRE> +<P> +or the TERMCAP equivalent: +<PRE> + Co#8 + AF=\E[3%dm + AB=\E[4%dm + op=\E[39;49m + ut +</PRE> +<P> + +If there are eight colors, the program uses colors 0, 1, ..., 7. +For an ANSI terminal, the foreground color is set by sending the escape +sequence "Escape LeftBracket 3 color_number m" to the terminal. +The background color is set by sending the sequence +"Escape LeftBracket 4 color_number m". +ANSI colors zero through seven are defined to be "black", +"red", "green", "yellow", "blue", +"magenta", "cyan", and "white". +Some terminal emulators will swap blue and red and swap yellow and cyan. +The capabilities "setf" and "setb" are usually designed +for those terminals so that they will flip the color numbers 1 and 4 and +the numbers 3 and 6 to compensate for this. +<EM>Alpine</EM> will use the ANSI versions of the capabilities if they exist, +and will use the non-ANSI versions (setf and setb) if the ANSI versions +don't exist. +Here's a version which does the flipping. +This can only be used with TERMINFO <EM>Alpine</EM>s, because of the arithmetic, +which is not supported by TERMCAP. +<PRE> + colors#8 + setf=\E[3%?%p1%{1}%=%t4%e%p1%{3}%=%t6%e%p1%{4}%=%t1%e%p1%{6}%=%t3%e%p1%d%;m + setb=\E[4%?%p1%{1}%=%t4%e%p1%{3}%=%t6%e%p1%{4}%=%t1%e%p1%{6}%=%t3%e%p1%d%;m + op=\E[39;49m + bce +</PRE> +<P> + +Some terminal emulators are capable of displaying eight more colors when +the foreground colors 30-37 are replaced with 90-97 and the background +colors 40-47 are replaced with 100-107. +These terminals require a fancy termcap entry which can take foreground +colors 0, 1, ..., 15 and map that into 30, 31, ..., 37, 90, 91, ..., 97, +and similarly for the background colors. +Here is a terminfo entry which will do just that: +<PRE> + colors#16 + setaf=%p1%{8}%/%{6}%*%{3}%+\E[%d%p1%{8}%m%dm + setab=%p1%{8}%/%{6}%*%{4}%+\E[%d%p1%{8}%m%dm + op=\E[39;49m + bce +</PRE> +and here is the termcap equivalent: +<PRE> + Co#16 + AF=\E[%i%i%>\001\034%>\045\064%dm + AB=\E[%i%i%>\001\046%>\057\064%dm + op=\E[39;49m + ut +</PRE> +<P> +This is a terminfo entry for 16 colors that also does the color flipping: +<PRE> + colors#16 + setf=%p1%{8}%/%{6}%*%{3}%+\E[%d%p1%{8}%m%Pa%?%ga%{1}%=%t4%e%ga%{3}%=%t6%e%ga%{4}%=%t1%e%ga%{6}%=%t3%e%ga%d%;m + setb=%p1%{8}%/%{6}%*%{4}%+\E[%d%p1%{8}%m%Pa%?%ga%{1}%=%t4%e%ga%{3}%=%t6%e%ga%{4}%=%t1%e%ga%{6}%=%t3%e%ga%d%;m + op=\E[39;49m + bce +</PRE> +<P> + +If you are always using the same display it probably won't matter to you +if the color pairs red/blue and cyan/yellow are flipped, since you'll +always be seeing them flipped. +You will get different defaults than on a display with them not flipped, +but that's about all. +If you are trying to use the same pinerc file from displays with different +color characteristics, or from <EM>Alpine</EM> and <EM>PC-Alpine</EM>, you will +have to be more careful. +The colors numbered 0 through 7 may be used portably between different +systems if you are careful to make them correspond to the ANSI order mentioned +above. +You can check this by looking at a color configuration screen for one of the +colors. +The first eight colors should be in the order above. +If they aren't, you could fix that by modifying your termcap entry on +the UNIX system. +This is not possible if your system uses TERMCAP instead of TERMINFO. + +<HR> + +<H2><A NAME="smime-general">S/MIME Overview</A></H2> + +UNIX <EM>Alpine</EM> only. +<P> +S/MIME is a standard for the public key encryption and signing of email. +UNIX <EM>Alpine</EM> contains a basic implementation of S/MIME based on +the <A HREF="http://www.openssl.org/">OpenSSL</A> libraries. +<P> +Some limitations: +<UL> + <LI> There is no <EM>PC-Alpine</EM> implementation. + <LI> There is no provision for checking for CRLs + (Certificate Revocation Lists) in <EM>Alpine</EM>. + <LI> This built-in S/MIME implementation is not compatible with and does not help with PGP. + <LI> There is no mechanism available for feeding either an entire incoming + or an entire outgoing message to an external + filter and using that external filter to do S/MIME or PGP processing. + <LI> Because the implementation currently uses OpenSSL, there is only a very + limited integration with the Mac OS Keychain (the storing and access of + public certificates). + <LI> There is no way to view or manipulate the lists of certificates from + within <EM>Alpine</EM>. +</UL> +<P> +The S/MIME configuration screen is reached by going to the Main Menu and typing +the "S Setup" command followed by "M S/MIME". +<P> + +<H3>S/MIME BASICS</H3> + +In order to digitally sign messages you send you must have a public/private key-pair. +This may be obtained from a public Certificate Authority (CA) such as Thawte, Verisign, Comodo, +or GoDaddy; or from a smaller CA such as a university which provides certificates for its +users or a company which provides certificates for its workers. +These certificates are bound to an email address, so the identity being verified is the +email address not a person's name. +<P> +Mail is signed by using the sender's private key, which only the owner of the private key +has access to. +The signature is verified using the signer's public key, which anyone can +have access to. +With <EM>Alpine</EM>, the first time you receive a signed message the public key of the +sender will be stored for future use. + +<P> +Mail is encrypted using the recipient's public key and decrypted by +the recipient with their private key. + +<P> +You need a key of your own in order to sign outgoing messages and to have others +encrypt messages sent to you. +You do not need a key of your own to verify signed messages sent by others or to +encrypt messages sent to others. + +<H3>ALPINE S/MIME CERTIFICATE STORAGE</H3> + +By default UNIX <EM>Alpine</EM> stores the certificates it uses in a directory in your +home directory. +The directory name is +<P> +<CENTER><SAMP>.alpine-smime</SAMP></CENTER> +<P> +Within that directory are three subdirectories. +Each of the three subdirectories contains files with PEM-encoded contents, +the default format for OpenSSL. +The "<SAMP>public</SAMP>" directory contains public certificates. +The files within that directory have names that are email addresses with the +suffix "<SAMP>.crt</SAMP>" appended. +An example filename is +<P> +<CENTER><SAMP>user@example.com.crt</SAMP></CENTER> +<P> +The "<SAMP>private</SAMP>" directory contains private keys, probably just one for +your private key. +These are also email addresses but with the suffix "<SAMP>.key</SAMP>" instead. +The third directory is "<SAMP>ca</SAMP>" and it contains certificates for any Certificate +Authorities that you want to trust but that aren't contained in the set of system CAs. +Those files may have arbitrary names as long as they end with the +suffix "<SAMP>.crt</SAMP>". + +<H3>HOW TO SIGN AND ENCRYPT</H3> + +If you have a certificate you may sign outgoing messages. +After typing the Ctrl-X command to send a message you will see the prompt +<P> +<CENTER><SAMP>Send message?</SAMP></CENTER> +<P> +Available subcommands include "G Sign" and "E Encrypt". +Typing the "G" command will change the prompt to +<P> +<CENTER><SAMP>Send message (Signed)?</SAMP></CENTER> +<P> +Typing the "E" command will change the prompt to +<P> +<CENTER><SAMP>Send message (Encrypted)?</SAMP></CENTER> +<P> +You may even type both to get +<P> +<CENTER><SAMP>Send message (Encrypted, Signed)?</SAMP></CENTER> +<P> + +<H3>HOW TO READ SIGNED OR ENCRYPTED MESSAGES</H3> + +The reading of a signed message should not require any special action on +your part. +There should be an editorial addition at the start of the message which +says either +<P> +<CENTER><SAMP>This message was cryptographically signed.</SAMP></CENTER> +<P> +or +<P> +<CENTER><SAMP>This message was cryptographically signed but the signature could not be verified.</SAMP></CENTER> +<P> +If an encrypted message is sent to you the encrypted text will not +be shown. +You will have to type the "Ctrl-D Decrypt" command (from the screen where +you are viewing the message) and supply your passphrase when asked. +<P> +For a signed or encrypted message there is also a "Ctrl-E Security" command +which gives you some information about the certificate used to sign or encrypt the message. + +<H3>MISCELLANEOUS</H3> + +You may have access to a private certificate in the PKCS12 format, +which would sometimes be in a file with a ".p12" suffix. +The UNIX shell command +<P> +<CENTER><SAMP>openssl pkcs12 -in file.p12 -out file.pem</SAMP></CENTER> +<P> +may work to convert that from the PKCS12 format to the PEM format. +Then that file could be placed in the "<SAMP>private</SAMP>" +directory with a filename of your email address followed by the +suffix "<SAMP>.key</SAMP>". + +<HR> + +<H2><A NAME="pc-notes">Additional Notes on PC-Alpine</A></H2> + +Below are a few odds and ends worth mentioning about <EM>PC-Alpine</EM>. They have +to do with DOS-specific behavior that is either necessary or useful (and +sometimes both!). <P> + +As <EM>PC-Alpine</EM> runs in an environment with limited access control, accounting +or auditing, an additional line is automatically inserted into the header +of mail messages generated by <EM>PC-Alpine</EM>: + +<PRE> + X-Sender: <userid>@<imap.host><BR> +</PRE> +<P> + +By popular demand of system administrators, <EM>PC-Alpine</EM> has been modified to +prevent sending messages until the user has successfully logged into a +remote mail server. Even though <EM>PC-Alpine</EM> cannot prevent users from +changing the apparent identity of the sender of a message, the IMAP server +login name and host name included in the <EM>X-Sender</EM> line +provide some level of traceability by the recipient. +However, this should not be considered a +rigorous form of authentication. It is extremely lightweight, and is not +a replacement for true authentication. <P> + +Hand in hand with authentication and accounting is user information. +Since <EM>PC-Alpine</EM> has no user database to consult for <EM>user-id</EM>, +<EM>personal-name</EM>, etc., necessary information must be provided by +the user/installer before <EM>PC-Alpine</EM> can properly construct the "From" +address required for outbound messages. <EM>PC-Alpine</EM> will, by default, prompt +for the requisite pieces as they are needed. This information corresponds +to the <EM>PINERC</EM> variables +<A HREF="config.html#user-id"><EM>user-id</EM></A>, +<A HREF="config.html#personal-name"><EM>personal-name</EM></A>, +<A HREF="config.html#user-domain"><EM>user-domain</EM></A>, +and <A HREF="config.html#smtp-server"><EM>smtp-server</EM></A>. <P> + +The user is then asked whether or not this information should +automatically be saved to the <EM>PINERC</EM>. This is useful behavior in +general, but can lead to problems in a lab or other shared environment. +Hence, these prompts and automatic saving of configuration can be turned +off on an entry by entry basis by setting any of the above values in the +<EM>PINERC</EM> to the null string (i.e., a pair of double quotes). This +means that the user will be prompted for the information once during each +<EM>Alpine</EM> session, and no opportunity to save them in the <EM>PINERC</EM> will +be offered. <P> + +Another feature of DOS is the lack of standard scratch area for temporary +files. During the course of a session, <EM>PC-Alpine</EM> may require numerous +temporary files (large message texts, various caches, etc.). Where to +create them can be a problem, particularly when running under certain +network operating systems. <EM>PC-Alpine</EM> observes the +<EM>TMPDIR</EM>, <EM>TMP</EM>, and +<EM>TEMP</EM> environment variables, and creates temporary files in the +directory specified by either. In their absence, <EM>PC-Alpine</EM> creates these +files in the root of the current working drive. +Some temporary files have to be created in the same directory as the file +they are a temporary copy of. For example, a pinerc file or a address book +file. +<P> + +<!-- pnuts --> + +</BODY> +</HTML> diff --git a/doc/tech-notes/config.html b/doc/tech-notes/config.html new file mode 100644 index 00000000..b9354838 --- /dev/null +++ b/doc/tech-notes/config.html @@ -0,0 +1,12523 @@ +<HTML><HEAD><TITLE>Alpine Technical Notes: Configuration and Preferences</TITLE></HEAD><BODY> +<H1>Configuration and Preferences</H1> + +<H2><A NAME="pine-conf">Alpine Configuration</A></H2> + +There is very little in <EM>Alpine</EM> which <STRONG>requires</STRONG> compile-time +configuration. In most cases, the compiled-in preferences will suit users +and administrators just fine. When running <EM>Alpine</EM> on a UNIX system, the +default built-in configuration can be changed by setting variables in the +system configuration files, <CODE>/usr/local/lib/pine.conf</CODE> +or <CODE>/usr/local/lib/pine.conf.fixed</CODE>. +(Actually, these files can be changed using the configure arguments +--with-system-pinerc=VALUE or --with-system-fixed-pinerc=VALUE.) +The location of the pine.conf file can be changed with the -P command line +argument. +Both <EM>Alpine</EM> +and <EM>PC-Alpine</EM> also use personal (user-based) configuration files. +On UNIX machines, the personal configuration file is the +file <CODE>~/.pinerc</CODE>. +For <EM>PC-Alpine</EM> systems, the personal configuration file is in +<CODE>$PINERC</CODE> or <CODE><PineRC registry value></CODE> or +<CODE>${HOME}\ALPINE\PINERC</CODE> or +<CODE><ALPINE.EXE </CODE>dir<CODE>>\PINERC</CODE>. +Or the personal configuration file can be specified with the -p command +line argument. +<P> +All of these configuration files, other than the fixed system +config <CODE>pine.conf.fixed</CODE> on UNIX systems, may optionally +be remote configuration files instead of local files. +This is discussed further in the following section and in +<A HREF="low-level.html#remote-config"><EM>Remote Configuration</EM></A>. + +<P> +After the personal configuration, <EM>Alpine</EM> may optionally use +a personal exceptions configuration file which is specified with the +command line option "-x exceptions_config". +"Exceptions_config" may also be either a local file or a remote +configuration folder. +For Unix <EM>Alpine</EM>, if you don't have a "-x" command line option, +<EM>Alpine</EM> will look for the file "<CODE>.pinercex</CODE>" +in the same local directory that the regular config file is located in. +If the regular config file is remote then Unix <EM>Alpine</EM> looks in the home +directory for "<CODE>.pinercex</CODE>". +<P> +For <EM>PC-Alpine</EM>, if you don't have a "-x" command line option, +<EM>PC-Alpine</EM> will use the value of the +environment variable <CODE>$PINERCEX</CODE>. +If that is not set, <EM>PC-Alpine</EM> will look for +the local file "<CODE>PINERCEX</CODE>" +in the same local directory that the regular config file is located in. +If the regular config file is remote then <EM>PC-Alpine</EM> looks in the +local directory specfied by the "-aux local_directory" command +line argument, or the directory <CODE>${HOME}\ALPINE</CODE>, or +in <CODE><ALPINE.EXE </CODE>directory<CODE>></CODE>. +<P> + +The syntax of a non-list configuration variable is this: + +<BLOCKQUOTE> +<variable> = <value><BR> +</BLOCKQUOTE> + +If the value is absent then the variable is unset. To set a variable to +the empty value two double quotes (""). This is equivalent to an absent value +except that it overrides any system-wide default 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, +<EM>use-only-domain-name</EM>, for which the only +appropriate values are <EM>yes</EM> and <EM>no</EM>. That's because it is +a variable from the early days of <EM>Alpine</EM> before features existed. +<P> + +There is also a +second type of variable, lists. A list is a comma-separated list of +values. The syntax for a list is: + +<BLOCKQUOTE> +<variable> = <value> [, <value> , ... ]<BR> +</BLOCKQUOTE> + +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 <CODE>#</CODE>. <P> + +For UNIX <EM>Alpine</EM>, there are five ways in which each variable can be set. +In decreasing order of precedence they are: + +<OL> + +<LI> the system-wide <EM>fixed</EM> configuration file + +<LI> a command line argument + +<LI> the personal exceptions file + +<LI> the personal configuration file + +<LI> the system-wide configuration file. + +</OL><P> + +If the variable is not set in any of those places, there is a default +setting in the source code. +<P> +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. +<EM>PC-Alpine</EM> has the same list, except that it +does not use a system-wide <EM>fixed</EM> configuration file. +This can be modified slightly by using inheritance, which is covered below. +<P> + +You may get a sample/fresh copy of the system configuration file by +running <EM>alpine -conf</EM>. The result will be printed on the standard +output with very short comments describing each variable. (The online help in +the Setup screens provides much 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 <EM>Alpine</EM>. +It is by no means a bullet-proof method.) <EM>Alpine</EM> will automatically create +the personal configuration file the first time it is run, so there is no +need to generate a sample. <EM>Alpine</EM> 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 <EM>Alpine</EM> to set the values in this file. If a +user does add additional comments to the personal configuration file they +will be retained. +<P> + +References to environment variables may be included in the <EM>Alpine</EM> +configuration files. The format is <CODE>$variable</CODE> or +<CODE>${variable}.</CODE> The character <CODE>~</CODE> will be expanded to the +<CODE>$HOME</CODE> environment variable. +For a more complete explanation of how environment variables work, see +the section +<A HREF="config-notes.html#env-variables">Using Environment Variables</A>.<P> + +When environment variables are used for <EM>Alpine</EM> settings which take lists, +you must have an environment variable set for each member of the list. +That is, <EM>Alpine</EM> 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 <EM>Alpine</EM> configuration file, which +will expand to nothing. <P> + +<H3>Remote and Local Configuration</H3> + +There are two types of storage for configuration information. +<EM>Local</EM> configuration files are used by default. +These are just regular files on the UNIX system or on the PC. +<EM>Remote</EM> 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 +<A HREF="low-level.html#remote-config"><EM>Remote Configuration</EM></A>. + +<H3>Generic and Exceptional Configuration</H3> + +If you use <EM>Alpine</EM> 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 <EM>Alpine</EM> 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. +<P> +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. +<P> +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 +<A HREF="cmd-line.html#copy_pinerc">copy_pinerc</A> +may also be useful. + +<H3>Configuration Inheritance</H3> + +Configuration inheritance is a power user feature. +It is confusing and not completely supported by the configuration +user interface. +<P> +For configuration variables which are lists, like "smtp-server" or +"incoming-folders", +the inheritance mechanism makes it possible to <EM>combine</EM> +the values of options from different configuration locations instead +of <EM>replacing</EM> the value. +<A HREF="config-notes.html#config-inheritance">Configuration Inheritance</A> +has more information about how inheritance is used. +<P> + +<HR> + +<H2><A NAME="gen-conf">General Configuration Variables</A></H2> + +The following is a list of all <EM>Alpine</EM> configuration variables, in +alphabetical order. Note that not all variables apply to all versions of +<EM>Alpine</EM> 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 <EM>variables</EM>. +<A HREF="#features-conf">Configuration <EM>Features</EM></A> +are in a separate section. +<P> + +<DL COMPACT> + +<DT> <A NAME="addrbook-sort-rule"><EM>addrbook-sort-rule</EM></A> + +<DD> This variable sets up the default address book sorting. Currently, +<EM>Alpine</EM> will accept the values <EM>dont-sort</EM>, +<EM>fullname-with-lists-last</EM>, <EM>fullname</EM>, +<EM>nickname-with-lists-last</EM>, and <EM>nickname</EM>. The default is +to sort by fullname with lists last. +If you use an address book from more than one computer and those +computers sort the address book differently then the sort order +will be the order where the last change to the address book was +made. +There are two reasons the sorting might be different on different +systems. +First, the addrbook-sort-rule may be set differently in the two +places. +Second, the collation rules on the two computers may be different. +For example, one system might ignore special characters while the other +doesn't or one may sort upper and lower case letters together while +the other doesn't. +In any case, the order you see is the order on the system where the +last change was made, for example by an address book edit or a +Take Address command. +<P> +This option is displayed as "Addressbook Sort Rule". +<P> + +<DT> <A NAME="pers-abook"><EM>address-book</EM></A> + +<DD> 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 <A HREF="low-level.html#addrbook"><EM>Remote address book</EM></A>. +Remote folder syntax is discussed in +<A HREF="config-notes.html#remote-folders">Syntax for Remote Folders</A>. +This list of address books will be combined with the +<A HREF="#glob-abook"><EM>global-address-book</EM></A> +list to arrive at the complete set of address books. <P> + +<DT> <A NAME="abook-formats"><EM>addressbook-formats</EM></A> + +<DD> 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. <P> + +<DT> <A NAME="alt-addresses"><EM>alt-addresses</EM></A> + +<DD> This option provides a place for you to list alternate email addresses +you may have. +Each address in the list should be the actual email address part of an +address, without the full name field or the angle brackets. +For example: + +<P> +<CENTER><SAMP>user@example.com</SAMP></CENTER> +<P> + +The matching is case-insensitive, so this would match any of +<SAMP>User@example.com</SAMP>, <SAMP>user@Example.Com</SAMP>, or +<SAMP>USER@EXAMPLE.COM</SAMP> as well. + +<P> +If set, the option affects the behavior of the Reply +command and the "+" symbol in the MESSAGE INDEX, which denotes that +a message has been addressed specifically to you. + +<P> +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. + +<P> +With respect to Reply, the reply-to-all option will exclude addresses +listed here. + +<P> +The feature +<A HREF="#copy-to-to-from">copy-to-address-to-from-if-it-is-us</A> +is somewhat related to this option. + +<P> +In addition to a list of actual addresses, +you may use regular expressions (as used with egrep with the ignore case flag) +to describe the addresses you want to match. +<EM>Alpine</EM> will somewhat arbitrarily interpret your entry as a regular +expression if it contains any of the characters +*, |, +, ?, {, [, ^, $, or \. +Otherwise, it will be treated literally. +The feature +<A HREF="#disable-regex">disable-regular-expression-matching-for-alternate-addresses</A> +may be used to turn off regular expression processing regardless of whether or not +special characters appear in the entry. + +<P> +A description of how regular expressions work is beyond the +scope of this help text, but some examples follow. + +<P> +The entry + +<P> +<CENTER><SAMP>.*@example.com</SAMP></CENTER> +<P> + +in the alt-addresses list would mean that any +address with a domain name of <SAMP>example.com</SAMP> (such as +<SAMP>fred@example.com</SAMP> or <SAMP>wilma@example.com</SAMP>) will be considered +one of your alternate addresses. +Strictly speaking, the dot in <SAMP>example.com</SAMP> ought to be escaped with +a backslash, as in <SAMP>example\.com</SAMP>, and a dollar sign anchor ought +to come at the end of the expression to prevent a match of <SAMP>example.com.org</SAMP>. +Complicating things further, the dollar sign +is special in the <EM>Alpine</EM> configuration (it signifies environment variable expansion) +so the dollar sign should be doubled or backslash escaped for <EM>Alpine</EM>'s sake. +Quotes around the whole expression will not escape the dollar sign successfully. +So this example should look like + +<P> +<CENTER><SAMP>.*@example\.com$$</SAMP></CENTER> +<P> + +<P> +The entry + +<P> +<CENTER><SAMP>^fred[0-9]*@example.com$$</SAMP></CENTER> +<P> + +would match +<SAMP>fred3@example.com</SAMP> or <SAMP>fred17@example.com</SAMP> as well +as <SAMP>fred@example.com</SAMP>. + +<P> +You could match all addresses that look like +<SAMP>fred+stuff@example.com</SAMP> for any value of <SAMP>stuff</SAMP> with the +entry + +<P> +<CENTER><SAMP>^fred\+.*@example.com$$</SAMP></CENTER> +<P> + +Notice that you have to escape the plus sign with a backslash because plus +is a special character in regular expressions. +If you wanted to match plain <SAMP>fred</SAMP> as well as <SAMP>fred+stuff</SAMP> +the expression + +<P> +<CENTER><SAMP>^fred(()|\+.*)@example.com$$</SAMP></CENTER> +<P> + +would do it, but it would be easier to just add fred@example.com as a +separate entry. + +<P> +One more example, a match of all first-level subdomains, is given by + +<P> +<CENTER><SAMP>^fred@[[:alnum:]_-]*\.example\.com$$</SAMP></CENTER> +<P> + +<P> +Because the regular expression matching is based on an old library +(<SAMP>hs_regex</SAMP>) the regular expressions might not work exactly as you expect, +but they should be close. + +<P> +This option is displayed as "Alternate Addresses". + +<DT> <A NAME="bugs-add"><EM>bugs-additional-data</EM></A> + +<DD> System-wide configuration files only. Program/Script used by +<EM>Report Bug</EM> command. Output from the program/script is +captured and attached to the bug report. <P> + +<DT> <A NAME="bugs"><EM>bugs-fullname</EM></A>, +<EM>bugs-address</EM>, <EM>local-fullname</EM>, <EM>local-address</EM>, +<EM>suggest-fullname</EM>, and <EM>suggest-address</EM> + +<DD> System-wide configuration files only. These are used by the bug +report commands which can be accessed from some of the Help screens. +<P> + +<DT> <A NAME="busy-cue-rate"><EM>busy-cue-rate</EM></A> + +<DD> When <EM>Alpine</EM> is delayed for some reason it usually shows that +something is happening with a small animated display in the status +message line near the bottom of the screen. +This option sets how frequently the characters (for example, a spinning bar) +in the active status message lines are updated. +At most, it can be set to be udpated 20 times per second. + +<P> +Setting this value to zero will prevent display of the animations +altogether. + +<P> +The option +<A HREF="#busy-cue-spinner-only"><EM>busy-cue-spinner-only</EM></A> +can be used to remove the randomness from this animated display. +<P> + +<DT> <A NAME="char-set"><EM>character-set</EM></A> + +<DD> This is now obsolete, replaced by three separate variables: +<EM>display-character-set</EM>, +<EM>keyboard-character-set</EM>, and +<EM>posting-character-set</EM>. +See the section on +<A HREF="low-level.html#char-set">International Character Sets</EM></A> for more +details.<P> + +<DT> <A NAME="color-style"><EM>color-style</EM></A> + +<DD> UNIX <EM>Alpine</EM> only (color is automatically on with <EM>PC-Alpine</EM>). +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 <EM>Alpine</EM>. +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. +<P> +This variable may be set to any of the following values: +<P> + +<DL> +<DT>no-color</DT> +<DD>Don't use color. +</DD> + +<DT>use-termdef</DT> +<DD>In order to decide if your terminal is capable of color, +<EM>Alpine</EM> looks in +the terminal capabilities database, TERMINFO or TERMCAP, depending on +how <EM>Alpine</EM> was compiled. +This is a good option to choose if you switch between a color and a non-color +terminal with the same <EM>Alpine</EM> configuration. +<EM>Alpine</EM> will know to use color on the color terminal because +it is described +in the termcap entry, and <EM>Alpine</EM> will know to use black and white on the +non-color terminal. +<A HREF="config-notes.html#color-config-notes">Color Details</A> +has more information about configuring a termcap entry for color. +This is usually something a system administrator does. +</DD> + +<DT>force-ansi-8color</DT> +<DD>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 <EM>Alpine</EM> 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 + + <P><CENTER>ESC [ 3 <color_number> m</CENTER><P> + +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. +There is also a 9th color available, the last one shown, which is the default +color from the terminal emulator. +When used as a background color some people refer to this color as +"transparent", which is why the letters "TRAN" are +shown in the color swatch of the SETUP COLOR screen. +The foreground transparent color is shown as +the color of the "TRAN" text. +(The transparent color will not work correctly in a PC-Alpine configuration.) +The escape sequences used to set the background colors are the same +as for the foreground colors except a "4" replaces the "3". +<P> +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. +</DD> + +<DT>force-ansi-16color</DT> +<DD>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 (plus a 17th for +the transparent color), it's working. +</DD> + +<DT>force-xterm-256color</DT> +<DD>Some versions of xterm (and some other terminal emulators) +have support for 256 colors. +The escape sequences used to set the foreground colors are + + <P><CENTER>ESC [ 38 ; 5 ; <color_number> m</CENTER><P> + +where the color_number is an ASCII digit between 0 and 255. +Background colors are the same with the 38 replaced with a 48. +The numbers 0 through 15 are probably similar to the 16 color version +above, then comes a 6x6x6 color cube, followed by 24 colors of gray. +The terminal default (transparent) color is the 257th color at the bottom. +Some terminal emulators will misinterpret these escape sequences causing +the terminal to blink or overstrike characters or to do something else +undesirable. +<P> +The PuTTY terminal emulator has an option called "Allow terminal to +use xterm 256-colour mode" which allows PuTTY to work well with +this 256-color setting. + +</DD> +</DL> + +<P> +There are two other possible color values which may be useful in some +situations. +In the color configuration screens there will sometimes be a color which has +the label "NORM" inside its color swatch. +If this is selected the corresponding foreground or background +<A HREF="#normal-color"><EM>Normal Color</EM></A> +will be used. +Another similar color is the one that has the +label "NONE" inside its color swatch. +The meaning of this setting is that no color changing will be done. +This NONE color is only useful in contexts where <EM>Alpine</EM> is already +coloring the text some color other than the Normal Color. +For example, if the +<A HREF="#reverse-color"><EM>Reverse Color</EM></A> is set then the current +line in the MESSAGE INDEX will be colored. +If one of the index symbols (for example, the Index-to-me Symbol) has the NONE +color as its background then the symbol's foreground color will be used +to draw the actual text but the background color will be the same as whatever +the background color already was. +The color values which end up in the configuration file for these special +values are the 11-character words "norm-padded", "none-padded", +and "transparent". + +<P> +The normal default is "no-color". +<P> +Once you've turned on color you may set the +colors of many objects on the screen individually. +The <A HREF="#color-config">Color Configuration</A> 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 <EM>Alpine</EM> supports are configurable there. +<A HREF="#index-color-config">Index line color</A> is configured separately. +<P> + +<DT> <A NAME="composer-word-separators"><EM>composer-word-separators</EM></A> + +<DD> This option affects how a "word" is defined in the composer. +The definition of a word is used when using the Forward Word and Backward +Word commands in the composer, as well as when using the spell checker. +Whitespace is always considered a word separator. +Punctuation (like question marks, periods, commas, and so on) is always +a word separator if it comes at the end of a word. +By default, a punctuation character which is in the middle of a word does +not break up that word as long as the character before and the character +after it are both alphanumeric. +If you add a character to this option it will be considered a +word separator even when it occurs in the middle of an alphanumeric word. +For example, if you want to skip through each part of an address instead +of skipping the whole address at once you might want to include"@" +and "." in this list. +If you want the word-skipper to stop on each part of a UNIX filename you +could add "/" to the list. +The equal sign and dash are other possibilities you might find helpful. +<P> + +<DT> <A NAME="composer-wrap-column"><EM>composer-wrap-column</EM></A> + +<DD> This option specifies an aspect of <EM>Alpine</EM>'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 <EM>74</EM>. The largest allowed setting is normally <EM>80</EM> 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. +<P> + +<DT> <A NAME="current-indexline-style"><EM>current-indexline-style</EM></A> + +<DD> <A HREF="#cur-il-style"><EM>current-indexline-style</EM></A>. +<P> + +<DT> <A NAME="cust-hdr"><EM>customized-hdrs</EM></A> + +<DD> 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 +<A HREF="#def-comp"><EM>default-composer-hdrs</EM></A> 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 <EM>displayed</EM> +when you view a message, take a look at the +<A HREF="#viewer-hdrs"><EM>viewer-hdrs</EM></A> +option instead.) +Here's an example which shows how you might set your From address +<P> +<CENTER><SAMP>From: Full Name <user@example.com></SAMP></CENTER> +<P> +and another showing how you might set a Reply-To address +<P> +<CENTER><SAMP>Reply-To: user@example.com</SAMP></CENTER> +<P> +You may also set non-standard header values here. +For example, you could add +<P> +<CENTER><SAMP>Organization: My Organization Name</SAMP></CENTER> +<P> +or even +<P> +<CENTER><SAMP>X-Favorite-Colors: Purple and Gold</SAMP></CENTER> +<P> +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 +<P> +<CENTER><SAMP>Reply-To:</SAMP></CENTER> +<P> +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. +<P> +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 <EM>NOT</EM> be used. +The subject derived from the subject of the message you are Replying +to will be used instead. +<P> +It is also possible to make header setting even more complicated and more +automatic by using +<A HREF="#role-config"><EM>Roles</EM></A>, +but if all you want to do is set a default value for a header, you don't +need to think about Roles. +<P> +If you change your From address you may also find it useful to add the +changed From address to the +<A HREF="#alt-addresses"><EM>alt-addresses</EM></A> +configuration option. +<P> +Limitation: Because commas are used to separate the list of +Customized-Headers, it is not possible to have the value of a +header contain a comma. +Nor is there currently an "escape" mechanism provided +to make this work. +<P> +This option is displayed as "Customized Headers". +<P> + +<DT> <A NAME="dead-letter-files"><EM>dead-letter-files</EM></A> + +<DD> This option affects <EM>Alpine</EM>'s behavior when you cancel a message being +composed. <EM>Alpine</EM>'s usual behavior is to write the canceled message to +a file named +"dead.letter" in your home directory, or +"DEADLETR" when using <EM>PC-Alpine</EM>, +overwriting any previous message. +<P> +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. + +<P> +If you set this option to zero, then NO record of canceled messages is +maintained. +<P> +If the feature +<A HREF="#quell-dead-letter-on-cancel">Quell-Dead-Letter-On-Cancel</A> +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. +<P> + +<DT> <A NAME="def-comp"><EM>default-composer-hdrs</EM></A> + +<DD> 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 <A HREF="#cust-hdr"><EM>Customized-Hdrs</EM></A> +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:. +<P> + +Note that the "Newsgroups:" header will be abbreviated in the Composer +display, but should be spelled out in full here. +<P> +This option is displayed as "Default Composer Headers". +<P> + +<DT> <A NAME="def-fcc"><EM>default-fcc</EM></A> + +<DD> The name of the folder to which all outgoing mail goes is set here. +The compiled-in default is <EM>sent-mail</EM> (UNIX) or <EM>sentmail</EM> +(PC). It can be set to "" (two double quotes with nothing between them) +to turn off saving copies of outgoing mail. If <EM>default-fcc</EM> is a +relative file name, then it is relative to your default collection for +saves (see <A HREF="#fold-coll"><EM>folder-collections</EM></A>). <P> +This option is displayed as "Default Fcc (File carbon copy)". +<P> + +<DT> <A NAME="def-save"><EM>default-saved-msg-folder</EM></A> + +<DD> This option determines the default folder name for <EM>Saves</EM>... +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 +<A HREF="#saved-msg-name"><EM>saved-msg-name-rule</EM></A> +doesn't override it. +Unix <EM>Alpine</EM> default is normally +<EM>saved-messages</EM> in the default folder collection. +<EM>PC-Alpine</EM> default is <EM>SAVEMAIL</EM> +(normally stored as <EM>SAVEMAIL.MTX</EM>). <P> +This option is displayed as "Default Saved Message Folder". +<P> + +<DT> <A NAME="disable-these-auths"><EM>disable-these-authenticators</EM></A> + +<DD> 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. +<P> + +<EM>Alpine</EM> 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, <EM>Alpine</EM> will revert to plaintext +login (or, in the case of SMTP, will be unable to authenticate at all). +<P> + +The candidates for disabling are listed below. +There may be more if you compile <EM>Alpine</EM> with additional authenticators +and/or a newer version of the c-client library. +<P> + +<UL> +<LI> GSSAPI +<LI> CRAM-MD5 +<LI> PLAIN +<LI> LOGIN +</UL> +<P> + +Normally, you will not disable any authenticators. +There are two exceptions: +<P> + +<OL> +<LI> You use a broken server that advertises an authenticator, +but does not actually implement it. +<LI> You have a Kerberos-capable version of <EM>Alpine</EM> 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 <EM>Alpine</EM>'s Kerberos support). +</OL> + +<P> +It is never necessary to disable authenticators, since <EM>Alpine</EM> will try +other authenticators before giving up. +However, disabling the relevant authenticator avoids annoying error messages. +<P> + +<DT> <A NAME="disable-these-drivers"><EM>disable-these-drivers</EM></A> + +<DD> 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 <EM>Alpine</EM> with +a newer version of the c-client library. +<P> + +<UL> +<LI> mbox +<LI> mbx +<LI> mh +<LI> mix +<LI> mmdf +<LI> mtx +<LI> mx +<LI> news +<LI> phile +<LI> tenex +<LI> unix +</UL> +<P> + +The <EM>mbox</EM> driver enables the following behavior: if there is a +file called <CODE>mbox</CODE> +in your home directory, and if that file is either empty or in Unix mailbox +format, then every time you open <EM>INBOX</EM> the <EM>mbox</EM> driver +will automatically transfer mail from the system mail spool directory into the +<CODE>mbox</CODE> file and +delete it from the spool directory. If you disable the <EM>mbox</EM> driver, +this will not happen. +<P> + +It is not recommended to disable the driver which supports the system default +mailbox format. On most non-SCO systems, that driver is the +<EM>unix</EM> driver. +On most SCO systems, it is the <EM>mmdf</EM> driver. +The system default driver may be +configured to something else on your system; check with your system manager +for additional information. +<P> + +It is most likely not very useful for you to disable any of the drivers other +than possibly <EM>mbox</EM>. +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. +<P> + +<DT> <A NAME="disp-char-set"><EM>display-character-set</EM></A> + +<DD> See the discussion in +<A HREF="low-level.html#char-set">International Character Sets</EM></A> for +details.<P> + +<DT> <A NAME="display-filters"><EM>display-filters</EM></A> + +<DD> 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. +<P> +Display filters do not work with <EM>PC-Alpine</EM>. +<P> + +The command is executed and the message is piped into its standard input. +The standard output of the command is read back by <EM>Alpine</EM>. The +<EM>_TMPFILE_</EM> token (see below) overrides this default behavior. + +<P> +The filter's use is based on the configured <EM>trigger</EM> string. The +format of a filter definition is: + +<P> +<CENTER><trigger> <command> <arguments></CENTER> + +<P> +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. + +<P> +The <EM>trigger</EM> 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. + +<P> +Trigger Modifying Tokens: +<DL> +<DT><EM>_CHARSET(<VAR>string</VAR>)_</EM> +<DD>This token tells <EM>Alpine</EM> to invoke the supplied command +if the text is in a character set matching <VAR>string</VAR> +(e.g., ISO-8859-2 or ISO-2022-JP). + +<DT><EM>_LEADING(<VAR>string</VAR>)_</EM> +<DD>This token tells <EM>Alpine</EM> to invoke the supplied command +if the enclosed <VAR>string</VAR> is found to be the first +non-whitespace text. +<BR>NOTE: Quotes are necessary if <VAR>string</VAR> contains +the space character. + +<DT><EM>_BEGINNING(<VAR>string</VAR>)_</EM> +<DD>This token tells <EM>Alpine</EM> to invoke the supplied command +if the enclosed <VAR>string</VAR> is found at the beginning +of any line in the text. +<BR>NOTE: Quotes are necessary if <VAR>string</VAR> contains +the space character. +</DL> + +<P> +The "command" and "arguments" portion is simply +the command line to be invoked if the trigger string is found. Below +are tokens that <EM>Alpine</EM> will recognize and replace with special values +when the command is actually invoked. + +<P> +Command Modifying Tokens: + +<DL> +<DT><EM>_TMPFILE_</EM> +<DD>When the command is executed, this token is +replaced with the path and name of the temporary +file containing the text to be filtered. <EM>Alpine</EM> +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. +<EM>Alpine</EM> restores the tty modes before invoking the +filter in case the filter interacts with the user +via its own standard input and output. + +<DT><EM>_RESULTFILE_</EM> +<DD>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. <EM>Alpine</EM> displays this in the message status +field. + +<DT><EM>_DATAFILE_</EM> +<DD>When the command is executed, this token is +replaced with the path and name of a temporary +file that <EM>Alpine</EM> 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. + +<DT><EM>_PREPENDKEY_</EM> +<DD>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 <EM>Alpine</EM> session +and is only generated once per session. +</DL> + +<P> +The feature +<A HREF="#disable-terminal-reset-for-display-filters"><EM>disable-terminal-reset-for-display-filters</EM></A> is related. +<P> +Performance caveat/considerations: +<BR> +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. +<P> +Limitation: +<BR> +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. +<P> + +<DT> <A NAME="download-command"><EM>download-command</EM></A> + +<DD> This option affects the behavior of the <EM>Export</EM> command. +It specifies a Unix program name, and any necessary command line arguments, +that <EM>Alpine</EM> can use to transfer the exported message to your +personal computer's disk. +<P> + +<DT> <A NAME="download-command-prefix"><EM>download-command-prefix</EM></A> + +<DD> This option is used in conjunction with the <EM>download-command</EM> +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). <P> + +<DT> <A NAME="editor"><EM>editor</EM></A> + +<DD> UNIX <EM>Alpine</EM> 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 +<A HREF="#enable-alt-imp"><EM>enable-alternate-editor-implicitly</EM></A> +feature is set. <P> + +<DT> <A NAME="empty-header-message"><EM>empty-header-message</EM></A> + +<DD> When sending, if both the To and Cc fields are empty and you +are sending the message to a Bcc, +<EM>Alpine</EM> 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 +<EM>empty-header-message</EM> variable to something else. +<P> + +<DT> <A NAME="fcc-name-rule"><EM>fcc-name-rule</EM></A> + +<DD> Determines default folder name for fcc when composing. Currently, +<EM>Alpine</EM> will accept the values <EM>default-fcc</EM>, <EM>by-recipient</EM>, +or <EM>last-fcc-used</EM>. If set to <EM>default-fcc</EM>, then <EM>Alpine</EM> will +use the value defined in the <A HREF="#def-fcc"><EM>default-fcc</EM></A> +variable (which itself +has a default) for the Fcc header field. If set to <EM>by-recipient</EM>, +then <EM>Alpine</EM> 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 <EM>Alpine</EM> 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. +<P> + +<DT> <A NAME="feat-list"><EM>feature-list</EM></A> + +<DD> This is a list of the many features (options) which may be turned on +or off. There is a separate section titled +<A HREF="#features-conf">Configuration Features</A> which explains +each of the features. There is some additional explanation about the +<EM>feature-list</EM> variable itself +in <A HREF="config-notes.html#feature-list"><EM>Feature List Variable</EM></A>. +<P> + +<DT> <A NAME="file-directory"><EM>file-directory</EM></A> + +<DD> <EM>PC-Alpine</EM> 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. + +<P> +Normally, when a filename is supplied that lacks a leading "path" +component, <EM>Alpine</EM> 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 <EM>Alpine</EM> should look for files +without a leading path. + +<P> +NOTE: this feature's value is ignored if either +<A HREF="#use-current-dir"><EM>use-current-dir</EM></A> feature +is set or the PINERC has a value for the +<A HREF="#operating-dir"><EM>operating-dir</EM></A> variable. +<P> + +<DT> <A NAME="fold-coll"><EM>folder-collections</EM></A> + +<DD> This is a list of one or more collections where saved mail is stored. +See the sections describing +<A HREF="config-notes.html#collections">folder collections and collection syntax</A> for more information. +The first collection in this list is the default +collection for <EM>Save</EM>s, +including <A HREF="#def-fcc"><EM>default-fcc</EM>'s</A>. +<P> + +<DT> <A NAME="folder-ext"><EM>folder-extension</EM></A> + +<DD> <EM>PC-Alpine</EM> only. File extension used for local folder names. This +is <CODE>.MTX</CODE> by default. +<P> + +<DT> <A NAME="reopen-rule"><EM>folder-reopen-rule</EM></A> + +<DD> <EM>Alpine</EM> normally checks for new mail in the currently open folder +and in the INBOX every few <A HREF="#mail-check"><EM>minutes</EM></A>. + +<P> +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. + +<P> +It may be possible to check for new mail in these cases by reopening the +folder. +<EM>Alpine</EM> 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.) + +<P> +There are some cases where <EM>Alpine</EM> 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 <EM>may</EM> be a way to discover new mail, but <EM>Alpine</EM> +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 <EM>Alpine</EM> will react to the apparent attempt to reopen a folder. + +<P> +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. + +<P> +In the possibilities listed below, the text says "POP/NNTP" in +several places. +That really implies the case where <EM>Alpine</EM> 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: +<P> + +<DL> +<DT>Always reopen</DT> +<DD><EM>Alpine</EM> 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. +</DD> + +<DT>Yes for POP/NNTP, Ask about other remote [Yes]</DT> +<DD><EM>Alpine</EM> 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. +</DD> + +<DT>Yes for POP/NNTP, Ask about other remote [No]</DT> +<DD><EM>Alpine</EM> 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. +</DD> + +<DT>Yes for POP/NNTP, No for other remote</DT> +<DD><EM>Alpine</EM> will assume a Yes answer if the access method is POP or NNTP, and +will assume a No answer for all other remote folders. +</DD> + +<DT>Always ask [Yes]</DT> +<DD><EM>Alpine</EM> will not differentiate based on access method. +It will always ask for all remote folders, with a default answer of Yes. +</DD> + +<DT>Always ask [No]</DT> +<DD><EM>Alpine</EM> will not differentiate based on access method. +It will always ask for all remote folders, with a default answer of No. +</DD> + +<DT>Ask about POP/NNTP [Yes], No for other remote</DT> +<DD><EM>Alpine</EM> 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. +</DD> + +<DT>Ask about POP/NNTP [No], No for other remote</DT> +<DD>This is the default. +<EM>Alpine</EM> 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. +</DD> + +<DT>Never reopen</DT> +<DD><EM>Alpine</EM> will never attempt to reopen already open folders. +</DD> +</DL> + +<P> +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. + +<P> +There is an alternative that may be of useful in some situations. +Instead of manually checking for new mail you can set up a +<A HREF="config-notes.html#maildrop">Mail Drop</A> +and automatically check for new mail. +<P> + +<DT> <A NAME="folder-sort-rule"><EM>folder-sort-rule</EM></A> + +<DD> This option controls the order in which folder list entries will be +presented in the FOLDER LIST screen. Choose one of the following: + + <DL> + <DT> <EM>Alphabetical</EM> + + <DD> sort by alphabetical name independent of type + + <DT> <EM>Alpha-with-dirs-last</EM> + + <DD> sort by alphabetical name grouping directory entries +to the end of the list + + <DT> <EM>Alpha-with-dirs-first</EM> + + <DD> sort by alphabetical name grouping directory entries +to the start of the list + </DL> + +The normal default is <EM>Alphabetical</EM>. +<P> + +<DT> <A NAME="font-name"><EM>font-name</EM></A> + +<DD> Winsock version of <EM>PC-Alpine</EM> only. <P> + +<DT> <A NAME="font-size"><EM>font-size</EM></A> + +<DD> Winsock version of <EM>PC-Alpine</EM> only. <P> + +<DT> <A NAME="font-style"><EM>font-style</EM></A> + +<DD> Winsock version of <EM>PC-Alpine</EM> only. <P> + +<DT> <A NAME="forced-abook"><EM>forced-abook-entry</EM></A> + +<DD> System-wide <EM>Alpine</EM> 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: + +<BLOCKQUOTE> + Nickname | Fullname | Address <BR> +</BLOCKQUOTE> + +with optional whitespace in all the obvious places. +<P> + +<DT> <A NAME="form-letter-folder"><EM>form-letter-folder</EM></A> + +<DD> 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. + +<P> +Setting this variable will alter <EM>Alpine</EM>'s usual behavior when you +execute the Compose command. Normally, <EM>Alpine</EM> 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, <EM>Alpine</EM> +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 <EM>Alpine</EM> will not automatically delete +the selected message from the Form Letter Folder. +<P> +Setting this variable will also affect <EM>Alpine</EM>'s behavior when you +Postpone a message from the composer. Normally, <EM>Alpine</EM> simply stashes +the message away in your +<A HREF="#postponed-folder"><EM>Postponed-Folder</EM></A>. +Regardless of the specified folder's existence, <EM>Alpine</EM> 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. + +<P> +Another method of adding messages to the folder is via the <EM>Alpine</EM> +composer's <SAMP>Fcc:</SAMP> 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. <EM>Alpine</EM>, 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. + +<P> +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. + +<P> +You may find that the <A HREF="#role-config"><EM>Roles</EM></A> +facility can be used +to replace the Form Letter Folder. + +<P> + +<DT> <A NAME="glob-abook"><EM>global-address-book</EM></A> + +<DD> 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 <A HREF="low-level.html#addrbook"><EM>Remote address book</EM></A>. +Remote folder syntax is discussed in +<A HREF="config-notes.html#remote-folders">Syntax for Remote Folders</A>. +This list will be added to the +<A HREF="#pers-abook"><EM>address-book</EM></A> list to +arrive at the complete set of address books. Global address books are +defined to be ReadOnly. <P> + +<DT> <A NAME="goto-default-rule"><EM>goto-default-rule</EM></A> + +<DD> This value affects <EM>Alpine</EM>'s behavior when using +the <EM>Goto</EM> command. +There are five possible values for this option: +<P> + + <DL> + + <DT> <EM>folder-in-first-collection</EM> + + <DD> <EM>Alpine</EM> will offer the most recently visited folder in the default +collection found in the "Collection List" screen as the default. +<P> + + <DT> <EM>inbox-or-folder-in-first-collection</EM> + + <DD> If the current folder is <EM>INBOX</EM>, +<EM>Alpine</EM> will offer the most recently visited folder in the +default collection found in the "Collection List" screen. +If the current folder is other than <EM>INBOX</EM>, +<EM>INBOX</EM> is offered as the default. +<P> + + <DT> <EM>inbox-or-folder-in-recent-collection</EM> + + <DD> This is <EM>Alpine</EM>'s default behavior. +If the current folder is <EM>INBOX</EM>, +<EM>Alpine</EM> will offer the last open +folder as the default. +If the current folder is other than <EM>INBOX</EM>, +<EM>INBOX</EM> is offered as the default. +<P> + + <DT> <EM>first-collection-with-inbox-default</EM> + + <DD> Instead of offering the most recently visited folder in the default +collection, the default collection is offered but with <EM>INBOX</EM> 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 <EM>INBOX</EM> will be opened. +<P> + + <DT> <EM>most-recent-folder</EM> + + <DD> The last accepted value simply causes the most recently opened +folder to be offered as the default regardless of the currently opened +folder. +<P> + + </DL> + +NOTE: The default while a newsgroup is open remains the same; the last +open newsgroup. <P> + +<DT> <A NAME="header-general-background-color"><EM>header-general-background-color</EM></A> +<DT> <A NAME="header-general-foreground-color"><EM>header-general-foreground-color</EM></A> + +<DD> <A HREF="#header-colors"><EM>Header Colors</EM></A>. +<P> + +<DT> <A NAME="image-viewer"><EM>image-viewer</EM></A> + +<DD> This variable names the program to call for displaying parts of a +MIME message that are of type IMAGE. If your system supports the +<EM>mailcap</EM> system, you don't need to set this variable. <P> + +<DT> <A NAME="inbox-path"><EM>inbox-path</EM></A> + +<DD> This specifies the name of the folder to use for the <EM>INBOX</EM>. +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 <EM>INBOX</EM>. For example, +<EM>{imap5.u.example.edu}inbox</EM> will open the user's standard +<EM>INBOX</EM> on the mail server, <EM>imap5</EM>. <P> + +<DT> <A NAME="incoming-archive-folders"><EM>incoming-archive-folders</EM></A> + +<DD> This is like <A HREF="#read-msg-fold"><EM>read-message-folder</EM></A>, +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 +<A HREF="#auto-read-msg"><EM>auto-move-read-msgs</EM></A> +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. <P> + +If these are not path names, they will be in the default collection for +<EM>Save</EM>s. Any valid folder specification, local or remote (via IMAP), is +allowed. There is no default. <P> + +<DT> <A NAME="incoming-check-interval"><EM>incoming-check-interval</EM></A> + +<DD> This option has no effect unless the feature +<A HREF="#enable-incoming-folders-checking"><EM>enable-incoming-folders-checking</EM></A> +is set, which in turn has no effect unless +<A HREF="#inc-fold"><EM>incoming-folders</EM></A> +is set. +<P> +This option specifies, in seconds, how often <EM>Alpine</EM> will check +for new mail and state changes in Incoming Folders when Incoming Folders +Checking is turned on. +The default is 3 minutes (180). +This value applies only to folders that are local to the system that +<EM>Alpine</EM> is running on or that are accessed using the IMAP protocol. +The similar option +<A HREF="#incoming-check-interval-secondary"><EM>incoming-check-interval-secondary</EM></A> +applies to all other monitored folders. +<P> + +<DT> <A NAME="incoming-check-interval-secondary"><EM>incoming-check-interval-secondary</EM></A> + +<DD> This option has no effect unless the feature +<A HREF="#enable-incoming-folders-checking"><EM>enable-incoming-folders-checking</EM></A> +is set, which in turn has no effect unless +<A HREF="#inc-fold"><EM>incoming-folders</EM></A> +is set. +<P> +This option together with the option +<A HREF="#incoming-check-interval"><EM>incoming-check-interval</EM></A> +specifies, in seconds, how often <EM>Alpine</EM> will check +for new mail and state changes in Incoming Folders when Incoming Folders +Checking is turned on. +The default for this option is 3 minutes (180). +For folders that are local to this system or +that are accessed using the IMAP protocol +the value of the option +<A HREF="#incoming-check-interval"><EM>incoming-check-interval</EM></A> +is used. +For all other monitored folders, the value of this option is used. +<P> +The reason there are two separate options is because it is usually +less expensive to check local and IMAP folders than it is to check +other types, like POP or NNTP folders. +You may want to set this secondary value to a higher number than +the primary check interval. +<P> + +<DT> <A NAME="incoming-check-list"><EM>incoming-check-list</EM></A> + +<DD> This option has no effect unless the feature +<A HREF="#enable-incoming-folders-checking"><EM>enable-incoming-folders-checking</EM></A> +is set, which in turn has no effect unless +<A HREF="#inc-fold"><EM>incoming-folders</EM></A> +is set. +<P> +When monitoring the Incoming Message Folders for Unseen messages Alpine will +normally monitor all Incoming Folders. +You may use this option to restrict the list of monitored folders to a +subset of all Incoming Folders. +<P> + +<DT> <A NAME="incoming-check-timeout"><EM>incoming-check-timeout</EM></A> + +<DD> This option has no effect unless the feature +<A HREF="#enable-incoming-folders-checking"><EM>enable-incoming-folders-checking</EM></A> +is set, which in turn has no effect unless +<A HREF="#inc-fold"><EM>incoming-folders</EM></A> +is set. +<P> +Sets the time in seconds that Alpine will +attempt to open a network connection used for monitoring for Unseen +messages in Incoming Folders. The default is 5. +If a connection has not completed within this many seconds Alpine will +give up and consider it a failed connection. +<P> + +<DT> <A NAME="inc-fold"><EM>incoming-folders</EM></A> + +<DD> This is a list of one or more folders other than <EM>INBOX</EM> 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 <EM>Alpine</EM> would monitor the folders +in this list for new mail. <P> + +<DT> <A NAME="incoming-startup-rule"><EM>incoming-startup-rule</EM></A> + +<DD> This rule affects <EM>Alpine</EM>'s behavior when opening +the <EM>INBOX</EM> or +another folder from the "INCOMING MESSAGE FOLDERS". +This rule tells <EM>Alpine</EM> +which message to make the current message when an incoming folder is opened. +There are seven possible values for this option: +<P> + + <DL> + + <DT> <EM>first-unseen</EM> + + <DD> 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. +<P> + + <DT> <EM>first-recent</EM> + + <DD> This is similar to <EM>first-unseen</EM>. 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. +<P> + + <DT> <EM>first-important</EM> + + <DD> 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. +<P> + + <DT> <EM>first-important-or-unseen</EM> + + <DD> This selects the minimum of the first unseen and the first important +messages. +<P> + + <DT> <EM>first-important-or-recent</EM> + + <DD> This selects the first of the first recent and the first important +messages. +<P> + + <DT> <EM>first</EM> + + <DD> Set the current message to the first undeleted message unless all +are deleted. In that case set it to the last message. +<P> + + <DT> <EM>last</EM> + + <DD> Set the current message to the last undeleted message unless all +are deleted. In that case set it to the last message. +<P> + + </DL> +<P> + +<DT> <A NAME="incoming-unseen-background-color"><EM>incoming-unseen-background-color</EM></A> +<DT> <A NAME="incoming-unseen-foreground-color"><EM>incoming-unseen-foreground-color</EM></A> + +<DD> <A HREF="#incoming-unseen-color"><EM>Incoming Unseen Color</EM></A>. +<P> + +<DT> <A NAME="index-answered-background-color"><EM>index-answered-background-color</EM></A> +<DT> <A NAME="index-answered-foreground-color"><EM>index-answered-foreground-color</EM></A> +<DT> <A NAME="index-arrow-background-color"><EM>index-arrow-background-color</EM></A> +<DT> <A NAME="index-arrow-foreground-color"><EM>index-arrow-foreground-color</EM></A> +<DT> <A NAME="index-deleted-background-color"><EM>index-deleted-background-color</EM></A> +<DT> <A NAME="index-deleted-foreground-color"><EM>index-deleted-foreground-color</EM></A> +<DT> <A NAME="index-from-background-color"><EM>index-from-background-color</EM></A> +<DT> <A NAME="index-from-foreground-color"><EM>index-from-foreground-color</EM></A> +<DT> <A NAME="index-highpriority-background-color"><EM>index-highpriority-background-color</EM></A> +<DT> <A NAME="index-highpriority-foreground-color"><EM>index-highpriority-foreground-color</EM></A> +<DT> <A NAME="index-important-background-color"><EM>index-important-background-color</EM></A> +<DT> <A NAME="index-important-foreground-color"><EM>index-important-foreground-color</EM></A> +<DT> <A NAME="index-lowpriority-background-color"><EM>index-lowpriority-background-color</EM></A> +<DT> <A NAME="index-lowpriority-foreground-color"><EM>index-lowpriority-foreground-color</EM></A> +<DT> <A NAME="index-new-background-color"><EM>index-new-background-color</EM></A> +<DT> <A NAME="index-new-foreground-color"><EM>index-new-foreground-color</EM></A> +<DT> <A NAME="index-opening-background-color"><EM>index-opening-background-color</EM></A> +<DT> <A NAME="index-opening-foreground-color"><EM>index-opening-foreground-color</EM></A> +<DT> <A NAME="index-recent-background-color"><EM>index-recent-background-color</EM></A> +<DT> <A NAME="index-recent-foreground-color"><EM>index-recent-foreground-color</EM></A> +<DT> <A NAME="index-subject-background-color"><EM>index-subject-background-color</EM></A> +<DT> <A NAME="index-subject-foreground-color"><EM>index-subject-foreground-color</EM></A> +<DT> <A NAME="index-to-me-background-color"><EM>index-to-me-background-color</EM></A> +<DT> <A NAME="index-to-me-foreground-color"><EM>index-to-me-foreground-color</EM></A> +<DT> <A NAME="index-unseen-background-color"><EM>index-unseen-background-color</EM></A> +<DT> <A NAME="index-unseen-foreground-color"><EM>index-unseen-foreground-color</EM></A> + +<DD> <A HREF="#index-colors"><EM>Index Colors</EM></A>. +<P> + +<DT> <A NAME="index-format"><EM>index-format</EM></A> + +<DD> 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. +<P> + +<EM>Alpine</EM> 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. +<P> + +The list of available tokens is +<A HREF="#index-tokens"><EM>here</EM></A>. +<P> + +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 enclosing either a number or percentage. For example, +"SUBJECT(13)" means to allocate 13 characters of space to the subject +column, and "SUBJECT(20%)" means to +allocate 20% of the available space +to the subjects column, while plain "SUBJECT" means the system will +attempt to figure out a reasonable amount of space. +<P> + +There is always one space between every pair of columns, so if you use fixed +column widths (like 13) you should remember to take that into account. +Several of the fields are virtually fixed-width, so it doesn't make +much sense to specify the width for them. The fields STATUS, +FULLSTATUS, IMAPSTATUS, MSGNO, the DATE fields, SIZE, +and DESCRIPSIZE all fall into that category. +You <EM>may</EM> specify widths for those if you wish, but +you're probably better off letting the system pick those widths. <P> + +<P> +The default is equivalent to: + +<P> +<CENTER><SAMP>index-format=STATUS MSGNO SMARTDATETIME24 FROMORTO(33%) SIZENARROW SUBJKEY(67%)</SAMP></CENTER> + +<P> +This means that the four fields without percentages will be allocated +first, and then 33% and 67% of the <EM>remaining</EM> space will go to +the from and subject fields. If one of those two fields is specified +as a percentage and the other is left for the system to choose, then +the percentage is taken as an absolute percentage of the screen, not +of the space remaining after allocating the first four columns. It +doesn't usually make sense to do it that way. If you leave off all +the widths, then the subject and from fields (if both are present) are +allocated space in a 2 to 1 ratio, which is almost exactly the same as +the default. + +<P> +What you are most likely to do with this configuration option is to +specify which fields appear at all, which order they appear in, and the +percentage of screen that is used for the from and subject fields if you +don't like the 2 to 1 default. +<P> +If you want to retain the default format that <EM>Pine</EM> 4.64 had, use + +<P> +<CENTER><SAMP>Index-Format=STATUS MSGNO DATE FROMORTO(33%) SIZE SUBJKEY(67%)</SAMP></CENTER> +<P> + +<EM>and</EM> set the feature +<A HREF="#disable-index-locale-dates"><EM>Disable-Index-Locale-Dates</EM></A>. + +<P> + +<DT> <A NAME="initial-keystroke-list"><EM>initial-keystroke-list</EM></A> + +<DD> This is a comma-separated list of keystrokes which <EM>Alpine</EM> executes on +startup. Items in the list are usually just characters, but there are +some special values. <EM>SPACE,</EM> <EM>TAB,</EM> and <EM>CR</EM> mean a +space character, tab character, and a carriage return, respectively. +<EM>F1</EM> through <EM>F12</EM> stand for the twelve function keys. +<EM>UP, DOWN, LEFT, </EM>and<EM> RIGHT </EM>stand for the arrow keys. +Control characters are represented with <EM>^<char></EM>. 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 <EM>Alpine</EM>. A +user can always use only <EM>character</EM> keys in the startup list even +if he or she is using <EM>function</EM> keys normally, or vice versa. If +an element in this list is a string surrounded by double quotes (") +then it will be expanded into the individual characters in the string, +excluding the double quotes. <P> + +<DT> <A NAME="kblock-count"><EM>kblock-passwd-count</EM></A> + +<DD> System-wide <EM>Alpine</EM> configuration files only. Number of times a user +will have to enter a password when they run the keyboard lock command in +the main menu. <P> + +<DT> <A NAME="keyb-char-set"><EM>keyboard-character-set</EM></A> + +<DD> See the discussion in +<A HREF="low-level.html#char-set">International Character Sets</EM></A> for +details.<P> + +<DT> <A NAME="keylabel-background-color"><EM>keylabel-background-color</EM></A> +<DT> <A NAME="keylabel-foreground-color"><EM>keylabel-foreground-color</EM></A> + +<DD> <A HREF="#keylabel-color"><EM>KeyLabel Color</EM></A>. +<P> + +<DT> <A NAME="keyname-background-color"><EM>keyname-background-color</EM></A> +<DT> <A NAME="keyname-foreground-color"><EM>keyname-foreground-color</EM></A> + +<DD> <A HREF="#keyname-color"><EM>KeyName Color</EM></A>. +<P> + +<DT> <A NAME="keywords"><EM>keywords</EM></A> + +<DD> You may define your own set of keywords and optionally set them on a +message by message basis. +These are similar to the "Important" flag which the user +may set using the Flag command. +The difference is that the Important flag is always present for each folder. +User-defined keywords are chosen by the user. +You may set up the list of possible keywords here, or you may add keywords +from the Flag Details screen that you +can get to after typing the +Flag (*) +command. +After the keywords have been defined, +then you use the Flag command +to set or clear the keywords in each message. +The behavior of the flag command may be modified by using the +<A HREF="#enable-flag-screen-implicitly">Enable-Flag-Screen-Implicitly</A> option or the +<A HREF="#enable-flag-screen-keyword-shortcut"><EM>Enable-Flag-Screen-Keyword-Shortcut</EM></A> option. + +<P> +Keywords may be used when Selecting messages (Select Keyword). +Keywords may also be used in the Patterns of Rules (Filters, Indexcolors, etc). +Filter rules may be used to set keywords automatically. +Keywords may be displayed as part of the Subject of a message by using +the SUBJKEY or SUBJKEYINIT tokens in the +<A HREF="#index-format">Index-Format</A> option. +The <A HREF="#keyword-surrounding-chars"><EM>Keyword-Surrounding-Chars</EM></A> +option may be used to modify the display of keywords using +SUBJKEY and SUBJKEYINIT slightly. +Keywords may also be displayed in a column of their own in the MESSAGE INDEX +screen by using the KEY or KEYINIT tokens. +It is also possible to color keywords in the index using the +Setup/Kolor screen +(<A HREF="#keyword-colors">Keyword Colors</A>). +Keywords are not supported by all mail servers. +<P> +You may give keywords nicknames if you wish. +If the keyword definition you type in contains a SPACE character, then the +actual value of the keyword is everything after the last SPACE and the +nickname for that keyword is everything before the last SPACE. +For example, suppose you are trying to interoperate with another email program +which uses a particular keyword with an unpleasant name. +Maybe it uses a keyword called +<P> +<CENTER><SAMP>VendorName.SoftwareName.08</SAMP></CENTER> +<P> +but for you that keyword means that the message is work-related. +You could define a keyword to have the value +<P> +<CENTER><SAMP>Work VendorName.SoftwareName.08</SAMP></CENTER> +<P> +and then you would use the name "Work" when dealing with +that keyword in <EM>Alpine</EM>. +If you defined it as +<P> +<CENTER><SAMP>My Work VendorName.SoftwareName.08</SAMP></CENTER> +<P> +the nickname would be everything before the last SPACE, that is the nickname +would be "My Work". +<P> +Some commonly used keywords begin with dollar signs. +This presents a slight complication, because the dollar sign is normally used +to signify +<A HREF="config-notes.html#env-variables">environment variable expansion</A> +in the <EM>Alpine</EM> configuration. +In order to specify a keyword which begins with a dollar sign you must +precede the dollar sign with a second dollar sign to escape its special +meaning. +For example, if you want to include the keyword +<P> +<CENTER><SAMP>$Label1</SAMP></CENTER> +<P> +as one of your possible keywords, you must enter the text +<P> +<CENTER><SAMP>$$Label1</SAMP></CENTER> +<P> +instead. +<P> + +<DT> <A NAME="keyword-surrounding-chars"><EM>keyword-surrounding-chars</EM></A> + +<DD> This option controls a minor aspect of <EM>Alpine</EM>'s MESSAGE INDEX and MESSAGE +TEXT screens. +If you have modified the +<A HREF="#index-format"><EM>Index-Format</EM></A> option +so that either the "SUBJKEY" or "SUBJKEYINIT" tokens +are used to display keywords or their initials along with the Subject; then +this option may be used to modify the resulting display slightly. +By default, the keywords or initials displayed for these tokens will be +surrounded with curly braces ({ and }) and a trailing space. +For example, if keywords "Work" and "Now" are set for +a message, the "SUBJKEY" token will normally look like +<P> +<CENTER><SAMP>{Work Now} actual subject</SAMP></CENTER> +<P> +and the SUBJKEYINIT token would look like +<P> +<CENTER><SAMP>{WN} actual subject</SAMP></CENTER> +<P> +The default character before the keywords is the left brace ({) and the +default after the keywords is the right brace followed by a space (} ). +<P> +This option allows you to change that. +You should set it to two values separated by a space. +The values may be quoted if they include space characters. +So, for example, the default value could be specified explicitly by setting this +option to +<P> +<CENTER><SAMP>Keyword-Surrounding-Chars="{" "} "</SAMP></CENTER> +<P> +The first part wouldn't need to be quoted (but it doesn't hurt). +The second part does need the quotes because it includes a space character. +If you wanted to change the braces to brackets you could use +<P> +<CENTER><SAMP>Keyword-Surrounding-Chars="[" "] "</SAMP></CENTER> +<P> +Inside the quotes you can use backslash quote to mean quote, so +<P> +<CENTER><SAMP>Keyword-Surrounding-Chars="\"" "\" "</SAMP></CENTER> +<P> +would produce +<P> +<CENTER><SAMP>"Work Now" actual subject</SAMP></CENTER> +<P> +It is also possible to color keywords in the index using the +Setup/Kolor screen +(<A HREF="#keyword-colors">Keyword Colors</A>). +<P> +It is not possible to change the fact that a space character is used to +separate the keywords if more than one keyword is set for a message. +It is also not possible to change the fact that there are no separators +between the keyword initials if more than one keyword is set. +<P> +This option is displayed as "Keyword Surrounding Characters". +<P> + +<DT> <A NAME="last-time"><EM>last-time-prune-questioned</EM></A> + +<DD> Personal configuration file only. This variable records the month +the user was last asked if his or her <EM>sent-mail</EM> folders should +be pruned. +The format is <EM>yy.mm</EM>. +This is automatically updated by <EM>Alpine</EM> when +the the pruning is done or declined. +If a user wanted to make <EM>Alpine</EM> stop +asking this question he or she could set this time to something +far in the future. +This may not be set in the system-wide configuration files. +Note: The <EM>yy</EM> year is actually the number of years since 1900, so it +will be equal to 101 in the year 2001. +<P> + +<DT> <A NAME="last-version-used"><EM>last-version-used</EM></A> + +<DD> Personal configuration file only. +This is set automatically by <EM>Alpine</EM>. +It is used to keep track of the last version of <EM>Alpine</EM> that +was run by the user. +Whenever the version number increases, a new version message is printed out. +This may not be set in the system-wide configuration files. +<P> + +<DT> <A NAME="ldap-servers"><EM>ldap-servers</EM></A> + +<DD> This is only available if <EM>Alpine</EM> was linked with an LDAP library +when it was compiled. This variable is normally managed by <EM>Alpine</EM> though +it can be set in the system-wide configuration files as well as the personal +configuration. It is a list variable. Each item in the +list contains quite a bit of extra information besides just the server name. +To put this into a system-wide config file the easiest thing to do is to +configure a personal <EM>Alpine</EM> for the LDAP server then copy the +configuration line +into the system-wide config file. Each item in the list looks like: + +<BLOCKQUOTE> + <CODE> + server_name[:port] <SPACE> "quoted stuff" </CODE><BR> +</BLOCKQUOTE> + +The <CODE>server_name</CODE> is just a hostname and it is followed by +an optional colon and port number. The default <CODE>port</CODE> is 389. +Following the server name is a single SPACE character followed by +a bunch of characters inside double quotes. The part inside the quotes is +a set of <EM>tag</EM> = <EM>value</EM> pairs. +Each tag is preceded by a slash (/) and followed +by an equal sign. The value for that tag is the text up to the next slash. +An example of some <CODE>quoted stuff</CODE> is: + +<BLOCKQUOTE> + <CODE> + "/base=o=University of Washington, c=US/impl=0/.../nick=My Server" + </CODE><BR> +</BLOCKQUOTE> + +This would set the search base for this server to +<CODE>o=University of Washington, c=US</CODE>, set the implicit bit to zero, +and set the nickname for the server to <CODE>My Server</CODE>. +All of the tags correspond directly to items in the Setup/Directory screen +so experiment with that if you want to see what the possible tags and values +are. +<P> + +<DT> <A NAME="literal-signature"><EM>literal-signature</EM></A> + +<DD> With this option your actual signature, as opposed to +the name of a file containing your signature, +is stored in the <EM>Alpine</EM> configuration file. +If this is defined it takes precedence over the <EM>signature-file</EM> option. +<P> + +This is simply a different way to store the signature data. +The signature is stored inside your <EM>Alpine</EM> configuration file +instead of in a separate signature file. +Tokens contained in the signature work the same way they do with the regular +<A HREF="#sig-file">signature-file</A>. +<P> + +The Setup/Signature command in <EM>Alpine</EM>'s Main Menu will edit +the <EM>literal-signature</EM> by default. However, if no +<EM>literal-signature</EM> is defined and the file named in the +<EM>signature-file</EM> option exists, then the latter will be used +instead. Compose (Reply, Forward, ...) will default to using the +<EM>literal-signature</EM> if defined, otherwise it will use the contents +of the file named in <EM>signature-file</EM>. +<P> + +The <EM>Alpine</EM> composer is used to edit the literal-signature. +The result of that edit is first converted to a C-style string before it +is stored in the configuration file. +In particular, the two character sequence \n (backslash followed by +the character "n") will be used to signify a +line-break in the signature. +You don't have to enter the \n, but it will be visible in the +SETUP CONFIGURATION window after you are done editing the signature. +<P> + +<DT> <A NAME="mail-check"><EM>mail-check-interval</EM></A> + +<DD> This option specifies, in seconds, +how often <EM>Alpine</EM> will check for new mail. +If set to zero, new-mail checking is disabled. +(You can always manually force a new-mail check by typing ^L (Ctrl-L), which is also +the command to refresh the screen, or by typing the Next command when the +current message is the last message of the folder.) +There is a minimum value for this option, normally 15 seconds. +The default value is normally 150 seconds. +The higher you set this option, the easier it is on the server. +<P> +There are some situations where automatic new-mail checking does not work. +See the discussion about new-mail checking in <A HREF="#reopen-rule"><EM>folder-reopen-rule</EM></A>. +<P> +The new-mail checking will not happen exactly at the frequency that you specify. +For example, <EM>Alpine</EM> may elect to defer a non-INBOX mail check if you +are busy typing. +Or, it may check more frequently than you have specified if that is +thought to be necessary to keep the server from closing the connection +to the folder due to inactivity. +If <EM>Alpine</EM> checks for new mail as a side effect of another command, it will reset +the timer, so that new-mail checking may seem to happen irregularly instead of +every X seconds like clockwork. +<P> +If you are anxious to know about new mail as soon as possible, set the check +interval low, and you'll know about the new mail by approximately +that amount of time after it arrives. +If you aren't so worried about knowing right away, set this option to a +higher value. +That will save the server some processing time and may save you some of +the time you spend waiting for new-mail checks to happen if you are +dealing with a slow server or slow network connection. +<P> +If you suspect that new-mail checking is causing slow downs for you, +you may want to look into the options +<A HREF="#quell-mailchecks-composing-except"><EM>Quell-Mailchecks-Composing-Except-Inbox</EM></A>, +<A HREF="#quell-mailchecks-composing-inbox"><EM>Quell-Mailchecks-Composing-Inbox</EM></A> and +<A HREF="#mail-check-noncurr"><EM>Mail-Check-Interval-Noncurrent</EM></A>, +which refine when mail checking is done. +<P> +If the mailbox being check uses a <A HREF="config-notes.html#maildrop">Mail Drop</A> then +there is a minimum time +(<A HREF="#maildrop-check-minimum"><EM>maildrop-check-minimum</EM></A>) +between new-mail checks. +Because of this minimum you may notice that new mail does not +appear promptly when you expect it. +The reason for this is to protect the server from over-zealous opening and +closing of the Mail Drop folder, since that is a costly operation. +<P> +A side effect of disabling mail checking is that there will be situations +in which the user's IMAP connection will be broken due to inactivity timers +on the server. Another side effect is that the +<A HREF="#user-input"><EM>user-input-timeout</EM></A> +option won't work. +<P> + +<DT> <A NAME="mail-check-noncurr"><EM>mail-check-interval-noncurrent</EM></A> + +<DD> This option is closely related to the +<A HREF="#mail-check"><EM>Mail-Check-Interval</EM></A> +option, as well as the +<A HREF="#quell-mailchecks-composing-except"><EM>Quell-Mailchecks-Composing-Except-Inbox</EM></A> and +<A HREF="#quell-mailchecks-composing-inbox"><EM>Quell-Mailchecks-Composing-Inbox</EM></A> options. +If the "Mail-Check-Interval" option is set to zero, then automatic +new-mail checking is disabled and this option will have no effect. +<P> +Normally this option is set to zero, which means that the value used will be +the same as the value for the "Mail-Check-Interval". +If you set this option to a value different from zero +(usually larger than the value for "Mail-Check-Interval") +then that is the check interval that will be used +for folders which are not the currently open folder or the INBOX. +You may not even have any folders that are noncurrent and not the INBOX. +If you do, it is likely that they are due to +<A HREF="#stay-open-folders">Stay-Open-Folders</A> +you have configured. +This option also affects the rate of mail checking done on cached +connections to folders you previously had open but are no longer actively +using. +You aren't expected to understand that last sentence, but if you are interested +take a look at +<A HREF="#max-remote-connections">Max-Remote-Connections</A>, +and the related options. +<P> + +<DT> <A NAME="mail-directory"><EM>mail-directory</EM></A> + +<DD> This variable was more important in previous versions of <EM>Alpine</EM>. Now +it is used only as the default for storing personal folders (and only if +there are no <A HREF="#fold-coll"><EM>folder-collections</EM></A> defined). +The default value is +<EM>~/mail</EM> on UNIX and <EM>${HOME}\MAIL</EM> on a PC. <P> + +<DT> <A NAME="mailcap-search-path"><EM>mailcap-search-path</EM></A> + +<DD> This variable is used to replace <EM>Alpine</EM>'s default +mailcap file search path. +It takes one or more file names (full paths must be specified) in +which to look for mail capability data. <P> + +<DT> <A NAME="maildrop-check-minimum"><EM>maildrop-check-minimum</EM></A> + +<DD> New-mail checking for a +<A HREF="config-notes.html#maildrop">Mail Drop</A> +is a little different from new +mail checking for a regular folder. +One of the differences is that the connection to the Mail Drop is not +kept open and so the cost of checking +(delay for you and additional load for the server) may be significant. +Because of this additional cost we set a minimum time that +must pass between checks. +This minimum only applies to the automatic checking done by <EM>Alpine</EM>. +If you force a check by typing ^L (Ctrl-L) or by typing the Next command when you are +at the end of a folder index, then the check is done right away. +<P> +This option specifies, in seconds, the <EM>minimum</EM> time between Mail Drop +new-mail checks. +You may want to set this minimum high in order to avoid experiencing some +of the delays associated with the checks. +Note that the time between checks is still controlled by the regular +<A HREF="#mail-check"><EM>Mail-Check-Interval</EM></A> option. +When <EM>Alpine</EM> is about to do an automatic check for new mail (because +the Mail-Check-Interval has expired) then if the time since the last +new-mail check +of any open Mail Drops has been greater than the MailDrop-Check-Minimum, +the Mail Drop is checked for new mail as well. +Therefore, it is only useful to set this option to a value that is higher +than the Mail-Check-Interval. +<P> +If this option is set to zero, automatic Mail Drop new-mail +checking is disabled. +There is a minimum value, normally 60 seconds. +The default value is normally 60 seconds as well. +This applies to the INBOX and to the currently open folder if that is +different from the INBOX. +<P> + +<DT> <A NAME="max-remote-connections"><EM>max-remote-connections</EM></A> + +<DD> This option affects low-level behavior of <EM>Alpine</EM>. +The default value for this option is <EM>2</EM>. +If your INBOX is accessed using the IMAP protocol +from an IMAP server, that connection is kept open throughout the +duration of your <EM>Alpine</EM> session, independent of the value of this option. +The same is true of any +<A HREF="#stay-open-folders">Stay-Open-Folders</A> +you have defined. +This option controls <EM>Alpine</EM>'s behavior when connecting to remote IMAP folders +other than your INBOX or your Stay-Open-Folders. +It specifies the maximum number of remote IMAP connections (other than +those mentioned above) that <EM>Alpine</EM> will use for accessing the rest of your +folders. +If you set this option to zero, you will turn off most remote connection +re-use. +It's difficult to understand exactly what this option does, and it is usually +fine to leave it set to its default value. +It is probably more likely that you will be interested in setting the +<A HREF="#stay-open-folders">Stay-Open-Folders</A> option +instead of changing the value of this option. +A slightly longer explanation of what is going on with this option +is given in the next paragraphs. + +<P> +There are some time costs involved in opening and closing remote IMAP +folders, the main costs being the time you have to wait for the connection +to the server and the time for the folder to open. +Opening a folder may involve not only the time the server takes to do its +processing but time that <EM>Alpine</EM> uses to do filtering. +These times can vary widely. +They depend on how loaded the server is, how large +the folder being opened is, and how you set up filtering, among other things. +Once <EM>Alpine</EM> has opened a connection to a particular folder, it will attempt +to keep that connection open in case you use it again. +In order to do this, +<EM>Alpine</EM> will attempt to use the Max-Remote-Connections (the value of +this option) IMAP connections you have alloted for this purpose. +<P> +For example, suppose the value of this option is set to "2". +If your INBOX is accessed on a remote server using the IMAP protocol, that +doesn't count as one of the remote connections but it is always kept open. +If you then open another IMAP folder, that would be your first +remote connection counted as one of the Max-Remote-Connections connections. +If you open a third folder the second will be left open, in case you +return to it. +You won't be able to tell it has been left open. +It will appear to be closed when you leave the folder but the connection +will remain in the background. +Now suppose you go back to the second folder (the first folder after the +INBOX). +A connection to that folder is still open so you won't have to wait +for the startup time to open it. +Meanwhile, the connection to the third folder will be left behind. +Now, if you open a fourth folder, you will bump into the +Max-Remote-Connections limit, because this will be the third folder other +than INBOX and you have the option set to "2". +The connection that is being used for +the third folder will be re-used for this new fourth folder. +If you go back to the third folder after this, it is no longer already +connected when you get there. +You'll still save some time since <EM>Alpine</EM> will re-use the connection to the +fourth folder and you have already logged in on that connection, +but the folder will have to be re-opened from scratch. +<P> +If a folder is large and the startup cost is dominated by the time it takes +to open that folder or to run filters on it, then it will pay to make the +value of this option large enough to keep it open. +On the other hand, if you only revisit a handful of folders or if +the folders are small, then it might +make more sense to keep this number small so that the reconnect +time (the time to start up a new connection and authenticate) +is eliminated instead. +<P> +You may also need to consider the impact on the server. +On the surface, a larger number here may cause a larger impact on the +server, since you will have more connections open to the server. +On the other hand, not only will <EM>you</EM> be avoiding the startup costs +associated with reopening a folder, but the <EM>server</EM> will be +avoiding those costs as well. +<P> +When twenty five minutes pass without any active use of an IMAP connection +being saved for possible re-use, that connection will be shut down, +<P> +This option is displayed as "Maximum Remote Connections". +<P> + +<DT> <A NAME="meta-message-background-color"><EM>meta-message-background-color</EM></A> +<DT> <A NAME="meta-message-foreground-color"><EM>meta-message-foreground-color</EM></A> + +<DD> <A HREF="#meta-message-color"><EM>Meta-message Color</EM></A>. +<P> + +<DT> <A NAME="mimetype-search-path"><EM>mimetype-search-path</EM></A> + +<DD> This variable is used to replace <EM>Alpine</EM>'s default mime.types file +search path. It takes one or more file names (full paths must be +specified) in which to look for file-name-extension to MIME type mapping +data. See the Config Notes for details on <EM>Alpine</EM>'s usage of the <A +HREF="config-notes.html#mime.types">MIME.Types File</A>. <P> + +<DT> <A NAME="new-version-threshold"><EM>new-version-threshold</EM></A> + +<DD> When a new version of <EM>Alpine</EM> is run for the first time it offers a +special explanatory screen to the user upon startup. This option +helps control when and if that special screen appears for users that +have previously run <EM>Alpine</EM>. It takes as its value a <EM>Alpine</EM> version +number. <EM>Alpine</EM> versions less than the specified value will supress this +special screen while versions equal to or greater than that specified +will behave normally. <P> + +<DT> <A NAME="newmail-fifo-path"><EM>newmail-fifo-path</EM></A> + +<DD> This option is only available in UNIX <EM>Alpine</EM>. +However, there is a very similar feature built in to <EM>PC-Alpine</EM>. +In <EM>PC-Alpine</EM>'s Config menu at the top of the screen +is an option called "New Mail Window". +<P> +You may have <EM>Alpine</EM> create a FIFO special file (also called a named pipe, see mkfifo(3) and fifo(4)) where +it will send a one-line message each time a new message is received in +the current folder, the INBOX, or any open +<A HREF="#stay-open-folders">Stay-Open-Folders</A>. +To protect against two different <EM>Alpine</EM>s both writing to the same FIFO, <EM>Alpine</EM> +will only create the FIFO and write to it if it doesn't already exist. +<P> +A possible way to use this option would be to have a separate window +on your screen running the command +<P> +<CENTER><SAMP>cat filename</SAMP></CENTER> +<P> +where "filename" is the name of the file given for this option. +Because the file won't exist until after you start <EM>Alpine</EM>, you must <EM>first</EM> +start <EM>Alpine</EM> and <EM>then</EM> run the "cat" command. +You may be tempted to use "tail -f filename" to view the new +mail log. +However, the common implementations of the tail command will not do what you +are hoping. +<P> +The width of the messages produced for the FIFO may be altered with the +<A HREF="#newmail-window-width">NewMail-Window-Width</A> option. +<P> +On some systems, fifos may only be created in a local filesystem. +In other words, they may not be in NFS filesystems. +This requirement is not universal. +If the system you are using supports it, it should work. +(It is often the case that your home directory is in an NFS filesystem. +If that is the case, you might try using a file in the "/tmp" +filesystem, which is usually a local filesytem.) +Even when it is possible to use an NFS-mounted filesystem as a place to name +the fifo (for example, your home directory), it will still be the case that +the reader (probably the "cat" command) and the +writer (<EM>Alpine</EM>) of the fifo must be running on the same system. <P> + +<DT> <A NAME="newmail-window-width"><EM>newmail-window-width</EM></A> + +<DD> UNIX <EM>Alpine</EM> only. +<P> +This option is only useful if you have turned on the +<A HREF="#newmail-fifo-path">NewMail-FIFO-Path</A> option. +That option causes new mail messages to be sent to a fifo file. +Those messages will be 80 characters wide by default. +You can change the width of the messages by changing this option. +For example, if you are reading those messages in another window you might +want to set this width to the width of that other window. <P> +For UNIX <EM>Alpine</EM>, this option is only useful if you have turned on the +<A HREF="#newmail-fifo-path">NewMail-FIFO-Path</A> option. +That option causes new mail messages to be sent to a fifo file. +Those messages will be 80 characters wide by default. +You can change the width of those messages by changing this option. +For example, if you are reading those messages in another window you might +want to set this width to the width of that other window. +<P> +If you are using <EM>PC-Alpine</EM>, it has an option in the Config menu to turn +on the "New Mail Window". +The present option also controls the width of that window. + +<DT> <A NAME="news-active"><EM>news-active-file-path</EM></A> + +<DD> This option tells <EM>Alpine</EM> where to look for the "active file" for +newsgroups when accessing news locally, rather than via NNTP. The default +path is usually <CODE>/usr/lib/news/active</CODE>. <P> + +<DT> <A NAME="news-coll"><EM>news-collections</EM></A> + +<DD> This is a list of collections where news folders are located. See +the section describing <A HREF="config-notes.html#collections">collections</A> +for more information. <P> + +<DT> <A NAME="news-spool"><EM>news-spool-directory</EM></A> + +<DD> This option tells <EM>Alpine</EM> where to look for the "news spool" for +newsgroups when accessing news locally, rather than via NNTP. The default +path is usually <CODE>/usr/spool/news</CODE>. <P> + +<DT> <A NAME="newsrc-path"><EM>newsrc-path</EM></A> + +<DD> This option overrides the default name <EM>Alpine</EM> uses for your "newsrc" +news status and subscription file. If set, <EM>Alpine</EM> will take this value as +the full pathname for the desired newsrc file. <P> + +<DT> <A NAME="nntp-range"><EM>nntp-range</EM></A> + +<DD> This option applies only to newsgroups accessed using the NNTP protocol. +It does not, for example, +apply to newsgroups accessed using an IMAP-to-NNTP proxy. +<P> +When you open a connection to a News server using the NNTP protocol, you +normally have access to all of the articles in each newsgroup. +If a server keeps a large backlog of messages it may speed performance +some to restrict attention to only the newer messages in a group. +This option allows you to set how many article numbers should be checked +when opening a newsgroup. +You can think of "nntp-range" as specifying the maximum number +of messages you ever want to see. +For example, if you only ever wanted to look at the last 500 messages in each +newsgroup you could set this option to 500. +In actuality, it isn't quite that. +Instead, for performance reasons, it specifies the range of article +numbers to be checked, beginning +with the highest numbered article and going backwards from there. +If there are messages that have been canceled or deleted +their article numbers are still counted as part of the range. +<P> +So, more precisely, setting the "nntp-range" will cause article +numbers +<P><CENTER>last_article_number - nntp-range + 1 through last_article_number</CENTER> +<P> +to be considered when reading a newsgroup. +The number of messages that show up in your index will be less than or equal +to the value of "nntp-range". +<P> +The purpose of this option is simply to speed up access when reading news. +The speedup comes because <EM>Alpine</EM> can ignore all but the last nntp-range article +numbers, and can avoid downloading any information about the ignored articles. +There is a cost you pay for this speedup. +That cost is that there is no way for you to see those ignored articles. +The articles that come before the range you specify are invisible to you and +to <EM>Alpine</EM>, as if they did not exist at all. +There is no way to see those messages using, for example, an unexclude command +or something similar. +The only way to see those articles is to set this option high enough (or +set it to zero) and then to reopen the newsgroup. + +<P> +If this option is set to 0 (which is also the default), +then the range is unlimited. +This option applies globally to all NNTP servers and to all newsgroups +on those servers. +There is no way to set different values for different newsgroups or servers. +<P> + +<DT> <A NAME="nntp-server"><EM>nntp-server</EM></A> + +<DD> One or more NNTP servers (host name or IP address) which <EM>Alpine</EM> will +use for reading and posting news. +If you read and post news to and from a single +NNTP server, you can get away with only setting the <EM>nntp-server</EM> +variable and leaving the <EM>news-collections</EM> variable unset. +<P> +When you define an NNTP server, <EM>Alpine</EM> implicitly defines a +news collection for you, assuming that server as the news server +and assuming that you will use the NNTP protocol and a local newsrc +configuration file for reading news. +See also <A HREF="#configuring-news">Configuring News</A>. +<P> +Your NNTP server may offer NNTP "AUTHINFO SASL" +or "AUTHINFO USER" authentication. +It may even require it. +If your NNTP server does offer such authentication you may specify a user name +parameter to cause <EM>Alpine</EM> to attempt to authenticate. +The same is true for the server name in a folder collection which uses NNTP. +This parameter requires an associated value, +the username identifier with which to establish the server connection. +An example might be: + +<P> +<CENTER><SAMP>nntpserver.example.com/user=katie</SAMP></CENTER> +<P> + +If authentication is offered by the server, this will cause <EM>Alpine</EM> to +attempt to use it. +If authentication is not offered by the server, this will cause <EM>Alpine</EM> +to fail with an error similar to: + +<P> +<CENTER><SAMP>Error: NNTP authentication not available</SAMP></CENTER> +<P> +For more details about the server name possibilities see +<A HREF="config-notes.html#server-name-syntax">Server Name Syntax</A>. +<P> + +<DT> <A NAME="norm-back"><EM>normal-background-color</EM></A> +<DT> <A NAME="normal-foreground-color"><EM>normal-foreground-color</EM></A> + +<DD> <A HREF="#normal-color"><EM>Normal Color</EM></A>. +<P> + +<DT> <A NAME="opening-text-separator-chars"><EM>opening-text-separator-chars</EM></A> +<DD> This option controls a minor aspect of <EM>Alpine</EM>'s MESSAGE INDEX screen. +With some setups the text of the subject is followed +by the opening text of the message if there is any room available in the index line. +If you have configured your +<A HREF="#index-format"><EM>Index-Format</EM></A> option +to include one of the Subject tokens which causes this behavior +(SUBJECTTEXT, SUBJKEYTEXT, or SUBJKEYINITTEXT), then this option may be used +to modify what is displayed slightly. +By default, the Subject is separated from the opening text of the message by +the three characters space dash space; +<P> +<CENTER><SAMP>" - "</SAMP></CENTER> +<P> +Use this option to set it to something different. +The value must be quoted if it includes any space characters. +For example, the default value could be specified explicitly by setting this +option to +<P> +<CENTER><SAMP>Opening-Text-Separator-Chars=" - "</SAMP></CENTER> +<P> +This option is displayed as "Opening Text Separator Characters". +<P> + +<DT> <A NAME="operating-dir"><EM>operating-dir</EM></A> + +<DD> System-wide <EM>Alpine</EM> configuration files only. +This names the root of the +tree to which the user is restricted when reading and writing folders and +files. It is usually used in the <EM>fixed</EM> configuration file. <P> + +<DT> <A NAME="patterns-filters2"><EM>patterns-filters2</EM></A> + +<DD> Matching patterns and their corresponding actions are stored in +this variable. +These patterns are used with +<A HREF="#filter-config"><EM>Filtering</EM></A>. +This variable is normally maintained through the Setup/Rules/Filters +configuration screen. +It is a list variable. +Each member of the list is a single pattern/action pair, or it can be +a file which contains zero or more lines of pattern/action pairs. +The only way to create a filters file is to use the InsertFile command in +the Setup/Rules/Filters screen with a filename which doesn't yet exist. +Then use the Shuffle command to move existing filter patterns into the file. +This isn't very convenient but it isn't thought that many users will +need this functionality. +The purpose of filter files is for sharing filters. +<P> +This option is displayed as "Patterns Filters". +<P> + +<DT> <A NAME="patterns-indexcolors"><EM>patterns-indexcolors</EM></A> + +<DD> Matching patterns and their corresponding actions are stored in +this variable. +These patterns are used for +<A HREF="#index-color-config"><EM>Index Line Colors</EM></A>. +This variable is normally maintained through the Setup/Rules/Indexcolor +configuration screen. +It is a list variable. +Each member of the list is a single pattern/action pair, or it can be +a file which contains zero or more lines of pattern/action pairs. +The only way to create a indexcolor file is to use the InsertFile command in +the Setup/Rules/Indexcolor screen with a filename which doesn't yet exist. +Then use the Shuffle command to move existing patterns into the file. +This isn't very convenient but it isn't thought that many users will +need this functionality. +The purpose of indexcolor files is for sharing indexcolors. +<P> + +<DT> <A NAME="patterns-other"><EM>patterns-other</EM></A> + +<DD> Matching patterns and their corresponding actions are stored in +this variable. +These patterns are used with +<A HREF="#other-config"><EM>Miscellaneous Rules</EM></A> configuration. +This variable is normally maintained through the Setup/Rules/Other +configuration screen. +It is a list variable. +Each member of the list is a single pattern/action pair, or it can be +a file which contains zero or more lines of pattern/action pairs. +The only way to create a rules file is to use the InsertFile command in +the Setup/Rules/Other screen with a filename which doesn't yet exist. Then use +the Shuffle command to move existing rules into the file. +This isn't very convenient but it isn't thought that many users will +need this functionality. +<P> + +<DT> <A NAME="patterns-roles"><EM>patterns-roles</EM></A> + +<DD> Matching patterns and their corresponding actions are stored in +this variable. +These patterns are used with +<A HREF="#role-config"><EM>Roles</EM></A>. +This variable is normally maintained through the Setup/Rules/Roles +configuration screen. +It is a list variable. +Each member of the list is a single pattern/action pair, or it can be +a file which contains zero or more lines of pattern/action pairs. +The only way to create a roles file is to use the InsertFile command in +the Setup/Rules/Roles screen with a filename which doesn't yet exist. Then use +the Shuffle command to move existing roles into the file. +This isn't very convenient but it isn't thought that many users will +need this functionality. +The purpose of role files is for sharing roles. +<P> + +<DT> <A NAME="patterns-scores2"><EM>patterns-scores2</EM></A> + +<DD> Matching patterns and their corresponding actions are stored in +this variable. +These patterns are used with +<A HREF="#scoring-config"><EM>Scoring</EM></A>. +This variable is normally maintained through the Setup/Rules/SetScores +configuration screen. +It is a list variable. +Each member of the list is a single pattern/action pair, or it can be +a file which contains zero or more lines of pattern/action pairs. +The only way to create a scores file is to use the InsertFile command in +the Setup/Rules/SetScores screen with a filename which doesn't yet exist. +Then use the Shuffle command to move existing scoring patterns into the file. +This isn't very convenient but it isn't thought that many users will +need this functionality. +The purpose of scoring files is for sharing scoring rules. +<P> +This option is displayed as "Patterns Scores". +<P> + +<DT> <A NAME="patterns-search"><EM>patterns-search</EM></A> + +<DD> Matching patterns for use with the Select command are stored in +this variable. +These patterns are used with +<A HREF="#search-rules-config"><EM>Search Rules</EM></A> configuration. +This variable is normally maintained through the Setup/Rules/searCh +configuration screen. +It is a list variable. +Each member of the list is a single pattern, or it can be +a file which contains zero or more lines of patterns. +The only way to create a rules file is to use the InsertFile command in +the Setup/Rules/searCh screen with a filename which doesn't yet exist. Then use +the Shuffle command to move existing rules into the file. +This isn't very convenient but it isn't thought that many users will +need this functionality. +<P> + +<DT> <A NAME="personal-name"><EM>personal-name</EM></A> + +<DD> Personal configuration file only. +User's full personal name. On UNIX systems, the default is taken +from the accounts data base (<CODE>/etc/passwd</CODE>). +The easiest way to change the full From address is with the +<A HREF="#cust-hdr"><EM>customized-hdrs</EM></A> variable. +<P> + +<DT> <A NAME="personal-print-category"><EM>personal-print-category</EM></A> + +<DD> Personal configuration file only. +This is the category that the default print command belongs to. There +are three categories. Category 1 is an attached printer which uses the ANSI +escape sequence, category 2 is the standard system print command, and +category 3 is the set of custom printer commands defined by the user. +This just helps <EM>Alpine</EM> figure out where to put the cursor when the user +runs the <EM>Setup/Printer</EM> command. This is not used by <EM>PC-Alpine</EM>. +<P> + +<DT> <A NAME="personal-print-command"><EM>personal-print-command</EM></A> + +<DD> Personal configuration file only. +This corresponds to the third category in the printer menu, the +personally selected print commands. This variable +contains the list of custom commands that the user has entered in the +<EM>Setup/Printer</EM> screen. This is not used by <EM>PC-Alpine</EM>. +<P> + +<DT> <A NAME="posting-char-set"><EM>posting-character-set</EM></A> + +<DD> See the discussion in +<A HREF="low-level.html#char-set">International Character Sets</EM></A> for +details.<P> + +<DT> <A NAME="postponed-folder"><EM>postponed-folder</EM></A> + +<DD> The folder where postponed messages are stored. The default is +<EM>postponed-msgs</EM> (Unix) or <EM>POSTPOND</EM> (PC). <P> + +<DT> <A NAME="print-font-name"><EM>print-font-name</EM></A> + +<DD> Winsock version of <EM>PC-Alpine</EM> only. <P> + +<DT> <A NAME="print-font-size"><EM>print-font-size</EM></A> + +<DD> Winsock version of <EM>PC-Alpine</EM> only. <P> + +<DT> <A NAME="print-font-style"><EM>print-font-style</EM></A> + +<DD> Winsock version of <EM>PC-Alpine</EM> only. <P> + +<DT> <A NAME="printer"><EM>printer</EM></A> + +<DD> Personal configuration file only. +This is the current setting for a user's printer. +This variable is set from <EM>Alpine</EM>'s <EM>Setup/Printer</EM> screen. +<P> + +<DT> <A NAME="prompt-background-color"><EM>prompt-background-color</EM></A> +<DT> <A NAME="prompt-foreground-color"><EM>prompt-foreground-color</EM></A> + +<DD> <A HREF="#prompt-color"><EM>Prompt Color</EM></A>. +<P> + +<DT> <A NAME="pruned-folders"><EM>pruned-folders</EM></A> + +<DD> This variable allows you to define a list of one or more folders that +<EM>Alpine</EM> will offer to prune for you in the same way it automatically offers +to prune your "sent-mail" folder each month. +Each folder in this list must be a folder in your default folder collection +(the first folder collection if you have more than one), and it is just +the relative name of the folder in the collection, not the fully-qualified name. +It is similar to sent-mail. +Instead of something like +<P> +<CENTER><SAMP>pruned-folders={servername}mail/folder</SAMP></CENTER> +<P> +the correct value to use would be +<P> +<CENTER><SAMP>folder</SAMP></CENTER> +<P> +There is an assumption here that your first collection is the folders in +<P> +<CENTER><SAMP>{servername}mail</SAMP></CENTER> +<P> + +Once a month, for each folder listed, <EM>Alpine</EM> will offer to move +the contents of the folder to a new folder of the same name but with +the previous month's date appended. <EM>Alpine</EM> will then look for any such +date-appended folder names created for a previous month, and offer each +one it finds for deletion. +<P> + +If you decline the first offer, no mail is moved and no new folder is +created. +<P> + +The new folders will be created +in your default folder collection. +<P> + +<DT> <A NAME="pruning-rule"><EM>pruning-rule</EM></A> + +<DD> By default, <EM>Alpine</EM> will ask at the beginning of each month whether or not +you want to rename your sent-mail folder to a name like sent-mail-month-year. +(See the feature <A HREF="#prune-uses-yyyy-mm">prune-uses-yyyy-mm</A> to +change the format of the folder to sent-mail-yyyy-mm.) +It will also ask whether you would like to delete old sent-mail folders. +If you have defined +<A HREF="#read-msg-fold"><EM>read-message-folder</EM></A> +or +<A HREF="#pruned-folders"><EM>pruned-folders</EM></A> +<EM>Alpine</EM> will also ask about pruning those folders. +With this option you may provide an automatic answer to the rename questions +and you may tell <EM>Alpine</EM> to not ask about deleting old folders.<P> + +<DT> <A NAME="quote1-background-color"><EM>quote1-background-color</EM></A> +<DT> <A NAME="quote1-foreground-color"><EM>quote1-foreground-color</EM></A> +<DT> <A NAME="quote2-background-color"><EM>quote2-background-color</EM></A> +<DT> <A NAME="quote2-foreground-color"><EM>quote2-foreground-color</EM></A> +<DT> <A NAME="quote3-background-color"><EM>quote3-background-color</EM></A> +<DT> <A NAME="quote3-foreground-color"><EM>quote3-foreground-color</EM></A> + +<DD> <A HREF="#quote-colors"><EM>Quote Colors</EM></A>. +<P> + +<DT> <A NAME="quote-replace-string"><EM>quote-replace-string</EM></A> + +<DD> This option specifies what string to use as a quote when <b>viewing</b> a +message. The standard way of quoting messages when replying is the string +"> " (quote space). +With this variable set, viewing a message will +replace occurrences of "> " with the replacement string. +This setting works best when +<A HREF="#reply-ind-string">Reply-Indent-String</A> +or the equivalent setting in your correspondents' mail programs +is set to the default "> ", but it will also work fine with the +Reply-Indent-String set to ">". +<P> +Enable the feature +<A HREF="#quote-replace-nonflowed">Quote-Replace-Nonflowed</A> +to also have quote-replacement performed on non-flowed messages. +<P> +Setting this option will replace ">" and +"> " with the new setting. This string may include trailing +spaces. To preserve those spaces enclose the full string in double quotes. +<P> +No padding to separate the text of the message from the quote string is +added. This means that if you do not add trailing spaces to the value of +this variable, text will be displayed right next to the quote string, +which may be undesirable. This can be avoided by adding a new string +separated by a space from your selection of quote string replacement. This +last string will be used for padding. For example, setting this variable to +">" " " has the effect of setting +">" as the quote-replace-string, with the text padded by +a space from the last quote string to make it more readable. +<P> +One possible setting for this variable could be +" " (four spaces wrapped in quotes), which +would have the effect of indenting each level of quoting four spaces and +removing the ">"'s. Different levels of quoting could be made +more discernible by setting colors for quoted text. +<P> +Replying to or forwarding the viewed message will preserve the original +formatting of the message, so quote-replacement will not be performed on +messages that are being composed. +<P> + +<DT> <A NAME="quote-suppression-threshold"><EM>quote-suppression-threshold</EM></A> + +<DD> This option should be used with care. +It will cause some of the quoted text to be eliminated from the +display when viewing a message in the MESSAGE TEXT screen. +For example, if you set the Quote-Suppression-Threshold to the +value "5", +this will cause quoted text that is longer than five lines to be truncated. +Quoted text of five or fewer consecutive lines will be displayed in its entirety. +Quoted text of more than six lines will have the first five lines displayed +followed by a line that looks something like +<P> +<CENTER><SAMP>[ 12 lines of quoted text hidden from view ]</SAMP></CENTER> +<P> +As a special case, if exactly one line of quoted text would be hidden, the +entire quote will be shown instead. +So for the above example, quoted text which is exactly six lines long will +will be shown in its entirety. +(In other words, instead of hiding a single line and adding a line +that announces that one line was hidden, the line is just shown.) +<P> +If the sender of a message has carefully chosen the quotes that he or she +includes, hiding those quotes may change the meaning of the message. +For that reason, <EM>Alpine</EM> requires that when you want to set the value of this +variable to something less than four lines, you actually have to set it +to the negative of that number. +So if you want to set this option to "3", you actually have to +set it to "-3". +The only purpose of this is to get you to think about whether or not you +really want to do this! +If you want to delete all quoted text you set the value of this option +to the special value "-10". +<P> +The legal values for this option are +<P> +<TABLE> +<TR> + <TD> 0 </TD> + <TD> Default, don't hide anything </TD> +</TR> +<TR> + <TD> -1,-2,-3 </TD> + <TD> Suppress quote lines past 1, 2, or 3 lines </TD> +</TR> +<TR> + <TD> 4,5,6,... </TD> + <TD> Suppress if more than that many lines </TD> +</TR> +<TR> + <TD> -10 </TD> + <TD> Suppress all quoted lines </TD> +</TR> +</TABLE> +<P> +If you set this option to a non-default value you may sometimes wish to +view the quoted text that is not shown. +When this is the case, the HdrMode (Header Mode) command may be used to +show the hidden text. +Typing the "H" command once will show the hidden text. +Typing a second "H" will also turn on Full Header mode. +The presence or absence of the HdrMode command is determined by the +<A HREF="#enable-full-header-cmd">"Enable-Full-Header-Cmd"</A> +Feature-List option in your <EM>Alpine</EM> configuration, so you will want to +be sure that is turned on if you use quote suppression. +<P> +For the purposes of this option, a quote is a line that begins with the +character ">". +<P> +Quotes are only suppressed when displaying a message on the screen. +The entire quote will be left intact when printing or forwarding or something +similar. +<P> + +<DT> <A NAME="read-msg-fold"><EM>read-message-folder</EM></A> + +<DD> If set, mail in the <EM>INBOX</EM> that has been read but not deleted +is moved here, or rather, the user is asked whether or not he or she wants +to move it here upon quitting <EM>Alpine</EM>. <P> + +<DT> <A NAME="remote-abook-history"><EM>remote-abook-history</EM></A> + +<DD> Sets how many extra copies of +<A HREF="low-level.html#addrbook">remote address book</A> +data will be kept in each remote address book folder. +The default is three. +These extra copies are simply old versions of the data. Each time a change +is made a new copy of the address book data is appended to the folder. Old +copies are trimmed, if possible, when <EM>Alpine</EM> exits. +An old copy can be put back into use by +deleting and expunging newer versions of the data from the folder. +Don't delete the first message from the folder. It is a special header +message for the remote address book and it must be there. +This is to prevent regular folders from being used as remote address book +folders and having their data destroyed. +<P> + +<DT> <A NAME="remote-abook-metafile"><EM>remote-abook-metafile</EM></A> + +<DD> Personal configuration file only. +This is usually set by <EM>Alpine</EM> and is the name of a file +that contains data about +<A HREF="low-level.html#addrbook">remote address books</A> and +<A HREF="low-level.html#remote-config">remote configuration files</A>. +<P> + +<DT> <A NAME="remote-abook-validity"><EM>remote-abook-validity</EM></A> + +<DD> Sets the minimum number of minutes that a +remote address book will be considered up to date. +Whenever an entry contained in a remote address book is used, +if more than this many minutes have +passed since the last check the remote server will be queried to see if the +address book has changed. +If it has changed, the local copy is updated. +The default value is five minutes. +The special value of -1 means never check. +The special value of zero means only check when the address book is first +opened. +<P> +No matter what the value, the validity check is always done when the +address book is about to be changed by the user. +The check can be initiated manually by typing <EM>^L</EM> (Ctrl-L) +while in the address book maintenance screen for the remote address book. +<P> + +<DT> <A NAME="reply-ind-str"><EM>reply-indent-string</EM></A> + +<DD> This variable specifies an aspect of <EM>Alpine</EM>'s <EM>Reply</EM> +command. +When a message is replied to and the text of the message is included, the +included text usually has the string "> " prepended +to each line indicating it is quoted text. + +<P> +This option specifies a different value for that string. +If you wish to use a string which begins or ends with a space, +enclose the string in double quotes. + +<P> +Besides simple text, the prepended string can be based +on the message being replied to. +The following tokens are substituted for the message's corresponding value: + +<DL> +<DT>_FROM_</DT> +<DD>This token gets replaced with the message sender's "username". +At most six characters are used. +</DD> + +<DT>_NICK_</DT> +<DD>This token gets replaced with the nickname of the message sender's +address as found in your addressbook. +If no addressbook entry is found, +Pine replaces the characters "_NICK_" with nothing. +At most six characters are used. +</DD> + +<DT>_INIT_</DT> +<DD>This token gets replaced with the initials of the sender of the message. +</DD> + +</DL> + +When the +<A HREF="#enable-reply-indent-string-editing"><EM>enable-reply-indent-string-editing</EM></A> +feature is enabled, you are given the opportunity to edit the string, whether +it is the default or one automatically generated using the above tokens. +<P> + +<DT> <A NAME="reply-leadin"><EM>reply-leadin</EM></A> + +<DD> This option is used to customize the content of the introduction line +that is included when replying to a message and including the original +message in the reply. +The normal default (what you will get if you delete this variable) looks +something like: +<P> +<CENTER><SAMP>On Sat, 24 Oct 1998, Fred Flintstone wrote:</SAMP></CENTER> +<P> +where the day of the week is only included if it is available in the +original message. +You can replace this default with text of your own. +The text may contain tokens that are replaced with text +that depends on the message you are replying to. +For example, the default is equivalent to: +<P> +<CENTER><SAMP>On _DAYDATE_, _FROM_ wrote:</SAMP></CENTER> +<P> + +Since this variable includes regular text mixed with special tokens +the tokens have to be surrounded by underscore characters. +For example, to use the token "<SAMP>PREFDATE</SAMP>" +you would need to use "<SAMP>_PREFDATE_</SAMP>", +not "<SAMP>PREFDATE</SAMP>". +<P> +The list of available tokens is +<A HREF="#index-tokens"><EM>here</EM></A>. + +<P> +By default, the text is all on a single line and is followed by a blank line. +If your <EM>Reply-Leadin</EM> turns out to be longer +than 80 characters when replying to a particular message, it is shortened. +However, if you use the token +<P> +<CENTER><SAMP>_NEWLINE_</SAMP></CENTER> +<P> + +anywhere in the value, no end of line or blank line is appended, and no +shortening is done. +The _NEWLINE_ token may be used to get rid of the blank line following +the text, to add more blank lines, or to form a multi-line +<EM>Reply-Leadin</EM>. +To clarify how _NEWLINE_ works recall that the default value is: +<P> +<CENTER><SAMP>On _DAYDATE_, _FROM_ wrote:</SAMP></CENTER> +<P> + +That is equivalent to +<P> +<CENTER><SAMP>On _DAYDATE_, _FROM_ wrote:_NEWLINE__NEWLINE_</SAMP></CENTER> +<P> + +In the former case, two newlines are added automatically because +no _NEWLINE_ token appears in the value of the option (for backwards +compatibility). In the latter case, the newlines are explicit. +If you want to remove the blank line that follows the +<EM>Reply-Leadin</EM> text use a single +_NEWLINE_ token like +<P> +<CENTER><SAMP>On _DAYDATE_, _FROM_ wrote:_NEWLINE_</SAMP></CENTER> +<P> + +Because of the backwards compatibility problem, it is not possible to +remove all of the ends of lines, because then there will be no _NEWLINE_ tokens +and that will cause the automatic adding of two newlines! +If you want, you may embed newlines in the middle of the text, as well, +producing a multi-line <EM>Reply-Leadin</EM>. + +<P> +By default, no attempt is made to localize the date. +If you prefer a localized form you may find that one of the tokens +_PREFDATE_ or _PREFDATETIME_ is a satisfactory substitute. +If you want more control one of the many other date tokens, such as _DATEISO_, +might be better. + +<P> +For the adventurous, there is a way to conditionally include text based +on whether or not a token would result in specific replacement text. +For example, you could include some text based on whether or not +the _NEWS_ token would result in any newsgroups if it was used. +It's explained in detail +<A HREF="#reply-token-conditionals"><EM>here</EM></A>. + +<P> +In the very unlikely event that you want to include a literal token +in the introduction line you must precede it with a backslash character. +For example, +<P> +<CENTER><SAMP>\_DAYDATE_ = _DAYDATE_</SAMP></CENTER> +<P> +would produce something like +<P> +<CENTER><SAMP>_DAYDATE_ = Sat, 24 Oct 1998</SAMP></CENTER> +<P> +It is not possible to have a literal backslash followed by an expanded token. +<P> + +<DT> <A NAME="reverse-background-color"><EM>reverse-background-color</EM></A> +<DT> <A NAME="reverse-foreground-color"><EM>reverse-foreground-color</EM></A> + +<DD> <A HREF="#reverse-color"><EM>Reverse Color</EM></A>. +<P> + +<DT> <A NAME="rsh-command"><EM>rsh-command</EM></A> + +<DD> Sets the format of the command used to +open a UNIX remote shell connection. The default is +"%s %s -l %s exec /etc/r%sd". All four "%s" entries MUST exist in the +provided command. The first is for the command's pathname, the second is +for the host to connnect to, the third is for the user to connect as, and +the fourth is for the connection method (typically <CODE>imap</CODE>). +<P> + +<DT> <A NAME="rsh-open-timeout"><EM>rsh-open-timeout</EM></A> + +<DD> Sets the time in seconds that <EM>Alpine</EM> will +attempt to open a UNIX remote shell connection. +The default is 15, the minimum non-zero value is 5, +and the maximum is unlimited. If this is set to zero rsh connections +will be completely disabled. +<P> + +<DT> <A NAME="rsh-path"><EM>rsh-path</EM></A> + +<DD> Sets the name of the command used to open a UNIX remote shell +connection. The default is typically <CODE>/usr/ucb/rsh</CODE>. +<P> + +<DT> <A NAME="saved-msg-name"><EM>saved-msg-name-rule</EM></A> + +<DD> Determines default folder name when <EM>Sav</EM>ing. +If set to <EM>default-folder</EM> (which is the default setting), +then <EM>Alpine</EM> will offer the folder "saved-messages" (UNIX) or "SAVEMAIL" +(PC) for <EM>Sav</EM>ing messages. The default folder offered in this way +may be changed by using the configuration variable +<A HREF="#def-save"><EM>default-saved-msg-folder</EM></A>. +<P> + +If this rule is set to <EM>last-folder-used</EM>, <EM>Alpine</EM> offers to +<EM>Save</EM> to the folder you last successfully <EM>Saved</EM> a message +to (this session). +The first time you <EM>Save</EM> a message in a session, +<EM>Alpine</EM> offers to <EM>Save</EM> the message to the default folder. +<P> + +Choosing any of the <EM>by-</EM> options causes <EM>Alpine</EM> to attempt +to get the chosen option's value for the message being <EM>Saved</EM> (or +for the first message being Saved if using an aggregate Save). +For example, if <EM>by-from</EM> is chosen, <EM>Alpine</EM> attempts to +get the value of who the message +came from (i.e. the from address). <EM>Alpine</EM> then attempts to +<EM>Save</EM> the message to a folder matching that value. +If <EM>by-from</EM> is chosen and no value is +obtained, <EM>Alpine</EM> uses <EM>by-sender</EM>. +The opposite is also true. +If <EM>by-recipient</EM> was chosen and the message was posted to a newsgroup, +<EM>Alpine</EM> will use the newsgroup name. +If <EM>by-replyto</EM> is chosen and no value is +obtained, <EM>Alpine</EM> uses <EM>by-from</EM>. +<P> + +If any of the "by-realname" options are chosen, <EM>Alpine</EM> will attempt +to use the personal name part of the address instead of the mailbox part. +If any of the "by-nick" options are chosen, the +address is looked up in your address book and if found, the +nickname for that entry is used. +Only simple address book entries are checked, not distribution lists. +Similarly, if any of the +"by-fcc" options are chosen, the fcc from the corresponding +address book entry is used. +If by-realname, or the by-nick or by-fcc lookups result in no value, +then if the chosen option ends with the "then-from", +"then-sender", "then-replyto", +or "then-recip" suffix, <EM>Alpine</EM> +reverts to the same behavior as "by-from", +"by-sender", "by-replyto", or "by-recip" +depending on which option was specified. +If the chosen option doesn't end with one of +the "then-" suffixes, then <EM>Alpine</EM> reverts to the default +folder when no match is found in the address book. + +<P> +Here is an example to make some of the options clearer. +If the message is From +<P> +<CENTER><SAMP>Fred Flintstone <flint@bedrock.org></SAMP></CENTER> +<P> +and this rule is set to "by-from", then the default folder offered +in the save dialog would be "flint". +<P> +If this rule is set to "by-realname-of-from" then the default would +be "Fred Flintstone". +<P> +If this rule is set to "by-nick-of-from" then <EM>Alpine</EM> will search +for the address "flint@bedrock.org" in your address book. +If an entry is found and it has a nickname associated with it, that nickname +will be offered as the default folder. +If not, the default saved message folder will be offered as the default. +<P> +If this rule is set to "by-fcc-of-from" then <EM>Alpine</EM> will search +for the address "flint@bedrock.org" in your address book. +If an entry is found and it has an Fcc associated with it, that Fcc +will be offered as the default folder. +If not, the default saved message folder will be offered as the default. +<P> +If this rule is set to "by-nick-of-from-then-from" then <EM>Alpine</EM> will search +for the address "flint@bedrock.org" in your address book. +If an entry is found and it has a nickname associated with it, that nickname +will be offered as the default folder. +If it is not found (or has no nickname) then the default offered will be +the same as it would be for the "by-from" rule. +That is, it would be "flint" +<P> +This option is displayed as "Saved Message Name Rule". +<P> + +<DT> <A NAME="scroll-margin"><EM>scroll-margin</EM></A> + +<DD> This option controls when <EM>Alpine</EM>'s line-by-line scrolling occurs. +Typically, when a selected item is at the top or bottom screen edge +and the UP or DOWN (and Ctrl-P or Ctrl-N) keys are pressed, the +displayed items are scrolled down or up by a single line. +<P> + +This option allows you to tell <EM>Alpine</EM> the number of lines from the top and +bottom screen edge that line-by-line scrolling should occur. For example, +setting this value to one (1) will cause <EM>Alpine</EM> to scroll the display +when you move to select an item on the display's top or +bottom edge (instead of moving when you move off the edge of the screen). +<P> + +By default, this variable is zero (0), indicating that scrolling happens +when you move up or down to select an item immediately off the display's +top or bottom edge. +<P> + +<DT> <A NAME="selectable-item-background-color"><EM>selectable-item-background-color</EM></A> +<DT> <A NAME="selectable-item-foreground-color"><EM>selectable-item-foreground-color</EM></A> + +<DD> <A HREF="#selectable-item-color"><EM>Selectable-item Color</EM></A>. +<P> + +<DT> <A NAME="sending-filters"><EM>sending-filters</EM></A> + +<DD> This option defines a list of text-filtering commands (programs and +scripts) that may be selectively invoked to process a message just before +it is sent. If set, the Composer's <EM>^X Send</EM> command will allow you to +select which filter (or none) to apply to the message before it is sent. +For security reasons, the full path of the filter program must be +specified. +<P> +Sending filters do not work with <EM>PC-Alpine</EM> and sending filters are +not used if the feature +<A HREF="#send-without-confirm">send-without-confirm</A> is set. +<P> +Command Modifying Tokens: + +<DL> +<DT><EM>_RECIPIENTS_</EM> +<DD>When the command is executed, this token is replaced +with the space delimited list of recipients of the +message being sent. + +<DT><EM>_TMPFILE_</EM> +<DD> +When the command is executed, this token is +replaced with the path and name of the temporary +file containing the text to be filtered. <EM>Alpine</EM> +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. +<EM>Alpine</EM> restores the tty modes before invoking the +filter in case the filter interacts with the user +via its own standard input and output. + +<DT><EM>_RESULTFILE_</EM> +<DD>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. <EM>Alpine</EM> displays this in the message status +field. + +<DT><EM>_DATAFILE_</EM> +<DD>When the command is executed, this token is replaced +in the command line with the path and name of a +temporary file that <EM>Alpine</EM> 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. + +<DT><EM>_PREPENDKEY_</EM> +<DD>When the command is executed, this token indicates +that a random number will be passed down the input +stream before the message text. It is not included as a command-line argument. +This number could be used as a session key. It is sent in this way +to improve security. The number is unique to the +current <EM>Alpine</EM> session and is only generated once per +session. + +<DT><EM>_INCLUDEALLHDRS_</EM> +<DD>When the command is executed, this token indicates +that the headers of the message will be passed down the input stream +before the message text. +It is not included as a command-line argument. +The filter should, of course, remove the headers before returning control +to <EM>Alpine</EM>. + +<DT><EM>_MIMETYPE_</EM> +<DD>When the command is executed, this token is replaced in the +command name with a temporary file name used to accept any new MIME +Content-Type information necessitated by the output of the filter. +Upon the filter's exit, if the file contains new MIME type +information, <EM>Alpine</EM> verifies its format and replaces the outgoing +message's MIME type information with that contained in the file. This +is basically a cheap way of sending something other than Text/Plain. +</DL> +<P> + +<DT> <A NAME="sendmail-path"><EM>sendmail-path</EM></A> + +<DD> This names the path to an +alternative program, and any necessary arguments, to be used in posting +mail messages. See the section on <A +HREF="background.html#SMTP">SMTP and Sendmail</A> for more details. +<P> + +<DT> <A NAME="sig-file"><EM>signature-file</EM></A></A> + +<DD> This is the name of a file which will be automatically inserted into +outgoing messages. +It typically contains information such as your +name, email address and organizational affiliation. +<EM>Alpine</EM> adds the +signature into the message as soon as you enter the composer so you +can choose to remove it or edit it on a message by message basis. +Signature file placement in message replies is controlled by the +<A HREF="#sig-at-bot">signature-at-bottom</A> +setting in the feature list. +<P> + +This defaults to +<CODE>~/.signature</CODE> on UNIX and <PINERC +directory><CODE>\PINE.SIG</CODE> on a PC. <P> + +To create or edit your signature file choose Setup from the Main Menu +and then select S for Signature (Main/Setup/Signature). +This puts you +into the Signature Editor where you can enter a <EM>few</EM> lines of +text containing your identity and affiliation. + +<P> +If the filename is followed by a vertical bar (|) then instead +of reading the contents of the file the file is assumed to be a +program which will produce the text to be used on its standard output. +The program can't have any arguments and doesn't receive any input from <EM>Alpine</EM>, +but the rest of the processing works as if the contents came from a file. + +<P> +Instead of storing the data in a local file, the +signature data may be stored remotely in an IMAP folder. +In order to do this, +you must use a remote name for the file. +A remote signature-file name might look like: +<P> +<CENTER><SAMP>{myimaphost.myschool.k12.wa.us}mail/signature</SAMP></CENTER> +<P> +or, if you have an SSL-capable version of <EM>Alpine</EM>, you might try +<P> +<CENTER><SAMP>{myimaphost.myschool.k12.wa.us/user=loginname/ssl}mail/signature</SAMP></CENTER> +<P> + +The syntax used here is the same as the syntax used for remote configuration +files from the command line. +Note that you may not access an existing signature file remotely, +you have to create a new <EM>folder</EM> which contains the signature data. +If the name you use here for the signature file is a remote name, then when +you edit the file from the Setup/Signature command the data will be stored +remotely in the folder. +You aren't required to do anything special to create the folder, it +gets created automatically if you use a remote name. + +<P> +Besides regular text, the signature file may also contain +(or a signature program may produce) tokens which +are replaced with text which usually depends on the message you are replying +to or forwarding. +For example, if the signature file contains the token +<P> +<CENTER><SAMP>_DATE_</SAMP></CENTER> +<P> +anywhere in the text, then that token is replaced by the date +the message you are replying to or forwarding was sent. +If it contains +<P> +<CENTER><SAMP>_CURDATE_</SAMP></CENTER> +<P> +that is replaced with the current date. +The first is an example of a token which depends on the message you +are replying to (or forwarding) and the second is an example which +doesn't depend on anything other than the current date. +You have to be a little careful with this facility since tokens which +depend on the message you are replying to or forwarding will be replaced +by nothing in the case where you are composing a new message from scratch. +The use of <A HREF="#role-config"><EM>roles</EM></A> may help you +in this respect. +It allows you to use different signature files in different cases. +<P> + +The list of tokens available for use in the signature file is +<A HREF="#index-tokens"><EM>here</EM></A>. +<P> + +Instead of, or along with the use of <EM>roles</EM> to give you +different signature files in different situations, there is also +a way to conditionally include text based +on whether or not a token would result in specific replacement text. +For example, you could include some text based on whether or not +the _NEWS_ token would result in any newsgroups if it was used. +This is explained in detail +<A HREF="#reply-token-conditionals"><EM>here</EM></A>. +This isn't for the faint of heart. +<P> +In the very unlikely event that you want to include a literal token +in the signature you must precede it with a backslash character. +For example, +<P> +<CENTER><SAMP>\_DAYDATE_ = _DAYDATE_</SAMP></CENTER> +<P> +would produce something like +<P> +<CENTER><SAMP>_DAYDATE_ = Sat, 24 Oct 1998</SAMP></CENTER> +<P> +It is not possible to have a literal backslash followed by an expanded token. +<P> + +<DT> <A NAME="signature-background-color"><EM>signature-background-color</EM></A> +<DT> <A NAME="signature-foreground-color"><EM>signature-foreground-color</EM></A> + +<DD> <A HREF="#signature-color"><EM>Signature Color</EM></A>. +<P> + +<DT> <A NAME="smime-public-cert-directory"><EM>smime-public-cert-directory</EM></A> + +<DD> UNIX <EM>Alpine</EM> only. +<P> +If the option +<A HREF="#smime-public-cert-container"><EM>smime-public-cert-container</EM></A> +is set then this option will have no effect. +<P> +Normally, Public Certificates for use with S/MIME will be stored in the directory +which is the value of this option. +Those certificates will be stored in PEM format, one certificate per file. +The name of the file for the certificate corresponding to +<P> +<CENTER><SAMP>emailaddress</SAMP></CENTER> +<P> +should be +<P> +<CENTER><SAMP>emailaddress.crt</SAMP></CENTER> +<P> +For example, a file for user@example.com would be in the file +<P> +<CENTER><SAMP>user@example.com.crt</SAMP></CENTER> +<P> +in this directory. +<P> +Use the Setup/SMIME screen to modify this variable. +<P> +Typically, the public certificates that you have will come from S/MIME signed +messages that are sent to you. +<EM>Alpine</EM> will extract the public certificate from the signed message and store +it in the certificates directory. +These PEM format public certificates look something like: +<PRE> +-----BEGIN CERTIFICATE----- +MIIFvTCCBKWgAwIBAgIQD4fYFHVI8T20yN4nus097DANBgkqhkiG9w0BAQUFADCB +rjELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAlVUMRcwFQYDVQQHEw5TYWx0IExha2Ug +Q2l0eTEeMBwGA1UEChMVVGhlIFVTRVJUUlVTVCBOZXR3b3JrMSEwHwYDVQQLExho +... +2b9KGqDyMWW/rjNnmpjzjT2ObGM7lRA8lke4FLOLajhrz4ogO3b4DFfAAM1VSZH8 +D6sOwOLJZkLY8FRsfk63K+2EMzA2+qAzMKupgeTLqXIf +-----END CERTIFICATE----- +</PRE> +<P> +<UL> +<LI><A HREF="config-notes.html#smime-general">General S/MIME Overview</A> +</UL><P> +This option is displayed as "S/MIME - Public Cert Directory". +<P> + +<DT> <A NAME="smime-public-cert-container"><EM>smime-public-cert-container</EM></A> + +<DD> UNIX <EM>Alpine</EM> only. +<P> +If this option is set it will be used instead of +<A HREF="#smime-public-cert-directory"><EM>smime-public-cert-directory</EM></A> +<P> +This option gives you a way to store certificates remotely on an IMAP server +instead of storing the certificates one per file locally. +In order to do that you just give this option a remote folder name for a folder +which does not yet exist. +The name is similar to the name you might use for a remote configuration file. +A remote folder name might look something like: +<P> +<CENTER><SAMP>{myimaphost.myschool.k12.wa.us}mail/publiccerts</SAMP></CENTER> +<P> +Use the Setup/SMIME screen to modify this variable. +<P> +<UL> +<LI><A HREF="config-notes.html#smime-general">General S/MIME Overview</A> +</UL><P> +This option is displayed as "S/MIME - Public Cert Container". +<P> + +<DT> <A NAME="smime-private-key-directory"><EM>smime-private-key-directory</EM></A> + +<DD> UNIX <EM>Alpine</EM> only. +<P> +In order to sign outgoing S/MIME messages you will need a +personal digital ID certificate. +You will usually get such a certificate from a certificate authority such as +Thawte or CAcert. +(In order to encrypt outgoing messages you don't need a personal digital ID, you +need the public certificate of the recipient instead.) +If the option +<A HREF="#smime-private-key-container"><EM>smime-private-key-container</EM></A> +is set then this option will have no effect. +<P> +Normally, Private Keys for use with S/MIME will be stored in the directory +which is the value of this option. +Those certificates will be stored in PEM format, one certificate per file. +The name of the file for the certificate corresponding to your +<P> +<CENTER><SAMP>emailaddress</SAMP></CENTER> +<P> +should be +<P> +<CENTER><SAMP>emailaddress.key</SAMP></CENTER> +<P> +For example, if your address is user@example.com the name of the file would be +<P> +<CENTER><SAMP>user@example.com.key</SAMP></CENTER> +<P> +in this directory. +<P> +Use the Setup/SMIME screen to modify this variable. +<P> +Typically, the private key that you have will come from a Certificate +Authority. +The private key should be stored in a PEM format file that +looks something like: +<PRE> +-----BEGIN RSA PRIVATE KEY----- +Proc-Type: 4,ENCRYPTED +DEK-Info: DES-EDE3-CBC,2CBD328FD84CF5C6 + +YBEXYLgLU9NJoc1V+vJ6UvcF08RX54S6jXsmgL0b5HGkudG6fhnmHkH7+UCvM5NI +SXO/F8iuZDfs1VGG0NyitkFZ0Zn2vfaGovBvm15gx24b2xnZDLRB7/bNZkurnK5k +VjAjZ2xXn2hFp2GJwqRdmxYNqsKGu52B99oti5HUWuZ2GFRaWjn5hYOqeApZE2uA +... +oSRqfI51UdSRt0tmGhHeTvybUVrHm9eKft8TTGf+qSBqzSc55CsmoVbRzw4Nfhix +m+4TJybNGNfAgOctSkEyY/OCb49fRRQTCBZVIhzLGGmpYmkO55HbIA== +-----END RSA PRIVATE KEY----- +</PRE> +<P> +<UL> +<LI><A HREF="config-notes.html#smime-general">General S/MIME Overview</A> +</UL><P> +This option is displayed as "S/MIME - Private Key Directory". +<P> + +<DT> <A NAME="smime-private-key-container"><EM>smime-private-key-container</EM></A> + +<DD> UNIX <EM>Alpine</EM> only. +<P> +If this option is set it will be used instead of +<A HREF="#smime-private-key-directory"><EM>smime-private-key-directory</EM></A>. +<P> +This option gives you a way to store keys remotely on an IMAP server +instead of storing the keys one per file locally. +In order to do that you just give this option a remote folder name for a folder +which does not yet exist. +The name is similar to the name you might use for a remote configuration file. +A remote folder name might look something like: +<P> +<CENTER><SAMP>{myimaphost.myschool.k12.wa.us}mail/privatekeys</SAMP></CENTER> +<P> +Use the Setup/SMIME screen to modify this variable. +<P> +<UL> +<LI><A HREF="config-notes.html#smime-general">General S/MIME Overview</A> +</UL><P> +This option is displayed as "S/MIME - Private Key Container". +<P> + +<DT> <A NAME="smime-cacert-directory"><EM>smime-cacert-directory</EM></A> + +<DD> UNIX <EM>Alpine</EM> only. +<P> +If the option +<A HREF="#smime-cacert-container"><EM>smime-cacert-container</EM></A> +is set then this option will have no effect. +<P> +CACert is a shorthand name for certification authority certificate. +Normally <EM>Alpine</EM> will use the CACerts that are located in the standard system +location for CACerts. +It may be the case that one of your correspondents has a Digital ID which has +been signed by a certificate authority that is not in the regular set of system certificate +authorities. +You may supplement the system list by adding further certificates of your own. +These should be stored in the directory +which is the value of this option. +The certificates will be stored in PEM format, one certificate per file. +The names of the files can be anything ending in ".crt". +<P> +Use the Setup/SMIME screen to modify this variable. +<P> +These PEM format CA certificates look very similar to your public +certificates for particular email addresses +(<A HREF="#smime-public-cert-directory"><EM>smime-public-cert-directory</EM></A>). +<P> +<UL> +<LI><A HREF="config-notes.html#smime-general">General S/MIME Overview</A> +</UL><P> +This option is displayed as "S/MIME - Cert Authority Directory". +<P> + +<DT> <A NAME="smime-cacert-container"><EM>smime-cacert-container</EM></A> + +<DD> UNIX <EM>Alpine</EM> only. +<P> +If this option is set it will be used instead of +<A HREF="#smime-cacert-directory"><EM>smime-cacert-directory</EM></A>. +<P> +This option gives you a way to store certificates remotely on an IMAP server +instead of storing the certificates one per file locally. +In order to do that you just give this option a remote folder name for a folder +which does not yet exist. +The name is similar to the name you might use for a remote configuration file. +A remote folder name might look something like: +<P> +<CENTER><SAMP>{myimaphost.myschool.k12.wa.us}mail/cacerts</SAMP></CENTER> +<P> +Use the Setup/SMIME screen to modify this variable. +<P> +<UL> +<LI><A HREF="config-notes.html#smime-general">General S/MIME Overview</A> +</UL><P> +This option is displayed as "S/MIME - Cert Authority Container". +<P> + +<DT> <A NAME="smtp-server"><EM>smtp-server</EM></A> + +<DD> One or more SMTP servers (host name or IP address) which <EM>Alpine</EM> will +use for outgoing mail. If not set, <EM>Alpine</EM> passes outgoing email to the +<EM>sendmail</EM> program on the local machine. <EM>PC-Alpine</EM> users must have +this variable set in order to send mail as they have no <EM>sendmail</EM> +program. +<P> +Your SMTP server may offer SMTP AUTH authentication. +It may even require it. +If your SMTP server offers SMTP AUTH authentication you may specify a +"user" name parameter to cause <EM>Alpine</EM> to attempt to authenticate. +This parameter requires an associated value, +the username identifier with which to establish the server +connection. +An example might be: + +<P> +<CENTER><SAMP>smtpserver.example.com/user=katie</SAMP></CENTER> +<P> + +If AUTH authentication is offered by the server, this will cause <EM>Alpine</EM> to +attempt to use it. +If AUTH authentication is not offered by the server, this will cause <EM>Alpine</EM> +to fail sending with an error similar to: + +<P> +<CENTER><SAMP>Error: SMTP authentication not available</SAMP></CENTER> +<P> + +Another type of authentication that is used by some ISPs is called +"POP before SMTP" or "IMAP before SMTP", +which means that you have to authenticate +yourself to the POP or IMAP server by opening a mailbox before you +can send mail. +To do this, you usually only have to open your INBOX. +<P> +You may tell <EM>Alpine</EM> to use the +<A HREF="http://www.ietf.org/rfc/rfc2476.txt">Message Submission</A> +port (587) instead of the SMTP port (25) by including the "submit" +parameter +in this option. +At this time "/submit" is simply equivalent to specifying +port 587, though it may imply more than that at some point in the future. +Some ISPs are blocking port 25 in order to reduce the amount of spam +being sent to their users. +You may find that the submit option allows you to get around such a block. + +<P> +<CENTER><SAMP>smtpserver.example.com/submit</SAMP></CENTER> +<P> + +To specify any non-standard port number on the SMTP server you may follow +the hostname with a colon followed by the portnumber. + +<P> +<CENTER><SAMP>smtpserver.example.com:12345</SAMP></CENTER> +<P> + +Normally, when a connection is made to the Smtp-Server <EM>Alpine</EM> will attempt +to negotiate a secure (encrypted) session using Transport Layer Security (TLS). +If that fails then a non-encrypted connection will be attempted instead. +You may specify that a TLS connection is required if you wish. +If you append "/tls" to the name then the connection will fail +instead of falling back to a non-secure connection. + +<P> +<CENTER><SAMP>smtpserver.example.com/tls</SAMP></CENTER> +<P> + +See the +<A HREF="config-notes.html#smtp-server">SMTP Servers</A> +section or the +<A HREF="config-notes.html#server-name-syntax">Server Name Syntax</A> +section for some more details. +<P> +This option is displayed as "SMTP Server (for sending)". +<P> + +<DT> <A NAME="sort-key"><EM>sort-key</EM></A> + +<DD> This variable sets up the default Message Index sorting. +The default is to +sort by arrival order (the order the messages arrived in the folder). +It has the same functionality as the +<EM>-sort</EM> command line argument and the <EM>$</EM> command in the +"Folder Index". If a <EM>sort-key</EM> is set, then all folders open during +the session will have that as the default sort order. <P> + +<DT> <A NAME="speller"><EM>speller</EM></A> + +<DD> UNIX <EM>Alpine</EM> only. +<P> +For <EM>PC-Alpine</EM>, you must install the aspell library code that you +may get from +<A HREF="http://aspell.net/win32/">http://aspell.net/win32/</A>. +<P> +This option affects the behavior of the <EM>^T</EM> (spell check) +command in the Composer. +It specifies the program invoked by <EM>^T</EM> in the Composer. +By default, <EM>Alpine</EM> uses the system's "spell" command. +<EM>Alpine</EM> will use the +command defined by this option (if any) instead. +When invoking the spell-checking program, +<EM>Alpine</EM> appends a tempfile name (where the message is passed) +to the command line. +<EM>Alpine</EM> expects the speller to correct the +spelling in that file. When you exit from the speller +program <EM>Alpine</EM> will read the +tmpfile back into the composer. +<P> +For Unix <EM>Alpine</EM> the program <EM>ispell</EM> works well as an +alternate spell checker. +If your Unix system has <EM>ispell</EM> it is probably reasonable to make +it the default speller by configuring it as the default in the +system configuration file, <CODE>/usr/local/lib/pine.conf</CODE>. + +<P> +If this option is not set, then the system's <EM>spell</EM> command is used. +The spell command does not work the same as the alternate speller. +It produces a list of misspelled words on its standard output, instead, +and doesn't take a tempfile as an argument. +Don't set this speller option to the standard Unix spell command. +That won't work. If you want to use the standard Unix spell command, +set the speller option to nothing. + +<DT> <A NAME="ssh-command"><EM>ssh-command</EM></A> + +<DD> Sets the format of the command used to +open a UNIX secure shell connection. The default is +"%s %s -l %s exec /etc/r%sd". All four "%s" entries MUST exist in the +provided command. The first is for the command's pathname, the second is +for the host to connnect to, the third is for the user to connect as, and +the fourth is for the connection method (typically <CODE>imap</CODE>). +<P> + +<DT> <A NAME="ssh-open-timeout"><EM>ssh-open-timeout</EM></A> + +<DD> Sets the time in seconds that <EM>Alpine</EM> will +attempt to open a UNIX secure shell connection. +The default is 15, the minimum non-zero value is 5, +and the maximum is unlimited. If this is set to zero ssh connections +will be completely disabled. +<P> + +<DT> <A NAME="ssh-path"><EM>ssh-path</EM></A> + +<DD> Sets the name of the command used to open a UNIX secure shell +connection. The default is typically <CODE>/usr/bin/ssh</CODE>. +<P> + +<DT> <A NAME="standard-printer"><EM>standard-printer</EM></A> + +<DD> System-wide configuration file only. Specifies a list of commands +for category 2 of the <EM>Setup/Printer</EM> screen, the standard print command +section. This is not used by <EM>PC-Alpine</EM>. +<P> + +<DT> <A NAME="status-background-color"><EM>status-background-color</EM></A> +<DT> <A NAME="status-foreground-color"><EM>status-foreground-color</EM></A> + +<DD> <A HREF="#status-color"><EM>Status Color</EM></A>. +<P> + +<DT> <A NAME="status-message-delay"><EM>status-message-delay</EM></A> + +<DD> This option has evolved over time, causing the possible values to be +counter-intuitive. +Read carefully before you set this option. +First we explain what the option does, then there is a longer discussion +following that. +<P> +If this is set to zero, the default value, it has <EM>no</EM> effect. +Positive and negative values serve two similar, but different purposes. +<P> +If it is set to a positive number, it causes the cursor to move to the +status line whenever a status message is printed and pause there for this +many seconds. +It will probably only be useful if the +<A HREF="#show-cursor"><EM>show-cursor</EM></A> +feature is +also turned on. +Setting this option to a postive number can only be used to +<EM>increase</EM> the status message delay. +This may be useful for Braille displays, or other non-traditional displays. +<P> +If it is set to a negative number the interpretation is a bit complicated. +Negative numbers are used to <EM>decrease</EM> the amount of delay <EM>Alpine</EM> uses to +allow you to read important status messages. +Of course, this may cause you to miss some important messages. +If you see a message flash by but miss what it says you can use the +Journal command from the Main menu to read it. +If you set this option to a negative value, the delay will be +no more than one second less than the absolute value +of the value you set. +So if you set it to -1, the delay will be no more than zero seconds, no +delay at all. +If you set it to -2, the delay will be no more than 1 second. +And so on, -3 is 2 seconds, -4 is 3 seconds, ... +If the delay that <EM>Alpine</EM> would have used by default is less than this delay, +then the smaller delay set by <EM>Alpine</EM> will be used. +Setting this option to a negative value can only reduce the amount of +delay, never increase it. +<P> +Here is a more detailed explanation. +Status messages are the messages which show up spontaneously in the +status message line, the third line from the bottom of the screen. +By default, <EM>Alpine</EM> assigns each status message it produces a minimum +display time. +Some status messages have a minimum display time of zero. +You can see an example of such a message by paging up in this help text +until you reach the top of the screen. +If you try to page past the top you will see the message +<P> +<CENTER><SAMP>[Already at start of help text]</SAMP></CENTER> +<P> +in the status line. +If there is another more important use of the status message line this message +might be replaced quickly, or it even might not be shown at all. +However, if there is no reason to get rid of the message, it might stay +there for several seconds while you read the help. +An example where it is replaced immediately happens when you page up in +the help text past the top of the screen, but then type the "WhereIs" +command right after paging up. +The message will disappear immediately without causing a delay (unless you +have set this option to a positive value) to allow you to type input for +the "WhereIs" command. +Since it isn't a very important message, <EM>Alpine</EM> has set its minimum display +time to zero seconds. +<P> +Other messages have minimum display times of three or more seconds. +These are usually error messages that <EM>Alpine</EM> thinks you ought to see. +For example, it might be a message about a failed Save or a failed folder open. +It is often the case that this minimum display time won't delay you in +any way because the status message line is not needed for another reason. +However, there are times when <EM>Alpine</EM> has to delay what it is doing in +order to display a status message for the minimum display time. +This happens when a message is being displayed and <EM>Alpine</EM> wants to ask +for input from the keyboard. +For example, when you Save a message you use the status message line. +You get a prompt there asking for the name of the folder to save to. +If there is a status message being displayed that has not +yet displayed for its minimum +time <EM>Alpine</EM> will display that status message surrounded with the characters +> and < to show you that it is delaying. +That might happen, for example, if you tried to save to a folder that +caused an error, then followed that immediately with another Save command. +You might find yourself waiting for a status message like +<P> +<CENTER><SAMP>[>Can't get write access to mailbox, access is readonly<]</SAMP></CENTER> +<P> +to finish displaying for three seconds. +If that is something you find happening to you frequently, you may use +negative values of this option to decrease or eliminate that delay, at +the risk of missing the message. +<P> + +<DT> <A NAME="stay-open-folders"><EM>stay-open-folders</EM></A> + +<DD> This option affects low-level behavior of <EM>Alpine</EM>. +There is no default value for this option. +It is related to the options +<A HREF="#preopen-stayopen-folders">Preopen-Stayopen-Folders</A>, +<A HREF="#max-remote-connections">Max-Remote-Connections</A>, +and <A HREF="#offer-expunge-of-stayopen-folders">offer-expunge-of-Stayopen-Folders</A>. + +<P> +Note: changes made to this list take effect the next time you open a +folder in the list. + +<P> +This is a list of folders that will be permanently kept open once they +are first opened. +The names in this list may be either the nickname of an Incoming folder +or the full technical specification of a folder. +The folders in this list need not be remote IMAP folders, they could usefully +be local folders, as well. +If a folder in the list is a newsgroup or is not accessed either locally +or via IMAP, then the entry will be ignored. +For example, folders accessed via NNTP or POP3 will not be kept open, since +the way that new mail is found with those protocols involves closing and +reopening the connection. +<P> +Once a Stay Open folder has been opened, new-mail checking will continue +to happen on that folder for the rest of the <EM>Alpine</EM> session. +Your INBOX is always implicitly included in this Stay-Open list and doesn't +need to be added explicitly. +<P> +Another difference that you may notice between a Stay Open folder and a +non-Stay Open folder is which message is selected as the current message +when you enter the folder index. +Normally, the starting position for an incoming folder (which most Stay Open +folders will likely be) is controlled by the +<A HREF="#incoming-startup-rule"><EM>Incoming-Startup-Rule</EM></A>. +However, if a folder is a Stay Open folder, when you re-enter the folder +after the first time the current message will be the same as it was when +you left the folder. +An exception is made if you use the TAB command to get to the folder. +In that case, the message number will be incremented by one from what it +was when you left the folder. +<P> +The above special behavior is thought to be useful. +However, it is special and different from what you might at first expect. +The feature +<A HREF="#use-reg-start-rule"><EM>Use-Regular-Startup-Rule-for-Stayopen-Folders</EM></A> +may be used to turn off this special treatment. +<P> +If the message that was current when you left the folder no longer exists, +then the regular startup rule will be used instead. +<P> +This option is displayed as "Stayopen Folders". +<P> + +<DT> <A NAME="tcp-open-timeout"><EM>tcp-open-timeout</EM></A> + +<DD> Sets the time in seconds that <EM>Alpine</EM> will +attempt to open a network connection. The default is 30, the minimum is 5, +and the maximum is system defined (typically 75). If a connection has not +completed within this many seconds <EM>Alpine</EM> will give up and consider it a +failed connection. +<P> + +<DT> <A NAME="tcp-query-timeout"><EM>tcp-query-timeout</EM></A> + +<DD> When <EM>Alpine</EM> times out a network read or write it will normally just display +a message saying "Still waiting". +However, if enough time has elapsed since it started waiting it will offer +to let you break the connection. +That amount of time is set by this option, which defaults to 60 seconds, +has a minimum of 5 seconds, and a maximum of 1000 seconds. +<P> + +<DT> <A NAME="tcp-read-warning-timeout"><EM>tcp-read-warning-timeout</EM></A> + +<DD> Sets the time in seconds that <EM>Alpine</EM> will +wait for a network read before warning you that things are moving slowly +and possibly giving you the option to break the connection. +The default is 15 seconds. The minimum is 5 seconds and the maximumn is +1000 seconds. +<P> + +<DT> <A NAME="tcp-write-warning-timeout"><EM>tcp-write-warning-timeout</EM></A> + +<DD> Sets the time in seconds that <EM>Alpine</EM> will +wait for a network write before warning you that things are moving slowly +and possibly giving you the option to break the connection. +The default is 0 which means it is unset. If set to a non-zero value, the +minimum is 5 and the maximum is 1000. + +<DT> <A NAME="threading-display-style"><EM>threading-display-style</EM></A> + +<DD> When a folder is sorted by Threads or OrderedSubject, +this option will affect the MESSAGE INDEX display. +By default, <EM>Alpine</EM> will display the MESSAGE INDEX in the +"show-thread-structure" style if a folder is sorted +by Threads or OrderedSubject. +The possible values are: +<P> + +<DL> +<DT><EM>none</EM></DT> +<DD>Regular index display. +The same index line as would be displayed without threading is used. +The only difference will be in the order of the messages. +</DD> + +<DT><EM>show-thread-structure</EM></DT> +<DD>Threaded Subjects will be indented and vertical bars and horizontal +lines will be added to make it easier to see the relationships among +the messages in a thread (a conversation). +</DD> + +<DT><EM>mutt-like</EM></DT> +<DD>This is the same as the option above except that the Subject +is suppressed (is blank) if it matches the previous Subject in the thread. +The name comes from the email client <A HREF="http://www.mutt.org/">Mutt</A>. +Here is an example of what a mutt-like index might look like. +In this example, the first column represents the message number, the +<A HREF="#threading-index-style"><EM>threading-index-style</EM></A> +is set to "regular-index-with-expanded-threads", and the +<A HREF="#threading-lastreply-character"><EM>Threading-Lastreply-Character</EM></A> +is set to a backslash: +<PRE> + 1 Some topic + 2 . Subject original message in thread + 3 |-> reply to 2 + 4 . |-> another reply to 2 + 5 . | \-> reply to 4 + 6 . | \-> reply to 5 + 7 | \-> reply to 6 + 8 |-> another reply to 2 + 9 . |->New subject another reply to 2 but with a New subject + 10 | |-> reply to 9 + 11 | \-> another reply to 9 + 12 | \-> reply to 11 + 13 \-> final reply to 2 + 14 Next topic +</PRE> +</DD> + +<DT><EM>indent-subject-1</EM></DT> +<DD>Threaded Subjects will be indented one space per level of the conversation. +The bars and lines that show up in the show-thread-structure display will +not be there with this style. +</DD> + +<DT><EM>indent-subject-2</EM></DT> +<DD>Same as above but indent two spaces per level instead of one space. +</DD> + +<DT><EM>indent-from-1</EM></DT> +<DD>Similar to indent-subject-1, except that instead of indenting the +Subject field one space the From field of a thread will be indented one +space per level of the conversation. +</DD> + +<DT><EM>indent-from-2</EM></DT> +<DD>Same as above but indent two spaces per level instead of one space. +</DD> + +<DT><EM>show-structure-in-from</EM></DT> +<DD>The structure of the thread is illustrated with indenting, vertical bars, +and horizontal lines just like with the show-thread-structure option, but +the From field is used to show the relationships instead of the Subject field. +</DD> + +</DL> +<P> + +<DT> <A NAME="threading-expanded-character"><EM>threading-expanded-character</EM></A> + +<DD> The Threading-Expanded-Character option has a small effect on the MESSAGE +INDEX display when using a +<A HREF="#threading-display-style"><EM>threading-display-style</EM></A> +other than <EM>none</EM>. +The value of this option is a single character. +This character is used to indicate that part of a thread has been expanded +and could be collapsed if desired with +the "/" Collapse/Expand command. +By default, the value of this option is a dot (.). +<P> +If this option is set to the Empty Value, then the column (and the following +blank column) will be deleted from the display. +<P> +This option is closely related to the +<A HREF="#threading-indicator-character"><EM>threading-indicator-character</EM></A> +option. +Another similar option which affects the thread display is the +<A HREF="#threading-lastreply-character"><EM>threading-lastreply-character</EM></A> option. + +<DT> <A NAME="threading-index-style"><EM>threading-index-style</EM></A> + +<DD> When a folder is sorted by Threads or OrderedSubject, +this option will affect the INDEX displays. +The possible values are: +<P> + +<DL> +<DT><EM>regular-index-with-expanded-threads</EM></DT> +<DD>This is the default display. +If the configuration option +<A HREF="#threading-display-style"><EM>threading-display-style</EM></A> +is set to something other than "none", then this setting +will cause <EM>Alpine</EM> to start off with a MESSAGE INDEX with all of +the threads expanded. +That is, each message will have a line in the MESSAGE INDEX display. +The Collapse/Expand command (/) may be used to manually collapse or +expand a thread or subthread (see also <A HREF="#slash-collapses-entire-thread"><EM>slash-collapses-entire-thread</EM></A>). +<P> +This setting affects the display when the folder is first threaded. +The collapsed state may also be re-initialized by re-sorting the folder manually +using the SortIndex command ($). +After re-sorting the threads will once again all be expanded, even if you +have previously collapsed some of them. +<P> +If "threading-display-style" is set to "none", then +the display will be the regular default <EM>Alpine</EM> MESSAGE INDEX, but sorted +in a different order. +</DD> + +<DT><EM>regular-index-with-collapsed-threads</EM></DT> +<DD>If the configuration option +<A HREF="#threading-display-style"><EM>threading-display-style</EM></A> +is set to something other than "none", then this setting +will cause <EM>Alpine</EM> to start out with all of the threads collapsed instead of +starting out with all of the threads expanded. +The Collapse/Expand command (/) may be used to manually collapse or +expand a thread or subthread (see also <A HREF="#slash-collapses-entire-thread"><EM>slash-collapses-entire-thread</EM></A>). +<P> +This setting affects the display when the folder is first threaded. +The collapsed state may also be re-initialized by re-sorting the folder manually +using the SortIndex command ($). +After re-sorting the threads will once again all be collapsed, even if you +have previously expanded some of them. +</DD> + +<DT><EM>separate-index-screen-always</EM></DT> +<DD>With this setting and the next, you will see an index of threads +instead of an +index of messages, provided you have sorted by Threads or OrderedSubject. +<P> +The THREAD INDEX contains a '*' in the first column if any message in the thread +is marked Important. +If not, it contains a '+' if any message in the thread is to you. +The second column is blank. The third column contains a 'D' if all of the +messages in the thread are deleted. +Otherwise, it contains an 'N' if any of the messages in the thread are New. +<P> +When you view a particular thread from the THREAD INDEX you will be +in the MESSAGE INDEX display +but the index will only contain messages from the thread you are viewing. +</DD> + +<DT><EM>separate-index-screen-except-for-single-messages</EM></DT> +<DD>This is very similar to the option above. +When you are in the THREAD INDEX, one of the available commands +is "ViewThd". +With the setting "separate-index-screen-always" (the option above) +when you view a particular thread you will be in the +MESSAGE INDEX display and the index will only contain messages from +the thread you are viewing. +If the thread you are viewing consists of a single message, the MESSAGE INDEX +will be an index with only one message in it. +If you use this "separate-index-screen-except-for-single-messages" +setting instead, then that index which contains a single message +will be skipped and you will go directly from the THREAD INDEX into the +MESSAGE TEXT screen. +</DD> + +</DL> + +<P> + +<DT> <A NAME="threading-indicator-character"><EM>threading-indicator-character</EM></A> + +<DD> The Threading-Indicator-Character option has a small effect on the MESSAGE +INDEX display when using a +<A HREF="#threading-display-style"><EM>threading-display-style</EM></A> +other than <EM>none</EM> and sorting by Threads or OrderedSubject. +The value of this option is a single character. +This character is used to indicate that part of a thread (a conversation) is +hidden beneath a message. +The message could be expanded +if desired with the "/" Collapse/Expand command. +By default, the value of this option is the greater than sign (>). +<P> +If this option is set to the Empty Value, then the column (and the following +blank column) will be deleted from the display. + +<P> +This option is closely related to the +<A HREF="#threading-expanded-character"><EM>threading-expanded-character</EM></A> +option. +Another similar option which affects the thread display is the +<A HREF="#threading-lastreply-character"><EM>threading-lastreply-character</EM></A> option. +<P> + +<DT> <A NAME="threading-lastreply-character"><EM>threading-lastreply-character</EM></A> + +<DD>The Threading-Lastreply-Character option has a small effect on the MESSAGE +INDEX display when using a +<A HREF="#threading-display-style"><EM>threading-display-style</EM></A> +of <EM>show-thread-structure</EM>, <EM>mutt-like</EM>, or +<EM>show-structure-in-from</EM>; and sorting by Threads or OrderedSubject. +The value of this option is a single character. +This character is used instead of the vertical line character when there are +no more replies directly to the parent of the current message. +It can be used to "round-off" the bottom of the vertical line +by setting it to a character such as a backslash (\) or +a backquote (`). +The default value of this option is the backslash character (\). +This option may not be set to the Empty Value. +In that case, the default will be used instead. +<P> +This option is displayed as "Threading Last Reply Character". +<P> + +<DT> <A NAME="title-background-color"><EM>title-background-color</EM></A> +<DT> <A NAME="title-foreground-color"><EM>title-foreground-color</EM></A> + +<DD> <A HREF="#title-color"><EM>Title Color</EM></A>. +<P> + +<DT> <A NAME="title-closed-background-color"><EM>title-closed-background-color</EM></A> +<DT> <A NAME="title-closed-foreground-color"><EM>title-closed-foreground-color</EM></A> + +<DD> <A HREF="#title-closed-color"><EM>Title-closed Color</EM></A>. +<P> + +<DT> <A NAME="titlebar-color-style"><EM>titlebar-color-style</EM></A> + +<DD> <A HREF="#titlebar-style"><EM>titlebar-color-style</EM></A>. +<P> + +<DT> <A NAME="unknown-character-set"><EM>unknown-character-set</EM></A> + +<DD> A text message should either be made up of all US-ASCII characters +or it should contain a charset label which tells the software which +character set encoding to use to interpret the message. +Sometimes a malformed message may be unlabeled but contain non-ascii text. +This message is outside of the standards so any attempt to read it could fail. +When <EM>Alpine</EM> attempts to read such a message it will try to interpret the +text in the character set you specify here. +For example, if you have correspondents who send you unlabeled messages that +are usually made up of characters from the WINDOWS-1251 character set, setting +this unknown-character-set to <CODE>WINDOWS-1251</CODE> will +allow you to read those messages. +Of course, if the unlabeled message is actually in some other character set, +then you may see garbage on your screen. + +<P> +In the Setup/Config screen you may choose from a list of all the +character sets <EM>Alpine</EM> knows about by using the "T" ToCharsets command. +<P> + +<DT> <A NAME="upload-command"><EM>upload-command</EM></A> + +<DD> This option affects the behavior of the Composer's <EM>^R</EM> (Read File) +and <EM>^J</EM> (Attach File, in the header) commands. It +specifies a Unix program name, and any necessary command line arguments, +that <EM>Alpine</EM> can use to transfer files from your personal computer into +messages that you are composing. <P> + +<DT> <A NAME="upload-command-prefix"><EM>upload-command-prefix</EM></A> + +<DD> This option is used in +conjunction with the <EM>upload-command</EM> option. +It defines text to be written to the terminal emulator (via standard +output) immediately prior to starting the upload command. This is useful for +integrated serial line file transfer agents that permit command passing +(e.g., Kermit's APC method). <P> + +<DT> <A NAME="url-viewers"><EM>url-viewers</EM></A> + +<DD> List of programs to use to open Internet URLs. +This value affects <EM>Alpine</EM>'s handling of URLs that are found in the text of +messages you read. Normally, only URLs <EM>Alpine</EM> can handle directly are +automatically offered for selection in the "Message Text" screen. When +one or more comma delimited Web browsers capable of deciphering URLs on +their command line are added here, <EM>Alpine</EM> will choose the first available +browser to display URLs it doesn't recognize. +<P> + +Additionally, to support various connection methods and browsers, each +entry in this list can begin with the special token +<CODE>_TEST(test-string)_</CODE>. +The <CODE>test-string</CODE> is a shell command that <EM>Alpine</EM> +will run and which must exit with a status of zero for <EM>Alpine</EM> to consider +that browser for use (the other criteria is that the browser must exist +as a full path or a path relative to your home directory). +<P> + +Now for an example: + +<BLOCKQUOTE> + <CODE> + url-viewers=_TEST("test -n '${DISPLAY}'")_ /usr/local/bin/netscape, + /usr/local/bin/lynx, + C:\BIN\NETSCAPE.BAT </CODE><BR> +</BLOCKQUOTE> + +This example shows that for the first browser in the list to be used the +environment variable <CODE>DISPLAY</CODE> must be defined. +If it is, then the file <CODE>/usr/local/bin/netscape</CODE> must exist. +If either condition is not met, then the file +<CODE>/usr/local/bin/lynx</CODE> must exist. +If it doesn't, then the final path and file must +exist. Note that the last entry is a DOS/Windows path. This is one way +to support <EM>Alpine</EM> running on more than one architecture with the same +configuration file. +<P> + +<DT> <A NAME="use-only"><EM>use-only-domain-name</EM></A> + +<DD> Can be set to <EM>yes</EM> or <EM>no.</EM> Anything but +<EM>yes</EM> means <EM>no.</EM> If set to <EM>yes</EM> the first label in +the host name will be lopped off to get the domain name and the domain +name will be used for outgoing mail and such. That is, if the host name +is <EM>carson.u.example.edu</EM> and this variable is set to <EM>yes,</EM> +then <EM>u.example.edu</EM> will be used on outgoing mail. Only +meaningful if <A HREF="#user-domain"><EM>user-domain</EM></A> is NOT set. <P> + +<DT> <A NAME="user-domain"><EM>user-domain</EM></A> + +<DD> Sets the domain or host name for the user, overriding the system host +or domain name. See the <A HREF="config-notes.html#domain"><EM>domain name section</EM></A>. +The easiest way to change the full From address is with the +<A HREF="#cust-hdr"><EM>customized-hdrs</EM></A> variable. +<P> + +<DT> <A NAME="user-id"><EM>user-id</EM></A> + +<DD> <EM>PC-Alpine</EM> only and personal configuration file only. +Sets the username that is placed on all outgoing +messages. The username is the part of the address that comes before the "@". +The easiest way to change the full From address is with the +<A HREF="#cust-hdr"><EM>customized-hdrs</EM></A> variable. +<P> + +<DT> <A NAME="user-input"><EM>user-input-timeout</EM></A> + +<DD> If this is set to an integer greater than zero, then this is the number +of <EM>hours</EM> to wait for user input before <EM>Alpine</EM> times out. +If <EM>Alpine</EM> is +in the midst of composing a message or is waiting for user response to +a question, then it will not timeout. +However, if <EM>Alpine</EM> is sitting idle waiting for +the user to tell it what to do next and the user does not give any +input for this many hours, <EM>Alpine</EM> will exit. +No expunging or moving of read +messages will take place. +It will exit similarly to the way it would exit +if it received a hangup signal. +This may be useful for cleaning up unused <EM>Alpine</EM> sessions which have been +forgotten by their owners. +The <EM>Alpine</EM> developers envision system administrators +setting this to a value of several hours (24?) so that it won't surprise +a user who didn't want to be disconnected. +<P> + +<DT> <A NAME="viewer-hdr-colors"><EM>viewer-hdr-colors</EM></A> + +<DD> This variable holds the optional Header Colors and patterns which +have been defined by the user. This is usually modified by using +the <A HREF="#header-colors"><EM>Header Colors</EM></A> section +of the Setup Color screen. +<P> + +<DT> <A NAME="viewer-hdrs"><EM>viewer-hdrs</EM></A> + +<DD> You may change the default list of headers that are viewed by listing +the headers you want to view here. If the headers in your <EM>viewer-hdrs</EM> +list are present in the message, then they will be shown. The order of +the headers you list will also be honored. If the special +value <EM>all-except</EM> +is included as the first header in the <EM>viewer-hdrs</EM> list, then all +headers in the message except those in the list will be shown. The values +are all case insensitive.<P> +This option is displayed as "Viewer Headers". +<P> + +<DT> <A NAME="viewer-margin-left"><EM>viewer-margin-left</EM></A> + +<DD> This variable controls the left-hand vertical margin's width in +<EM>Alpine</EM>'s Message Viewing screen. +Its value is the number of space characters preceding each displayed line. +For consistency with +<A HREF="#viewer-margin-right">Viewer-Margin-Right</A>, +you may specify the column number to start in +(column numbering begins with number 1) +instead of the width of the margin by appending a lower case letter +"c" to the number. +For example, a value of "2c" means to start the text in column two, +which is entirely equivalent to a value of "1", which means to +leave a margin of 1 space. +<P> +The default is a left margin of 0 (zero). +Misconfigurations (for example, negative values or values with starting +left columns greater than the ending right column) +are silently ignored. +If the number of columns for text between the Viewer-Margin-Left and +the Viewer-Margin-Right is fewer than 8, then margins of zero will be used +instead. +<P> + +<DT> <A NAME="viewer-margin-right"><EM>viewer-margin-right</EM></A> + +<DD> This variable controls the right-hand vertical margin's width in +<EM>Alpine</EM>'s Message Viewing screen. +Its value is the number of space characters following each displayed line. +You may specify the column number to end the text in +(column numbering begins with number 1) +instead of the width of the margin by appending a lower case letter +"c" to the number. +For example, a value of "76c" means to end the text in column 76. +If the screen is 80 characters wide, this is equivalent to a value +of "4", which means to leave a margin of 4 spaces. +However, if you use different size screens at different times, then these +two values are not equivalent. +<P> +The default right margin is 4. +Misconfigurations (for example, negative values or values with starting +left columns greater than the ending right column) +are silently ignored. +If the number of columns for text between the +<A HREF="#viewer-margin-left">Viewer-Margin-Left</A> and +the Viewer-Margin-Right is fewer than 8, then margins of zero will be used +instead. +<P> + +<DT> <A NAME="overlap"><EM>viewer-overlap</EM></A> + +<DD> This option specifies an aspect of <EM>Alpine</EM>'s Message Viewing screen. +When the space bar is used to page forward in a message, the number of +lines specified by the <EM>viewer-overlap</EM> variable +will be repeated from the +bottom of the screen. That is, if this was set to two lines, then the +bottom two lines of the screen would be repeated on the top of the next +screen. The normal default value is "2". <P> + +<DT> <A NAME="window-position"><EM>window-position</EM></A> + +<DD> Winsock version of <EM>PC-Alpine</EM> only. Window position in the format: +CxR+X+Yn Where C and R are the window size in characters and X and Y are +the screen position of the top left corner of the window. <P> + +</DL> + +<HR> + +<H2><A NAME="features-conf">Configuration Features</A></H2> + +There are several features (options) which may be turned off or on. +The configuration variable +<A HREF="#feat-list"><EM>feature-list</EM></A> is a list of all the +features that are turned on or off. +If the name of a feature is in +the list it will be turned on. +If the name of a feature with the characters +<CODE>no-</CODE> prepended is in the list, it will turn the feature off. +This is useful for overriding system-wide defaults. +This is because, unlike all the other configuration variables, +the <EM>feature-list</EM> is additive. +That is, first the system-wide <EM>feature-list</EM> is read +and then the user's <EM>feature-list</EM> is read. This makes it possible +for the system manager to turn some of the features on by default while +still allowing the user to cancel that default. +For example, if the system manager has +turned on the <EM>allow-talk</EM> feature by default then a user may turn +it back off by including the feature <EM>no-allow-talk</EM> in his or her +personal configuration file. Of course, these details are usually handled +by <EM>Alpine</EM> when the user turns an option on or off from inside the +<EM>Setup/Config</EM> screen. +<P> + +System managers should take some care when turning on features by default. +Some of the documentation assumes that all of the features are off by +default, so it could be confusing for a user if some are on by default instead. +Feature names are case-independent. +<P> + +Here is an alphabetical list of possible features. + +<DL COMPACT> + +<DT> <A NAME="allow-from"><EM>allow-changing-from</EM></A> + +<DD> Prior to <EM>Pine</EM> 4.00 there was a <EM>compile</EM>-time option called +ALLOW_CHANGING_FROM. That has been replaced by a <EM>runtime</EM> feature. +If this feature is turned on then the From line can be changed just like +all the other header fields that can be changed. See the configuration +variables <A HREF="#cust-hdr"><EM>customized-hdrs</EM></A> +and <A HREF="#def-comp"><EM>default-composer-hdrs</EM></A> +for more information on editing headers. +<P> +The default value for this feature +is ON, so that editing of From headers is allowed +by default. +<P> + +<DT> <A NAME="allow-talk"><EM>allow-talk</EM></A> + +<DD> Unix <EM>Alpine</EM> only. By default, permission for +others to <EM>talk</EM> to your terminal is turned +off when you are running <EM>Alpine</EM>. When this feature is set, permission is +instead turned on. +<P> + +Note: The <EM>talk</EM> program has nothing to do with <EM>Alpine</EM> or email. The +<EM>talk</EM> daemon on your system will +attempt to print a message on your screen +when someone else is trying to contact you. If you wish to see these +messages while you are running <EM>Alpine</EM>, you should enable this feature. +<P> + +If you do enable this feature and see a <EM>talk</EM> message, you must +suspend or quit <EM>Alpine</EM> before you can respond. +<P> + +<DT> <A NAME="alternate-compose-menu"><EM>alternate-compose-menu</EM></A> + +<DD>This feature controls the menu that is displayed when Compose is selected. +If set, a list of options will be presented, with each option representing +the type of composition that could be used. This feature is most useful for +users who want to avoid being prompted with each option separately, or who +want to avoid the checking of remote postponed or form letter folders. +The possible types of composition are: + +<P> +New, for starting a new composition. Note that if New is selected and roles +are set, roles are checked for matches and applied according to the setting +of the matching role. + +<P> +Interrupted, for continuing an interrupted composition. This option is only +offered if an interrupted message folder is detected. + +<P> +Postponed, for continuing postponed compositions. This option is offered +if a postponed-folder is set in the config <EM>REGARDLESS OF</EM> whether or not +the postponed folder actually exists. This option is especially handy +for avoiding having to check for the existence of a remote postponed folder. + +<P> +Form, for using form letters. This option is offered if the form-letter-folder +is set in the config, and is not checked for existence for reasons similar +to those explained by the postponed option. + +<P> +setRole, for selecting a role to apply to a composition. + +<P> + +<DT> <A NAME="alternate-role-menu"><EM>alternate-role-menu</EM></A> + +<DD> Normally the Role Command allows you to choose +a role and compose a new message using that role. +When this feature is set, the role command will first ask whether you want to +Compose a new message, Forward the current message, Reply to the +current message, or Bounce the current message. +If you are not in the MESSAGE INDEX and are not viewing a message, +then there is no current message and the question will be skipped. +After you have chosen to Compose, Forward, Reply or Bounce you will +then choose the role to be used. +<P> +When Bouncing the "Set From" address is used for the +Resent-From header, the "Set Fcc" value is used for the Fcc +provided that the option +<A HREF="#fcc-on-bounce">"Fcc-On-Bounce"</A> is turned on, +and the "Use SMTP Server" value is used for the SMTP server, if +set. +Other actions of the role are ignored when Bouncing. +<P> +This feature is displayed as "Alternate Role (#) Menu". +<P> + + +<DT> <A NAME="assume-slow-link"><EM>assume-slow-link</EM></A> + +<DD> UNIX <EM>Alpine</EM> only. +<P> +This feature affects <EM>Alpine</EM>'s display routines. If set, the normal +inverse-video cursor (used to highlight the current item in a list) will be +replaced by an <EM>arrow</EM> cursor and other screen update optimizations for +low-speed links (e.g. 2400 bps dialup connections) will be activated. +One of the optimizations is that colored index lines (set up with Indexcolor +Rules) will not be colored. +This might be useful if <I>you</I> know you have a slow speed link but for some +reason <EM>Alpine</EM> doesn't know. +<P> + +<DT> <A NAME="auto-read-msg"><EM>auto-move-read-msgs</EM></A> + +<DD> This feature controls an aspect +of <EM>Alpine</EM>'s behavior upon quitting. If set, +and the <A HREF="#read-msg-fold"><EM>read-message-folder</EM></A> +variable is also set, then <EM>Alpine</EM> will +automatically transfer all read messages from the <EM>INBOX</EM> to +the designated folder and mark +them as deleted in the <EM>INBOX</EM>. Messages in the <EM>INBOX</EM> marked +with an <EM>N</EM> (meaning New, or unseen) are not affected. +<P> +This feature is displayed as "Auto Move Read Messages". +<P> + +<DT> <A NAME="auto-open-next-unread"><EM>auto-open-next-unread</EM></A> + +<DD> This feature controls the behavior of the TAB key when traversing folders +in the optional <A HREF="#inc-fold"><EM>incoming-folders</EM></A> +collection or in optional <A HREF="#news-coll"><EM>news-collections</EM></A>. +<P> + +When the TAB (Next New) key is pressed, and there are no more unseen +messages in the current (incoming message or news) folder, <EM>Alpine</EM> will +search the list of folders in the current collection for one containing +New or Recent (new since the last time the folder was opened) messages. +This behavior may be modified slightly with the +<A HREF="#tab-uses-unseen-for-next-folder">Tab-Uses-Unseen-For-Next-Folder</A> +feature which causes <EM>Alpine</EM> to look for Unseen messages instead of Recent +messages. +By default, when such a folder is found, +<EM>Alpine</EM> will ask whether you wish to +open the folder. +If this feature is set, <EM>Alpine</EM> will automatically open the +folder without prompting. +<P> + +<DT> <A NAME="auto-unselect-after-apply"><EM>auto-unselect-after-apply</EM></A> + +<DD> This feature affects the behavior of the Apply command. If set, +the Apply command will do the operation you specify, but then will +implicitly do an "UnSelect All", so that you will automatically be back in +the normal Index view after the Apply. +<P> + +<DT> <A NAME="auto-unzoom-after-apply"><EM>auto-unzoom-after-apply</EM></A> + +<DD> If set, and if +you are currently looking at a Zoomed Index view of selected messages, +the <EM>Apply</EM> command will do the operation you specify, but then will +implicitly do an <EM>UnZoom</EM>, so that you will automatically be back in +the normal Index view after the <EM>Apply</EM>. +This feature is set by default. +<P> + +<DT> <A NAME="auto-zoom-after-select"><EM>auto-zoom-after-select</EM></A> + +<DD> If set, the <EM>; select</EM> command will automatically +perform a <EM>Zoom</EM> after the <EM>select</EM> is complete. +This feature is set by default. +<P> + +<DT> <A NAME="busy-cue-spinner-only"><EM>busy-cue-spinner-only</EM></A> + +<DD> When <EM>Alpine</EM> is delayed for some reason it usually shows that +something is happening with a small animated display in the status +message line near the bottom of the screen. +Setting this feature will cause that animation to be the same +each time instead of having <EM>Alpine</EM> choose a random animation. +You may turn the animation off altogether by setting the +<A HREF="#busy-cue-rate"><EM>busy-cue-rate</EM></A> +option to zero. +<P> + +<DT> <A NAME="check-newmail-when-quitting"><EM>check-newmail-when-quitting</EM></A> + +<DD> If set, <EM>Alpine</EM> will check for new mail after you give the +Quit command. +If new mail has arrived since the previous check, you will be notified +and given the choice of quitting or not quitting. +<P> + +<DT> <A NAME="combined-addrbook-display"><EM>combined-addrbook-display</EM></A> + +<DD> This feature affects the address book display screens. +Normally, expanding an address book from the ADDRESS BOOK LIST screen +will cause the remaining address books and directory servers to disappear +from the screen, leaving only the entries of the expanded address book. +If this feature is set, then the other address books will remain on the screen, +so that all of the address books can be present at once. + +<P> +The way that commands work won't be changed. +For example, the Select All command will select all of the entries in the +current address book, not all of the entries in all of the address books. +The WhereIs command will change a little. +It will search through all of the text on the screen plus all of the entries +from expanded address books. + +<P> +When this feature is set, the setting of the feature +<A HREF="#expanded-view-of-addressbooks"><EM>expanded-view-of-addressbooks</EM></A> +has an effect. +<P> +This feature is displayed as "Combined Addressbook Display". +<P> + +<DT> <A NAME="combined-folder-display"><EM>combined-folder-display</EM></A> + +<DD> This feature affects the folder list display screens. +Normally, each folder list is viewed within its collection only. This +command allows folder lists to be viewed within a single screen that +combines the contents of all collections. + +<P> +The way that commands work won't be changed. +For example, the Select All command will select all of the folders in the +current collection, not all of the entries in all of the collections. +The WhereIs command will change a little. +It will search through all of the folders in the current collection as well +as all the folder in any other expanded collection. + +<P> +When this feature is set, the setting of the feature +<A HREF="#expanded-view-of-folders"><EM>expanded-view-of-folders</EM></A> +has an effect. +<P> + +<DT> <A NAME="combined-subdirectory-display"><EM>combined-subdirectory-display</EM></A> + +<DD> This feature affects the Folder List screen when +the +<A HREF="#combined-folder-display"><EM>combined-folder-display</EM></A> +feature is enabled. Normally, selecting a directory from the Folder +List takes you into a new screen displaying only the contents of +that directory. + +<P> +Enabling this feature will cause the contents of the selected +directory to be +displayed within the boundaries of the +<A HREF="background.html#collections"><EM>Collection</EM></A> +it is a part of. All previously displayed collections will remain +in the screen. + +<P> +The way that commands work won't be changed. +For example, the Select All command will select all of the folders in the +directory, as opposed to all of the entries in all of the collections. +The WhereIs command will change a little. +It will search through all of the folders in the current collection as well +as all the folder in any other expanded collection. + +<P> + +<DT> <A NAME="compose-cancel-confirm-uses-yes"><EM>compose-cancel-confirm-uses-yes</EM></A> + +<DD> This feature affects what happens when you type ^C to cancel a composition. +By default, if you attempt to cancel a composition by typing ^C, you will be +asked to confirm the cancellation by typing a "C" +for <EM>C</EM>onfirm. +It logically ought to be a "Y" for <EM>Y</EM>es, but that is +risky because the "^C Y" needed to cancel a message +is close (on the keyboard) to the "^X Y" needed to send a message. +<P> +If this feature is set the confirmation asked for +will be a "<EM>Y</EM>es" +instead of a "<EM>C</EM>onfirm" response. +<P> + +<DT> <A NAME="compose-cut-from-cursor"><EM>compose-cut-from-cursor</EM></A> + +<DD> If set, the <EM>^K</EM> command in the composer will cut from the +current cursor position to the end of the line, +rather than cutting the entire line. +<P> +This feature is displayed as "Ctrl-K Cuts From Cursor". +<P> + +<DT> <A NAME="compose-maps-delete-key-to-ctrl-d"><EM>compose-maps-delete-key-to-ctrl-d</EM></A> + +<DD> If set, Delete will be equivalent to ^D, and delete +the current character. Normally <EM>Alpine</EM> defines the Delete key +to be equivalent to ^H, which deletes the <EM>previous</EM> +character. +<P> +This feature is displayed as "Delete Key Maps to Ctrl-D". +<P> + +<DT> <A NAME="compose-rejects-unqualified-addrs"><EM>compose-rejects-unqualified-addrs</EM></A> + +<DD> If set, unqualified names entered as addresses will be treated as errors +unless they match an addressbook nickname or are looked up successfully +on an LDAP server. <EM>Alpine</EM> will not attempt to turn +them into complete addresses by adding your local domain (which <EM>Alpine</EM> normally +does by default). +<P> + +A complete (fully-qualified) address is one containing a username +followed by an <EM>@</EM> symbol, followed by a host or domain name (e.g. +<EM>jsmith@example.com</EM>). An unqualified name is one without the +<EM>@</EM> symbol +and host or domain name (e.g. <EM>jsmith</EM>). +<P> +This feature is displayed as "Compose Rejects Unqualified Addresses". +<P> + +<DT> <A NAME="compose-send-offers-first-filter"><EM>compose-send-offers-first-filter</EM></A> + +<DD> If you have <A HREF="#sending-filters"><EM>sending-filters</EM></A> +configured, setting this feature will cause the first filter in the +<EM>sending-filters</EM> list to be offered as the default +instead of <EM>unfiltered</EM>, the usual default. +<P> + +<DT> <A NAME="compose-sets-newsgroup-without-confirm"><EM>compose-sets-newsgroup-without-confirm</EM></A> + +<DD> If you enter the +composer while reading a newsgroup, you will normally be prompted to +determine whether you intend the new message to be posted to the current +newsgroup or not. If this feature is set, <EM>Alpine</EM> will not prompt you +in this situation, and will assume that you do indeed wish to post +to the newsgroup you are reading. +<P> +This feature is displayed as "Compose Sets Newsgroup Without Confirming". +<P> + +<DT> <A NAME="confirm-role-even-for-default"><EM>confirm-role-even-for-default</EM></A> + +<DD> If you have roles, when you Reply to or Forward a message, or Compose +a new message, <EM>Alpine</EM> +will search through your roles for one which matches. +Normally, if no matches are found you will be placed into the composer +with no opportunity to select a role. +If this feature is set, then you will be asked to confirm that you don't +want a role. +This will give you the opportunity to select a role (with the ^T command). +If you confirm no role with a Return, you will be placed in +the composer with no role. +You may also confirm with either an "N" or a "Y". +These behave the same as if you pressed the Return. +(The "N" and "Y" answers are available because they +match what you might type if there was a role match.) +<P> +If you are using the alternate form of the Compose command called +"Role", then all of your roles will be available to you, +independent of the value of this feauture and of the values set for all of +Reply Use, Forward Use, and Compose Use. +<P> + +<DT> <A NAME="continue-tab-without-confirm"><EM>continue-tab-without-confirm</EM></A> + +<DD> Normally, when you use the TAB NextNew +command and there is a problem checking a folder, you are asked +whether you want to continue with the search in the following folder or not. +This gives you a chance to stop the NextNew processing. +<P> +If this feature is set you will not be asked. +It will be assumed that you want to continue. +<P> +This feature is displayed as "Continue NextNew Without Confirming". +<P> + +<DT> <A NAME="convert-dates-to-localtime"><EM>convert-dates-to-localtime</EM></A> + +<DD> Normally, the message dates that you see in the +MESSAGE INDEX and MESSAGE VIEW are displayed in the timezone they were sent from. +For example, if a message was sent to you from a few timezones to the east +it might appear that it was sent from the future; +or if it was sent from somewhere to the west it might appear +as if it is from yesterday even though it was sent only a few minutes ago. +If this feature is set an attempt will be made to convert the dates +to your local timezone to be displayed. +<P> +Note that this does not affect the results of Select by Date or of +anything else other than these displayed dates. +When viewing the message you may look at the original unconverted value of the Date +header by using the HdrMode Command. +<P> + +<DT> <A NAME="copy-to-to-from"><EM>copy-to-address-to-from-if-it-is-us</EM></A> + +<DD> This feature affects the From address used when Replying to a message. +It is probably only useful if you have some +<A HREF="#alt-addresses">alt-addresses</A> +defined. +When enabled, it checks to see if any of the addresses in the To or Cc +fields of the message you are replying to is one of your addresses. +If it is, and there is only one of them, then that address is used as +the From address in the message you are composing. +In other words, you will be using a From address that is the same +as the To address that was used to get the mail to you in the first place. + +<P> +If a role is being used and it has a From address defined, that From address will +be used rather than the one derived from this feature. +<P> + +<DT> <A NAME="delete-skips-deleted"><EM>delete-skips-deleted</EM></A> + +<DD> If set, this +feature will cause the <EM>Delete</EM> command to +advance past other messages that +are marked deleted. In other words, pressing <EM>D</EM> will both mark the +current message deleted and advance to the next message that is not marked +deleted. +This feature is set by default. +<P> + +<DT> <A NAME="disable-config-cmd"><EM>disable-config-cmd</EM></A> + +<DD> If set, the configuration +screen <EM>Setup/Config</EM> will not be available at all. +<P> + +<DT> <A NAME="disable-save-input-history"><EM>disable-save-input-history</EM></A> + +<DD> Many of the prompts that ask for input in the status line near the +bottom of the screen will respond to Up Arrow and Down Arrow +with the history of previous entries. +For example, in the MESSAGE INDEX screen when you use the WhereIs +command the text you entered will be remembered and can be recalled +by using the Up Arrow key. +Another example, when saving a message the folders saved to will +be remembered and can be recalled using the arrow keys. +<P> +In the Save prompt, some users prefer that the Up and Down arrow keys +be used for the Previous Collection and Next Collection commands +instead of for a history of previous saves. +If this option is set the Up and Down arrow keys will become synonyms for the +Previous Collection and Next Collection (^P and ^N) commands in the +prompt for the name of a folder to Save to or in the prompt for the +name of a folder to GoTo. +When this feature is not set (the default), ^P and ^N will change the +collection and the arrow keys will show the history. +<P> + +<DT> <A NAME="disable-kblock"><EM>disable-keyboard-lock-cmd</EM></A> + +<DD> In the Main <EM>Alpine</EM> menu there is a Keyboard locking +command (<EM>KBLock</EM>). If this feature is set, that command won't be +available to the user. +<P> + +<DT> <A NAME="disable-keymenu"><EM>disable-keymenu</EM></A> + +<DD> If set, the command key menu that normally appears on the +bottom two lines of the screen will not usually be there. Asking for +help with <EM>^G</EM> or <EM>?</EM> will cause the key menu to +appear instead of causing the help message to come up. If you want to +actually see the help text, +another <EM>^G</EM> or <EM>?</EM> will show it to you. +After the key menu has popped +up with the help key it will remain there for an <EM>O Other</EM> command but +will disappear if any other command is typed. +<P> + +<DT> <A NAME="disable-password-caching"><EM>disable-password-caching</EM></A> +<P> + +<DD> Normally, loginname/password combinations are cached in <EM>Alpine</EM> +so that the user does not have to enter the same password more than once +in a session. +A disadvantage to this approach is that the password must be stored in +the memory image of the running <EM>Alpine</EM> in order that it can be reused. +In the event that <EM>Alpine</EM> crashes and produces a core dump, and that core +dump is readable by others, the loginname and password could possibly be read +from the core dump. +<P> +If this feature is set, then the passwords will not be cached and +the user will have to retype the password whenever <EM>Alpine</EM> needs it. +Even with this feature set there is still some chance that the core +file will contain a password, so care should be taken to make the +core files unreadable. +<P> +NOTE: If PASSFILE caching is enabled, this does not disable it. +That is a separate and independent feature. +<P> + +<DT> <A NAME="disable-password-cmd"><EM>disable-password-cmd</EM></A> + +<DD> If set the <EM>Newpassword</EM> command usually available under the +<EM>Setup</EM> command will not be available. +<P> + +<DT> <A NAME="disable-pipes-in-sigs"><EM>disable-pipes-in-sigs</EM></A> + +<DD> If set it will be an error to append a vertical bar (|) to the name +of a signature file. +Appending a vertical bar normally causes the signature file to be executed +to produce the signature. +<P> + +<DT> <A NAME="disable-pipes-in-templates"><EM>disable-pipes-in-templates</EM></A> + +<DD> If set it will be an error to append a vertical bar (|) to the name +of a template file. +Appending a vertical bar normally causes the signature file to be executed +to produce the signature. +<P> + +<DT> <A NAME="disable-regex"><EM>disable-regular-expression-matching-for-alternate-addresses</EM></A> + +<DD> Normally, the +<A HREF="#alt-addresses">alt-addresses</A> +option is interpreted as a regular expression. +One type of address that might cause trouble is an address that +contains a plus sign. +If you want to have an address with a plus as one of your +alternate addresses +and you don't want to use regular expressions, then setting this +feature will cause <EM>Alpine</EM> to treat the addresses you list literally instead. +<P> + +<DT> <A NAME="disable-roles-setup-cmd"><EM>disable-roles-setup-cmd</EM></A> + +<DD> If set the <EM>Roles</EM> command usually available under the +<EM>Setup</EM> command will not be available. +<P> + +<DT> <A NAME="disable-roles-sig-edit"><EM>disable-roles-sig-edit</EM></A> + +<DD> If set the roles editor in the <EM>Setup/Roles</EM> command will not allow +editing of signature files with the F subcommand. +<P> + +<DT> <A NAME="disable-roles-template-edit"><EM>disable-roles-template-edit</EM></A> + +<DD> If set the roles editor in the <EM>Setup/Roles</EM> command will not allow +editing of template files with the F subcommand. +<P> + +<DT> <A NAME="disable-sender"><EM>disable-sender</EM></A> + +<DD> If set, <EM>Alpine</EM> will not generate a "Sender:" or "X-X-Sender" header. +This may be desirable on a system which is virtually hosting many domains, +and the sysadmin has other methods available for tracking a message to +its originator. +<P> +This feature is displayed as "Do Not Generate Sender Header". +<P> + +<DT> <A NAME="disable-setlocale-collate"><EM>disable-setlocale-collate</EM></A> + +<DD> This is a hard to understand feature that should only be used in rare cases. +Normally, the C function call +<P> +<CENTER><SAMP>setlocale(LC_COLLATE, "")</SAMP></CENTER> +<P> +is used by <EM>Alpine</EM>. +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. +<P> + +<DT> <A NAME="disable-shared-namespaces"><EM>disable-shared-namespaces</EM></A> + +<DD> If this hidden feature is set +the automatic search for namespaces "ftp", +"imapshared", and "imappublic" by the underlying library +will be disabled. +The reason this feature exists is because there are some implementations +of system password lookup routines which are very slow when presented with +a long loginname which does not exist. +This feature could be set to prevent the delay at startup time when the +names above are searched for in the password file. +<P> + +<DT> <A NAME="disable-signature-edit-cmd"><EM>disable-signature-edit-cmd</EM></A> + +<DD> If set the <EM>Signature</EM> editing command usually available under the +<EM>Setup</EM> command will not be available. +<P> + +<DT> <A NAME="disable-take-fullname"><EM>disable-take-fullname-in-addresses</EM></A> + +<DD> Normally, when TakeAddr is used to copy an address or addresses +from a message into an address book entry, <EM>Alpine</EM> will try to preserve +the full name associated with each address in the list of addresses. +The reason for this is so that if the entry is a list or later becomes a +list, then information about the individual addresses in the list +is preserved. +If you would rather just have the simple addresses in the list of addresses, +set this feature. For example, with the default setting you might +see something like this in the ADDRESS BOOK editor after you type TakeAddr +<P> +<PRE> + Nickname : nick + Fullname : Bedrock Elders + Fcc : + Comment : + Addresses : Fred Flintstone <flint@bedrock.org>, + Barney Rubble <rubble@bedrock.org> +</PRE> +<P> +but with this feature set it would look like +<P> +<PRE> + Nickname : nick + Fullname : Bedrock Elders + Fcc : + Comment : + Addresses : flint@bedrock.org, + rubble@bedrock.org +</PRE> +<P> +instead. Note the difference in the Addresses field. +<P> + +<DT> <A NAME="disable-take-last-comma-first"><EM>disable-take-last-comma-first</EM></A> + +<DD> Normally, when <EM>TakeAddr</EM> is used to copy an address +from a message into an address book, <EM>Alpine</EM> will attempt to rewrite the +full name of the address in the form: + +<BLOCKQUOTE> + Last, First <BR> +</BLOCKQUOTE> + +instead of + +<BLOCKQUOTE> + First Last <BR> +</BLOCKQUOTE> + +It does this because many people find it useful to sort by Last name instead +of First name. If this feature is set, then the <EM>TakeAddr</EM> command will +not attempt to reverse the name in this manner. +<P> + +<DT> <A NAME="disable-terminal-reset-for-display-filters"><EM>disable-terminal-reset-for-display-filters</EM></A> + +<DD> UNIX <EM>Alpine</EM> only. +<P> +This feature affects <EM>Alpine</EM>'s behavior when using +<A HREF="#display-filters"><EM>Display-Filters</EM></A>. +Normally, before the display filter is run, the terminal mode is reset +to what it was before you started <EM>Alpine</EM>. +This may be necessary if the filter requires the use of the terminal. +For example, it may need to interact with you. +If you set this feature, then the terminal mode will not be reset. +One thing that turning on this feature should fix is the coloring of +quoted text in the message view, which +breaks because the terminal reset resets the color state of the terminal +(<A HREF="#color-config">Color Configuration</A>). +<P> + +<DT> <A NAME="downgrade-multipart-to-text"><EM>downgrade-multipart-to-text</EM></A> + +<DD> This feature affects <EM>Alpine</EM>'s behavior when sending mail. Internet +standards require <EM>Alpine</EM> to translate all non-ASCII characters in +messages that it sends using MIME encoding. This encoding can be +ostensibly broken for recipients if any agent between <EM>Alpine</EM> and the +recipient, such as an email list expander, appends text to the +message, such as list information or advertising. When sending such +messages <EM>Alpine</EM> attempts to protect such encoding by placing extra +MIME boundaries around the message text. +<P> +These extra boundaries are invisible to recipients that +use MIME-aware email programs (the vast majority). However, if +you correspond with users of email programs that are not MIME-aware, +or do not handle the extra boundaries gracefully, you can +use this feature to prevent <EM>Alpine</EM> from including the extra +MIME information. Of course, it will increase the likelihood +that non-ASCII text you send may appear corrupt to the recipient. +<P> + +<DT> <A NAME="enable-8bit-esmtp-negotiation"><EM>enable-8bit-esmtp-negotiation</EM></A> + +<DD> This feature affects <EM>Alpine</EM>'s behavior when sending mail. +By default, this feature is set. +Internet standards +require that all electronic mail messages traversing the global Internet +consist of 7bit ASCII characters unless a pair of cooperating mail +transfer agents explicitly agree to allow 8bit messages. In general, +then, exchanging messages in non-ASCII characters requires MIME encoding. +<P> + +However, there are now Internet standards that allow for unencoded 8bit +exchange of messages between cooperating systems. When this feature is set +<EM>Alpine</EM> will try to negotiate unencoded 8bit transmission during the +sending process. Should the negotiation fail, <EM>Alpine</EM> will fall back to its +ordinary encoding rules. +<P> + +Note, this feature relies on your system's mail transport agent or +configured <A HREF="#smtp-server"><EM>smtp-server</EM></A> +having the negotiation mechanism introduced in +"Extended SMTP" (ESMTP) and the specific extension called <EM>8BITMIME</EM>. +<P> + +<DT> <A NAME="enable-8bit-nntp-posting"><EM>enable-8bit-nntp-posting</EM></A> + +<DD> The Internet standard for exchanging USENET news messages (RFC-1036) +specifies that USENET messages should conform to Internet mail standards +and contain only 7bit characters, but much of the news transport software +in use today is capable of successfully sending messages containing 8bit +characters. Hence, many people believe that it is appropriate to send 8bit +news messages without any MIME encoding. +<P> + +Moreover, there is no Internet standard for explicitly negotiating 8bit +transfer, as there is for Internet email. Therefore, <EM>Alpine</EM> provides the +option of posting unencoded 8bit news messages, though not as the default. +Setting this feature will turn OFF <EM>Alpine</EM>'s MIME encoding of newsgroup +postings that contain 8bit characters. +<P> + +Note, articles may cross a path or pass through news transport software +that is unsafe or even hostile to 8bit characters. At best this will only +cause the posting to become garbled. The safest way to transmit 8bit +characters is to leave <EM>Alpine</EM>'s MIME encoding turned on, but recipients +who lack MIME-aware tools are often annoyed when they receive MIME-encoded +messages. +<P> + +<DT> <A NAME="enable-aggregate-command-set"><EM>enable-aggregate-command-set</EM></A> + +<DD> When this feature is set you may use the commands and subcommands that relate to +performing operations on more than one message at a time. +We call these "aggregate operations". +In particular, the <EM>; Select</EM>, <EM>A Apply</EM>, and +<EM>Z Zoom</EM> commands are enabled by this feature. +<EM>Select</EM> is used to <EM>tag</EM> one +or more messages meeting the specified criteria. <EM>Apply</EM> can then be used +to apply any message command to all of the selected/tagged messages. +Further, the <EM>Zoom</EM> command allows you to toggle the "Folder Index" view +between just those Selected and all messages in the folder. +<P> + +This feature also enables the <EM>^X</EM> subcommand in +the "Folder Index" <EM>WhereIs</EM> +command which causes +all messages matching the <EM>WhereIs</EM> argument to become +selected. +<P> + +You may also use aggregate operations in the address book screens where +you are operating on address book entries instead of on messages. +<P> + +<DT> <A NAME="enable-alt-ed"><EM>enable-alternate-editor-cmd</EM></A> + +<DD> If this feature is set (the default), and the <A HREF="#editor"><EM>editor</EM></A> +variable is not set, entering +the <EM>^_</EM> (Control-underscore) key while +composing a message will prompt you +for the name of the editor you would like to use. +<P> + +If the environment variable <CODE>$EDITOR</CODE> is set, +this value will be offered as a default. + +If the <EM>editor</EM> variable is set, the <EM>^_</EM> key will activate +the specified editor without prompting, in which case it is not necessary to +set the <EM>enable-alternate-editor-cmd</EM> feature. +This feature is not available in <EM>PC-Alpine</EM>. +<P> +This feature is displayed as "Enable Alternate Editor Command". +<P> + +<DT> <A NAME="enable-alt-imp"><EM>enable-alternate-editor-implicitly</EM></A> + +<DD> If this feature and the <A HREF="#editor"><EM>editor</EM></A> +variable are both set, <EM>Alpine</EM> will +automatically activate the specified editor when the cursor is moved from +the header of the message being composed into the message text. For +replies, the alternate editor will be activated immediately. If this +feature is set but the <EM>editor</EM> variable is not set, +then <EM>Alpine</EM> will +automatically ask for the name of an alternate editor when the cursor +is moved out of the headers, or if a reply is being done. +This feature is not available in <EM>PC-Alpine</EM>. +<P> + +<DT> <A NAME="enable-arrow-navigation"><EM>enable-arrow-navigation</EM></A> + +<DD> This feature controls the behavior of the left and right arrow keys. +If set, the left and right arrow keys will operate like the usual +navigation keys <EM><</EM> and <EM>></EM>. +This feature is set by default. + +<P> +If you set this feature, and do not like the changed behavior of the up/down +arrow keys when navigating through the FOLDER LIST screen -- +<B>first</B> from column to column, if more than one folder is +displayed per row, +and <B>then</B> from row to row -- you may either also wish to set the feature +<A HREF="#enable-arrow-navigation-relaxed"><EM>enable-arrow-navigation-relaxed</EM></A>, +<A HREF="#single-column-folder-list"><EM>single-column-folder-list</EM></A>, +or use the ^P/^N (instead of up/down arrow) keys to move up/down the list of +folders in each column. +<P> + +<DT> <A NAME="enable-arrow-navigation-relaxed"><EM>enable-arrow-navigation-relaxed</EM></A> + +<DD> This feature controls the behavior of the left and right arrow keys +in the FOLDER LIST screen when the +<A HREF="#enable-arrow-navigation"><EM>enable-arrow-navigation</EM></A> +feature is set. +This feature is set by default. +<P> + +When this feature is set, the left and right +arrow keys in the FOLDER LIST screen +move the highlight bar to the left or right, and the up and +down arrows move it up or down. + +<P> +When the "Enable-Arrow-Navigation" feature is set and this +feature is not set; +the left and right arrow keys in the Folder List screen strictly +track the commands bound to the '<' and '>' keys, and the up +and down arrow keys move the highlight bar to the previous and next +folder or directory name. + +<P> + +<DT> <A NAME="enable-background-sending"><EM>enable-background-sending</EM></A> + +<DD> If set, this +feature enables a subcommand in the composer's <EM>Send?</EM> confirmation +prompt. The subcommand allows you to tell <EM>Alpine</EM> to handle the actual +posting in the background. While this feature usually allows posting +to appear to happen very fast, it has no affect on the actual delivery +time it takes a message to arrive at its destination. +<P> + +This feature isn't supported on all systems. All DOS and Windows, +as well as several Unix ports, do not recognize this feature. +It is not possible to use background sending if the feature +<A HREF="#send-without-confirm">send-without-confirm</A> is set. +<P> + +Error handling is significantly different when this feature is +enabled. Any message posting failure results in the message +being appended to your <EM>Interrupted</EM> mail folder. When you +type the <EM>Compose</EM> command, <EM>Alpine</EM> will notice this folder and +offer to extract any messages contained. Upon continuing a +failed message, <EM>Alpine</EM> will display the nature of the failure +in the status message line. +<P> + +Under extreme conditions, it is possible for message data to +get lost. Do not enable this feature if you typically run close +to any sort of disk-space limits or quotas. +<P> + +<DT> <A NAME="enable-bounce-cmd"><EM>enable-bounce-cmd</EM></A> + +<DD> Setting this feature enables the <EM>B Bounce</EM> command, +which will prompt +for an address and <EM>remail</EM> the message to the new recipient. +This command +is used to re-direct messages that you have received in error, or need to +be redirected for some other reason (e.g. list moderation). The final +recipient will see a header indicating that you have Resent the msg, but +the message's From: header will show the original author of the message, +and replies to it will go back to that author, and not to you. +<P> +This feature is displayed as "Enable Bounce Command". +<P> + +<DT> <A NAME="enable-cruise-mode"><EM>enable-cruise-mode</EM></A> + +<DD> This feature affects <EM>Alpine</EM>'s behavior when you hit the "Space Bar" at +the end of a displayed message. Typically, <EM>Alpine</EM> complains that the end +of the text has already been reached. Setting this feature causes such +keystrokes to be interpreted as if the <EM>Tab</EM> key had been hit, thus +taking you to the next <EM>interesting</EM> message, or scanning ahead to the +next incoming folder with <EM>interesting</EM> messages. +<P> + +<DT> <A NAME="enable-cruise-mode-delete"><EM>enable-cruise-mode-delete</EM></A> + +<DD> This feature modifies the behavior of <EM>Alpine</EM>'s <EM>enable-cruise-mode</EM> +feature. Setting this feature causes <EM>Alpine</EM> to implicitly delete read +messages when it moves on to display the next <EM>interesting</EM> message. +<P> + +NOTE: Beware when enabling this feature <B>and</B> the +<A HREF="#expunge-wo-confirm"><EM>expunge-without-confirm</EM></A> feature. +<P> +This feature is displayed as "Enable Cruise Mode With Deleting". +<P> + +<DT> <A NAME="enable-delivery-status-notification"><EM>enable-delivery-status-notification</EM></A> + +<DD> If set, this +feature enables a subcommand in the composer's "Send?" confirmation +prompt. The subcommand allows you to tell <EM>Alpine</EM> to request the type of +Delivery Status Notification (DSN) which you would like. Most users will +be happy with the default, and need not enable this feature. See the online +help for more details. +<P> +It is not possible to use delivery status notifications if the feature +<A HREF="#send-without-confirm">send-without-confirm</A> is set. +<P> + +Note that this is not a method to request <EM>READ</EM> receipts, which tells +the sender when the receiver has read the message. In this case we're talking +about notification of delivery to the mailbox, not notification that the +message has been seen. +<P> + +<DT> <A NAME="enable-dot-files"><EM>enable-dot-files</EM></A> + +<DD> If set, files beginning with dot (".") will be +visible in the file browser. For example, you'll be able to select them +when using the browser to add an attachment to a message. +<P> + +<DT> <A NAME="enable-dot-folders"><EM>enable-dot-folders</EM></A> + +<DD> If set, folders beginning with dot (".") may be added +and viewed. +This feature is displayed as "Enable Hidden Folders". +<P> + +<DT> <A NAME="enable-exit-via-lessthan-command"><EM>enable-exit-via-lessthan-command</EM></A> + +<DD> If set, then on screens where there is an <EM>Exit</EM> command +but no <EM><</EM> command, the <EM><</EM> key will perform +the same function as the <EM>Exit</EM> command. +This feature is set by default. +<P> + +<DT> <A NAME="enable-fast-recent-test"><EM>enable-fast-recent-test</EM></A> + +<DD> This feature controls the behavior of the TAB key when traversing folders +in the optional +<A HREF="#enable-incoming-folders">Incoming-Folders</A> +collection or in optional News-Collections. + +<P> +When the TAB +(NextNew) +key is pressed, the default behavior is to +explicitly examine the status of the folder for the number of recent +messages (messages delivered since the last time it was viewed). +Depending on the size and number of messages in the folder, this test +can be time consuming. + +<P> +Enabling this feature will cause <EM>Alpine</EM> to only test for the existence of +any recent messages rather than to obtain the count. This is much faster +in many cases. The downside is that you're not given the number of recent +messages when prompted to view the next folder. +If the feature +<A HREF="#tab-uses-unseen-for-next-folder">Tab-Uses-Unseen-For-Next-Folder</A> +is turned on, then the present feature will have no effect. +<P> + +<DT> <A NAME="enable-flag-cmd"><EM>enable-flag-cmd</EM></A> + +<DD> Setting this feature enables the <EM>* Flag</EM> command, +which allows you to +manipulate the status flags associated with a message. +By default, <EM>Flag</EM> +will set the <EM>Important</EM> flag, which results in an asterisk being +displayed in column one of the "Folder Index" for such messages. +<P> +This feature is displayed as "Enable Flag Command". +<P> + +<DT> <A NAME="enable-flag-screen-implicitly"><EM>enable-flag-screen-implicitly</EM></A> + +<DD> This feature modifies the behavior of the <EM>* Flag</EM> command +(provided it too is enabled). +By default, when the <EM>* Flag</EM> command is selected, +<EM>Alpine</EM> offers a prompt to set one of several flags and also offers the +option of entering the detailed flag manipulation screen via the <EM>^T</EM> +key. Enabling this feature causes <EM>Alpine</EM> to immediately enter the detailed +flag screen rather than first offer the simple prompt. +The +<A HREF="#enable-flag-screen-keyword-shortcut">Enable-Flag-Screen-Keyword-Shortcut</A> option offers a slightly different way of setting keywords. +<P> + +<DT> <A NAME="enable-flag-screen-keyword-shortcut"><EM>enable-flag-screen-keyword-shortcut</EM></A> + +<DD> This feature modifies the behavior of the +Flag command and the Select command. +By default, when the "* Flag" command is selected, +<EM>Alpine</EM> offers a prompt to set one of several flags and also offers the +option of entering the detailed flag manipulation screen via the "^T" +key. +If you have +<A HREF="#keywords">keywords</A> +defined, then enabling this feature adds a shortcut way to set or unset +keywords. +You use "*" followed by the first letter of a keyword (or the nickname of +a keyword if you've given it a nickname) and that will set the keyword. +<P> +An example is easier to understand than the explanation. +The flag command can always be used to set the system flags. +For example, to set the Answered flag you would type +<P> +<CENTER><SAMP>* A</SAMP></CENTER> +<P> +Now suppose you have defined a keyword "Work" using the Keywords +option in the Config screen. +By default, to set a keyword like "Work" you would usually +have to go to the Flag Details screen using +the "^T To Flag Details" command. +Instead, if you have enabled this feature, you may type +<P> +<CENTER><SAMP>* W</SAMP></CENTER> +<P> +to set the Work flag, or +<P> +<CENTER><SAMP>* ! W</SAMP></CENTER> +<P> +to unset it. +Just like for the other flag setting commands, the case of the letter does +not matter, so "w" or "W" both set the "Work" +keyword. +<P> +Notice that you can only use this trick for one keyword that begins +with "W". +If you happen to have a "Work" keyword and another keyword that is +"WIFI" the "* W" command will set the first one in +your list of keywords. +Also, there are five letters which are reserved for system +flags and the NOT command. +If you type "* A" it will always set the Answered flag, not +your "Aardvark" keyword. +In order to set the "Aardvark" keyword you'll still have to use +the Flag Details screen. +<P> +Because enabling the +<A HREF="#enable-flag-screen-implicitly">Enable-Flag-Screen-Implicitly</A> +option causes <EM>Alpine</EM> to skip directly to the Flag Details screen when the +Flag command is used, +setting it will cause this feature to have no effect at all. +<P> +Similarly, when Selecting by Keyword, setting this option will allow you +to use Keyword initials instead of full keywords. +<P> + +<DT> <A NAME="enable-full-header-cmd"><EM>enable-full-header-cmd</EM></A> + +<DD> This feature enables the <EM>H Full Headers</EM> command which +toggles between +the display of all headers in the message and the normal edited view of +headers. The <EM>Full Header</EM> command also controls +which headers are included +for <EM>Export</EM>, <EM>Pipe</EM>, <EM>Print</EM>, <EM>Forward</EM>, +and <EM>Reply</EM> functions. (For <EM>Reply</EM>, the +<EM>Full Header</EM> mode will respect +the <EM>include-headers-in-reply</EM> feature setting.) +<P> +If Full Header mode is turned on and you Forward a message, you will +be asked if you'd like to forward the message as an attachment, as opposed +to including the text of the message in the body of your new message. +<P> +If you have also turned on the +<A HREF="#quote-suppression-threshold">"Quote Suppression"</A> +option then the Full Headers command actually rotates through three states +instead of just two. +The first is the normal view with long quotes suppressed. +The second is the normal view but with the long quotes included. +The last enables the display of all headers in the message. +When using Export, Pipe, Print, Forward, or Reply the quotes are +never suppressed, so the first two states are identical. +<P> +Normally, the Header Mode will reset +to the default behavior when moving to a new message. +The mode can be made to persist from message to message by setting the feature +<A HREF="#quell-full-header-auto-reset">Quell-Full-Header-Auto-Reset</A>. +<P> +This feature is displayed as "Enable Full Header Command". +<P> + +<DT> <A NAME="enable-full-header-and-text"><EM>enable-full-header-and-text</EM></A> + +<DD> +<P>This feature affects how the <EM>H Full Headers</EM> command displays +message text. If set, the raw message text will be displayed. This +especially affects MIME formatted email, where the entire MIME format +will be displayed. This feature similarly affects how messages are +included for the <EM>Export</EM>, <EM>Pipe</EM>, <EM>Print</EM>, <EM>Forward</EM>, +and <EM>Reply</EM> functions. + +<DT> <A NAME="enable-goto-in-file-browser"><EM>enable-goto-in-file-browser</EM></A> + +<DD> Setting this causes <EM>Alpine</EM> to offer the <EM>G Goto</EM> command in +the file browser. The Goto command allows you to explicitly type in the +desired directory. +That is the default. +<P> + +<DT> <A NAME="enable-incoming-folders"><EM>enable-incoming-folders</EM></A> + +<DD> If set, this feature defines a pseudo-folder collection called +<EM>INCOMING MESSAGE FOLDERS</EM>. +Initially, the only folder included in this collection +will be your <EM>INBOX</EM>, which will no longer show up in your default +saved-message folder collection. +<P> +This feature is displayed as "Enable Incoming Folders Collection". +<P> + +<DT> <A NAME="enable-incoming-folders-checking"><EM>enable-incoming-folders-checking</EM></A> + +<DD> This feature is only operational if you have enabled the optional +<A HREF="#inc-fold"><EM>incoming-folders</EM></A> +If you do have Incoming Message Folders and you also set this feature, +then the number of Unseen messages in each folder will be displayed +in the FOLDER LIST screen for the Incoming Message Folders. +The number of Unseen messages in a folder will be displayed in parentheses +to the right of the name of each folder. +If there are no Unseen messages in a folder then only the name +is displayed, not a set of parentheses with zero inside them. +A redraw command, Ctrl-L, can be used in the FOLDER LIST screen for +the Incoming Message Folders to cause an immediate update. +<P> +If a check for Unseen messages fails for a particular folder then Alpine +will no longer attempt to check that folder for the duration of the +session and this will be indicated by a question mark inside the +parentheses. +<P> +The features +<A HREF="#incoming-checking-includes-total"><EM>incoming-checking-includes-total</EM></A>, +<A HREF="#incoming-checking-uses-recent"><EM>incoming-checking-uses-recent</EM></A>, +<A HREF="#incoming-check-list"><EM>incoming-check-list</EM></A>, +<A HREF="#incoming-check-interval"><EM>incoming-check-interval</EM></A>, +<A HREF="#incoming-check-interval-secondary"><EM>incoming-check-interval-secondary</EM></A>, and +<A HREF="#incoming-check-timeout"><EM>incoming-check-timeout</EM></A> +all affect how this feature behaves. +<P> + +<DT> <A NAME="disable-index-locale-dates"><EM>Disable-Index-Locale-Dates</EM></A> + +<DD> This feature affects the display of dates in the MESSAGE INDEX. +Normally an attempt is made to localize the dates +used in the MESSAGE INDEX display to your locale. +This is controlled with the +LC_TIME locale setting on a UNIX system. +On Windows the Regional Options control panel may be used to set the date format. +At the programming level, <EM>Alpine</EM> is using the strftime routine +to print the parts of a date. +<P> +If this feature is set, dates are displayed in English and +with the conventions of the United States. +<P> + +<DT> <A NAME="enable-jump-shortcut"><EM>enable-jump-shortcut</EM></A> + +<DD> When this feature is set you may enter a number (followed by RETURN) +and jump to that message number, when in the MESSAGE INDEX or MESSAGE TEXT +screens. In other words, it obviates the need for typing the <EM>J</EM> for the +<EM>Jump</EM> command. +<P> + +<DT> <A NAME="enable-lame-list-mode"><EM>enable-lame-list-mode</EM></A> + +<DD> This feature modifies the method <EM>Alpine</EM> uses to ask your IMAP +server for folder names to display in the the FOLDER LIST screen. +It is intended to compensate for a small set of IMAP servers that +are programmed to ignore a part of the request, and thus respond +to <EM>Alpine</EM>'s query with nonsensical results. +<P> + +If you find that <EM>Alpine</EM> is erroneously displaying blank folder lists, +try enabling this feature. +<P> + +NOTE: Enabling this feature has consequences for the Goto and Save +commands. Many servers allow access to folders outside the area +reserved for your personal folders via some reserved character, +typically '#' (sharp), '~' (tilde) or '/' (slash). This mechanism +allows, at the Goto and Save prompts, quick access to folders +outside your personal folder collection without requiring a specific +collection definition. This behavior will generally not be available +when this feature is enabled. +<P> +This feature is displayed as "Compensate for Deficient IMAP servers". +<P> + +<DT> <A NAME="enable-mail-check-cue"><EM>enable-mail-check-cue</EM></A> + +<DD> If set, this will cause an asterisk to appear in the upper +left-hand corner of the screen whenever <EM>Alpine</EM> checks for new mail, and two +asterisks whenever <EM>Alpine</EM> saves (checkpoints) the state of the current +mailbox to disk. +<P> + +<DT> <A NAME="enable-mailcap-param-substitution"><EM>enable-mailcap-param-substitution</EM></A> + +<DD> If set, this will allow mailcap named parameter substitution to occur +in mailcap entries. +By default, this is turned off to prevent security problems which may occur +with some incorrect mailcap configurations. +For more information, RFC1524 and look for "named parameters" in the +text of the RFC. +<P> +This feature is displayed as "Enable Mailcap Parameter Substitution". +<P> + +<DT> <A NAME="enable-mouse-in-xterm"><EM>enable-mouse-in-xterm</EM></A> + +<DD> +This feature controls whether or not an X terminal mouse can be used with +<EM>Alpine</EM>. If set, and the $DISPLAY variable indicates that an X terminal is +being used, the left mouse button on the mouse can be used to select text +or commands. +Clicking on a command at the bottom of the screen will behave as if you had +typed that command. +Clicking on an index line will move the current message highlight to +that line. +Double-clicking on an index line will view the message. +Double-clicking on a link will view the link. +<P> +This type of mouse support will also work in some terminal emulators which are +not actually X terminals, but which have extra code to support the xterm +style mouse. +For those emulators you not only need to turn this feature on but you also +have to set the $DISPLAY environment variable even though it isn't needed +for your terminal. +That will cause <EM>Alpine</EM> to think that it is an xterm and to properly interpret the +escape sequences sent by the mouse. +<P> +Note: if this feature is set, the behavior of X terminal cut-and-paste is +also modified. It is sometimes possible to hold the shift key down while clicking +left or middle mouse buttons for the normal xterm cut/paste operations. +There is also an <EM>Alpine</EM> command to toggle this mode on or off. +The command is Ctrl-\ (Control-backslash). +<P> + +<DT> <A NAME="enable-msg-view-addresses"><EM>enable-msg-view-addresses</EM></A> + +<DD> This feature modifies the behavior of <EM>Alpine</EM>'s "Message Text" screen. +Setting this feature causes <EM>Alpine</EM> to select possible email addresses +from the displayed text and display them in boldface for selection. +<P> + +The first available email address is displayed in inverse. This is the +"selected" address. +Pressing <EM>RETURN</EM> will cause <EM>Alpine</EM> to enter the message +composition screen with the To field filled in with the selected address. +<P> + +Use the up and down arrow keys to change which of the addresses +displayed in boldface is the current selection. +<P> +This feature is displayed as "Enable Message View Address Links". +<P> + +<DT> <A NAME="enable-msg-view-attachments"><EM>enable-msg-view-attachments</EM></A> + +<DD> This feature modifies the behavior of <EM>Alpine</EM>'s "Message Text" screen. +Setting this feature causes <EM>Alpine</EM> to present attachments in boldface. +The first available attachment is displayed in inverse. This is the +"selected" attachment. Pressing <EM>RETURN</EM> will cause <EM>Alpine</EM> to display +the selected attachment. Use the up and down arrow keys to change which of the +attachments displayed in boldface is the current selection. +<P> + +Speaking of arrow keys, the Up and Down Arrows will select the next +and previous attachments if one is available on the screen for selection. +Otherwise, they will simply adjust the viewed text one line up or down. +<P> + +Similarly, when selectable items are present in a message, the Ctrl-F +key can be used to select the next item in the message independent +of which portion of the viewed message is currently displayed. The +Ctrl-B key can be used to select the previous item in the same way. +<P> +This feature is displayed as "Enable Message View Attachment Links". +<P> + +<DT> <A NAME="enable-msg-view-forced-arrows"><EM>enable-msg-view-forced-arrows</EM></A> + +<DD> This feature modifies Up and Down arrow key behavior in <EM>Alpine</EM>'s +"Message Text" screen when selectable Attachments, URL's, or +web-hostnames are presented. <EM>Alpine</EM>'s usual behavior is to move to +the next or previous selectable item if currently displayed or +simply to adjust the screen view by one line if the next selectable line +is off the screen. +<P> + +Setting this feature causes the Up and Down arrow keys to behave as +if no selectable items were present in the message. +<P> + +Note, the <EM>Ctrl-F</EM> (next selectable item) and +<EM>Ctrl-B</EM> (previous selectable item) functionality is unchanged. +<P> +This feature is displayed as "Enable Message View Forced Arrows". +<P> + +<DT> <A NAME="enable-msg-view-urls"><EM>enable-msg-view-urls</EM></A> + +<DD> This feature modifies the behavior of <EM>Alpine</EM>'s "Message Text" screen. +When this feature is set (the default) <EM>Alpine</EM> will select possible URLs from the +displayed text and display them in boldface for selection. +<P> + +The first available URL is displayed in inverse. This is the +"selected" URL. Pressing <EM>RETURN</EM> will cause <EM>Alpine</EM> to display +the selected URL via either built-in means as with <CODE>mailto:</CODE>, +<CODE>imap:</CODE>, <CODE>news:</CODE>, and <CODE>nntp:</CODE>, +or via an external application as defined +by the <A HREF="#url-viewers"><EM>url-viewers</EM></A> variable. +<P> + +Use the up and down arrow keys to change which of the URLs displayed in boldface +is the current selection. +<P> +This feature is displayed as "Enable Message View URL Links". +<P> + +<DT> <A NAME="enable-msg-view-web-hostnames"><EM>enable-msg-view-web-hostnames</EM></A> + +<DD> This feature modifies the behavior of <EM>Alpine</EM>'s "Message Text" screen. +When this feature is set (the default) <EM>Alpine</EM> will select possible web hostnames +from the displayed text and display them in boldface for selection. +<P> + +The first available hostname is displayed in inverse. This is the +"selected" hostname. Pressing <EM>RETURN</EM> will cause <EM>Alpine</EM> to display +the selected hostname via an external application as defined +by the <A HREF="#url-viewers"><EM>url-viewers</EM></A> variable. +<P> + +Use the up and down arrow keys to change which of the hostnames displayed in +boldface is the current selection. +<P> +This feature is displayed as "Enable Message View Web Hostname Links". +<P> + +<DT> <A NAME="enable-multiple-newsrcs"><EM>enable-multiple-newsrcs</EM></A> + +<DD> This feature makes it so <EM>Alpine</EM> can use multiple newsrcs based on +the news server being connected to, which allows for separate lists +of subscribed-to newsgroups. When this feature is not set, there is only +one list of newsgroups. +<P> +Under this feature, the name of a newsrc is based on the news server. +For example, if your <a href="#newsrc-path">newsrc-path</a> +is set to ".newsrc", and the news server you are connecting to is +news.example.com, then the newsrc to be used is .newsrc-news.example.com. +Setting this feature for the first time will allow for the option of using +your old newsrc the next time you read news. +<P> +If this feature is set, then the feature +<A HREF="#mult-newsrc-hostnames-as-typed">Mult-Newsrc-Hostnames-As-Typed</A> +also may affect the name of the newsrc file that is used. + +<P> + +<DT> <A NAME="enable-newmail-in-xterm-icon"><EM>enable-newmail-in-xterm-icon</EM></A> + +<DD> This feature controls whether or not <EM>Alpine</EM> will attempt to announce new +mail arrival when it is running in an X terminal window and that window +is iconified. +If set, and the <CODE>$DISPLAY</CODE> variable indicates that an X +terminal is being used, <EM>Alpine</EM> will send appropriate escape sequences to +the X terminal to modify the label on <EM>Alpine</EM>'s icon to indicate that new +mail has arrived. <EM>Alpine</EM> will also modify the <EM>Alpine</EM> window's title to +indicate new mail. +See also <A HREF="#enable-newmail-short-text-in-icon">Enable-Newmail-Short-Text-in-Icon</A>. +<P> + +<DT> <A NAME="enable-newmail-short-text-in-icon"><EM>enable-newmail-short-text-in-icon</EM></A> + +<DD> This feature controls the text to be displayed in an icon in the event +of a new message arrival. Normally, the message will +be the one that is displayed on the screen. This feature shortens the +message to a count of the number of new messages in brackets. This may be +more useful for those who use the window's title bar in the task bar as a +new mail indicator. This feature is only useful if the +<A HREF="#enable-newmail-in-xterm-icon">Enable-Newmail-in-Xterm-Icon</A> +is also set. Like the Enable-Newmail-in-Xterm-Icon +feature, this feature is only relevant when run in an xterm environment. +<P> + +<DT> <A NAME="enable-partial-match-lists"><EM>enable-partial-match-lists</EM></A> + +<DD> This feature affects the subcommands available when <EM>Sav</EM>ing +or Opening a new folder. If set, the subcommand <EM>^X ListMatches</EM> will be +available. This command allows you to type in a substring of the folder +you are looking for and when you type <EM>^X</EM> it will display all folders +which contain that substring in their names. +This feature is set by default. +<P> + +<DT> <A NAME="enable-print-via-y-command"><EM>enable-print-via-y-command</EM></A> + +<DD> By default, <EM>Alpine</EM>'s print command is available by pressing the <EM>%</EM> +key. In older versions of <EM>Pine</EM>, the print command was accessed by +pressing the <EM>Y</EM> key. +<P> + +Enabling this feature will cause <EM>Alpine</EM> to recognize both the old +command, <EM>Y</EM>, and the new <EM>%</EM> method for invoking +printing. Note, key menu labels are not changed as a result of +enabling this feature. +<P> + +<DT> <A NAME="enable-reply-indent-string-editing"><EM>enable-reply-indent-string-editing</EM></A> + +<DD> This feature affects the Reply command's "Include original message +in Reply?" prompt. When enabled, it causes the +"Edit Indent String" sub-command to appear which allows +you to edit the string <EM>Alpine</EM> would otherwise use to denote included +text from the message being replied to.<P> + +Thus, you can change <EM>Alpine</EM>'s default message quote character (usually +an angle bracket) on a per message basis. So you could change your quoted message to +look, for example, like this:<p> + +<pre>On Tues, 26 Jan 1999, John Q. Smith wrote: + +John: I just wanted to say hello and to congratulate you +John: on a job well done!</pre><p> + +The configuration option +<A HREF="#reply-ind-str">"reply-indent-string"</A> +may be used to change what appears as the default string to be edited. +<P> +NOTE: Edited reply-indent-strings only apply to the message +currently being replied to. +<P> + +<DT> <A NAME="enable-rules-under-take"><EM>enable-rules-under-take</EM></A> + +<DD> Normally, the Take command takes addresses from a message and helps you +put them into your Address Book. +If you use Rules for Indexcolors, Roles, Filtering, or Scoring; +you may find it useful +to be able to Take information from a message's headers and put it into +a new Rule. +When this feature is set, you will be given an extra prompt which gives +you the choice to Take into the Address Book or Take into a rule. +<P> +This feature is displayed as "Enable Take Rules". +<P> + +<DT> <A NAME="enable-search-and-replace"><EM>enable-search-and-replace</EM></A> + +<DD> If set <EM>Alpine</EM>'s composer offers the <EM>R Replace</EM> command +option inside the <EM>W WhereIs</EM> command. +<P> + +<DT> <A NAME="enable-sigdashes"><EM>enable-sigdashes</EM></A> + +<DD> If set and a <EM>signature-file</EM> exists, the line consisting of +the three characters "<CODE>-- </CODE>" (dash dash space) is included +before the signature. +This only happens if the signature doesn't already contain such a line. +<P> +In addition, when you Reply or Followup to a message containing one of +these special lines and choose to include its text, <EM>Alpine</EM> will observe +the convention of not including text beyond the special line in your +reply. +<P> + +<DT> <A NAME="enable-suspend"><EM>enable-suspend</EM></A> + +<DD> Setting this feature will allow you to type <EM>^Z</EM> +and temporarily suspend <EM>Alpine</EM>. Not available on <EM>PC-Alpine</EM>. +<P> + +<DT> <A NAME="enable-tab-completion"><EM>enable-tab-completion</EM></A> + +<DD> This feature enables the <EM>TAB</EM> key when +at a prompt for a filename. In this +case, <EM>TAB</EM> will cause the +partial name already entered to be automatically +completed, provided the partial name is unambiguous. +This feature is set by default. +<P> +Similarly, this feature also enables TAB completion of address book +nicknames when at a prompt for a nickname, +or when typing in an address field in the composer. +<P> + +<DT> <A NAME="enable-take-export"><EM>enable-take-export</EM></A> + +<DD> Normally, the Take command takes addresses from a message and helps you +put them into your Address Book. +When this feature is set, you will be given an extra prompt which gives you +the choice to Take addresses into a file instead of your Address +Book. +Only the user@domain_name part of the address is put in the file. +<P> + +<DT> <A NAME="enable-tray-icon"><EM>enable-tray-icon</EM></A> + +<DD> <EM>PC-Alpine</EM> only. This option restores a behavior of +previous versions of PC-Alpine. These +versions, when started, installed a PC-Alpine icon in the notification +tray of Window's Taskbar. The primary use of this icon was to indicate +new mail arrival by turning red (while the Taskbar icon remained green). +Additionally, the icon now changes to yellow to signify that a mail folder +has been closed unexpectedly. +<P> +Rather than add another icon to the Taskbar, this version of PC-Alpine will +color its Taskbar entry's icon red (as well as the icon in the Window +Title). This feature is only provided for backwards compatibility. +<P> + +<DT> <A NAME="enable-unix-pipe-cmd"><EM>enable-unix-pipe-cmd</EM></A> + +<DD> This feature enables the <EM>| Pipe</EM> command +that sends the current message +to the specified Unix command for external processing. +<P> +This feature is displayed as "Enable Unix Pipe Command". +<P> + +<DT> <A NAME="enable-verbose-smtp-posting"><EM>enable-verbose-smtp-posting</EM></A> + +<DD> This feature controls an aspect of <EM>Alpine</EM>'s message sending. When enabled, +<EM>Alpine</EM> will send a <CODE>VERB</CODE> (i.e., VERBose) command +early in the posting process +intended to cause the server SMTP to provide a more detailed account of +the transaction. This feature is typically only useful to system +administrators and other support personel as an aid in troublshooting +problems. + +Note, this feature relies on a specific capability of the system's mail +transport agent or configured <A HREF="#smtp-server"><EM>smtp-server</EM></A>. +<P> + +<DT> <A NAME="expanded-view-of-addressbooks"><EM>expanded-view-of-addressbooks</EM></A> + +<DD> If multiple address books (either personal or global) are defined, and you +wish to have them all expanded implicitly upon entering the ADDRESS BOOK +screen, then set this feature. This feature will have no effect unless the +feature +<A HREF="#combined-addrbook-display"><EM>combined-addrbook-display</EM></A> +is also set. +<P> + +<DT> <A NAME="expanded-view-of-distribution-lists"><EM>expanded-view-of-distribution-lists</EM></A> + +<DD> If this feature is set, then distribution lists in the address book +screen will always be expanded automatically. +<P> + +<DT> <A NAME="expanded-view-of-folders"><EM>expanded-view-of-folders</EM></A> + +<DD> If multiple folder collections are defined, and you +wish to have them all expanded implicitly upon entering the FOLDER LIST +screen, then set this feature. This feature will have no effect unless the +feature +<A HREF="#combined-folder-display"><EM>combined-folder-display</EM></A> +is also set. +<P> + +<DT> <A NAME="expose-hidden-config"><EM>expose-hidden-config</EM></A> + +<DD> The purpose of this feature is to allow you to change configuration +features and variables which are normally hidden. +This is particularly useful if you are using a remote configuration file, +where it is difficult to edit the file manually, but it may also be used +on a local pinerc configuration file. +<P> +If set, most configuration variables and features which are normally +hidden from view will show up in the Setup/Configuration screen. +They will be at the bottom of the configuration screen. +You can find them by searching for the word "hidden". +<P> + +Note that this is an advanced feature which should be used with care. +The reason that this part of the configuration is normally hidden is because +there is a significant potential for causing problems if you change these +variables. +If something breaks after a change try changing it back to see if that is +what is causing the problem. +There are also some variables which are normally hidden because they are +manipulated through <EM>Alpine</EM> in other ways. +For example, the "address-book" variable is normally set using +the Setup/AddressBooks screen, so there is little reason to edit it directly. +The "incoming-folders" variable is normally changed by using +the Add, Delete, and Rename commands in the FOLDER LIST screen, +and the "last-time-prune-questioned" variable is normally used +internally by <EM>Alpine</EM> and not set directly by the user. +<P> + +<DT> <A NAME="expunge-only-manually"><EM>expunge-only-manually</EM></A> + +<DD> Normally, when you close a folder which contains deleted messages you are +asked if you want to expunge those messages from the folder permanently. +If this feature is set, you won't be asked and the deleted messages will +remain in the folder. +If you choose to set this feature you will have to expunge the +messages manually using the eXpunge command, which you can use while +in the MESSAGE INDEX screen. +If you do not expunge deleted messages the size of your +folder will continue to increase until you are out of disk space. +<P> + +<DT> <A NAME="expunge-wo-confirm"><EM>expunge-without-confirm</EM></A> + +<DD> If set, you will not be prompted to confirm your intent before +the expunge takes place. Actually, you will still be prompted for confirmation +if the folder is not the <EM>INBOX</EM> folder or another folder in the +Incoming Folders collection. See the <EM>expunge-without-confirm-everywhere</EM> +feature which follows. +<P> +This feature is displayed as "Expunge Without Confirming". +<P> + +<DT> <A NAME="expunge-without-confirm-everywhere"><EM>expunge-without-confirm-everywhere</EM></A> + +<DD> The regular <EM>expunge-without-confirm</EM> feature actually only +works for the <EM>INBOX</EM> folder and for other folders in the "Incoming +Folders" collection. If this feature is set then you also won't be prompted +to confirm expunges for all other folders. +<P> +This feature is displayed as "Expunge Without Confirming Everywhere". +<P> + +<DT> <A NAME="fcc-on-bounce"><EM>fcc-on-bounce</EM></A> + +<DD> If set, normal Fcc (File Carbon Copy) processing will be +done for bounced messages, +just as if you had composed a message to the address you are +bouncing to. If not set, no Fcc of the message will be saved. +<P> +This feature is displayed as "Include Fcc When Bouncing Messages". +<P> + +<DT> <A NAME="fcc-only-without-confirm"><EM>fcc-only-without-confirm</EM></A> + +<DD> This features controls an aspect of <EM>Alpine</EM>'s composer. +The only time this feature will be used is if you attempt to send mail +which has no recipients but does have an Fcc. +Normally, <EM>Alpine</EM> will ask if you really mean to copy the message only to +the Fcc. +That is, it asks if you really meant to have no recipients. +If this feature is set, you +will <B>not</B> be prompted to confirm your intent to make only a copy +of a message with no recipients. +<P> +This feature is closely related to +<A HREF="#warn-if-blank-to-and-cc-and-newsgroups"><EM>warn-if-blank-to-and-cc-and-newsgroups</EM></A>. +The difference between this feature and that feature is that this feature +considers a Bcc to be a recipient while that feature will ask for confirmation +even if there is a Bcc when there is no To, Cc, or Newsgroup. +The default values also differ. This feature defaults to asking the question +and you have to turn it off. +The warn-if-blank-to-and-cc-and-newsgroups feature defaults to not asking +unless you turn it on. +<P> +This feature is displayed as "Send to Fcc Only Without Confirming". +<P> + +<DT> <A NAME="fcc-without-attachments"><EM>fcc-without-attachments</EM></A> + +<DD> This features controls the way FCC's (File Carbon Copies) are +made of the messages you send. + +<P> +Normally, <EM>Alpine</EM> saves an exact copy of your message as it was sent. +When this feature is enabled, the "body" of the message +you send (the text you type in the composer) is preserved in the +copy as before, however all attachments are replaced with text +explaining what had been sent rather than the attachments themselves. + +<P> +This feature also affects <EM>Alpine</EM>'s "Send ?" confirmation prompt +in that a new "^F Fcc Attchmnts" option becomes available which +allows you to interactively set whether or not attachments are saved +to the Fcc'd copy. +<P> +This feature is displayed as "Fcc Does Not Include Attachments". +<P> + +<DT> <A NAME="force-arrow-cursor"><EM>force-arrow-cursor</EM></A> + +<DD> This feature affects <EM>Alpine</EM>'s MESSAGE INDEX display routine. +If set, the normal inverse-video cursor will be +replaced by a simple "arrow" cursor, which normally occupies the +second column of the index display. +<P> +This is the same index cursor you get if you turn on +<A HREF="#assume-slow-link">Assume-Slow-Link</A>, but the index +line coloring will still be present if this feature is turned on and +Assume-Slow-Link is off. +<P> +An alternative version of the Arrow cursor is available by including the +ARROW +token in the +<A HREF="#index-format"><EM>Index-Format</EM></A> option. +<P> +It ought to be the case that this feature also affects the ATTACHMENT INDEX, +but that is not implemented. +<P> + +<DT> <A NAME="hide-nntp-path"><EM>hide-nntp-path</EM></A> + +<DD> Normally the Path header that <EM>Alpine</EM> generates when posting to a newsgroup +contains the name of the computer from which the message is being sent and +the user name. +Some believe that this information is used by spammers. +If this feature is set, that information will be replaced with the text +<P> +<CENTER><SAMP>not-for-mail</SAMP></CENTER> +<P> +instead. +<P> +It should be noted that many servers being connected to will still reveal +the information that this feature attempts to protect. +<P> +<DT> <A NAME="include-attachments-in-reply"><EM>include-attachments-in-reply</EM></A> + +<DD> If set, any MIME +attachments that were part of the original message will automatically be +included in a <EM>Reply</EM>. +<P> + +<DT> <A NAME="include-header-in-reply"><EM>include-header-in-reply</EM></A> + +<DD> If set, and a +message being replied to is included in the <EM>Reply</EM>, +then headers from that +message will also be part of the reply. +<P> + +<DT> <A NAME="include-text-in-reply"><EM>include-text-in-reply</EM></A> + +<DD> Normally, <EM>Alpine</EM> will ask whether you +wish to include the original message in your <EM>Reply</EM>. +If this feature is set and the feature +<A HREF="#enable-reply-indent-string-editing"><EM>enable-reply-indent-string-editing</EM></A> +is <EM>not</EM> set, then the original message will be included in the reply +automatically, without prompting. +<P> + +<DT> <A NAME="incoming-checking-includes-total"><EM>incoming-checking-includes-total</EM></A> + +<DD> This option has no effect unless the feature +<A HREF="#enable-incoming-folders-checking"><EM>enable-incoming-folders-checking</EM></A> +is set, which in turn has no effect unless +<A HREF="#inc-fold"><EM>incoming-folders</EM></A> +is set. +<P> +When incoming folder checking is turned on the default is to display +the number of unseen messages in each folder. +More precisely, it is the number of undeleted unseen messages. +Using this option you may also display the total number of messages +in each folder. +Instead of a single number representing the number of unseen messages +you will get two numbers separated by a slash character. +The first is the number of unseen messages and the second is the +total number of messages. +<P> +You may also use the recent message count instead of the unseen message +count by turning on the feature +<A HREF="#incoming-checking-uses-recent"><EM>incoming-checking-uses-recent</EM></A>. +<P> + +<DT> <A NAME="incoming-checking-uses-recent"><EM>incoming-checking-uses-recent</EM></A> + +<DD> This option has no effect unless the feature +<A HREF="#enable-incoming-folders-checking"><EM>enable-incoming-folders-checking</EM></A> +is set, which in turn has no effect unless +<A HREF="#inc-fold"><EM>incoming-folders</EM></A> +is set. +<P> +When incoming folder checking is turned on the default is to display +the number of unseen messages in each folder. +More precisely, it is the number of undeleted unseen messages. +Using this option you may display the number of recent messages instead +of the number of unseen messages. +A message is only counted as recent if this is the first session to +see it, so the recent count might be less than the unseen count. +The difference between the two would be accounted for by the unseen messages +in the folder which were there previously but have not been looked at yet. +<P> +If you simultaneously run more than one email client at a time +(for example, you run more than one <EM>Alpine</EM> in parallel) then turning +this feature on can cause some confusion. +The confusion stems from the fact that each message is only considered to be +recent in one session. +That means that the counts of new messages may be different in the two +<EM>Alpine</EM>s running side by side, because each incoming message will only be +counted as recent in one of the two sessions. +<P> +You may also display the total number of messages +in each folder by using the +<A HREF="#incoming-checking-includes-total"><EM>incoming-checking-includes-total</EM></A> +option. +<P> + +<DT> <A NAME="ldap-result-to-addrbook-add"><EM>ldap-result-to-addrbook-add</EM></A> + +<DD> This is only available if <EM>Alpine</EM> was linked with an LDAP library +when it was compiled. +If both the per-directory-server option +<A HREF="#use-implicitly-from-composer"><EM>use-implicitly-from-composer</EM></A> +and this feature are set, +then when an implicit directory lookup is done from the +composer you will automatically be prompted to add the result of the +directory lookup to your address book. +<P> +This feature is displayed as "LDAP Result to Addressbook Add". +<P> + +<DT> <A NAME="maildrops-preserve-state"><EM>maildrops-preserve-state</EM></A> + +<DD> +This feature affects the way +<A HREF="config-notes.html#maildrop">Mail Drops</A> work. +Normally, when mail is moved from a Mail Drop folder to a destination +folder, the state changes that have taken place since the mail was originally +delivered are lost. +Any Seen/New, Answered, Important/Flagged state that has changed will be +ignored. +All of the mail will be considered unSeen, unAnswered, and unImportant after +it is moved. +<P> +If this feature is set, then the state changes will not be lost. +<P> +In any case, messages which are already marked Deleted when the +mail is to be copied from the Mail Drop will be ignored. +<P> + +<DT> <A NAME="mark-fcc-seen"><EM>mark-fcc-seen</EM></A> + +<DD> This features controls the way FCCs (File Carbon Copies) are +made of the messages you send. +Normally, when <EM>Alpine</EM> saves a copy of a message you sent as an Fcc, that +copy will be marked as Unseen. +When you look at the folder it was saved in the message will appear to +be a New message until you read it. +When this feature is enabled, the message will be marked as having +been Seen. +<P> + +<DT> <A NAME="mark-for-cc"><EM>mark-for-cc</EM></A> + +<DD> This feature affects <EM>Alpine</EM>'s MESSAGE INDEX display. +By default, a '+' is displayed in the first column if the +message is addressed directly to you. +When this feature is set and the message is not addressed to you, then a +'-' character is displayed if the message is instead Cc'd directly +to you. +<P> + +<DT> <A NAME="mult-newsrc-hostnames-as-typed"><EM>mult-newsrc-hostnames-as-typed</EM></A> + +<DD> This feature will be of little use to most users. +It has no effect unless the feature +<A HREF="#enable-multiple-newsrcs">Enable-Multiple-Newsrcs</A> +is set. + +When the Enable-Multiple-Newsrcs feature is set +then the setting of this feature may have an effect on the names of the +newsrc files used. +Normally, the name of the news server will be canonicalized before it is +used in the newsrc file name. +For example, if you type the news server name + +<P> +<CENTER><SAMP>servername</SAMP></CENTER> +<P> + +it is likely that the canonical name will be something like + +<P> +<CENTER><SAMP>servername.example.com</SAMP></CENTER> +<P> + +Or it may be the case that + +<P> +<CENTER><SAMP>servername.example.com</SAMP></CENTER> +<P> + +is really an alias (a DNS CNAME) for + +<P> +<CENTER><SAMP>othername.example.com</SAMP></CENTER> +<P> + +If this feature is not set, then the canonicalized names will be used. +If this feature is set, then the name you typed in (or put in your +configuration) will be used. +<P> +This feature is displayed as "Multiple Newsrc Hostnames as Typed". +<P> + +<DT> <A NAME="news-approximates-new-status"><EM>news-approximates-new-status</EM></A> + +<DD> This feature causes certain messages to be marked as <EM>New</EM> in the +MESSAGE INDEX of newsgroups. +This feature is set by default. +<P> + +When opening a newsgroup, <EM>Alpine</EM> will consult +your <EM>newsrc</EM> file and +determine the last message you have previously disposed of via the <EM>D</EM> +key. If this feature is set, any subsequent messages will be shown in the +Index with an <EM>N</EM>, and the first of these messages will be highlighted. +Although this is only an approximation of true <EM>New</EM> or <EM>Unseen</EM> +status, it provides a useful cue to distinguish more-or-less recent +messages from those you have seen previously, but are not yet ready to +mark deleted. +<P> + +Background: your <EM>newsrc</EM> file (used to store message status information +for newsgroups) is only capable of storing a single flag, and <EM>Alpine</EM> uses +this to record whether or not you are "done with" a message, as +indicated by marking the message as <EM>Deleted</EM>. Unfortunately, this +means that <EM>Alpine</EM> has no way to record exactly which messages you have +previously seen, so it normally does not show the <EM>N</EM> status flag for +any messages in a newsgroup. This feature enables a starting +<I>approximation</I> of seen/unseen status that may be useful. +<P> + +<DT> <A NAME="news-deletes-across-groups"><EM>news-deletes-across-groups</EM></A> + +<DD> This feature controls what <EM>Alpine</EM> does when you delete a +message in a newsgroup that appears in more than one newsgroup. +Such a message is sometimes termed a "crossposting" +in that it was posted across several newsgroups. + +<P> +<EM>Alpine</EM>'s default behavior when you delete such a message is to remove +only the copy in the current newsgroup from view when you use the +"Exclude" command or the next time you visit the newsgroup. + +<P> +Enabling this feature causes <EM>Alpine</EM> to remove every occurrence of the +message from all newsgroups it appears in and to which you are +subscribed. + +<P> +NOTE: As currently implemented, enabling this feature may increase the +time it takes the Expunge command and newsgroup closing to complete. +<P> + +<DT> <A NAME="news-offers-catchup-on-close"><EM>news-offers-catchup-on-close</EM></A> + +<DD> This feature controls what <EM>Alpine</EM> does as it closes a newsgroup. +When set, <EM>Alpine</EM> will offer to delete all messages from the newsgroup +as you are quitting <EM>Alpine</EM> or opening a new folder. + +<P> +This feature is useful if you typically read all the interesting messages +in a newsgroup each time you open it. This feature saves you from +having to delete each message in a newsgroup as you read it or from +selecting all the messages and doing an +aggregate delete before you move on to the next folder or newsgroup. +<P> + +<DT> <A NAME="news-post-without-validation"><EM>news-post-without-validation</EM></A> + +<DD> This feature controls whether the NNTP server is queried as newsgroups +are entered for posting. Validation over slow links (e.g. dialup using +SLIP or PPP) can cause delays. Set this feature to eliminate such delays. +<P> + +<DT> <A NAME="news-read-in-newsrc-order"><EM>news-read-in-newsrc-order</EM></A> + +<DD> This feature controls the order that newsgroups will be presented. If +set, they will be presented in the same order as they occur in +your <EM>newsrc</EM> file. +If not set, the newsgroups +will be presented in alphabetical order. +<P> + +<DT> <A NAME="next-thread-without-confirm"><EM>next-thread-without-confirm</EM></A> + +<DD> This feature controls an aspect of <EM>Alpine</EM>'s Next and Prev commands in +the case where you are using one of the +"separate-index-screen" styles for the configuration option +<A HREF="#threading-index-style"><EM>threading-index-style</EM></A> +and currently have the folder sorted by a Threaded or OrderedSubject sort. +When you are Viewing a particular thread you have a +MESSAGE INDEX of only the messages in that thread. +If you press the Next command with the last message in the thread highlighted +you will normally be asked if you want to "View next thread?", +assuming there is a next thread to view. +If this feature is set it will be assumed that you always want to view the +next thread and you won't be asked to confirm that. +Similarly, if the first message of the thread is highlighted and you +press the Prev command, this feature will prevent the question +"View previous thread". +<P> +This feature only has an effect in the MESSAGE INDEX screen. +If you then view a particular message from that screen and press the +Next command, you will be sent to the next thread without being asked, +independent of the setting of this feature. +<P> +The feature +<A HREF="#auto-open-next-unread">auto-open-next-unread</A>, +also has some similar effects. +<P> +This feature is displayed as "Read Next Thread Without Confirming". +<P> + +<DT> <A NAME="offer-expunge-of-inbox"><EM>offer-expunge-of-inbox</EM></A> + +<DD> The INBOX is normally treated differently from regular folders in several +ways. +One of the differences is that the normal "close" sequence of +events is deferred until <EM>Alpine</EM> is exited, instead of happening when you +leave the INBOX to view another folder. +The "close" sequence normally includes the Expunging +of deleted messages +(either automatically or after a prompt, controlled by the features +<A HREF="#expunge-wo-confirm">Expunge-Without-Confirm</A>, +<A HREF="#expunge-without-confirm-everywhere">Expunge-Without-Confirm-Everywhere</A>, and +<A HREF="#expunge-only-manually">Expunge-Only-Manually</A>), and the +handling of the +<A HREF="#read-msg-fold">Read-Message-Folder</A>. + +<P> +If this feature is set the "close" sequence handling will take +place every time you leave the INBOX. +The INBOX will still be kept open, but the offer to Expunge and the archiving +to the Read-Message-Folder +will take place each time you leave the INBOX instead of only once at the +end of the session. +<P> + +<DT> <A NAME="offer-expunge-of-stayopen-folders"><EM>offer-expunge-of-stayopen-folders</EM></A> + +<DD> This feature is related to the option +<A HREF="#stay-open-folders">Stay-Open-Folders</A>. +Stay Open folders are treated differently from regular folders in several +ways. +One of the differences is that the normal "close" sequence of +events is deferred until <EM>Alpine</EM> is exited, instead of happening when you +leave the folder to view another folder. +The "close" sequence normally includes the Expunging +of deleted messages +(either automatically or after a prompt, controlled by the features +<A HREF="#expunge-wo-confirm">Expunge-Without-Confirm</A>, +<A HREF="#expunge-without-confirm-everywhere">Expunge-Without-Confirm-Everywhere</A>, and +<A HREF="#expunge-only-manually">Expunge-Only-Manually</A>), and the +handling of +<A HREF="#incoming-archive-folders">Incoming-Archive-Folders</A>. + +<P> +If this feature is set the "close" sequence handling will take +place when you leave the Stay Open folder. +The folder will still be kept open, but the offer to Expunge and the archiving +will take place each time you leave the folder instead of only once at the +end of the session. +This feature does not affect the INBOX, which will still only be processed +when you exit <EM>Alpine</EM>. +<P> + +<DT> <A NAME="pass-c1-control-characters-as-is"><EM>pass-c1-control-characters-as-is</EM></A> + +<DD> It is probably not useful to set this option. +This is a legacy option left behind "just in case". +Multi-byte characters which have an octet which has the same +value as a control character are permitted through whether or not +this option is turned on. +<P> +If the feature <A HREF="#pass-control-characters-as-is">pass-control-characters-as-is</A> +is set, then this feature has no effect. +However, if you wish to filter out regular control characters but pass the +so-called C1 control characters (0x80 <= char < 0xA0) through unchanged, then +you may leave <A HREF="#pass-control-characters-as-is">pass-control-characters-as-is</A> +unset and set this feature. +<P> + +<DT> <A NAME="pass-control-characters-as-is"><EM>pass-control-characters-as-is</EM></A> + +<DD> It is probably not useful to set this option. +This is a legacy option left behind "just in case". +Multi-byte characters which have an octet which has the same +value as a control character are permitted through whether or not +this option is turned on. +<P> +If set, all characters in a message will be sent to the +screen. Normally, control characters are automatically suppressed in +order to avoid inadvertently changing terminal setup parameters. +Control characters are usually displayed as two character sequences like +<P><CENTER><SAMP> ^C </SAMP></CENTER><P> +for Control-C, +<P><CENTER><SAMP> ^[ </SAMP></CENTER><P> +for ESCAPE, +<P><CENTER><SAMP> ^? </SAMP></CENTER><P> +for DELETE, and +<P><CENTER><SAMP> ~E </SAMP></CENTER><P> +for the character with value 133 (0x85). +(The DEL character is displayed as ^?, regular control characters are displayed +as the character ^ followed by the character obtained by adding the +five low-order bits of the character to 0x40, and the C1 +control characters 0x80 - 0x9F are displayed as the character ~ followed by the +character obtained by adding the +five low-order bits of the character to 0x40.) +Sometimes, in cases where changing a single control character into a +two-character sequence would confuse <EM>Alpine</EM>'s display routines, +a question mark is substituted for the control character. +<P> +If you wish to filter out regular control characters but pass the +so-called C1 control characters (0x80 <= char < 0xA0) through unchanged, then +you may leave this feature unset and set the feature <A HREF="#pass-c1-control-characters-as-is">pass-c1-control-characters-as-is</A> instead. +<P> + +<DT> <A NAME="predict-nntp-server"><EM>predict-nntp-server</EM></A> + +<DD> This feature allows <EM>Alpine</EM> to assume that the open NNTP server at the +time of composition is the NNTP server to which the message should be +posted. This is especially recommended when there are multiple News +collections. If this feature is not set, <EM>Alpine</EM> will try to post to the first server in +the <a href="#nntp-server">nntp-server</a> variable. Setting +this feature also negates the need to add News collection servers to +the nntp-server variable. +<P> +This feature can be especially handy when used in conjunction with +<a href="#enable-multiple-newsrcs">enable-multiple-newsrcs</a>. +<P> +This option is displayed as "NNTP Server (for news)". +<P> + +<DT> <A NAME="prefer-plain-text"><EM>prefer-plain-text</EM></A> + +<DD> A message being viewed may contain alternate versions of the same content. +Those alternate versions are ordered by the sending software such that the +first alternative is the least preferred and the last alternative is the +most preferred. <EM>Alpine</EM> will normally display the most-preferred version that +it knows how to display. This is most often encountered where the two +alternate versions are a plain text version and an HTML version, with the +HTML version listed last as the most preferred. +<P> + +If this option is set, then any plain text version will be preferred to +all other versions. +<P> + +<DT> <A NAME="preopen-stayopen-folders"><EM>preopen-stayopen-folders</EM></A> + +<DD> This feature is related to the option +<A HREF="#stay-open-folders">Stay-Open-Folders</A>. +Normally, Stay Open folders are only opened on demand, when the user +asks to open them. +From then on they are kept open for the duration of the session. +However, if this feature is set, then the Stay Open folders will all be +opened at startup, at the same time that the INBOX is opened. +<P> + +<DT> <A NAME="preserve-start-stop-characters"><EM>preserve-start-stop-characters</EM></A> + +<DD> This feature controls how special control key characters, typically +<EM>^S</EM> and <EM>^Q</EM>, are interpreted when input to <EM>Alpine</EM>. +These characters +are known as the "start" and "stop" characters and are sometimes used in +communications paths to control data flow between devices that operate at +different speeds. +<P> + +By default, <EM>Alpine</EM> turns the system's handling of these special characters +off except during printing. However, if you see <EM>Alpine</EM> reporting input errors +such as: + +<BLOCKQUOTE> + [ Command "^Q" not defined for this screen. ] <BR> +</BLOCKQUOTE> + +and, at the same time, see your display become garbled, then it is likely +that setting this option will solve the problem. Be aware, though, that +enabling this feature will also cause <EM>Alpine</EM> to ostensibly "hang" +whenever the <EM>Ctrl-S</EM> key combination is entered as the system is now +interpreting such input as a "stop output" command. To "start +output" again, simply type <EM>Ctrl-Q</EM>. +<P> +This feature is displayed as "Preserve Start/Stop Characters". +<P> + +<DT> <A NAME="print-formfeed-between-messages"><EM>print-formfeed-between-messages</EM></A> + +<DD> Setting this feature causes a formfeed to be printed between messages when +printing multiple messages with the <EM>Apply Print</EM> command. +<P> + +<DT> <A NAME="print-includes-from-line"><EM>print-includes-from-line</EM></A> + +<DD> If this feature is set, then the Unix mail style From line is included +at the start of each message that is printed. This line looks something +like the following, with the address replaced by the address from the +From line of the message being printed: + +<BLOCKQUOTE> + From user@domain.somewhere.com Mon May 13 14:11:06 1996 <BR> +</BLOCKQUOTE> +<P> + +<DT> <A NAME="print-index-enabled"><EM>print-index-enabled</EM></A> + +<DD> This feature controls the behavior of the <EM>Print</EM> command +when in the +"Folder Index" screen. +If set, the <EM>Print</EM> command will give you a prompt +asking if you wish to print the message index, or the currently highlighted +message. If not set, the message will be printed. +<P> + +<DT> <A NAME="print-offers-custom-cmd-prompt"><EM>print-offers-custom-cmd-prompt</EM></A> + +<DD> When this feature is set, the <EM>Print</EM> command +will have an additional +subcommand called <EM>C CustomPrint</EM>. +If selected, you will have +the opportunity to enter any system print command, instead of being +restricted to using those that have been previously configured in the +<EM>Setup/Printer</EM> screen. +<P> +This feature is displayed as "Print Offers Custom Command Prompt". +<P> + +<DT> <A NAME="prune-uses-yyyy-mm"><EM>prune-uses-yyyy-mm</EM></A> + +<DD> By default, <EM>Alpine</EM> asks monthly whether or not you would like to rename +some folders to a new name containing the date. +It also asks whether or not you would like to delete some old folders. +See the <A HREF="#pruning-rule">pruning-rule</A> option for an +explanation. + +<P> +By default, the name used when renaming a folder looks like +<P> +<CENTER><SAMP><foldername>-<month>-<year></SAMP></CENTER> +<P> +For example, the first time you run <EM>Alpine</EM> in May of 2004, +the folder "sent-mail" might be renamed to +<P> +<CENTER><SAMP>sent-mail-apr-2004</SAMP></CENTER> +<P> +If this feature is set, the name used will be of the form +<P> +<CENTER><SAMP><foldername>-<yyyy>-<mm></SAMP></CENTER> +<P> +where "yyyy" is the year and "mm" is the two-digit +month (01, 02, ..., 12). +For the April, 2004 example above, it would instead be +<P> +<CENTER><SAMP>sent-mail-2004-04</SAMP></CENTER> +<P> +because April is the 4th month of the year. +A reason you might want to set this feature is so that the folders +will sort in chronological order. +<P> + +<DT> <A NAME="publiccerts-in-keychain"><EM>publiccerts-in-keychain</EM></A> + +<DD> Mac OS X <EM>Alpine</EM> only. +<P> +If this feature is set the Mac OS X default keychain will be used as the place +to store public certificates instead of a +<A HREF="#smime-public-cert-directory"><EM>smime-public-cert-directory</EM></A> +or a +<A HREF="#smime-public-cert-container"><EM>smime-public-cert-container</EM></A>. +<P> +This feature is displayed as "S/MIME -- Public Certs in MacOS Keychain". +<P> + +<DT> <A NAME="quell-attachment-extension-warn"><EM>quell-attachment-extension-warn</EM></A> +<DD> This feature suppresses the extra warning you can get when trying +to view an attachment for which there is no mime-type match. Turning +on this feature will just run the program according to extension +instead of first warning the user that it will run according to the +file's extension. +<P> +This feature can be used along side +<A HREF="#quell-attachment-extra-prompt"><EM>quell-attachment-extra-prompt</EM></A> +to preserve the behavior exhibited in <EM>Pine</EM> versions prior to <EM>Pine</EM> 4.50. +<P> +This feature is displayed as "Suppress Attachment Extension Warning". +<P> + +<DT> <A NAME="quell-attachment-extra-prompt"><EM>quell-attachment-extra-prompt</EM></A> +<DD> By default, when you attempt to view an attachment externally +from the "Attachment View" screen, you are asked if you +really want to view the selected attachment. +<P> +If this feature is set, you will <B>not</B> be prompted to confirm +your selection. Prior to <EM>Pine</EM> 4.50, the default behavior was to not +prompt. This feature was added for those wanting to preserve that +behavior. +<P> +This feature is displayed as "Suppress Attachment Extra Prompt". +<P> + +<DT> <A NAME="quell-berkeley-format-timezone"><EM>quell-berkeley-format-timezone</EM></A> + +<DD> POSIX mandates a timezone in UNIX mailbox format folder delimiters +(the line which begins with From <SPACE>). +Some versions of Berkeley mail have trouble with this, and don't recognize +the line as a message delimiter. +If this feature is set, the timezone will be left off the delimiter line. +<P> +This feature is displayed as "Suppress Berkeley Format Timezone". +<P> + +<DT> <A NAME="quell-charset-warning"><EM>quell-charset-warning</EM></A> + +<DD> By default, if the message you are viewing contains characters that are +not representable in your +<A HREF="#disp-char-set"><EM>display-character-set</EM></A> +then <EM>Alpine</EM> will +add a warning to the start of the displayed text. +If this option is set, then that editorial message will be suppressed. +<P> +Setting this feature also suppresses the comment about the character set +in header lines. +For example, when viewing a message you might see +<P> +<CENTER><SAMP>From: "[ISO-8859-2] Name" <address></SAMP></CENTER> +<P> +in the From header if your Character-Set is something other than ISO-8859-2. +If you set this feature, the comment about the character set will +no longer be there. +<P> +This feature is displayed as "Suppress Character Set Warning". +<P> + +<DT> <A NAME="quell-content-id"><EM>quell-content-id</EM></A> + +<DD> This feature changes the behavior of <EM>Alpine</EM> when sending messages. +It is intended to work around a bug in Microsoft's Outlook XP mail user +agent. +As of this writing, Microsoft has acknowledged the bug but +has not added it to the Knowledge Base. +We have been told that there will be a post-SP1 hotfix for Outlook XP. +This particular bug has bug fix number OfficeQFE:4781. +The nature of the bug is that messages with attachments which +contain a Content-ID header (which standard <EM>Alpine</EM> attachments do) +do not show the attachment indicator (a paperclip) when viewed with +Outlook XP. +So the user has no indication that the message contains an attachment. + +<P> +If this feature is set then <EM>Alpine</EM> will remove most Content-ID headers +before sending a message. +If an attachment is of type MESSAGE, then the existing Content-ID headers +inside the message will be left intact. +This would only happen with <EM>Alpine</EM> if a message was forwarded as an attachment +or if a message with a message attached was forwarded. +Similarly if an attachment of type MULTIPART/ALTERNATIVE is forwarded, +the Content-ID headers of the alternative parts will not be removed. + +<P> +Because the Content-ID header is a standard part of MIME it is possible +that setting this feature will break something. +For example, if an attachment has a Content-ID header which is necessary +for the correct functioning of that attachment, it is possible that <EM>Alpine</EM> +may remove that header when the attachment is forwarded. +However, it seems fairly safe at this time. +<P> +This feature is displayed as "Suppress Content-ID". +<P> + +<DT> <A NAME="quell-dead-letter-on-cancel"><EM>quell-dead-letter-on-cancel</EM></A> + +<DD> This feature affects <EM>Alpine</EM>'s behavior when you cancel a message being +composed. <EM>Alpine</EM>'s usual behavior is to write the canceled message to +a file named <CODE>dead.letter</CODE> in your home directory (under UNIX; +<CODE>DEADLETR</CODE> under WINDOWS/DOS) overwriting any previous message. +Under some conditions (some routine), this can introduce a noticeable delay. +<P> + +Setting this feature will cause <EM>Alpine</EM> NOT to write canceled compositions +into the file called <CODE>dead.letter</CODE>. +<P> +This feature affects the newer option +<A HREF="#dead-letter-files"><EM>Dead-Letter-Files</EM></A>, which specifies the +number of dead letter files to keep around. +If this feature is set, then the Dead-Letter-Files option has no effect. +<P> +This feature is displayed as "Do Not Save to Deadletter on Cancel". +<P> + +<DT> <A NAME="quell-empty-directories"><EM>quell-empty-directories</EM></A> + +<DD> This feature causes <EM>Alpine</EM> to remove from the display any directories +that do not contain at least one file or directory. This can be useful +to prevent overly cluttered folder lists when a collection is stored on +a server that treats all names as both a folder and a directory. + +<P> +Note, enabling this feature can cause surprising behavior! For example, +you can still use Add to create a directory, but unless you immediately +enter that directory and create a folder, that newly created directory +may not be displayed next time you enter the folder list. + +<P> +This feature is displayed as "Hide Empty Directories". +<P> + +<DT> <A NAME="quell-extra-post-prompt"><EM>quell-extra-post-prompt</EM></A> + +<DD> This feature causes <EM>Alpine</EM> to skip the extra question about +posting a message which may go to thousands of readers when you +are about to post to a newsgroup. + +<P> +This feature is displayed as "Suppress Extra Posting Prompt". +<P> + +<DT> <A NAME="quell-filtering-done-message"><EM>quell-filtering-done-message</EM></A> + +<DD> This feature causes <EM>Alpine</EM> to suppress the "filtering done" message. + +<P> +This feature is displayed as "Suppress Filtering Done Message". +<P> + +<DT> <A NAME="quell-filtering-messages"><EM>quell-filtering-messages</EM></A> + +<DD> This feature causes <EM>Alpine</EM> to suppress the messages about +moving filtered messages and setting flags in messages, due to Filter Rules. + +<P> +This feature is displayed as "Suppress Filtering Messages". +<P> + +<DT> <A NAME="quell-flowed-text"><EM>quell-flowed-text</EM></A> + +<DD> <EM>Alpine</EM> generates flowed text where possible. +The method for generating flowed text is defined by +<A HREF="http://www.ietf.org/rfc/rfc3676.txt">RFC 3676</A>, +the benefit of doing so is +to send message text that can properly be viewed both on normal width displays +and on displays with smaller or larger than normal screen widths. +With flowed text, a space at the end of a line tells the receiving mail +client that the following line belongs to the same paragraph. +Quoted text will also be affected, with only the innermost +level of ">" quoting being followed by a space. +However, if you have changed the +<A HREF="#reply-ind-str">"Reply-Indent-String"</A> +so that it is not equal to the default value of "> ", then +quoted text will not be flowed. +For this reason, we recommend that you leave your +"Reply-Indent-String" set to the default. +<P> +This feature turns off the generation of flowed text, as it might be +desired to more tightly control how a message is displayed on the receiving end. +<P> +If this feature is <EM>not</EM> set, you can control on a message by message +basis whether or not flowed text is generated. +You do this by typing ^V at the Send confirmation prompt that you get +after typing ^X to send a message. +^V is a toggle which turns flowing off and back on if typed again. +If for some reason flowing cannot be done on a particular message, then the +^V command will not be available. +This would be the case, for example, if this feature was set, or if your +"Reply-Indent-String" was set to a non-default value. +If the feature +<A HREF="#send-without-confirm">Send-Without-Confirm</A> is set, +then the opportunity to control on a message by message basis +whether or not flowed text is generated is lost. +<P> +When this feature is not set and you have typed ^V to turn off flowing, +the Send confirmation prompt will change to look like +<P> +<CENTER><SAMP>Send message (not flowed)?</SAMP></CENTER> +<P> +<A HREF="#strip-whitespace-before-send">Strip-Whitespace-Before-Send</A> will +also turn off the sending of flowed text messages, but it differs in that +it also trims all trailing white space from a message before sending it. +<P> +If alternate editors are used extensively, be aware that a message will still +be sent flowed if this feature is unset. In most cases this will be fine, +but if the editor has a "flowed text" mode, it would be best to +use that. +<P> +This feature is displayed as "Do Not Send Flowed Text". +<P> + +<DT> <A NAME="quell-folder-internal-msg"><EM>quell-folder-internal-msg</EM></A> + +<DD> This feature determines whether or not <EM>Alpine</EM> will create +"pseudo messages" in folders that are in standard Unix or +MMDF format. +<P> + +<EM>Alpine</EM> will normally create these +pseudo messages when they are not already +present in a standard Unix or MMDF folder. +Their purpose is to record +certain mailbox state data needed for correct IMAP and POP server operation, +and also for <EM>Alpine</EM> to be able to mark messages as Answered when +the Reply has been postponed. +<P> + +Sites which do not use IMAP/POP for remote mail access, and which need to +support mail tools that are adversely affected by the presence of the +pseudo-messages (e.g. some mail notification tools) may enable this +feature to tell <EM>Alpine</EM> not to create them. +Note that <EM>Alpine</EM>'s "Answered" flag +capability will be adversely affected if this is done. +<P> + +Note too that, even if this feature is enabled, <EM>Alpine</EM> will not remove +pseudo-messages when it encounters them (e.g. those created by UW's imapd +or ipopd servers.) +This feature has no effect on folders that are not in +standard Unix or MMDF format, as pseudo-messages are not needed in the +other formats to record mailbox state information. +<P> +This feature is displayed as "Prevent Folder Internal Message". +<P> + +<DT> <A NAME="quell-full-header-auto-reset"><EM>quell-full-header-auto-reset</EM></A> + +<DD> The HdrMode Command +normally resets to the default state when switching to a new message. +For example, if you've used the "H" command to turn on Full +Headers for a message you are viewing, and then you type the Next command +to look at the next message, the full headers will no longer be shown. +Setting this feature disables that reset. +Instead, the Header Mode remains the same from message to message. + +<P> +The presence or absence of the HdrMode command is determined by the +<A HREF="#enable-full-header-cmd">"Enable-Full-Header-Cmd"</A> +Feature-List option. +<P> +This feature is displayed as "Suppress Full Header Auto Reset". +<P> + +<DT> <A NAME="quell-imap-envelope-update"><EM>quell-imap-envelope-update</EM></A> + +<DD> In the MESSAGE INDEX screen, if the open folder is being accessed +using IMAP, <EM>Alpine</EM> normally tries to paint the index lines on the screen +as soon as the information arrives from the IMAP server. +This means that the index information makes it onto the screen more quickly +than it otherwise would. +This sometimes results in behavior that bothers some users. +For example, when paging to a new page of the index, it may be possible for +the lines to be painted on the screen in a random order, rather than from +top to bottom. +<P> + +Setting this feature causes <EM>Alpine</EM> to wait for all of the information +to be gathered before it paints the index screen. +Once it collects all of the information, the screen will be painted quickly +from top to bottom. +<P> +This feature is displayed as "Suppress IMAP Envelope Update". +<P> + +<DT> <A NAME="quell-lock-failure-warnings"><EM>quell-lock-failure-warnings</EM></A> + +<DD> This feature affects <EM>Alpine</EM>'s behavior when it encounters a problem +acquiring a mail folder lock. Typically, a secondary file associated +with the mail folder being opened is created as part of the locking +process. On some systems, such file creation has been administratively +precluded by the system configuration. +<P> + +<EM>Alpine</EM> issues a warning when such failures occur, which can become bothersome +if the system is configured to disallow such actions. Setting this +feature causes <EM>Alpine</EM> to remain silent when this part of lock creation fails. +<P> + +WARNING: systems that have been configured in a way that precludes locking +introduce some risk of mail folder corruption when more than one program +attempts to modify the mail folder. This is most likely to occur to one's +<EM>INBOX</EM> or other "Incoming Message Folder". +<P> +This feature is displayed as "Suppress Lock Failure Warnings". +<P> + +<DT> <A NAME="quell-mailchecks-composing-except"><EM>Quell-Mailchecks-Composing-Except-Inbox</EM></A> + +<DD> This option is closely related to the +<A HREF="#mail-check"><EM>Mail-Check-Interval</EM></A> +option, the +<A HREF="#mail-check-noncurr"><EM>Mail-Check-Interval-Noncurrent</EM></A> option, and +<A HREF="#quell-mailchecks-composing-inbox"><EM>Quell-Mailchecks-Composing-Inbox</EM></A>. +<P> +If this option is set, then the normal new-mail checking which happens +while you are composing will not happen for folders other than your +INBOX (which depends on the setting +of "Quell-Mailchecks-Composing-Inbox"). +<P> +You might want to set this option if you are experiencing delays while +composing which you think might be related to the speed of the new-mail +checks. +<P> +Even with this option turned on, an occasional new-mail check may be done +in order to keep the server from killing the connection to the folder. +For example, IMAP servers may remove a connection to a folder if there +has been no activity on the connection for 30 minutes or more. +Instead of letting that happen, <EM>Alpine</EM> will check for new mail before the +30 minutes is up even though you have turned on this feature to quell +those checks. +<P> +Besides new-mail checks, checkpoint operations on the folders +will also be quelled when you set this option. +The purpose of checkpointing is to write the changes to a folder out to +disk periodically in order to avoid losing those changes when system or +software problems occur. +New-mail checking and checkpointing while you are not composing are not +affected by this option. +<P> +This feature is displayed as "Prevent Mailchecks While Composing Except for INBOX". +<P> + +<DT> <A NAME="quell-mailchecks-composing-inbox"><EM>Quell-Mailchecks-Composing-Inbox</EM></A> + +<DD> This option is closely related to the +<A HREF="#mail-check"><EM>Mail-Check-Interval</EM></A> +option, the +<A HREF="#mail-check-noncurr"><EM>Mail-Check-Interval-Noncurrent</EM></A> option, and +<A HREF="#quell-mailchecks-composing-except"><EM>Quell-Mailchecks-Composing-Except-Inbox</EM></A>. +<P> +If this option is set, then the normal new-mail checking which happens +while you are composing will not happen for your INBOX. +Checking of other folders is controlled in a similar way with the +"Quell-Mailchecks-Composing-Except-Inbox" option. +<P> +You might want to set this option if you are experiencing delays while +composing which you think might be related to the speed of the new-mail +checks. +<P> +Even with this option turned on, an occasional new-mail check may be done +in order to keep the server from killing the connection to the folder. +For example, IMAP servers may remove a connection to a folder if there +has been no activity on the connection for 30 minutes or more. +Instead of letting that happen, <EM>Alpine</EM> will check for new mail before the +30 minutes is up even though you have turned on this feature to quell +those checks. +<P> +Besides new-mail checks, checkpoint operations on the INBOX +will also be quelled when you set this option. +The purpose of checkpointing is to write the changes to a folder out to +disk periodically in order to avoid losing those changes when system or +software problems occur. +New-mail checking and checkpointing while you are not composing are not +affected by this option. +<P> +This feature is displayed as "Prevent Mailchecks While Composing for INBOX". +<P> + +<DT> <A NAME="quell-maildomain-warning"><EM>quell-maildomain-warning</EM></A> + +<DD> When your configuration is set up so that your domain name contains no dots, +it is usually a configuration error. +By default, <EM>Alpine</EM> will warn you about this when you start it up. +You will see a warning message that looks like +<P> +<CENTER><SAMP>Incomplete maildomain "<domain>".</SAMP></CENTER> + +<P> +If this feature is set, the warning is turned off. +This feature is displayed as "Suppress Maildomain Warning". +<P> + +<DT> <A NAME="quell-news-envelope-update"><EM>quell-news-envelope-update</EM></A> + +<DD> In the MESSAGE INDEX screen, if the open folder is being accessed +using NNTP (News), <EM>Alpine</EM> normally tries to paint the index lines on the screen +as soon as the information arrives from the NNTP server. +This means that the index information makes it onto the screen more quickly +than it otherwise would. +This sometimes results in behavior that bothers some users. +For example, when paging to a new page of the index, it may be possible for +the lines to be painted on the screen in a random order, rather than from +top to bottom. +<P> + +Setting this feature causes <EM>Alpine</EM> to wait for all of the information +to be gathered before it paints the index screen. +Once it collects all of the information, the screen will be painted quickly +from top to bottom. +<P> +This feature is displayed as "Suppress News Envelope Update". +<P> + +<DT> <A NAME="quell-partial-fetching"><EM>quell-partial-fetching</EM></A> + +<DD> Partial fetching is a feature of the IMAP protocol. +By default, <EM>Alpine</EM> +will use partial fetching when copying the contents of a message or attachment +from the IMAP server to <EM>Alpine</EM>. +This means that the fetch will be done in many +small chunks instead of one big chunk. The main benefit of this approach is +that the fetch becomes interruptible. That is, the user can type <EM>^C</EM> +to stop the fetch early. In some cases partial fetching may cause a performance +problem so that the fetching of data takes significantly longer when partial +fetching is used. Turning on this feature will turn off partial fetching. +<P> +This feature is displayed as "Prevent Partial Fetching". +<P> + +<DT> <A NAME="quell-personal-name-prompt"><EM>quell-personal-name-prompt</EM></A> + +<DD> <EM>PC-Alpine</EM> only. This feature quells the prompting for a +<A HREF="#personal-name">personal-name</A>. This prompt normally happens +before composing a message, and only happens when there is no personal name +already set. +<P> + +<DT> <A NAME="quell-server-after-link-in-html"><EM>quell-server-after-link-in-html</EM></A> + +<DD> By default, links in HTML text are displayed with the host the link +references appended, within square brackets, to the link text. <EM>Alpine</EM> +does this to help indicate where a link will take you, particularly when +the link text might suggest a different destination. + +<P> +Setting this feature will prevent the server name from being appended +to the displayed text. +<P> +This feature is displayed as "Suppress Server After Link in HTML". +<P> + +<DT> <A NAME="quell-ssl-largeblocks"><EM>quell-ssl-largeblocks</EM></A> + +<DD> This feature (<EM>PC-Alpine</EM> only) changes the behavior of fetching messages +and attachments so that the message data is fetched in chunks no larger +than 12K bytes. +This works around a bug in Microsoft's SSL/TLS support. +Some versions of Microsoft SSL are not able to read full-sized (16K) +SSL/TLS packets. +Some servers will send such packets and this will +cause <EM>PC-Alpine</EM> to crash with the error + +<P> +<CENTER><SAMP>incomplete SecBuffer exceeds maximum buffer size</SAMP></CENTER> + +<P> +Microsoft is aware of the problem and has developed a hotfix for it, but as of +this writing the hotfix has not yet been added to the Knowledge Base. +<P> +This feature is displayed as "Prevent SSL Largeblocks". +<P> + +<DT> <A NAME="quell-status-message-beeping"><EM>quell-status-message-beeping</EM></A> + +<DD> If set status messages will never emit a beep. +<P> +This feature is displayed as "Suppress Status Message Beeping". +<P> + +<DT> <A NAME="quell-timezone-comment-when-sending"><EM>quell-timezone-comment-when-sending</EM></A> + +<DD> Normally, when <EM>Alpine</EM> generates a Date header for outgoing mail, +it will try to include the symbolic timezone at the end of the +header inside parentheses. +The symbolic timezone is often three characters long, but on +some operating systems, it may be longer. +Apparently there are some SMTP servers in the world which will reject an +incoming message if it has a Date header longer than about 80 characters. +If this feature is set, the symbolic timezone normally generated by +<EM>Alpine</EM> will not be included. +You probably don't need to worry about this feature unless you run into +the problem described above. +<P> +This feature is displayed as "Suppress Timezone Comment When Sending". +<P> + +<DT> <A NAME="quell-user-id-prompt"><EM>quell-user-id-prompt</EM></A> + +<DD> <EM>PC-Alpine</EM> only. This feature quells the prompting for a +<A HREF="#user-id">user-id</A> +if the information can be obtained from the login name used +to open the INBOX. Normally, this prompt happens before composing +a message, and only happens when there is no user-id already set +in the configuration. +<P> +With this feature set, composing a message is only possible after +establishing a connection to the INBOX. +<P> + +<DT> <A NAME="quell-user-lookup-in-passwd-file"><EM>quell-user-lookup-in-passwd-file</EM></A> + +<DD> This feature controls an aspect of +<EM>Alpine</EM>'s Composer, and if needed, will usually be set by the +system manager in <EM>Alpine</EM>'s system-wide configuration file. +Specifically, if this feature is set, <EM>Alpine</EM> will not attempt to look +in the system password file to find a Full Name for the entered address. +<P> + +Normally, names you enter into address fields (e.g. To: or Cc:) are +checked against your address book(s) to see if they match an address book +nickname. +Failing that, (in Unix <EM>Alpine</EM>) the name is then checked against +the Unix password file. If the entered name matches a username in the +system password file, <EM>Alpine</EM> extracts the corresponding Full Name information +for that individual, and adds that to the address being entered. +<P> + +However, password file matching can have surprising (incorrect) results if +other users of the system do not receive mail at the domain you are using. +That is, if either the <A HREF="#user-domain"><EM>user-domain</EM></A> +or <A HREF="#use-only"><EM>use-only-domain-name</EM></A> option +is set such that the administrative domain of other users on the system +isn't accurately reflected, <EM>Alpine</EM> should be told that a password +file match is coincidental, +and Full Name info will be incorrect. +For example, a +personal name from the password file could get falsely paired with the +entered name as it is turned into an address in the configured domain. +<P> + +If you are seeing this behavior, enabling this feature will prevent Unix +<EM>Alpine</EM> from looking up names in the password file to find the Full Name +for incomplete addresses you enter. +<P> +This feature is displayed as "Prevent User Lookup in Password File". +<P> + +<DT> <A NAME="quit-without-confirm"><EM>quit-without-confirm</EM></A> + +<DD> This feature controls whether or not <EM>Alpine</EM> will ask for confirmation when a +<EM>Quit</EM> command is received. +<P> +This feature is displayed as "Quit Without Confirming". +<P> + +<DT> <A NAME="quote-replace-nonflowed"><EM>quote-replace-nonflowed</EM></A> + +<DD> This feature, which is only active when +<A HREF="#quote-replace-string">Quote-Replace-String</A> is +also set, +enables quote-replacement on non-flowed messages. It is off +by default because a non-flowed message is more dependent on its format, +and thus quote-replacement may cause less-than-pleasing results. +Setting this feature will cause quote-replacement similar to that of flowed +messages, but with the added possibility of long lines being wrapped +into new lines if the Quote-Replacement-String is longer than the string +it is replacing, which is "> ". + +<P> + +<DT> <A NAME="reply-always-uses-reply-to"><EM>reply-always-uses-reply-to</EM></A> + +<DD> If set, <EM>Alpine</EM> +will not prompt when a message being replied to contains a <EM>Reply-To:</EM> +header value, but will simply use its value (as opposed to using the +<EM>From:</EM> field's value). +<P> + +<DT> <A NAME="return-to-inbox-without-confirm"><EM>return-to-inbox-without-confirm</EM></A> + +<DD> +Normally, when you use the TAB +command and there are no more folders or newsgroups to visit, you are asked +if you want to return to the INBOX. +If this feature is set you will not be asked. +It will be assumed that you do want to return to the INBOX. +<P> +This feature is displayed as "Return to INBOX Without Confirming". +<P> + +<DT> <A NAME="save-aggregates-copy-sequence"><EM>save-aggregates-copy-sequence</EM></A> + +<DD> This feature will optimize an aggregate copy operation, if +possible, by issuing a single IMAP <EM>COPY</EM> command with a +list of the messages to be copied. +This feature is set by default. +This may reduce network traffic and elapsed time for the Save. +<EM>However, many IMAP servers (including the UW IMAP server) do +not preserve the order of messages when this optimization is applied.</EM> +If this feature is not set, +<EM>Alpine</EM> will copy each message individually and the order of the +messages will be preserved. +<P> +This feature is displayed as "Save Combines Copies (may be out of order)". +<P> + +<DT> <A NAME="save-partial-wo-confirm"><EM>save-partial-msg-without-confirm</EM></A> + +<DD> This feature controls an aspect of <EM>Alpine</EM>'s Save command. +By default, when you Save a message that has some deleted parts, you will +be asked to confirm that you want to Save with a prompt that looks like: +<P> +<CENTER><SAMP>Saved copy will NOT include entire message! Continue?</SAMP></CENTER> +<P> +If this feature is set, you will not be asked. +<P> +This feature is displayed as "Save Partial Message Without Confirming". +<P> + +<DT> <A NAME="save-will-advance"><EM>save-will-advance</EM></A> + +<DD> If set, <EM>Save</EM> will +(in addition to copying the current message to the designated folder) also +advance to the next message. +<P> + +<DT> <A NAME="save-will-not-delete"><EM>save-will-not-delete</EM></A> + +<DD> If set, <EM>Save</EM> will +not mark the message Deleted (its default behavior) after it has been +copied to the designated folder. +<P> + +<DT> <A NAME="save-will-quote"><EM>save-will-quote-leading-froms</EM></A> + +<DD> This feature controls an aspect of the <EM>Save</EM> command +(and also the way +outgoing messages are saved to an FCC folder). If set, <EM>Alpine</EM> will add +a leading <CODE>></CODE> character in front of message +lines beginning with "From" when they are +saved to another folder, including lines syntactically +distinguishable from the type of message separator line commonly used on +Unix systems. +<P> + +The default behavior is that a <CODE>></CODE> will be prepended only to lines +beginning with "From " that might otherwise be confused with a message +separator line on Unix systems. If <EM>Alpine</EM> is the only mail program you use, +this default is reasonable. If another program you use has trouble +displaying a message with an unquoted From saved by <EM>Alpine</EM>, you should +enable this feature. This feature only applies to the common Unix mailbox +format that uses message separator lines beginning with "From ". If +<EM>Alpine</EM> has been configured to use a different mailbox format (possibly +incompatible with other mail programs), then this issue does not arise, +and the feature is irrelevant. +<P> + +<DT> <A NAME="scramble-message-id"><EM>scramble-message-id</EM></A> + +<DD> Normally the Message-ID header that <EM>Alpine</EM> generates when sending a message +contains the name of the computer from which the message is being sent. +Some believe that this hostname could be used by spammers or could +be used by others for nefarious purposes. +If this feature is set, that name will be transformed with a simple +Rot13 transformation. +The result will still have the correct syntax for a Message-ID but the +part of the MessageID that is often a domain name will not be an actual +domain name because the letters will be scrambled. +<P> +It is possible (but unlikely?) that some spam detection +software will use that as a reason to reject the mail as spam. +It has also been reported that some spam detection software uses the +fact that there are no dots after the "@" as a reason to reject +messages. +If your <EM>PC-Alpine</EM> Message-ID is using a name without a dot that is because +that is what Windows thinks is your "Full computer name". +The method used to set this varies from one type of Windows to another but +check under Settings -> Control Panel -> System and +look for Network Identification or Computer Name or something similar. +How to set it is beyond the scope of <EM>Alpine</EM>. +<P> +This feature is displayed as "Scramble the Message-ID When Sending". +<P> + +<DT> <A NAME="select-without-confirm"><EM>select-without-confirm</EM></A> + +<DD> This feature controls an aspect of +<EM>Alpine</EM>'s <EM>Save</EM>, <EM>Export</EM>, and <EM>Goto</EM> commands. +These commands all take text input to specify the name of the folder or +file to be used, but allow you to press <EM>^T</EM> for a +list of possible names. +If set, the selected name will be used immediately, without further +opportunity to confirm or edit the name. +<P> +This feature is displayed as "Select Ctrl-T Foldername Without Confirming". +<P> + +<DT> <A NAME="send-without-confirm"><EM>send-without-confirm</EM></A> + +<DD> By default, when you send or post a message you will be asked to confirm +with a question that looks something like: + +<P> +<CENTER><SAMP>Send message?</SAMP></CENTER> +<P> + +If this feature is set, you +will <B>not</B> be prompted to confirm your intent to send +and your message will be sent. +<P> +If this feature is set it disables some possibilities and renders some +other features meaningless. +You will not be able to use +<A HREF="#sending-filters">Sending Filters</A>, +Verbose sending mode, +<A HREF="#enable-background-sending">Background Sending</A>, +<A HREF="#enable-delivery-status-notification">Delivery Status Notifications</A>, +or ^V to turn off the generation of flowed text for this message. +These options are normally available as suboptions in the Send prompt, but +with no Send prompt the options are gone. + +<P> +A somewhat related feature is +<A HREF="#quell-extra-post-prompt">quell-extra-post-prompt</A>. +which may be used to eliminate the extra confirmation +question when posting to a newsgroup. +<P> +This feature is displayed as "Send Without Confirming". +<P> + +<DT> <A NAME="separate-folder-and-directory-display"><EM>separate-folder-and-directory-display</EM></A> + +<DD> This feature affects folder collections wherein a folder +and directory can have the same name. By default, <EM>Alpine</EM> displays them +only once, denoting that it is both a folder and directory by appending +the folder name with the hierarchy character enclosed +in square brackets. +<P> + +Enabling this feature will cause <EM>Alpine</EM> to display such names +separately marking the name representing a directory with a trailing +hierarchy delimiter (typically the slash, "/", character). +<P> + +The feature also alters the command set slightly. By default, the +right-arrow descends into the directory, while hitting the Return key will +cause the folder by that name to be opened. +<P> + +With this feature set, the Return key will open the highlighted folder, or +enter the highlighted directory. +<P> + +<DT> <A NAME="show-cursor"><EM>show-cursor</EM></A> + +<DD> If set, the system +cursor will move to convenient locations in the displays. For example, +to the beginning of the status field of the highlighted index line, or +to the highlighted word after a successful <EM>WhereIs</EM> command. +It is intended to draw your attention to the <EM>interesting</EM> +spot on the screen. +<P> + +<DT> <A NAME="show-plain-text-internally"><EM>show-plain-text-internally</EM></A> + +<DD> This feature modifies the method <EM>Alpine</EM> uses to display Text/Plain +MIME attachments from the Attachment Index screen. Normally, the +"View" command searches for any externally defined (usually +via the Mailcap file) viewer, +and displays the selected text within that viewer. + +<P> +Enabling this feature causes <EM>Alpine</EM> to ignore any external viewer +settings and always display text with <EM>Alpine</EM>'s internal viewer. + +<P> + +<DT> <A NAME="show-selected-in-boldface"><EM>show-selected-in-boldface</EM></A> + +<DD> This feature controls an aspect of <EM>Alpine</EM>'s aggregate operation commands; +in particular, the <EM>Select</EM> and <EM>WhereIs</EM> commands. +<EM>Select</EM> and <EM>WhereIs</EM> (with +the <EM>^X</EM> subcommand) will search the current folder +for messages meeting a +specified criteria, and <EM>tag</EM> the resulting +messages with an <EM>X</EM> in the +first column of the applicable lines in the "Folder Index". If this feature +is set, instead of using the <EM>X</EM> to denote a selected message, +<EM>Alpine</EM> will attempt to display those index lines in boldface. +Whether this is preferable to the <EM>X</EM> will depend on personal +taste and the type of terminal being used. +<P> + +<DT> <A NAME="show-sort"><EM>show-sort</EM></A> + +<DD> If this feature is set and there is sufficient space on the screen, +a short indication of the current sort order will be +added in the titlebar (the top line on the screen), before the name +of the folder. +For example, with the default Arrival sort in effect, +the display would have the characters + +<P><CENTER>[A]</CENTER><P> + +added between the title of the screen and the folder name. +The letters are the same as the letters you may type to manually +sort a folder with the SortIndex command ($). +The letters in the table below are the ones that may show +up in the titlebar line. +<P> +<TABLE> +<TR> <TD> A </TD> <TD> <EM>A</EM>rrival </TD> </TR> +<TR> <TD> S </TD> <TD> <EM>S</EM>ubject </TD> </TR> +<TR> <TD> F </TD> <TD> <EM>F</EM>rom </TD> </TR> +<TR> <TD> T </TD> <TD> <EM>T</EM>o </TD> </TR> +<TR> <TD> C </TD> <TD> <EM>C</EM>c </TD> </TR> +<TR> <TD> D </TD> <TD> <EM>D</EM>ate </TD> </TR> +<TR> <TD> Z </TD> <TD> si<EM>Z</EM>e </TD> </TR> +<TR> <TD> O </TD> <TD> <EM>O</EM>rderedsubject </TD> </TR> +<TR> <TD> E </TD> <TD> scor<EM>E</EM> </TD> </TR> +<TR> <TD> H </TD> <TD> t<EM>H</EM>read </TD> </TR> +</TABLE> +<P> +If the sort order is Reversed, the letter above will be preceded by the letter +"R", for example + +<P><CENTER>[RS]</CENTER><P> + +means that a Reverse Subject sort is in effect. +For the case where the sort is in Reverse Arrival order, the "A" is +left out, and just an "R" is shown. + +<P><CENTER>[R]</CENTER> +<P> +This feature is displayed as "Show Sort in Titlebar". +<P> + +<DT> <A NAME="sig-at-bot"><EM>signature-at-bottom</EM></A> + +<DD> If this feature +is set, and a message being <EM>Repl</EM>ied to is being included in +the reply, then the +contents of the signature file (if any) will be inserted after the included +message. +This feature does not affect the results of a <EM>Forward</EM> command. +<P> + +<DT> <A NAME="single-column-folder-list"><EM>single-column-folder-list</EM></A> + +<DD> If set, the "Folder List" screen will list one folder per line +instead of several per line. +<P> + +<DT> <A NAME="slash-collapses-entire-thread"><EM>slash-collapses-entire-thread</EM></A> + +<DD> Normally, the Collapse/Expand Thread command Collapses or Expands the subthread which +starts at the currently highlighted message, if any. +If this feature is set, then the slash command Collapses or Expands the +<EM>entire</EM> current thread instead of just the subthread. +<P> + +<DT> <A NAME="smime-dont-do-smime"><EM>smime-dont-do-smime</EM></A> + +<DD> UNIX <EM>Alpine</EM> only. +<P> +Setting this feature turns off all of <EM>Alpine</EM>'s S/MIME support. +You might want to set this if you are having trouble due to the S/MIME support. +<P> +<UL> +<LI><A HREF="config-notes.html#smime-general">General S/MIME Overview</A> +</UL><P> +This feature is displayed as "S/MIME -- Turn off S/MIME". +<P> + +<DT> <A NAME="smime-encrypt-by-default"><EM>smime-encrypt-by-default</EM></A> + +<DD> UNIX <EM>Alpine</EM> only. +<P> +This feature only has an effect if your version of <EM>Alpine</EM> includes +support for S/MIME. +It affects <EM>Alpine</EM>'s behavior when you send a message. +If this option is set, the "Encrypt" option will default to ON when sending messages. +<P> +Only the default value is affected. +In any case, you may still toggle the Encrypt option on or off before sending +with the "E Encrypt" command (provided you have a the public digital ID +for the recipient). +<P> +<UL> +<LI><A HREF="config-notes.html#smime-general">General S/MIME Overview</A> +</UL><P> +This feature is displayed as "S/MIME -- Encrypt by Default". +<P> + +<DT> <A NAME="smime-remember-passphrase"><EM>smime-remember-passphrase</EM></A> + +<DD> UNIX <EM>Alpine</EM> only. +<P> +This feature only has an effect if your version of <EM>Alpine</EM> includes +support for S/MIME. +If this option is set, you will only have to enter your passphrase for your private key +once during an <EM>Alpine</EM> session. +<P> +<UL> +<LI><A HREF="config-notes.html#smime-general">General S/MIME Overview</A> +</UL><P> +This feature is displayed as "S/MIME -- Remember S/MIME Passphrase". +<P> + +<DT> <A NAME="smime-sign-by-default"><EM>smime-sign-by-default</EM></A> + +<DD> UNIX <EM>Alpine</EM> only. +<P> +This feature only has an effect if your version of <EM>Alpine</EM> includes +support for S/MIME. +It affects <EM>Alpine</EM>'s behavior when you send a message. +If this option is set, the "Sign" option will default to ON when sending messages. +<P> +Only the default value is affected. +In any case, you may still toggle the Signing option on or off before sending +with the "G Sign" command (provided you have a personal digital ID +certificate). +<P> +<UL> +<LI><A HREF="config-notes.html#smime-general">General S/MIME Overview</A> +</UL><P> +This feature is displayed as "S/MIME -- Sign by Default". +<P> + +<DT> <A NAME="sort-default-fcc-alpha"><EM>sort-default-fcc-alpha</EM></A> + +<DD> This feature controls an aspect of <EM>Alpine</EM>'s FOLDER LIST screen. +If set, the default FCC folder will be sorted alphabetically with the other +folders instead of appearing right after the INBOX. +<P> +This feature is displayed as "Sort Default Fcc Folder Alphabetically". +<P> + +<DT> <A NAME="sort-default-save-alpha"><EM>sort-default-save-alpha</EM></A> + +<DD> This feature controls an aspect of <EM>Alpine</EM>'s FOLDER LIST screen. +If set, the default save folder will be sorted alphabetically with the other +folders instead of appearing right after the INBOX (and default FCC folder). +<P> +This feature is displayed as "Sort Default Save Folder Alphabetically". +<P> + +<DT> <A NAME="spell-check-before-sending"><EM>spell-check-before-sending</EM></A> + +<DD> When this feature is set, every composed message will be spell-checked before +being sent. + +<P> + +<DT> <A NAME="store-window-position-in-config"><EM>store-window-position-in-config</EM></A> + +<DD> Normally, <EM>PC-Alpine</EM> will store its window size and position in the +Windows Registry. +This is convenient if you want to use the same remote +configuration from more than one PC. +If you use multiple configuration files to start <EM>PC-Alpine</EM>, you may want +to store the window size and position in the configuration file instead +of in the Registry. +Setting this feature causes that to happen. + +<P> + +<DT> <A NAME="strip-from-sigdashes-on-reply"><EM>strip-from-sigdashes-on-reply</EM></A> + +<DD> This feature doesn't do anything if the feature +<A HREF="#enable-sigdashes"><EM>enable-sigdashes</EM></A> is turned on. +However, if the <EM>enable-sigdashes</EM> feature is not turned on, +then turning on this feature enables support for the convention +of not including text beyond the sigdashes line when Replying or Following +up to a message and including the text of that message. +<P> +In other words, this is a way to turn on the signature stripping behavior +without also turning on the dashes-adding behavior. +<P> + +<DT> <A NAME="strip-whitespace-before-send"><EM>strip-whitespace-before=send</EM></A> + +<DD> Trailing whitespace is not stripped from +a message before sending. Trailing whitespace should have no effect on an +email message, and in flowed text can aid in delimiting paragraphs. +However, the old behavior of stripping trailing whitespace was in place +to better deal with older clients that couldn't handle certain types of +text encodings. This feature restores the old behavior +<P> +Trailing whitespace is of aid to flowed-text-formatted messages, which are +generated by default but can be turned off via the +<A HREF="#quell-flowed-text">quell-flowed-text</A> feature. +strip-whitespace-before-send also has the effect of turning off sending +of flowed text. +<P> +This feature is displayed as "Strip Whitespace Before Sending". +<P> + +<DT> <A NAME="suppress-asterisks-in-password-prompt"><EM>suppress-asterisks-in-password-prompt</EM></A> + +<DD> When you are running <EM>Alpine</EM> you will sometimes be asked for a password +in a prompt on the third line from the bottom of the screen. +Normally each password character you type will cause an asterisk to echo +on the screen. That gives you some feedback to know that your typing is +being recognized. +There is a very slight security risk in doing it this way because someone +watching over your shoulder might be able to see how many characters there +are in your password. +If you'd like to suppress the echoing of the asterisks set this feature. +<P> + +<DT> <A NAME="suppress-user-agent-when-sending"><EM>suppress-user-agent-when-sending</EM></A> +<DD> If this feature is set then <EM>Alpine</EM> will not generate a +<CODE>User-Agent</CODE> header in outgoing messages. +<P> + +<DT> <A NAME="tab-checks-recent"><EM>tab-checks-recent</EM></A> + +<DD> In a FOLDER LIST screen, the TAB key usually just changes which +folder is highlighted. +If this feature is set, then the TAB key will cause the number of +recent messages and the total number of messages in the highlighted folder +to be displayed instead. +<P> +This feature is displayed as "Tab Checks for Recent Messages". +<P> + +<DT> <A NAME="tab-uses-unseen-for-next-folder"><EM>tab-uses-unseen-for-next-folder</EM></A> + +<DD> This feature affects <EM>Alpine</EM>'s behavior when using the TAB +NextNew Command +to move from one folder to the next. +<EM>Alpine</EM>'s usual behavior is to search for folders +with <EM>Recent</EM> messages in them. +Recent messages are messages which have arrived since the last time the +folder was opened. + +<P> +Setting this feature causes <EM>Alpine</EM> to search for <EM>Unseen</EM> +messages instead of Recent messages. +Unseen messages remain Unseen until you view them (or flag then as Seen with +the Flag Command). +Setting this feature allows you to locate messages you have not read +instead of only recently received messages. +When this feature is set, the feature +<A HREF="#enable-fast-recent-test">Enable-Fast-Recent-Test</A> +will have no effect, so the checking may be slower. + +<P> +Another reason why you might want to use this feature is that <EM>Alpine</EM> sometimes +opens folders implicitly behind the scenes, and this clears the +Recent status of all messages in the folder. +One example where this happens is when Saving or filtering a +message to another folder. +If that message has some <A HREF="#keywords">keywords</A> +set, then because of some shortcomings +in the IMAP specification, the best way to ensure that those keywords are +still set in the saved copy of the message is to open the folder and +set the keywords explicitly. +Because this clears the Recent status of all messages in that folder the +folder will not be found by the NextNew command unless this feature is set. +<P> + +<DT> <A NAME="tab-visits-next-new-message-only"><EM>tab-visits-next-new-message-only</EM></A> + +<DD> This feature affects <EM>Alpine</EM>'s behavior when using the <EM>TAB</EM> +key to move from one message to the next. +<EM>Alpine</EM>'s usual behavior is to select the next +<EM>Unread</EM> message or message flagged as <EM>Important</EM>. +<P> + +Setting this feature causes <EM>Alpine</EM> to skip the +messages flagged as <EM>Important</EM>, +and select <EM>Unread</EM> messages exclusively. +Tab behavior when there are no +new messages left to select remains unchanged. +<P> + +<DT> <A NAME="termdef-takes-precedence"><EM>termdef-takes-precedence</EM></A> + +<DD> This feature may affect <EM>Alpine</EM>'s low-level input routines. Termcap (or +terminfo, depending on how your copy of <EM>Alpine</EM> was compiled and linked) +is the name of the database which describes terminal capabilities. In +particular, it describes the sequences of characters that various keys +will emit. + +<P> +An example would be the Up Arrow key on the keyboard. Up +Arrow is not a distinct character on most Unix systems. When you press +the Up Arrow key a short sequence of characters are produced. This +sequence is supposed to be described in the termcap database by the +"ku" capability (or by the "kcuu1" capability if you +are using terminfo instead of termcap). + +<P> +By default, <EM>Alpine</EM> defines some terminal +escape sequences that are commonly used. For example, the sequence +"ESC O A" is recognized as an Up Arrow key. The sequence +"ESC [ A" +is also recognized as an Up Arrow key. These are chosen because common +terminals like VT100's or ANSI standard terminals produce these +sequences when you press the Up Arrow key. + +<P> +If your system's termcap +(terminfo) database assigns some other function to the sequence +"ESC O A" +it is usually ignored by <EM>Alpine</EM>. Also, if your termcap (terminfo) +database assigns a sequence which doesn't begin with an escape +character (<SAMP>ESC</SAMP>) it is usually ignored by <EM>Alpine</EM>. +This usually works fine +because most terminals emit the escape sequences that <EM>Alpine</EM> has defined +by default. We have also found that it is usually better to have these +defaults take precedence over the definitions contained in the database +because the defaults are more likely to be correct than the database. + +<P> +There are some terminals where this breaks down. If you want <EM>Alpine</EM> to +believe the definitions given in your termcap (terminfo) database in +preference to the defaults the <EM>Alpine</EM> itself sets up, then you may turn +this feature on. Then, sequences of characters which are defined in +both termcap (terminfo) and in <EM>Alpine</EM>'s set of defaults will be +interpreted the way that termcap (terminfo) says they should be +interpreted. Also, if your terminal capabilities database assigns a +sequence which doesn't begin with escape, it will not be ignored. +<P> + +<DT> <A NAME="thread-index-shows-important-color"><EM>thread-index-shows-important-color</EM></A> + +<DD> This option affects only the THREAD INDEX screen. +Whether or not you ever see a THREAD INDEX screen depends on the setting +of the configuration option +<A HREF="#threading-index-style"><EM>threading-index-style</EM></A> +and on the sort order of the index. +If a message within a thread is flagged as Important +and this option is set, then +the entire line in the THREAD INDEX will be colored the color of the +Index-important Symbol, which can be set using the +Setup Kolor screen. +<P> + +<DT> <A NAME="try-alternative-authentication-driver-first"><EM>try-alternative-authentication-driver-first</EM></A> + +<DD> This feature affects how <EM>Alpine</EM> connects to IMAP servers. +It's utility has largely been overtaken by events, +but it may still be useful in some circumstances. +If you only connect to modern IMAP servers that support +"TLS" you can ignore this feature. + +<P> +Details: + +<P> +By default, <EM>Alpine</EM> will attempt to connect to an IMAP server on the +normal IMAP service port (143), and if the server offers "Transport Layer +Security" (TLS) and <EM>Alpine</EM> has been compiled with encryption capability, +then a secure (encrypted) session will be negotiated. + +<P> +With this feature enabled, before connecting on the normal IMAP port, <EM>Alpine</EM> +will first attempt to connect to an alternate IMAP service port (993) used +specifically for encrypted IMAP sessions via the Secure Sockets Layer +(SSL) method. +If the SSL attempt fails, <EM>Alpine</EM> will then try the default +behavior described in the previous paragraph. + +<P> +TLS negotiation on the normal port is preferred, and supersedes the use of +SSL on port 993, but older servers may not provide TLS support. +This feature may be convenient when accessing IMAP servers that do not support +TLS, but do support SSL connections on port 993. +However, it is important to understand that with this feature enabled, +<EM>Alpine</EM> will <EM>attempt</EM> to make a secure connection if that is possible, +but it will proceed to make an insecure connection if that is the only +option offered by the server, or if the <EM>Alpine</EM> in question has been built +without encryption capability. + +<P> +Note that this feature specifies a per-user (or system-wide) default +behavior, but host/folder specification flags may be used to control the +behavior of any specific connection. +This feature interacts with some of +the possible host/folder path specification flags as follows: + +<P> +The <SAMP>/tls</SAMP> host flag, for example, + +<P> +<CENTER><SAMP>{foo.example.com/tls}INBOX</SAMP></CENTER> +<P> +will over-ride this feature for the specified host by bypassing the +SSL connection attempt. +Moreover, with <SAMP>/tls</SAMP> specified, +the connection attempt will fail if the +service on port 143 does not offer TLS support. + +<P> +The <SAMP>/ssl</SAMP> host flag, for example, + +<P> +<CENTER><SAMP>{foo.example.com/ssl}INBOX</SAMP></CENTER> +<P> +will insist on an SSL connection for the specified host, +and will fail if the SSL service on port 993 is not available. +<EM>Alpine</EM> will not subsequently retry a connection +on port 143 if <SAMP>/ssl</SAMP> is specified. +<P> + +<DT> <A NAME="unselect-will-not-advance"><EM>unselect-will-not-advance</EM></A> + +<DD> Normally, when the Unselect current message command (:) is typed when the +current message is selected, the message will be unselected and the next +message will become the current message. +If this feature is set, the cursor will not advance to the next message. +Instead, the current message will remain the current message after +unselecting. +<P> + +<DT> <A NAME="use-current-dir"><EM>use-current-dir</EM></A> + +<DD> This feature controls an aspect of several commands. If set, your +"current working directory" will be used instead of your home directory +for all of the following operations: + +<UL> +<LI> <EM>Export</EM> in the "Folder Index" and "Message Text" screens +<LI> Attachment <EM>Save</EM> in the "Message Text" and "Attachment Text" screens +<LI> <EM>^R</EM> file inclusion in the Composer +<LI> <EM>^J</EM> file attachment in the Composer +</UL> +<P> +This feature is displayed as "Use Current Directory". +<P> + +<DT> <A NAME="use-function-keys"><EM>use-function-keys</EM></A> + +<DD> This feature specifies that <EM>Alpine</EM> will +respond to function keys instead of +the normal single-letter commands. In this mode, the key menus at the +bottom of each screen will show function key designations instead of the +normal mnemonic key. +<P> + +<DT> <A NAME="use-reg-start-rule"><EM>use-regular-startup-rule-for-stayopen-folders</EM></A> + +<DD> This feature affects which message is selected as the current message +when you enter a +<A HREF="#stay-open-folders">Stay Open</A> folder. +<P> +Normally, the starting position for an incoming folder (which most Stay Open +folders will likely be) is controlled by the +<A HREF="#incoming-startup-rule"><EM>Incoming-Startup-Rule</EM></A>. +However, if a folder is a Stay Open folder, when you re-enter the folder +after the first time the current message will be the same as it was when +you left the folder. +An exception is made if you use the TAB command to get to the folder. +In that case, the message number will be incremented by one from what it +was when you left the folder. +<P> +The above special behavior is thought to be useful. +However, it is special and different from what you might at first expect. +If this feature is set, then Stay Open folders will not be treated specially +as far as the startup rule is concerned. +<P> + +<DT> <A NAME="use-resent-to-in-rules"><EM>use-resent-to-in-rules</EM></A> + +<DD> This feature is turned off by default because turning it on causes problems +with some deficient IMAP servers. +In <EM>Alpine</EM> Filters and other types of Rules, if the +Pattern +contains a To header pattern and this feature is turned on, +then a check is made in the message to see +if a Resent-To header is present, and that is used instead of the To header. +If this feature is not turned on, then the regular To header will always +be used. +<P> + +<DT> <A NAME="use-sender-not-x-sender"><EM>use-sender-not-x-sender</EM></A> + +<DD> Normally <EM>Alpine</EM> on Unix adds a header line labeled <EM>X-X-Sender</EM>, +if the sender is different from the <EM>From:</EM> line. + +<P> +The standard specifies that this header +line should be labeled <EM>Sender</EM>, not <EM>X-X-Sender</EM>. +Setting this feature causes +<EM>Sender</EM> to be used instead of <EM>X-X-Sender</EM>. The standard also states +that the data associated with this header field should not be used as a Reply address. +Unfortunately, certain implementations of mail list management servers will use the +Sender address for such purposes. These implementations often even recognize the +<EM>X-Sender</EM> fields as being equivalent to the <EM>Sender</EM> field, and use it +if present. This is why <EM>Alpine</EM> defaults to <EM>X-X-Sender</EM>. +<P> +Note, <EM>PC-Alpine</EM> always adds +either an <EM>X-X-Sender</EM> line if there is an open, remote mailbox, or an +<EM>X-Warning: UNAuthenticated User</EM> otherwise + +<P> +This feature is displayed as "Use Sender Instead of X-X-Sender". +<P> + +<DT> <A NAME="use-subshell-for-suspend"><EM>use-subshell-for-suspend</EM></A> + +<DD> This feature affects <EM>Alpine</EM>'s behavior when process suspension +is enabled and then activated via the <EM>^Z</EM> key. +<EM>Alpine</EM> suspension allows one to +temporarily interact with the operating system command "shell" without +quitting <EM>Alpine</EM>, +and then subsequently resume the still-active <EM>Alpine</EM> session. +<P> + +When the <EM>enable-suspend</EM> feature is set and subsequently the +<EM>^Z</EM> key is pressed, +<EM>Alpine</EM> will normally suspend itself and return temporary +control to <EM>Alpine</EM>'s parent shell process. +However, if this feature is set, <EM>Alpine</EM> will instead create an +inferior subshell process. +This is useful when the parent process is not intended to be used +interactively. +Examples include invoking <EM>Alpine</EM> via the <CODE>-e</CODE> argument +of the Unix <EM>xterm</EM> program, or via a menu system. +<P> + +Note that one typically resumes a suspended <EM>Alpine</EM> by entering the Unix +<EM>fg</EM> command, but if this feature is set, it will be necessary to enter +the <EM>exit</EM> command instead. +<P> + +<DT> <A NAME="use-system-translation"><EM>use-system-translation</EM></A> + +<DD> UNIX <EM>Alpine</EM> only. <EM>Alpine</EM> normally uses its own internal software to convert between the multi-byte +representation of characters and the Unicode representation of those +same characters +( see the section on <A HREF="low-level.html#char-set">International Character Sets</EM></A>). +It converts from the multi-byte characters your keyboard produces to Unicode, +and from Unicode to the multi-byte characters your display expects. +Alpine also uses its own internal software to decide how much space on +the screen a particular Unicode character will occupy. + +<P> +Setting this feature tells <EM>Alpine</EM> to use the system-supplied routines to +perform these tasks instead. +In particular there are three tasks and three system routines that will +be used for these tasks. + +<P> +To convert from multi-byte to Unicode the routine + +<P> +<CENTER><SAMP>mbstowcs</SAMP></CENTER> +<P> + +is used. +To convert from Unicode to multi-byte the routine + +<P> +<CENTER><SAMP>wcrtomb</SAMP></CENTER> +<P> + +is used. +And to find the screen width a particular Unicode character will +occupy the routine used is + +<P> +<CENTER><SAMP>wcwidth</SAMP></CENTER> +<P> + +This feature has been only lightly tested. +The internal routines should normally be used unless you run into +a problem that you think may be solved by using the system routines. +Note that your environment needs to be set up for these +routines to work correctly. +In particular, the LANG or LC_CTYPE variable in your environment will +need to be set. +<P> + +<DT> <A NAME="vertical-folder-list"><EM>vertical-folder-list</EM></A> + +<DD> This feature controls an aspect of <EM>Alpine</EM>'s FOLDER LIST screen. If set, +the folders will be listed alphabetically down the columns rather +than across the columns as is the default. + +<P> +This feature is displayed as "Use Vertical Folder List". +<P> + +<DT> <A NAME="warn-if-blank-subject"><EM>warn-if-blank-subject</EM></A> + +<DD> This feature affects <EM>Alpine</EM>'s behavior when you send a message being +composed. +If this option is set, <EM>Alpine</EM> will check to see if the message about to be sent +has a subject or not. +If not, you will be asked if you want to send the message anyway. +<P> + +<DT> <A NAME="warn-if-blank-to-and-cc-and-newsgroups"><EM>warn-if-blank-to-and-cc-and-newsgroups</EM></A> + +<DD> This feature affects <EM>Alpine</EM>'s behavior when you send a message being +composed. +If this option is set, <EM>Alpine</EM> will check to see if the message about to be sent +has either a To address, a Cc address, or a Newsgroup. +If none of these is set, +you will be asked if you want to send the message anyway. +<P> +This feature is closely related to +<A HREF="#fcc-only-without-confirm"><EM>fcc-only-without-confirm</EM></A>. +<EM>Alpine</EM> will normally ask if you want to copy a message only to the Fcc. +This feature also applies to cases where there is a Bcc but still no To, Cc, +or Newsgroup. +If the Fcc-Only-Without-Confirm feature is set and you are sending a +message with only an Fcc, then you won't be asked about sending with +a blank To and Cc and Newsgroups header even if this feature is set. +Similarly, if you have already been asked if you want to send to the Fcc +only and you have answered Yes, then you won't be asked again about sending with +blank To, Cc, and Newsgroups headers even if this feature is set. + +<P> + +</DL> +<P> + +<H2><A NAME="hidden-config">Hidden Config Variables and Features</A></H2> + +There are several configuration variables and features which are normally hidden +from the user. That is, they don't appear on any of the configuration +screens. Some of these are suppressed because they are intended to be used +by system administrators, and in fact may only be set in system-wide +configuration files. Others are available to users but are thought to be +of such little value to most users that their presence on the Config +screens would cause more confusion than help. +Others are hidden in the Setup/Config screen because they are normally +configured in one of the other configuration screens. For example, all +of the colors are hidden because the normal way to configure colors is +through Setup/Colors not Setup/Config. +You may set the feature <A HREF="#expose-hidden-config">expose-hidden-config</A> +to cause most of these hidden variables and features to show up at the bottom +of the Setup/Config screen. + +<H3>Hidden Variables Not Settable by Users</H3> + +These variables are settable only in system-wide configuration files. + +<UL> +<LI> <A HREF="#bugs-add">bugs-additional-data</A> +<LI> <A HREF="#bugs">bugs-address</A> +<LI> <A HREF="#bugs">bugs-fullname</A> +<LI> <A HREF="#forced-abook">forced-abook-entry</A> +<LI> <A HREF="#kblock-count">kblock-passwd-count</A> +<LI> <A HREF="#bugs">local-address</A> +<LI> <A HREF="#bugs">local-fullname</A> +<LI> <A HREF="#mail-directory">mail-directory</A> +<LI> <A HREF="#standard-printer">standard-printer</A> +<LI> <A HREF="#bugs">suggest-address</A> +<LI> <A HREF="#bugs">suggest-fullname</A> +</UL> + +<H3>Hidden Variables Which are Settable by Users</H3> + +These variables are not shown to users but are settable by means +of hand editing the personal configuration file. This first group +is usually maintained by <EM>Alpine</EM> and there will usually +be no reason to edit them by hand. + +<UL> +<LI> <A HREF="#last-version-used">last-version-used</A> +<LI> <A HREF="#patterns-filters2">patterns-filters2</A> +<LI> <A HREF="#patterns-indexcolors">patterns-indexcolors</A> +<LI> <A HREF="#patterns-roles">patterns-roles</A> +<LI> <A HREF="#patterns-scores2">patterns-scores2</A> +<LI> <A HREF="#remote-abook-metafile">remote-abook-metafile</A> +</UL> +<P> + +This group is usually correct but may be changed by system managers or +users in special cases. + +<UL> +<LI> <A HREF="#disable-these-auths">disable-these-authenticators</A> +<LI> <A HREF="#disable-these-drivers">disable-these-drivers</A> +<LI> <A HREF="#last-time">last-time-prune-questioned</A> +<LI> <A HREF="#new-version-threshold">new-version-threshold</A> +<LI> <A HREF="#remote-abook-history">remote-abook-history</A> +<LI> <A HREF="#remote-abook-validity">remote-abook-validity</A> +<LI> <A HREF="#rsh-command">rsh-command</A> +<LI> <A HREF="#rsh-open-timeout">rsh-open-timeout</A> +<LI> <A HREF="#rsh-path">rsh-path</A> +<LI> <A HREF="#sendmail-path">sendmail-path</A> +<LI> <A HREF="#ssh-command">ssh-command</A> +<LI> <A HREF="#ssh-open-timeout">ssh-open-timeout</A> +<LI> <A HREF="#ssh-path">ssh-path</A> +<LI> <A HREF="#tcp-open-timeout">tcp-open-timeout</A> +<LI> <A HREF="#tcp-query-timeout">tcp-query-timeout</A> +<LI> <A HREF="#tcp-read-warning-timeout">tcp-read-warning-timeout</A> +<LI> <A HREF="#tcp-write-warning-timeout">tcp-write-warning-timeout</A> +<LI> <A HREF="#use-function-keys">use-function-keys</A> +</UL> +<P> + +System managers are usually interested in setting these in the system-wide +configuration files, though users may set them if they wish. + +<UL> +<LI> <A HREF="#operating-dir">operating-dir</A> +<LI> <A HREF="#user-input">user-input-timeout</A> +</UL> +<P> + +<H3>Hidden Features Which are Settable by Users</H3> + +These are <EM>features</EM> (as opposed to variables) which users or system +administrators may set. Some of them only make sense for administrators. +To turn these on manually, the configuration file should be edited and the +feature added to the <EM>feature-list</EM> variable. +You may set the feature <A HREF="#expose-hidden-config">expose-hidden-config</A> +to cause these hidden features to show up in the Setup/Config screen. +They will be at the bottom of the screen. + +<UL> +<LI> <A HREF="#disable-config-cmd">disable-config-cmd</A> +<LI> <A HREF="#disable-kblock">disable-keyboard-lock-cmd</A> +<LI> <A HREF="#disable-password-cmd">disable-password-cmd</A> +<LI> <A HREF="#disable-pipes-in-sigs">disable-pipes-in-sigs</A> +<LI> <A HREF="#disable-pipes-in-templates">disable-pipes-in-templates</A> +<LI> <A HREF="#disable-roles-setup-cmd">disable-roles-setup-cmd</A> +<LI> <A HREF="#disable-roles-sig-edit">disable-roles-sig-edit</A> +<LI> <A HREF="#disable-roles-template-edit">disable-roles-template-edit</A> +<LI> <A HREF="#disable-setlocale-collate">disable-setlocale-collate</A> +<LI> <A HREF="#disable-shared-namespaces">disable-shared-namespaces</A> +<LI> <A HREF="#disable-signature-edit-cmd">disable-signature-edit-cmd</A> +</UL> +<P> + +<H2><A NAME="ret-var">Retired Variables and Features</A></H2> + +Variables and features that are no longer used by the current <EM>Alpine</EM> version. +When an obsolete variable is encountered, its value is applied to any new +corresponding setting. +The replaced values include: +<P> + +<DL COMPACT> + +<DT> <EM>character-set</EM> + +<DD> Replaced by three separate variables: +<EM>display-character-set</EM>, +<EM>keyboard-character-set</EM>, and +<EM>posting-character-set</EM>. + +<DT> <EM>compose-mime</EM> + +<DT> <EM>elm-style-save</EM> + +<DD> Replaced by <EM>saved-msg-name-rule</EM> + +<DT> <EM>feature-level</EM> + +<DD> Replaced by <EM>feature-list.</EM> + +<DT> <EM>header-in-reply</EM> + +<DD> Replaced by <EM>include-header-in-reply</EM> in the +<EM>feature-list.</EM> + +<DT> <EM>old-style-reply</EM> + +<DD> Replaced by <EM>signature-at-bottom</EM> in the +<EM>feature-list.</EM> + +<DT> <EM>use-old-unix-format-write</EM> + +<DD> No replacement. + +<DT> <EM>patterns</EM> + +<DD> Replaced by four separate patterns variables: +<EM>patterns-roles</EM>, +<EM>patterns-filters</EM>, +<EM>patterns-scores</EM>, and +<EM>patterns-indexcolors</EM>. +Since then, <EM>patterns-filters</EM> has also become obsolete and is replaced +by <EM>patterns-filters2</EM>; <EM>patterns-scores</EM> is replaced by +<EM>patterns-scores2</EM>. + +<DT> <EM>save-by-sender</EM> + +<DD> Replaced by <EM>saved-msg-name-rule.</EM> + +<DT> <EM>show-all-characters</EM> + +<DD> No replacement, it always works this way now. + +</DL> + +<P> + +<H2><A NAME="index-tokens"></A>Tokens for Index and Replying</H2> + +This set of special tokens may be used in the +<A HREF="#index-format"><EM>index-format</EM></A> option, +in the <A HREF="#reply-leadin"><EM>reply-leadin</EM></A> option, +in signature files, +in template files used in +<A HREF="#role-config"><EM>roles</EM></A>, +and in the folder name that is the target of a Filter Rule. +Some of them aren't available in all situations. +<P> +The tokens are used as they appear below for the <EM>Index-Format</EM> +option, but they must be surrounded by underscores for the +<EM>Reply-Leadin</EM> option, in signature and template files, +and in the target of Filter Rules. +<P> + +<H3><EM>Tokens Available for all Cases (except Filter Rules)</EM></H3> + +<DL> +<DT>SUBJECT</DT> +<DD> +This token represents the Subject the sender gave the message. +Alternatives for use in the index screen are +SUBJKEY, SUBJKEYINIT, SUBJECTTEXT, SUBJKEYTEXT, and SUBJKEYINITTEXT. +You may color the subject text in the MESSAGE INDEX screen differently by using the +<A HREF="#index-subject-color">Index Subject Color</A> +and the +<A HREF="#index-opening-color">Index Opening Color</A>. +options available from +the Setup Kolor screen. +</DD> + +<DT>FROM</DT> +<DD> +This token represents the personal name (or email address if the name +is unavailable) of the person specified in the message's "From:" +header field. +You may color the from text in the MESSAGE INDEX screen differently by using the +<A HREF="#index-from-color">Index From Color</A> +option available from the Setup Kolor screen. +</DD> + +<DT>ADDRESS</DT> +<DD> +This is similar to the "FROM" token, only it is always the +email address, never the personal name. +For example, "mailbox@domain". +</DD> + +<DT>MAILBOX</DT> +<DD> +This is the same as the "ADDRESS" except that the +domain part of the address is left off. +For example, "mailbox". +</DD> + +<DT>SENDER</DT> +<DD> +This token represents the personal name (or email address) of the person +listed in the message's "Sender:" header field. +</DD> + +<DT>TO</DT> +<DD> +This token represents the personal names (or email addresses if the names +are unavailable) of the persons specified in the +message's "To:" header field. +</DD> + +<DT>NEWSANDTO</DT> +<DD> +This token represents the newsgroups from the +message's "Newsgroups:" header field <EM>and</EM> +the personal names (or email addresses if the names +are unavailable) of the persons specified in the +message's "To:" header field. +</DD> + +<DT>TOANDNEWS</DT> +<DD> +Same as "NEWSANDTO" except in the opposite order. +</DD> + +<DT>NEWS</DT> +<DD> +This token represents the newsgroups from the +message's "Newsgroups:" header field. +</DD> + +<DT>CC</DT> +<DD> +This token represents the personal names (or email addresses if the names +are unavailable) of the persons specified in the +message's "Cc:" header field. +</DD> + +<DT>RECIPS</DT> +<DD> +This token represents the personal names (or email addresses if the names +are unavailable) of the persons specified in both the +message's "To:" header field and +the message's "Cc:" header field. +</DD> + +<DT>NEWSANDRECIPS</DT> +<DD> +This token represents the newsgroups from the +message's "Newsgroups:" header field <EM>and</EM> +the personal names (or email addresses if the names +are unavailable) of the persons specified in the +message's "To:" and "Cc:" header fields. +</DD> + +<DT>RECIPSANDNEWS</DT> +<DD> +Same as "NEWSANDRECIPS" except in the opposite order. +</DD> + +<DT>INIT</DT> +<DD> +This token represents the initials from the personal name +of the person specified in the message's "From:" +header field. +If there is no personal name, it is blank. +</DD> + +<DT>DATE</DT> +<DD> +This token represents the date on which the message was sent, according +to the "Date" header field. +It has the format MMM DD. For example, "Oct 23". +The feature +<A HREF="#convert-dates-to-localtime"><EM>convert-dates-to-localtime</EM></A>, +which adjusts for the timezone the message was sent from, +may have an affect on the value of this token as well as the values of +all of the other DATE or TIME tokens. +Some of the DATE and TIME tokens are displayed in a locale-specific +way unless the option +<A HREF="#disable-index-locale-dates"><EM>Disable-Index-Locale-Dates</EM></A> is set. +</DD> + +<DT>SMARTDATE</DT> +<DD> +This token represents the date on which the message was sent, according +to the "Date" header field. +It is "Today" if the message was sent today, +"Yesterday" for yesterday, +"Wednesday" if it was last Wednesday, and so on. If the +message is from last year and is more than six months old it includes the year, as well. +There is no adjustment made for different time zones, so you'll get +the day the message was sent according to the time zone the sender +was in. +See the SMARTDATE alternatives below, as well. +</DD> + +<DT>SMARTTIME</DT> +<DD> +This token represents the most relevant elements of the date on which +the message was sent (according to the "Date" header field), +in a compact form. If the message was sent today, only the time is used +(e.g. "9:22am", "10:07pm"); if it was sent during +the past week, the day of the week and the hour are used +(e.g. "Wed09am", "Thu10pm"); other dates are +given as date, month, and year (e.g. "23Aug00", +"9Apr98"). +There is no adjustment made for different time zones, so you'll get +the day/time the message was sent according to the time zone the sender +was in. +</DD> + +<DT>SMARTDATETIME</DT> +<DD> +This is a combination of SMARTDATE and SMARTTIME. +It is SMARTDATE unless the SMARTDATE value is "Today", in which +case it is SMARTTIME. +See the SMARTDATETIME alternatives below, as well. +</DD> + +<DT>DATEISO</DT> +<DD> +This token represents the date on which the message was sent, according +to the "Date" header field. +It has the format YYYY-MM-DD. For example, "1998-10-23". +</DD> + +<DT>SHORTDATEISO</DT> +<DD> +This token represents the date on which the message was sent, according +to the "Date" header field. +It has the format YY-MM-DD. For example, "98-10-23". +</DD> + +<DT>SHORTDATE1</DT> +<DD> +This token represents the date on which the message was sent, according +to the "Date" header field. +It has the format MM/DD/YY. For example, "10/23/98". +</DD> + +<DT>SHORTDATE2</DT> +<DD> +This token represents the date on which the message was sent, according +to the "Date" header field. +It has the format DD/MM/YY. For example, "23/10/98". +</DD> + +<DT>SHORTDATE3</DT> +<DD> +This token represents the date on which the message was sent, according +to the "Date" header field. +It has the format DD.MM.YY. For example, "23.10.98". +</DD> + +<DT>SHORTDATE4</DT> +<DD> +This token represents the date on which the message was sent, according +to the "Date" header field. +It has the format YY.MM.DD. For example, "98.10.23". +</DD> + +<DT>LONGDATE</DT> +<DD> +This token represents the date on which the message was sent, according +to the "Date" header field. +It has the format MMM DD, YYYY. For example, "Oct 23, 1998". +</DD> + +<DT>SMARTDATE alternatives</DT> +<DD> +There are several versions of SMARTDATE which are all the same except +for the way they format dates far in the past. +SMARTDATE formats the date using the information from your locale settings +to format the date string. It may end up formatting dates so that they look +like DATEISO tokens, or SHORTDATE2 tokens, or something else entirely. +The feature +<A HREF="#convert-dates-to-localtime"><EM>convert-dates-to-localtime</EM></A> +may have an affect on the values of these tokens. +If you want more control you may use one of the following. + <DL> + <DT>SMARTDATE</DT> <DD>If the option +<A HREF="#disable-index-locale-dates"><EM>Disable-Index-Locale-Dates</EM></A> is not set +then this will be locale specific. Control this with the +LC_TIME locale setting on a UNIX system. On Windows +the Regional Options control panel may be used to set the Short date +format. At the programming level, the strftime routine is what <EM>Alpine</EM> +uses to print the date. +If the Disable-Index-Locale-Dates option is set then this is equivalent +to SMARTDATES1.</DD> + <DT>SMARTDATEISO</DT> <DD>DATEISO format. See text above.</DD> + <DT>SMARTDATESHORTISO</DT> <DD>SHORTDATEISO format.</DD> + <DT>SMARTDATES1</DT> <DD>SHORTDATE1 format.</DD> + <DT>SMARTDATES2</DT> <DD>SHORTDATE2 format.</DD> + <DT>SMARTDATES3</DT> <DD>SHORTDATE3 format.</DD> + <DT>SMARTDATES4</DT> <DD>SHORTDATE4 format.</DD> + </DL> +</DD> + +<DT>SMARTDATETIME alternatives</DT> +<DD> +There are several versions of SMARTDATETIME which are all very similar. +The ones which end in 24 use a 24-hour clock for Today's messages instead +of a 12-hour clock. +The other variation is +for the way they format dates far in the past. +SMARTDATETIME and SMARTDATETIME24 format the date using the information from your locale settings +to format the date string. It may end up formatting dates so that they look +like DATEISO tokens, or SHORTDATE2 tokens, or something else entirely. +The feature +<A HREF="#convert-dates-to-localtime"><EM>convert-dates-to-localtime</EM></A> +may have an affect on the values of these tokens. +The possible choices are: + <DL> + <DT>SMARTDATETIME</DT> <DD>Locale specific. Control this with the +LC_TIME locale setting on a UNIX system. On Windows +the Regional Options control panel may be used to set the Short date +format. At the programming level, the strftime routine is what <EM>Alpine</EM> +uses to print the date.</DD> + <DT>SMARTDATETIME</DT> <DD>If the option +<A HREF="#disable-index-locale-dates"><EM>Disable-Index-Locale-Dates</EM></A> is not set +then this will be locale specific. Control this with the +LC_TIME locale setting on a UNIX system. On Windows +the Regional Options control panel may be used to set the Short date +format. At the programming level, the strftime routine is what <EM>Alpine</EM> +uses to print the date. +If the Disable-Index-Locale-Dates option is set then this is equivalent +to SMARTDATETIMES1.</DD> + <DT>SMARTDATETIME24</DT> <DD>Use TIME24 for Today</DD> + <DT>SMARTDATETIMEISO</DT> <DD>DATEISO format. See text above.</DD> + <DT>SMARTDATETIMEISO24</DT> <DD>Use TIME24 for Today</DD> + <DT>SMARTDATETIMESHORTISO</DT> <DD>SHORTDATEISO format.</DD> + <DT>SMARTDATETIMESHORTISO24</DT> <DD>Use TIME24 for Today</DD> + <DT>SMARTDATETIMES1</DT> <DD>SHORTDATE1 format.</DD> + <DT>SMARTDATETIMES124</DT> <DD>Use TIME24 for Today</DD> + <DT>SMARTDATETIMES2</DT> <DD>SHORTDATE2 format.</DD> + <DT>SMARTDATETIMES224</DT> <DD>Use TIME24 for Today</DD> + <DT>SMARTDATETIMES3</DT> <DD>SHORTDATE3 format.</DD> + <DT>SMARTDATETIMES324</DT> <DD>Use TIME24 for Today</DD> + <DT>SMARTDATETIMES4</DT> <DD>SHORTDATE4 format.</DD> + <DT>SMARTDATETIMES424</DT> <DD>Use TIME24 for Today</DD> + </DL> +</DD> + +<DT>DAYDATE</DT> +<DD> +This token represents the date on which the message was sent, according +to the "Date" header field. +It looks like "Sat, 23 Oct 1998". +This token is never converted in any locale-specific way. +</DD> + +<DT>PREFDATE</DT> +<DD> +This token represents the date on which the message was sent, according +to the "Date" header field. +It is your operating system's idea of the preferred date representation for the current locale. +Internally it uses the %x version of the date from the strftime routine. +</DD> + +<DT>PREFTIME</DT> +<DD> +This token represents the time at which the message was sent, according +to the "Date" header field. +It is the preferred time representation for the current locale. +Internally it uses the %X version of the time from the strftime routine. +</DD> + +<DT>PREFDATETIME</DT> +<DD> +This token represents the date and time at which the message was sent, according +to the "Date" header field. +It is the preferred date and time representation for the current locale. +Internally it uses the %c version of the time from the strftime routine. +</DD> + +<DT>DAY</DT> +<DD> +This token represents the day of the month on which the message was sent, +according to the "Date" header field. +For example, "23" or "9". +</DD> + +<DT>DAY2DIGIT</DT> +<DD> +This token represents the day of the month on which the message was sent, +according to the "Date" header field. +For example, "23" or "09". +It is always 2 digits. +</DD> + +<DT>DAYORDINAL</DT> +<DD> +This token represents the ordinal number which is the day of +the month on which the message was sent, +according to the "Date" header field. +For example, "23rd" or "9th". +</DD> + +<DT>DAYOFWEEK</DT> +<DD> +This token represents the day of the week on which the message was sent, +according to the "Date" header field. +For example, "Sunday" or "Wednesday". +</DD> + +<DT>DAYOFWEEKABBREV</DT> +<DD> +This token represents the day of the week on which the message was sent, +according to the "Date" header field. +For example, "Sun" or "Wed". +</DD> + +<DT>MONTHABBREV</DT> +<DD> +This token represents the month the message was sent, according +to the "Date" header field. +For example, "Oct". +</DD> + +<DT>MONTHLONG</DT> +<DD> +This token represents the month in which the message was sent, according +to the "Date" header field. +For example, "October". +</DD> + +<DT>MONTH</DT> +<DD> +This token represents the month in which the message was sent, according +to the "Date" header field. +For example, "10" or "9". +</DD> + +<DT>MONTH2DIGIT</DT> +<DD> +This token represents the month in which the message was sent, according +to the "Date" header field. +For example, "10" or "09". +It is always 2 digits. +</DD> + +<DT>YEAR</DT> +<DD> +This token represents the year the message was sent, according +to the "Date" header field. +For example, "1998" or "2001". +</DD> + +<DT>YEAR2DIGIT</DT> +<DD> +This token represents the year the message was sent, according +to the "Date" header field. +For example, "98" or "01". +It is always 2 digits. +</DD> + +<DT>TIME24</DT> +<DD> +This token represents the time at which the message was sent, according +to the "Date" header field. +There is no adjustment made for different time zones, so you'll get +the time the message was sent according to the time zone the sender +was in. +It has the format HH:MM. For example, "17:28". +</DD> + +<DT>TIME12</DT> +<DD> +This token represents the time at which the message was sent, according +to the "Date" header field. +This time is for a 12 hour clock. +It has the format HH:MMpm. +For example, "5:28pm" or "11:13am". +</DD> + +<DT>TIMEZONE</DT> +<DD> +This token represents the numeric timezone from +the "Date" header field. +It has the format [+-]HHMM. For example, "-0800". +</DD> + +</DL> + +<P> +<H3><EM>Tokens Available Only for Index-Format</EM></H3> + +<DL> +<DT>MSGNO</DT> +<DD> +This token represents the message's current position in the folder which, +of course, may change as the folder is sorted or new mail arrives. +</DD> + +<DT>STATUS</DT> +<DD> +This token represents a three character wide field displaying various +aspects of the message's state. +The first character is either blank, +a '*' for message marked Important, or a '+' indicating a message +addressed directly to you (as opposed to your having received it via a +mailing list, for example). +When the feature +<A HREF="#mark-for-cc"><EM>mark-for-cc</EM></A> +is set, if the first character would have been +blank then it will instead be a '-' if the message is cc'd to you. +The second character is typically blank, +though the arrow cursor may occupy it if either the +<A HREF="#assume-slow-link"><EM>assume-slow-link</EM></A> +or the +<A HREF="#force-arrow-cursor"><EM>force-arrow-cursor</EM></A> feature +is set (or you actually are on a slow link). +The third character is either D (Deleted), +A (Answered), +N (New), or blank. +<P> +If you are using a threaded view of the index and this message is at the +top of a collapsed portion of a thread, +then this token refers to all of the messages in the collapsed portion of +the thread instead of just the top message. +The first character will be a '*' if <EM>any</EM> of the messages in the thread +are marked Important, else a '+' if any of the messages are addressed +to you, else a '-' if any of the messages are cc'd to you. +The third character will be a 'D' if <EM>all</EM> of the messages +in the collapsed thread are marked deleted, +an 'A' if <EM>all</EM> of the messages +in the collapsed thread are marked answered, +it will be an 'N' if any of +the messages are undeleted and unseen, and it will be blank otherwise. +</DD> + +<DT>FULLSTATUS</DT> +<DD> +This token represents a less abbreviated alternative +to the "STATUS" token. +It is six characters wide. +The first character is '+', '-', or blank, the +second blank, the third either '*' or blank, the fourth +N or blank, +the fifth A +or blank, and the sixth character is +either D or +blank. +<P> +If you are using a threaded view of the index and this message is at the +top of a collapsed portion of a thread, +then this token refers to all of the messages in the collapsed portion of +the thread instead of just the top message. +The first character is '+', '-', or blank depending on whether <EM>any</EM> +of the messages in the collapsed thread are addressed to you or cc'd to you. +The third character will be '*' if any of the messages are marked +Important. +The fourth character will be 'N' if all of the messages in the thread +are New, else 'n' if some of the messages in the thread are New, else blank. +The fifth character will be 'A' or 'a' or blank, and the sixth character +will be 'D' or 'd' or blank. +</DD> + +<DT>IMAPSTATUS</DT> +<DD> +This token represents an even less abbreviated alternative to the +"STATUS" token. +It differs from "FULLSTATUS" in only the fourth character which is +an 'N' if the message is new to this folder since the last time +it was opened <EM>and</EM> it has not been viewed, an 'R' (Recent) if the message +is new to the folder and has been viewed, a 'U' (Unseen) if the message is not +new to the folder since it was last opened <EM>but</EM> has not been +viewed, or a blank if the message has been in the folder since it was +last opened and has been viewed. +<P> +If you are using a threaded view of the index and this message is at the +top of a collapsed portion of a thread, +then the fourth character will be +'N' if all of the messages in the thread are unseen and recent; +else 'n' if some of the messages in the thread are unseen and recent; +else 'U' if all of the messages in the thread are unseen and not recent; +else 'u' if some of the messages in the thread are unseen and not recent; +else 'R' if all of the messages in the thread are seen and recent; +else 'r' if some of the messages in the thread are seen and recent; +else blank. +</DD> + +<DT>SHORTIMAPSTATUS</DT> +<DD> +This is the same as the last four of the six characters of IMAPSTATUS, +so the '+' To Me information will be missing. +</DD> + +<DT>SIZE</DT> +<DD> +This token represents the total size, in bytes, of the message. +If a "K" (Kilobyte) +follows the number, the size is approximately 1,000 +times that many bytes (rounded to the nearest 1,000). +If an "M" (Megabyte) follows the number, the size is approximately +1,000,000 times that many bytes. +Commas are not used in this field. +This field is seven characters wide, including the enclosing parentheses. +Sizes are rounded when "K" or "M" is present. +The progression of sizes used looks like: + +<P> +<CENTER><SAMP>0 1 ... 9999 10K ... 999K 1.0M ... 99.9M 100M ... 2000M</SAMP></CENTER> +<P> +</DD> + +<DT>SIZECOMMA</DT> +<DD> +This token represents the total size, in bytes, of the message. +If a "K" (Kilobyte) +follows the number, the size is approximately 1,000 +times that many bytes (rounded to the nearest 1,000). +If an "M" (Megabyte) follows the number, the size is approximately +1,000,000 times that many bytes. +Commas are used if the number shown is 1,000 or greater. +The SIZECOMMA field is one character wider than the SIZE field. +Sizes are rounded when "K" or "M" is present. +The progression of sizes used looks like: + +<P> +<CENTER><SAMP>0 1 ... 99,999 100K ... 9,999K 10.0M ... 999.9M 1,000M ... 2,000M</SAMP></CENTER> +<P> +</DD> + +<DT>KSIZE</DT> +<DD> +This token represents the total size of the message, expressed in +kilobytes or megabytes, as most appropriate. +These are 1,024 byte kilobytes and 1,024 x 1,024 byte megabytes. +The progression of sizes used looks like: + +<P> +<CENTER><SAMP>0K 1K ... 1023K 1.0M ... 99.9M 100M ... 2047M</SAMP></CENTER> +<P> +</DD> + +<DT>SIZENARROW</DT> +<DD> +This token represents the total size, in bytes, of the message. +If a "K" (Kilobyte) +follows the number, the size is approximately 1,000 +times that many bytes. +If an "M" (Megabyte) follows the number, the size is approximately +1,000,000 times that many bytes. +If a "G" (Gigabyte) follows the number, the size is approximately +1,000,000,000 times that many bytes. +This field uses only five characters of screen width, including the enclosing +parentheses. +The progression of sizes used looks like: + +<P> +<CENTER><SAMP>0 1 ... 999 1K ... 99K .1M ... .9M 1M ... 99M .1G ... .9G 1G 2G</SAMP></CENTER> +<P> +</DD> + +<DT>DESCRIPSIZE</DT> +<DD> +This token is intended to represent a more useful description of the +message than just its size, but it isn't very useful at this point. +The plus sign in this view means there are attachments. +Note that including this token in +the "Index-Format" could slow down the +display a little while <EM>Alpine</EM> collects the necessary information. +</DD> + +<DT>SUBJKEY</DT> +<DD> +This token is the same as the SUBJECT token unless keywords are set for +the message. +In that case, a list of keywords enclosed in braces will be prepended to +the subject of the message. +Only those keywords that you have defined in your +<A HREF="#keywords">Keywords</A> option +in Setup/Config are considered in the list. +In other words, keywords that have been set by some other means, perhaps +by another email program, won't show up unless included in +<A HREF="#keywords">Keywords</A>. +Having this set in the Index-Format will also cause the keywords to be +prepended to the subject in the MESSAGE TEXT screen. +If you have given a keyword a nickname +(<A HREF="#keywords"><EM>keywords</EM></A>), that nickname is displayed +instead of the actual keyword. +The <A HREF="#keyword-surrounding-chars"><EM>keyword-surrounding-chars</EM></A> +option may be used to modify this token slightly. +It is also possible to color keywords in the index using the +Setup/Kolor screen. +</DD> + +<DT>SUBJKEYINIT</DT> +<DD> +This token is the same as the SUBJKEY token except that instead of +prepending a list of keywords to the subject, a list of first initials +of keywords will be prepended instead. +For example, if a message has the keywords <EM>Work</EM> and <EM>Now</EM> +set (or Work and Now are the <EM>Alpine</EM> nicknames of keywords which are set) +then the SUBJKEY token would cause a result like +<P> +<CENTER><SAMP>{Work Now} actual subject</SAMP></CENTER> +<P> +whereas the SUBJKEYINIT token would give +<P> +<CENTER><SAMP>{WN} actual subject</SAMP></CENTER> +<P> +Only those keywords that you have defined in your +<A HREF="#keywords">Keywords</A> option +in Setup/Config are considered in the list. +In other words, keywords that have been set by some other means, perhaps +by another email program, won't show up unless included in +<A HREF="#keywords">Keywords</A>. +The <A HREF="#keyword-surrounding-chars"><EM>keyword-surrounding-chars</EM></A> +option may be used to modify this token slightly. +It is also possible to color keywords in the index using the +Setup/Kolor screen. +</DD> + +<DT>SUBJECTTEXT</DT> +<DD> +Same as SUBJECT but if there is room in the Subject field for more text, +the opening part of the text of the message is displayed after the subject. +The time needed to fetch the text may cause a performance problem +which can, of course, be avoided by using the SUBJECT version of +the Subject instead. +You may color this opening text differently by using the +<A HREF="#index-opening-color"><EM>Index Opening Color</EM></A> option available from +the Setup Kolor screen. +You may adjust the characters that are displayed between the Subject and the +opening text with the option +<A HREF="#opening-text-separator-chars"><EM>Opening-Text-Separator-Chars</EM></A>. +</DD> + +<DT>SUBJKEYTEXT</DT> +<DD> +Same as SUBJKEY but with the opening message text. +</DD> + +<DT>SUBJKEYINITTEXT</DT> +<DD> +Same as SUBJKEYINIT but with the opening message text. +</DD> + +<DT>OPENINGTEXT</DT> +<DD> +This is similar to SUBJECTTEXT. +Instead of combining the Subject and the opening text in a single +field in the index screen this token allows you to allocate a +separate column just for the opening text of the message. +The time needed to fetch this text may cause a performance problem. +You may color this opening text differently by using the +<A HREF="#index-opening-color"><EM>Index Opening Color</EM></A> option available from +the Setup Kolor screen. +</DD> + +<DT>OPENINGTEXTNQ</DT> +<DD> +This is very similar to OPENINGTEXT. +The NQ stands for No Quotes. +The only difference is that quoted text (lines beginning with >) is deleted. +For some messages this may be confusing. +For example, a message might have a line preceding some quoted +text that reads something like "On May 8th person A said." +That no longer makes sense after the quoted text is deleted and it +will appear that person A said whatever the text after the quote +is, even though that is really person B talking. +</DD> + +<DT>KEY</DT> +<DD> +This is a space-delimited list of keywords that are set for the message. +Only those keywords that you have defined in your +<A HREF="#keywords">Keywords</A> option +in Setup/Config are considered in the list. +In other words, keywords that have been set by some other means, perhaps +by another email program, won't show up unless included in +<A HREF="#keywords">Keywords</A>. +If you have given a keyword a nickname +that nickname is displayed +instead of the actual keyword. +It is also possible to color keywords in the index using the +Setup/Kolor screen. +This token defaults to an arbitrary width of 5. +You should set it to whatever width suits you using something +like KEY(17) in the Index-Format. +</DD> + +<DT>KEYINIT</DT> +<DD> +This is a list of keyword initials that are set for the message. +If you have given a keyword a nickname +the initial of that nickname +is displayed instead of the initial of the actual keyword. +It is also possible to color keyword initials in the index using the +Setup/Kolor screen. +This token defaults to an arbitrary width of 2. +You should set it to whatever width suits you using something +like KEYINIT(3) in the Index-Format. +</DD> + +<DT>PRIORITY</DT> +<DD> +The X-Priority header is a non-standard header that is used in a +somewhat standard way by many mail programs. +<EM>Alpine</EM> expects the value of this header to be a digit with a value +from 1 to 5, with 1 being the highest priority and 5 the lowest priority. +Since this priority is something that the sender sets it is only an indication +of the priority that the sender attaches to the mail and it is therefore almost +totally unreliable for use as a filtering criterion. +This token will display the numeric value of the priority if it is between +1 and 5. +It will be suppressed (blank) if the value is 3, which is normal priority. +It is also possible to set the color of the PRIORITY field. +By default the token is colored the same +as the index line it is part of. +You may set it to be another color with the +<A HREF="#index-pri-color">Index Priority Colors</A> options available from +the Setup Kolor screen. +</DD> + +<DT>PRIORITYALPHA</DT> +<DD> +This is a more verbose interpretation of the X-Priority field. +Once again nothing is displayed unless the value of the field +is 1, 2, 4, or 5. +The values displayed for those values are: +<P> +<TABLE> +<TR> <TD>1</TD> <TD>Highest</TD> </TR> +<TR> <TD>2</TD> <TD>High</TD> </TR> +<TR> <TD>4</TD> <TD>Low</TD> </TR> +<TR> <TD>5</TD> <TD>Lowest</TD> </TR> +</TABLE> +<P> +You may color this token with the +<A HREF="#index-pri-color">Index Priority Colors</A> options. +</DD> + +<DT>PRIORITY!</DT> +<DD> +This is a one character, non-numeric version of the X-Priority field. +If the value of the X-Priority header is 1 or 2 an exclamation +point is displayed. +If the value is 4 or 5 a "v" (think down arrow) is displayed. +You may color this token with the +<A HREF="#index-pri-color">Index Priority Colors</A> options. +</DD> + +<DT>ATT</DT> +<DD> +This is a one column wide field which represents the number of attachments +a message has. It will be blank if there are no attachments, a single +digit for one to nine attachments, or an asterisk for more than nine. +Note that including this token in +the "Index-Format" could slow down the +display a little while <EM>Alpine</EM> collects the necessary information. +</DD> + +<DT>FROMORTO</DT> +<DD> +This token represents <EM>either</EM> the personal name (or email address) of +the person listed in the message's "From:" header +field, <EM>or</EM>, if that address is yours or one of your +<A HREF="#alt-addresses">alternate addresses</A>, +the first person specified in the +message's "To:" header field +with the prefix "To: " prepended. +If the from address is yours and there is also no "To" address, +<EM>Alpine</EM> will use the address on the "Cc" line. +If there is no address there, either, <EM>Alpine</EM> will look for a newsgroup name +from the "Newsgroups" header field and put +that after the "To: " prefix. +</DD> + +<DT>FROMORTONOTNEWS</DT> +<DD> +This is almost the same as <EM>FROMORTO</EM>. +The difference is that newsgroups aren't considered. +When a message is from you, doesn't have a To or Cc, and does have +a Newsgroups header; this token will be your name instead of the name +of the newsgroup (like it would be with FROMORTO). +</DD> + +<DT>TEXT</DT> +<DD> +This is a different sort of token. +It allows you to display a label within each index line. +It will be the same fixed text for each line. +It is different from all the other tokens in that there is no space column +displayed after this token. +Instead, it is butted up against the following field. +It also has a different syntax. +The text to display is given following a colon after the +word "TEXT". +For example, +<P> +<CENTER><SAMP>TEXT:abc=</SAMP></CENTER> +<P> +would insert the literal text "abc=" (without the quotes) +into the index display line. +You must quote the text if it includes space characters, like +<P> +<CENTER><SAMP>TEXT:"abc = "</SAMP></CENTER> +<P> +</DD> + +<DT>HEADER</DT> +<DD> +This allows you to display the text from a particular header line in the +message. +The syntax for this token is substantially different from all the others +in order that you might be able to display a portion of the text following +a particular header. +The header name you are interested in is given following a colon +after the word "HEADER". +For example, +<P> +<CENTER><SAMP>HEADER:X-Spam</SAMP></CENTER> +<P> +would display the text of the X-Spam header, if any. +Like for other index tokens a width field may (and probably should) +follow this. +<P> +<CENTER><SAMP>HEADER:X-Spam(10)</SAMP></CENTER> +<P> +displays the first ten characters of the X-Spam header. +Unlike other index tokens, the syntax for HEADER is more flexible. +An optional second argument comes after a comma inside the parentheses. +It specifies the "field" number. +By default, the field separator is a space character. +No extra space characters are allowed in the argument list. +<P> +<CENTER><SAMP>HEADER:X-Spam(10,2)</SAMP></CENTER> +<P> +would display the second field, left-justified, in a 10 character +wide field. +The second field would consist of all the text after the first space +up to the next space or the end of the header. +The default field number is zero, which stands for the entire line. +There is also an optional third argument which is a list of field +separators. It defaults to a space character. +The example +<P> +<CENTER><SAMP>HEADER:X-Spam(10,2,:% )</SAMP></CENTER> +<P> +would cause the field separators to be any of colon, percent, +or space (there is a space character between the percent and the +right parenthesis). +The first field runs from the start of the header value up to the first +colon, percent, or space; the second goes from there to the next; and so on. +In order to use a comma character as a field separator you must escape +it by preceding it with a backslash (\). +The same is true of the backslash character itself. +There is one further optional argument. +It is an R or an L to specify right or left adjustment of the text +within the field. +The default is to left justify, however if you are displaying numbers +you might prefer to right justify. +<P> +Here's an example of a SpamAssassin header. +The exact look of the header will vary, but if your incoming mail +contains headers that look like the following +<P> +<CENTER><SAMP>X-Spam-Status: Yes, hits=10.6 tagged_above=-999.0 required=7.0 tests=BAYE...</SAMP></CENTER> +<P> +you might want to display the hits value. +The first field starts with the Y in Yes. +To get what you're interested in you might use "=" and +space as the field separators and display the third field, like +<P> +<CENTER><SAMP>HEADER:X-Spam-Status(4,3,= )</SAMP></CENTER> +<P> +or maybe you would break at the dot instead +<P> +<CENTER><SAMP>HEADER:X-Spam-Status(2,2,=.,R)</SAMP></CENTER> +<P> +Another example we've seen has headers that look like +<P> +<CENTER><SAMP>X-Spam: Gauge=IIIIIII, Probability=7%, Report=...</SAMP></CENTER> +<P> +Because there are two equals and a comma before the 7% and a comma +after it, the token +<P> +<CENTER><SAMP>HEADER:X-Spam-Status(3,4,=\,,R)</SAMP></CENTER> +<P> +should display the probability (for example 7% or 83%) right justified +in a 3-wide field. +</DD> + + +<DT>ARROW</DT> +<DD> +This gives an alternative way to display the current message in the +MESSAGE INDEX screen. +Usually the current message is indicated by the line being shown in +reverse video. +Instead, if the ARROW token is included in your Index-Format, +the current line will include an "arrow" that +looks like +<P> +<CENTER><SAMP>-></SAMP></CENTER> +<P> +in the ARROW token's field. +For all of the non-current messages, the ARROW field will be filled +with blanks. +If you use the fixed-field width feature the length of the "arrow" +may be adjusted. +The arrow will be drawn as width-1 dashes followed by a greater than sign. +For example, if you use ARROW(3) you will get +<P> +<CENTER><SAMP>--></SAMP></CENTER> +<P> +and ARROW(1) will give you just +<P> +<CENTER><SAMP>></SAMP></CENTER> +<P> +It is also possible to set the color of the ARROW field. +By default (and for non-current messages) the arrow is colored the same +as the index line it is part of. +You may set it to be another color with the +<A HREF="#index-arrow-color">Index Arrow Color</A> option available from +the Setup Kolor screen. +</DD> + +<DT>SCORE</DT> +<DD> +This gives the +score +of each message. +This will be six columns wide to accomodate the widest possible score. +You will probably want to use the Index-Format fixed-field width feature +to limit the width of the field to the widest score that +you use (e.g. SCORE(3) if your scores are always between 0 and 999). +If you have not defined any score rules the scores will all be zero. +If any of your score rules contain AllText or BodyText patterns +then including SCORE in the Index-Format +may slow down the display of the MESSAGE INDEX screen. +</DD> +</DL> + +<P> +<H3><EM>Tokens Available for all but Index-Format</EM></H3> + +<DL> +<DT>CURNEWS</DT> +<DD> +This token represents the current newsgroup if there is one. +For example, "comp.mail.pine". +</DD> + +<DT>MSGID</DT> +<DD> +This token represents the message ID of the message. +This token does not work with Filter Rule folder names. +</DD> + +<DT>CURDATE</DT> +<DD> +This token represents the current date. +It has the format MMM DD. For example, "Oct 23". +</DD> + +<DT>CURDATEISO</DT> +<DD> +This token represents the current date. +It has the format YYYY-MM-DD. For example, "1998-10-23". +</DD> + +<DT>CURDATEISOS</DT> +<DD> +This token represents the current date. +It has the format YY-MM-DD. For example, "98-10-23". +</DD> + +<DT>CURPREFDATE</DT> +<DD> +This token represents the current date. +It is your operating system's idea of the preferred date representation for the current locale. +Internally it uses the %x version of the date from the strftime routine. +</DD> + +<DT>CURPREFTIME</DT> +<DD> +This token represents the current time. +It is the preferred time representation for the current locale. +Internally it uses the %X version of the time from the strftime routine. +</DD> + +<DT>CURPREFDATETIME</DT> +<DD> +This token represents the current date and time. +It is the preferred date and time representation for the current locale. +Internally it uses the %c version of the time from the strftime routine. +</DD> + +<DT>CURTIME24</DT> +<DD> +This token represents the current time. +It has the format HH:MM. For example, "17:28". +</DD> + +<DT>CURTIME12</DT> +<DD> +This token represents the current time. +This time is for a 12 hour clock. +It has the format HH:MMpm. +For example, "5:28pm" or "11:13am". +</DD> + +<DT>CURDAY</DT> +<DD> +This token represents the current day of the month. +For example, "23" or "9". +</DD> + +<DT>CURDAY2DIGIT</DT> +<DD> +This token represents the current day of the month. +For example, "23" or "09". +It is always 2 digits. +</DD> + +<DT>CURDAYOFWEEK</DT> +<DD> +This token represents the current day of the week. +For example, "Sunday" or "Wednesday". +</DD> + +<DT>CURDAYOFWEEKABBREV</DT> +<DD> +This token represents the current day of the week. +For example, "Sun" or "Wed". +</DD> + +<DT>CURMONTH</DT> +<DD> +This token represents the current month. +For example, "10" or "9". +</DD> + +<DT>CURMONTH2DIGIT</DT> +<DD> +This token represents the current month. +For example, "10" or "09". +It is always 2 digits. +</DD> + +<DT>CURMONTHLONG</DT> +<DD> +This token represents the current month. +For example, "October". +</DD> + +<DT>CURMONTHABBREV</DT> +<DD> +This token represents the current month. +For example, "Oct". +</DD> + +<DT>CURYEAR</DT> +<DD> +This token represents the current year. +For example, "1998" or "2001". +</DD> + +<DT>CURYEAR2DIGIT</DT> +<DD> +This token represents the current year. +For example, "98" or "01". +It is always 2 digits. +</DD> + +<DT>LASTMONTH</DT> +<DD> +This token represents last month. +For example, if this is November (the 11th month), +it is equal to "10" or if this is October (the 10th month), +it is "9". +It is possible that this and the other tokens beginning with LASTMONTH +below could be useful when used with a Filtering Rule that +has the "Beginning of Month" option set. +</DD> + +<DT>LASTMONTH2DIGIT</DT> +<DD> +This token represents last month. +For example, if this is November (the 11th month), +it is equal to "10" or if this is October (the 10th month), +it is "09". +It is always 2 digits. +</DD> + +<DT>LASTMONTHLONG</DT> +<DD> +This token represents last month. +For example, if this is November the value is "October". +</DD> + +<DT>LASTMONTHABBREV</DT> +<DD> +This token represents last month. +For example, if this is November the value is "Oct". +</DD> + +<DT>LASTMONTHYEAR</DT> +<DD> +This token represents what the year was a month ago. +For example, if this is October, 1998, it is "1998". +If this is January, 1998, it is "1997". +</DD> + +<DT>LASTMONTHYEAR2DIGIT</DT> +<DD> +This token represents what the year was a month ago. +For example, if this is October, 1998, it is "98". +If this is January, 1998, it is "97". +</DD> + +<DT>LASTYEAR</DT> +<DD> +This token represents last year. +For example, if this is 1998, it equals "1997". +It is possible that this +could be useful when used with a Filtering Rule that +has the "Beginning of Year" option set. +</DD> + +<DT>LASTYEAR2DIGIT</DT> +<DD> +This token represents last year. +For example, if this is 1998, it equals "97". +It is always 2 digits. +</DD> + +<DT>ROLENICK</DT> +<DD> +This token represents the nickname of the +role currently being used. If no role is being used, +then no text will be printed for this token. +This token does not work with Filter Rule folder names. +</DD> +</DL> + +<P> +<H3><EM>Token Available Only for Reply-Leadin</EM></H3> +See the help for the +<A HREF="#reply-leadin"><EM>Reply-Leadin</EM></A> option, +to see why you might want to use this. +Since the <EM>Reply-Leadin</EM> contains free text this token +must be surrounded by underscores when used. + +<DL> +<DT>NEWLINE</DT> +<DD> +This is an end of line marker. +</DD> +</DL> +<P> +<H3><EM>Token Available Only for Templates and Signatures</EM></H3> + +<DL> +<DT>CURSORPOS</DT> +<DD> +This token is different from the others. +When it is replaced it is replaced with nothing, but it sets a <EM>Alpine</EM> +internal variable which tells the composer to start with the cursor +positioned at the position where this token was. +If both the template file and the signature file contain +a "CURSORPOS" token, then the position in the template file +is used. +If there is a template file and neither it nor the signature file contains +a "CURSORPOS" token, then the cursor is positioned +after the end of the contents of the +template file when the composer starts up. +</DD> +</DL> + +<H2><A NAME="reply-token-conditionals"></A>Conditional Inclusion of Text for Reply-Leadin, Signatures, and Templates</H2> + +Conditional text inclusion may be used with +the <A HREF="#reply-leadin"><EM>Reply-Leadin</EM></A> option, +in signature files, and in template files used in +roles. +It may <EM>not</EM> be used with the +<EM>Index-Format</EM> option. + +<P> +There is a limited if-else capability for including text. +The if-else condition is based +on whether or not a given token would result in replacement text you +specify. +The syntax of this conditional inclusion is +<P> +<CENTER><SAMP>_token_(match_this, if_matched [ , if_not_matched ] )</SAMP></CENTER> +<P> +The left parenthesis must follow the underscore immediately, with no +intervening space. +It means the token is expanded and the results of that expansion are +compared against the "match_this" argument. +If there is an exact match, then the "if_matched" text is used +as the replacement text. +Otherwise, the "if_not_matched" text is used. +One of the most useful values for the "match_this" argument is +the empty string, "". +In that case the expansion is compared against the empty string. +<P> +Here's an example to make it clearer. +This text could be included in one of your template files: +<P> +<CENTER><SAMP>_NEWS_("", "I'm replying to email","I'm replying to news")</SAMP></CENTER> +<P> +If that is included in a template file which you are using while replying +to a message (because you chose to use the role it was part of), +and that message has a newsgroup header and a newsgroup in that header, +then the text +<P> +<CENTER><SAMP>I'm replying to news</SAMP></CENTER> +<P> +will be included in the message you are about to compose. +On the other hand, if the message you are replying to does not have +a newsgroup, then the text +<P> +<CENTER><SAMP>I'm replying to email</SAMP></CENTER> +<P> +would be included instead. +This would also work in signature files and in +the "Reply-Leadin" option. +If the "match_this", "if_matched", +or "if_not_matched" arguments contain +spaces, parentheses, or commas; +they have to be quoted with double quotation marks (like in the example +above). +If you want to include a literal quote in the text you must escape the +quote by preceding it with a backslash character. +If you want to include a literal backslash character you must escape it +by preceding it with another backslash. +<P> +The comma followed by "if_not_matched" is optional. +If there is no "if_not_matched" +present then no text is included if the not_matched case is true. +Here's another example: +<P> +<CENTER><SAMP>_NEWS_("", "", "This msg was seen in group: _NEWS_.")</SAMP></CENTER> +<P> +Here you can see that tokens may appear in the arguments. +The same is true for tokens with the conditional parentheses. +They may appear in arguments, +though you do have to be careful to get the quoting and escaping of +nested double quotes correct. +If this was in the signature file being used and you were replying to a message +sent to comp.mail.pine the resulting text would be: +<P> +<CENTER><SAMP>This msg was seen in group: comp.mail.pine.</SAMP></CENTER> +<P> +If you were replying to a message which wasn't sent to any newsgroup the +resulting text would be a single blank line. +The reason you'd get a blank line is because the end of the line is +outside of the conditional, so is always included. +If you wanted to get rid of that blank line you could do so by moving +the end of line inside the conditional. +In other words, it's ok to have multi-line +"if_matched" or "if_not_matched" arguments. +The text just continues until the next double quotation, even if it's not +on the same line. +<P> +Here's one more (contrived) example illustrating a matching argument +which is not the empty string. +<P> +<CENTER><SAMP>_SMARTDATE_("Today", _SMARTDATE_, "On _DATE_") _FROM_ wrote:</SAMP></CENTER> +<P> +If this was the value of your "Reply-Leadin" option and you +were replying to +a message which was sent today, then the value of the "Reply-Leadin" +would be +<P> +<CENTER><SAMP>Today Fred Flintstone wrote:</SAMP></CENTER> +<P> +But if you were replying to a message sent on Oct. 27 (and that wasn't +today) you would get +<P> +<CENTER><SAMP>On Oct 27 Fred Flintstone wrote:</SAMP></CENTER> +<P> + +<H2><A NAME="per-server-ldap-config"></A>Per Server Directory Configuration</H2> + +This is only available if <EM>Alpine</EM> was built with LDAP support. +If that's the case, there will be a Directory option underneath the Setup +command on the Main Menu. +Each server that is defined there has several configuration variables +which control the behavior when using it. + +<DL COMPACT> + +<DT> <A NAME="ldap-server"><EM>ldap-server</EM></A> + +<DD> This is the name of the host where an LDAP server is running. +<P> +To find out whether your organization has its own LDAP server, +contact its computing support staff. +<P> + +<DT> <A NAME="search-base"><EM>search-base</EM></A> + +<DD> This is the search base to be used on this server. +It functions as a filter +by restricting your searches in the LDAP server database +to the specified contents of the specified fields. +Without it, searches submitted to this directory server may fail. +It might be something like: + +<PRE> + O = <Your Organization Name>, C = US +</PRE> + +or it might be blank. +(Some LDAP servers actually ignore anything specified here.) +<P> + +If in doubt what parameters you should specify here, +contact the maintainers of the LDAP server. +<P> + +<DT> <A NAME="port"><EM>port</EM></A> + +<DD> This is the TCP port number to be used with this LDAP server. +If you leave this blank port <CODE>389</CODE> will be used. +<P> + +<DT> <A NAME="ldap-nickname"><EM>nickname</EM></A> + +<DD> This is a nickname to be used in displays. +If you don't supply a nickname the server name from +"ldap-server" will be used instead. +This option is strictly for your convenience. +<P> + +<DT> <A NAME="use-implicitly-from-composer"><EM>use-implicitly-from-composer</EM></A> + +<DD> Set this feature to have lookups done to this server implicitly from +the composer. +If an address doesn't look like a fully-qualified address, it will be looked +up in your address books, and if it doesn't match a nickname there, then it +will be looked up on the LDAP servers which have this feature set. +The lookups will also be done when using the address completion feature +(TAB command) in the composer if any of the serves have this feature set. +Also see the LDAP feature +<A HREF="#lookup-addrbook-contents"><EM>lookup-addrbook-contents</EM></A> +and the Setup/Config feature +<A HREF="#ldap-result-to-addrbook-add"><EM>ldap-result-to-addrbook-add</EM></A>. +<P> + +<DT> <A NAME="lookup-addrbook-contents"><EM>lookup-addrbook-contents</EM></A> + +<DD> Normally implicit LDAP lookups from the composer are done only for the +strings you type in from the composer screen. In other words, you type in +something in the To or CC field and press return, then the string is looked up. +First that string is looked up in your address books. If a match is found +there, then the results of that match are looked up again. If you place +a string in your address book that you want to have looked up on the LDAP +directory server, you need to turn on this feature. If you set this feature +for a server, you almost always will also want to set the +<A HREF="#use-implicitly-from-composer"><EM>use-implicitly-from-composer</EM></A> +feature. +An example might serve to best illustrate this feature. +<P> +If an LDAP lookup of "William Clinton" normally returns an +entry with an +address of pres@whitehouse.gov, then you might put an entry in your address +book that looks like: +<PRE> + Nickname Address + bill "William Clinton" +</PRE> +Now, when you type "bill" into an +address field in the composer <EM>Alpine</EM> will +find the "bill" entry in your address book. +It will replace "bill" with +"William Clinton". +It will then search for an entry with that nickname +in your address book and not find one. If this feature +is set, <EM>Alpine</EM> will then attempt to lookup +"William Clinton" on the LDAP server and find the entry with address +pres@whitehouse.gov. +<P> +A better way to accomplish the same thing is probably to use the feature +<A HREF="#save-search-criteria-not-result"><EM>save-search-criteria-not-result</EM></A>. +<P> + +<DT> <A NAME="save-search-criteria-not-result"><EM>save-search-criteria-not-result</EM></A> + +<DD> Normally when you save the results of an LDAP directory lookup to your +address book the <EM>results</EM> of the lookup are saved. +If this feature is set +and the entry being saved was found on this directory server, then the +search <EM>criteria</EM> is saved instead of the <EM>results</EM> of the search. +When this address book entry is used in the future, instead of copying +the results from the address book the directory lookup will be done again. +This could be useful if the copied result might become stale because the data on +the directory server changes (for example, the entry's email address changes). +You probably don't want to set this feature if the server is at all slow or +unreliable. +<P> +The way this actually works is that instead of saving the email address +in your address book, <EM>Alpine</EM> saves enough +information to look up the same directory entry again. +In particular, it saves the server name and the +distinguished name of the entry. +It's possible that the server administrators +might change the format of distinguished names on the server, or that the +entry might be removed from the server. If <EM>Alpine</EM> notices this, you will be warned +and a backup copy of the email address will be used. You may want to create +a new entry in this case, since you will get the annoying warning every +time you use the old entry. You may do that by Saving the entry to a new +nickname in the same address book. You will be asked whether or not you +want to use the backup email address. +<P> +A related feature in the Setup/Config screen is +<A HREF="#ldap-result-to-addrbook-add"><EM>ldap-result-to-addrbook-add</EM></A>. +<P> + +<DT> <A NAME="disable-ad-hoc-space-substitution"><EM>disable-ad-hoc-space-substitution</EM></A> + +<DD> Spaces in your input are normally handled specially. +Each space character is replaced +by +<PRE> + * <SPACE> +</PRE> +in the search query (but not by "* <SPACE> *"). +The reason this is done is so the input string +<PRE> + Greg Donald +</PRE> +(which is converted to "Greg* Donald") will match +the names "Greg Donald", +"Gregory Donald", "Greg F. Donald", and +"Gregory F Donald"; but it won't match "Greg McDonald". +If the "Search-Rule" you were using was "begins-with", +then it would also match the name "Greg Donaldson". +<P> +Turning on this feature will disable this substitution. +<P> + +<DT> <A NAME="search-type"><EM>search-type</EM></A> + +<DD> This affects the way that LDAP searches are done. +In particular, this tells the server where to look for the string to be matched. +If set to "name" then the string that is being searched for will +be compared with the string in the +"Name" field on the server +(technically, it is the "commonname" field on the server). +"Surname" means we're looking for a +match in the "Surname" field on the +server (actually the "sn" field). +"Givenname" really is "givenname" +and "email" is the electronic mail address (this is actually the field +called "mail" or "electronicmail" on the server). +The other three types are combinations of +the types listed so far. "Name-or-email" +means the string should appear +in either the "name" field OR the "email" field. +Likewise, "surname-or-givenname" +means "surname" OR "givenname" +and "sur-or-given-or-name-or-email" means the obvious thing. +<P> +This search <EM>type</EM> is combined with the +search <A HREF="#search-rule"><EM>rule</EM></A> +to form the actual search query. +<P> +The usual default value for this +option is "sur-or-given-or-name-or-email". +This type of search may be slow on some servers. +Try "name-or-email", which is often +faster, or just "name" if the performance seems to be a problem. +<P> +Some servers have been configured with different attribute names for +these four fields. +In other words, instead of using the attribute name "mail" +for the email address field, the server might be configured to use something +else, for example, "rfc822mail" or "internetemailaddress". +<EM>Alpine</EM> can be configured to use these different attribute names by using +the four per-server configuration options: +<P><UL> +<LI><A HREF="#email-attribute"><EM>email-attribute</EM></A> +</UL> +<P><UL> +<LI><A HREF="#name-attribute"><EM>name-attribute</EM></A> +</UL> +<P><UL> +<LI><A HREF="#surname-attribute"><EM>surname-attribute</EM></A> +</UL> +<P><UL> +<LI><A HREF="#givenname-attribute"><EM>givenname-attribute</EM></A> +</UL> +<P> + +<DT> <A NAME="search-rule"><EM>search-rule</EM></A> + +<DD> This affects the way that LDAP searches are done. +If set to "equals" then +only exact matches count. +"Contains" means that the string you type in +is a substring of what you are matching against. +"Begins-with" and "ends-with" +mean that the string starts or ends with the string you type in. +<P> +Spaces in your input are normally handled specially, but you can turn that +special handling off with the +<A HREF="#disable-ad-hoc-space-substitution"><EM>disable-ad-hoc-space-substitution</EM></A> +feature. +<P> +The usual default value for this option is <EM>begins-with</EM>. +<P> + +<DT> <A NAME="email-attribute"><EM>email-attribute</EM></A> + +<DD> This is the name of the attribute which is searched for when looking for +an email address. The default value for this option is "mail" or +"electronicmail". +If the server you are using uses a different attribute name for the email +address, put that attribute name here. +<P> +This will affect the search filter used if your Search-Type is one that +contains a search for "email". +It will also cause the attribute value matching this attribute name to be used +as the email address when you look up an entry from the composer. +<P> + +<DT> <A NAME="name-attribute"><EM>name-attribute</EM></A> + +<DD> This is the name of the attribute which is searched for when looking for +the name of the entry. The default value for this option is "cn", which +stands for common name. +If the server you are using uses a different attribute name for the name, +put that attribute name here. +This will affect the search filter used if your Search-Type is one that +contains a search for "name". +<P> + +<DT> <A NAME="surname-attribute"><EM>surname-attribute</EM></A> + +<DD> This is the name of the attribute which is searched for when looking for +the surname of the entry. The default value for this option is "sn". +If the server you are using uses a different attribute name for the surname, +put that attribute name here. +This will affect the search filter used if your Search-Type is one that +contains a search for "surname". +<P> + +<DT> <A NAME="givenname-attribute"><EM>givenname-attribute</EM></A> + +<DD> This is the name of the attribute which is searched for when looking for +the given name of the entry. The default value for this option is "givenname". +If the server you are using uses a different attribute name for the given name, +put that attribute name here. +This will affect the search filter used if your Search-Type is one that +contains a search for "givenname". +<P> + +<DT> <A NAME="timelimit"><EM>timelimit</EM></A> + +<DD> This places a limit on the number of seconds the LDAP search will continue. +The default is 30 seconds. A value of 0 means no limit. Note that some servers +may place limits of their own on searches. +<P> + +<DT> <A NAME="sizelimit"><EM>sizelimit</EM></A> + +<DD> This places a limit on the number of entries returned by the LDAP server. +A value of 0 means no limit. The default is 0. Note that some servers +may place limits of their own on searches. +<P> + +<DT> <A NAME="custom-search-filter"><EM>custom-search-filter</EM></A> + +<DD> This one is for advanced users only! If you define this, then the +<A HREF="#search-type"><EM>search-type</EM></A> +and +<A HREF="#search-rule"><EM>search-rule</EM></A> +defined are both ignored. +However, the feature +<A HREF="#disable-ad-hoc-space-substitution"><EM>disable-ad-hoc-space-substitution</EM></A> +is still in effect. +That is, the space substitution will take place even in a custom filter unless +you disable it. +<P> +If your LDAP service stops working and you suspect it might be because +of your custom filter, just delete this filter and try using the +<EM>search-type</EM> and <EM>search-rule</EM> instead. +Another option that sometimes causes trouble is the +<A HREF="#search-base"><EM>search-base</EM></A> option. +<P> +This variable may be set to the string representation of an LDAP search +filter (see RFC1960). In the places where you want the address string to be +substituted in, put a '%s' in this filter string. Here are some examples: +<P> +A "Search-Type" of "name" with "Search-Rule" of "begins-with" +is equivalent to the "custom-search-filter" +<PRE> + (cn=%s*) +</PRE> +When you try to match against the string "string" the program replaces +the "%s" with "string" (without the quotes). You may have multiple "%s"'s and +they will all be replaced with the string. There is a limit of 10 "%s"'s. +<P> +A "Search-Type" of "name-or-email" with "Search-Rule" +of "contains" is equivalent to +<PRE> + (|(cn=*%s*)(mail=*%s*)) +</PRE> +<P> +If your server uses a different attribute <EM>name</EM> than +<EM>Alpine</EM> uses by default, +(for example, it uses "rfc822mail" instead of "mail"), +then you may be able to use one or more of the four attribute configuration +options instead of defining a custom filter: +<P><UL> +<LI><A HREF="#email-attribute"><EM>email-attribute</EM></A> +</UL> +<P><UL> +<LI><A HREF="#name-attribute"><EM>name-attribute</EM></A> +</UL> +<P><UL> +<LI><A HREF="#surname-attribute"><EM>surname-attribute</EM></A> +</UL> +<P><UL> +<LI><A HREF="#givenname-attribute"><EM>givenname-attribute</EM></A> +</UL> + +</DL> +<P> + +<H2><A NAME="color-config"></A>Color Configuration</H2> + +If the terminal or terminal emulator you are using is capable of using +color (see <A HREF="#color-style"><EM>color-style</EM></A> option), +or if you are using <EM>PC-Alpine</EM>, then it is possible to +set up <EM>Alpine</EM> so that various parts of the display will be +shown in colors you configure. +This is done using the Setup Color screen. +The Setup Color screen is divided into five broad sections: Options, +General Colors, Index Colors, Header Colors, and Keyword Colors. +In addition to these five categories you may also color lines in the +MESSAGE INDEX screen by configuring the +<A HREF="#index-color-config">Index Line Color</A>. +<P> +Each color is defined as a foreground color (the color of the actual text) +and a background color (the color of the area behind the text). +<P> +<H3><A NAME="color-options"></A>Color Options</H3> + +<DL> + +<DT> <A NAME="cur-il-style"><EM>current-indexline-style</EM></A> +<DD> +This option affects the colors used to display the current line in the +MESSAGE INDEX screen. +If you do not have +<A HREF="#index-color-config">Index Line Colors</A> +defined, then this option will have no effect in the index. +Those Rules may be defined by going to the Setup/Rules/Indexcolor screen. +<P> +If the option +<A HREF="#enable-incoming-folders-checking"><EM>enable-incoming-folders-checking</EM></A> +is turned on and the +<A HREF="#incoming-unseen-color"><EM>Incoming Unseen Color</EM></A> +is set to something other than the default, then +this option also affects the color used to display the current folder +in the Incoming FOLDER LIST screen. + +<P> +The available options include: +<P> + +<DL> +<DT>flip-colors</DT> +<DD>This is the default. +If an index line is colored because it matches one of your +Index Color Rules, then its colors will be reversed when it is the currently +highlighted line. +For example, if the line is normally red text on a blue background, then +when it is the current line it will be drawn as blue text on a red background. +<P> +The rest of the option values all revert to this flip-colors behavior if +there is no Reverse Color defined. +</DD> + +<DT>reverse</DT> +<DD>With this option the Reverse color is always used to highlight the +current line. +</DD> + +<DT>reverse-fg</DT> +<DD>The foreground part of the Reverse Color is used to highlight +the current line. +If this would cause the text to be unreadable (because the foreground and +background colors are the same) or if it would cause no change in the +color of the index line, then the colors are flipped instead. +<P> +Some people think this works particularly well if you use different +background colors to emphasize "interesting" lines, +but always with the same Normal foreground color, +and you use a different foreground color for the Reverse Color. +</DD> + +<DT>reverse-fg-no-ambiguity</DT> +<DD>With the "reverse-fg" rule above, it is possible that +the resulting color will be exactly the same as the regular Reverse +Color. +That can lead to some possible confusion because an +"interesting" +line which is the current line will be displayed exactly the same as a +non-interesting line which is current. +You can't tell whether the line is just a regular current line or if it is +an "interesting" current line by looking at the color. +Setting the option to this value removes that ambiguity. +It is the same as the "reverse-fg" setting unless the resulting +interesting current line would look just like a non-interesting current line. +In that case, the interesting line's colors are simply flipped (like in the +default behavior). +<P> +As an alternative way to preserve the line's interestingness in this case, +you may find that using both a different foreground and a different +background color for the interesting line will help. +</DD> + +<DT>reverse-bg</DT> +<DD>The background part of the Reverse Color is used to highlight +the current line. +If this would cause the text to be unreadable (because the foreground and +background colors are the same) or if it would cause no change in the +color of the index line, then the colors are flipped instead. +<P> +Some people think this works particularly well if you use different +foreground colors to emphasize "interesting" lines, +but always with the same Normal background color, +and you use a different background color for the Reverse Color. +</DD> + +<DT>reverse-bg-no-ambiguity</DT> +<DD>As with the "reverse-fg" case, the "reverse-bg" +rule may also result in a color which is exactly the same as the regular +Reverse Color. +Setting the option to this value removes that ambiguity. +It is the same as the "reverse-bg" setting unless the resulting +current line has the same color as the Reverse Color. +In that case, the interesting line's colors are simply flipped (like in the +default behavior). +</DD> +</DL> + +<DT> <A NAME="titlebar-style"><EM>titlebar-color-style</EM></A> +<DD> +This option affects the colors used to display the titlebar (the top +line on the screen) when viewing a message. + +<P> +The available options include: +<P> + +<DL> +<DT>default</DT> +<DD>The color of the titlebar will be the color you set for the +<A HREF="#title-color"><EM>Title Color</EM></A>. +The Title Color may be set by using the +</DD> + +<DT>indexline</DT> +<DD>The color of the titlebar will be the same as the color of the +index line corresponding to the message being viewed. +The rules which determine what color the index line will be may be set +up by going to the Setup/Rules/Indexcolor screen. +If the index line for a message is not colored explicitly by the +Indexcolor rules, then the titlebar will be colored the same as for +the "default" option above (which is not the same color that +the index line itself will have). +</DD> + +<DT>reverse-indexline</DT> +<DD>This is similar to the "indexline" option except the +foreground and background colors from the corresponding index line will +be reversed. +For example, if the index line color is red letters on a white background, +then the titlebar will be white letters on a red background. +If the index line for a message is not colored explicitly by the +Indexcolor rules, then the titlebar will be colored the same as for +the "default" option above (which is not the same color that +the index line itself will have). +</DD> +</DL> + +</DL> + +<P> +<H3><A NAME="general-colors"></A>General Colors</H3> + +<DL COMPACT> + +<DT> <A NAME="normal-color"><EM>Normal Color</EM></A> + +<DD> This is the color which most of the screen is painted in. +By default this color is black characters on a white background. +<P> + +<DT> <A NAME="reverse-color"><EM>Reverse Color</EM></A> + +<DD> The color <EM>Alpine</EM> uses for reverse video characters. +Actually, the name is misleading. This used to be reverse video and so +the name remains. It is still used to highlight certain parts of the +screen but the color may be set to whatever you'd like. +<P> + +<DT> <A NAME="title-color"><EM>Title Color</EM></A> + +<DD> The color <EM>Alpine</EM> uses for the titlebar (the top line on the +screen). +By default, the Title Color is black characters on a yellow background. +The actual titlebar color may be different from the Title Color if +the option +<A HREF="#titlebar-color-style"><EM>titlebar-color-style</EM></A> +is set to some value other than the default. +It may also be different if the current folder is closed and the +<A HREF="#title-closed-color">Title Closed Color</A> +is set to something different from the Title Color. +<P> + +<DT> <A NAME="title-closed-color"><EM>Title-closed Color</EM></A> + +<DD> The color <EM>Alpine</EM> uses for the titlebar (the top line on the +screen) when the current folder is closed. +By default, the Title Color Closed Color is white characters on a red background. +<P> + +<DT> <A NAME="status-color"><EM>Status Color</EM></A> + +<DD> The color <EM>Alpine</EM> uses for messages written to the status +message line near the bottom of the screen. +By default, the Status Color is the same as the Reverse Color. +<P> + +<DT> <A NAME="keylabel-color"><EM>KeyLabel Color</EM></A> + +<DD> The color <EM>Alpine</EM> uses for the labels of the commands in the +two-line menu at the bottom of the screen. +The label is the long name, for example, "PrevMsg". +By default, the KeyLabel Color is the same as the Normal Color. +<P> +WARNING: Some terminal emulators have the property that the screen will scroll +down one line whenever a character is written to the character cell in the +lower right corner of the screen. +<EM>Alpine</EM> can usually avoid writing a character in that corner of the screen. +However, if you have defined a KeyLabel Color then <EM>Alpine</EM> does have to write +a character in that cell in order to color the cell correctly. +If you find that your display sometimes scrolls up a line this could be +the problem. +The most obvious symptom is probably that the titlebar at the top of the +screen scrolls off the screen. +Try setting KeyLabel Color to Default to see if that fixes the problem. +<P> + +<DT> <A NAME="keyname-color"><EM>KeyName Color</EM></A> + +<DD> The color <EM>Alpine</EM> uses for the names of the commands in the +two-line menu at the bottom of the screen. +The KeyName is the shorter name in the menu. For example, the "W" +before the "WhereIs". +By default, the KeyName Color is the same as the Normal Color. +<P> + +<DT> <A NAME="selectable-item-color"><EM>Selectable-item Color</EM></A> + +<DD> The color <EM>Alpine</EM> uses for displaying selectable items, such +as URLs. +By default, the Selectable-item Color is the same as the Normal Color, except +it is also Bold. +<P> + +<DT> <A NAME="meta-message-color"><EM>Meta-message Color</EM></A> + +<DD> The color <EM>Alpine</EM> uses in the MESSAGE TEXT screen for messages to you +that aren't part of the message itself. +By default, the Meta-Message Color is black characters on a yellow background. +<P> + +<DT> <A NAME="quote-colors"><EM>Quote Colors</EM></A> + +<DD> The colors <EM>Alpine</EM> uses for coloring quoted text in the +MESSAGE TEXT screen. +If a line begins with a > character (or space followed by >) it +is considered a quote. That line will be given the Quote1 Color (first +level quote). If there is a second level of quoting then the Quote2 Color +will be used. <EM>Alpine</EM> considers there to be a second level of quoting if +that first > is followed by another > (or space followed by >). +If there are characters other than whitespace and > signs, then it isn't +considered another level of quoting. Similarly, if there is a third level +of quoting the Quote3 Color will be used. If there are more levels after +that the Quote Colors are reused. If you define all three colors then it +would repeat like Color1, Color2, Color3, Color1, Color2, Color3, ... +If you only define the first two it would be Color1, Color2, +Color1, Color2, ... +If you define only the Quote1 Color, then the entire quote would be +that color regardless of the quoting levels. +By default, the Quote1 Color is black characters on a greenish-blue background; +the Quote2 Color is black characters on a dull yellow background; and +the Quote3 Color is black characters on a green background. +<P> + +<DT> <A NAME="incoming-unseen-color"><EM>Incoming Unseen Color</EM></A> + +<DD> If the option +<A HREF="#enable-incoming-folders-checking"><EM>enable-incoming-folders-checking</EM></A> +is turned on it is possible to highlight the folders that contain +unseen messages by coloring them with this color. +By default, this is the same as the Normal Color and no highlighting is done. +<P> +Usually the "current" folder (the folder the cursor is on) +is highlighted using reverse video. +If the current folder is colored because it contains unseen messages then +the color used to show that it is also the current folder is controlled +by the <A HREF="#cur-il-style"><EM>current-indexline-style</EM></A> +feature at the top of the SETUP COLOR screen. +<P> + +<DT> <A NAME="signature-color"><EM>Signature Color</EM></A> + +<DD> The color <EM>Alpine</EM> uses for coloring the signature in the MESSAGE TEXT +screen. According to USENET conventions, the signature is defined as the +paragraph following the "sigdashes", that is, the special line +consisting of the three characters +"-- " (i.e., dash, dash, and space). <EM>Alpine</EM> allows for one +empty line right after the sigdashes to be considered as part of the +signature. +By default, the Signature Color is blue characters on a white background. +<P> + +<DT> <A NAME="prompt-color"><EM>Prompt Color</EM></A> + +<DD> The color <EM>Alpine</EM> uses for confirmation prompts and questions +which appear in the status message line near the bottom of the screen. +By default, the Prompt Color is the same as the Reverse Color. +<P> + +</DL> + +<H3><A NAME="index-colors"></A>Index Colors</H3> + +You may add color to the single character symbols which give the status +of each message in the MESSAGE INDEX. +By default the characters "+", "*", "D", +"A", and "N" show up near the left hand side of the +screen, depending on whether the message is addressed to you, and whether +the message is marked Important, is Deleted, is Answered, or is New. +You may set the color of those symbols. +By default, all of these symbols are drawn with the same color as the rest +of the index line they are a part of. +<P> +Besides coloring the message status symbols, you may also color the +entire index line. +This is done by using the +<A HREF="#index-color-config">Index Line Color</A> configuration screen. +It is also possible to color +(<A HREF="#keywords">keywords</A> +in the index using the +Setup/Kolor screen (<A HREF="#keyword-colors">Keyword Colors</A>); +the <A HREF="#index-arrow-color">ARROW</A> cursor; +the Subject using +<A HREF="#index-subject-color">Index Subject Color</A>; +the From using +<A HREF="#index-from-color">Index From Color</A>; +and the +<A HREF="#index-opening-color">Index Opening</A> text. +<P> + +<DL COMPACT> + +<DT> <A NAME="index-to-me-color"><EM>Index-to-me Symbol Color</EM></A> + +<DD> The color used for drawing the "+" symbol which signifies a +message is addressed directly to you. +<P> + +<DT> <A NAME="index-important-color"><EM>Index-important Symbol Color</EM></A> + +<DD> The color used for drawing the "*" symbol which signifies a +message has been flagged Important. +<P> + +<DT> <A NAME="index-deleted-color"><EM>Index-deleted Symbol Color</EM></A> + +<DD> The color used for drawing the "D" symbol which signifies a +message has been marked Deleted. +<P> + +<DT> <A NAME="index-answered-color"><EM>Index-answered Symbol Color</EM></A> + +<DD> The color used for drawing the "A" symbol which signifies a +message has been answered. +<P> + +<DT> <A NAME="index-new-color"><EM>Index-new Symbol Color</EM></A> + +<DD> The color used for drawing the "N" symbol which signifies a +message is New. +<P> + +<DT> <A NAME="index-recent-color"><EM>Index-recent Symbol Color</EM></A> + +<DD> The color used for drawing the "R" symbol which signifies a +message is Recent (only visible if the "IMAPSTATUS" or "SHORTIMAPSTATUS" token is +part of the +<A HREF="#index-format"><EM>index-format</EM></A> option). +<P> + +<DT> <A NAME="index-unseen-color"><EM>Index-unseen Symbol Color</EM></A> + +<DD> The color used for drawing the "U" symbol which signifies a +message is Unseen (only visible if the "IMAPSTATUS" or "SHORTIMAPSTATUS" token is +part of the +<A HREF="#index-format"><EM>Index-Format</EM></A> option). +<P> + +<DT> <A NAME="index-pri-color"><EM>Index-priority Symbol Colors</EM></A> + +<DD> The colors used for drawing the tokens "PRIORITY", + "PRIORITYALPHA", and "PRIORITY!" when these are +configured as part of the +<A HREF="#index-format"><EM>Index-Format</EM></A> option. +You may set the color used to draw these tokens by use of the colors +Index High Priority Symbol Color and Index Low Priority Symbol Color. +This coloring takes place for all but the current index line, and the Priority +Color appears to be in front of any color from an Index Color Rule. +If the priority has a value of 1 or 2 the High Priority color will be +used, +and if the value is 4 or 5 the Low Priority color will be used. +<P> +If you don't set these colors the index line will be colored in the same color as +the bulk of the index line. +<P> + +<DT> <A NAME="index-arrow-color"><EM>Index-arrow Symbol Color</EM></A> + +<DD> The color used for drawing the "ARROW" token when it is +configured as part of the +<A HREF="#index-format"><EM>Index-Format</EM></A> option. +<P> + +<DT> <A NAME="index-subject-color"><EM>Index-subject Symbol Color</EM></A> + +<DD> You may set the color used to draw the Subject part of the index line. +This coloring takes place for all but the current index line, and the Subject +Color appears to be in front of any color from an Index Color Rule. +<P> +If you don't set this color it will be colored in the same color as +the bulk of the index line. +<P> + +<DT> <A NAME="index-from-color"><EM>Index-from Symbol Color</EM></A> + +<DD> You may set the color used to draw the From part of the index line. +This coloring takes place for all but the current index line, and the From +Color appears to be in front of any color from an Index Color Rule. +<P> +If you don't set this color it will be colored in the same color as +the bulk of the index line. +<P> + +<DT> <A NAME="index-opening-color"><EM>Index-opening Symbol Color</EM></A> + +<DD> It is possible to configure the +<A HREF="#index-format"><EM>Index-Format</EM></A> option +so that it includes the subject followed by the "opening" text of the +message if there is enough space. +This is done by using one of the tokens SUBJECTTEXT, SUBJKEYTEXT, or +SUBJKEYINITTEXT. +The color used for drawing this opening text is given by this option. +The coloring happens for all but the current index line, and this opening +color appears to be in front of any color from an Index Color Rule. +<P> +By default the Index Opening Color is gray characters on a white background. +<P> + +</DL> +<P> +The default colors for these symbols are: +<TABLE> +<TR> <TD> Index-to-me </TD> <TD> black on cyan </TD> </TR> +<TR> <TD> Index-important </TD> <TD> white on bright red </TD> </TR> +<TR> <TD> Index-deleted </TD> <TD> same as Normal Color </TD> </TR> +<TR> <TD> Index-answered </TD> <TD> bright red on yellow </TD> </TR> +<TR> <TD> Index-new </TD> <TD> white on magenta </TD> </TR> +<TR> <TD> Index-recent </TD> <TD> same as Normal Color </TD> </TR> +<TR> <TD> Index-unseen </TD> <TD> same as Normal Color </TD> </TR> +</TABLE> + +<H3><A NAME="header-colors"></A>Header Colors</H3> + +You may add color to the header fields in the MESSAGE TEXT screen. +The +<P> +<DL COMPACT> +<DT> <A NAME="header-general-color"><EM>Header-general Color</EM></A> + +<DD> may be used to color all of the headers of +the message. +</DL> +<P> +It is also possible to set the colors for specific header fields, +for example for the Subject or From fields, using the +<A HREF="#viewer-hdr-colors"><EM>viewer-hdr-colors</EM></A> +option. +<P> +For Header Colors, +there is an additional line on the configuration +screen labeled "Pattern to match". +If you leave that blank, then the whole field for that header will +always be colored. +However, if you give a pattern to match, the coloring will only take place +if there is a match for that pattern in the value of the field. +For example, if you are working on a color for the Subject header and +you fill in a pattern of "important", then only Subjects which +contain the word "important" will be colored. +For address fields like From or To, a pattern match will cause only the +addresses which match the pattern to be colored. +<P> +If the pattern you enter is a comma-separated list of patterns, then coloring +happens if any of those patterns matches. +<P> + +<H3><A NAME="keyword-colors"></A>Keyword Colors</H3> + +Sets the colors <EM>Alpine</EM> uses for Keyword fields in the MESSAGE INDEX screen. +Keywords may be displayed as part of the Subject of a message by using +the "SUBJKEY" or "SUBJKEYINIT" tokens in the +<A HREF="#index-format">Index-Format</A> option. +Keywords may also be displayed in a column of their own in the MESSAGE INDEX +screen by using the "KEY" or "KEYINIT" tokens. +<P> +For example, you might have set up a Keyword +"Work" using the +<A HREF="#keywords">Keywords</A> +option in the Setup/Config screen. +You could cause that Keyword to show up as a special color +by setting up the Keyword Color using this option, and then including it +in the MESSAGE INDEX screen using one of the tokens listed above in the +Index-Format. +<P> + +<H3><A NAME="index-line-colors"></A>Index Line Colors</H3> + +You may color whole index lines by using roles. +This isn't configured in the Setup Colors screen, but is configured in +the <A HREF="#index-color-config">Setup Rules IndexColor</A> screen. + +<H2><A NAME="index-color-config"></A>Index Line Color Configuration</H2> + +Index Line Color causes lines in the MESSAGE INDEX screen to be colored. +This action is only available if your terminal is capable of displaying +color and color display has been enabled with the +<A HREF="#color-style"><EM>Color-Style</EM></A> option. +(In PC-Alpine, color is always enabled so there is no option to turn on.) +<P> +Each rule has a "Pattern", +which is used to decide which of the rules is used; and the color which +is used if the Pattern matches a particular message. + +<H3>Rule Patterns</H3> + +In order to determine whether or not a message matches a rule the message is +compared with the rule's Pattern. +These Patterns are the same for use with Roles, Filtering, Index Coloring, +Scoring, Other Rules, and Search Rules, so are described in only one place, +"<A HREF="#patterns-section">here</A>". + +<H3>Index Line Color</H3> + +This is the color that index lines are colored when there is a matching +Pattern. +This colors the whole index line, except possibly the status letters +which may be colored separately using +the <A HREF="#color-config">Setup Kolor</A> screen. + +<H2><A NAME="role-config"></A>Role Configuration</H2> + +You may play different roles depending on who you are replying to. +For example, if you are replying to a message addressed to <EM>help-desk</EM> you +may be acting as a Help Desk Worker. +That role may require that you use a different return address and/or +a different signature. +<P> +Roles are optional. +If you set up roles they work like this: Each role has a set of +"Uses", which indicate whether or not a role is eligible to be +considered for a particular use; a "Pattern", +which is used to decide which of the eligible roles is used; and a set +of "Actions", which are taken when that role is used. +When you reply to a message, the message you are replying to is compared +with the Patterns of the roles marked as eligible for use when replying. +The comparisons start with the first eligible role and keep going until there +is a match. +If a match is found, the matching role's Actions are taken. +<P> +It is also possible to set a default role and to change that role during +your <EM>Alpine</EM> session. +When you start <EM>Alpine</EM> no default role will be set. +You may set or change the current default role by using the "D" +command in the role selection screen. +You'll see that screen while composing a message and being asked to select +a role. +An easy way to get to that screen is to use the Role Command to +compose a message. +You may find a default role useful if you normally perform the duties of one +of your roles for a while, then you switch to another role and stay in the +new role for another period of time. +It may be easier than using the Role Command to select the role each time you +compose a message. + +<H3>Role Uses</H3> + +There are three types of use to be configured; +one for Replying, one for Forwarding, and one for Composing. +These indicate whether or not you want a role to be considered when you +type the Reply, Forward, or Compose commands. +(The Role command is an alternate form of the Compose command, and it is +not affected by these settings.) +Each of these Use types has three possible values. +The value "Never" +means that the role will never be considered as a candidate for use with +the corresponding command. +For example, if you set a role's Reply Use to Never, then when you Reply to +a message, the role won't even be considered. +(That isn't quite true. If the message you are replying to matches some other +role which requires confirmation, +then there will be a ^T command available which allows you to select a role +from all of your roles, not just the reply-eligible roles.) +<P> + +The options "With confirmation" and "Without confirmation" +both mean that you do want to consider this role when using the corresponding +command. +For either of these settings the role's Pattern will +be checked to see if it matches the message. +For Reply Use, the message used to compare the Patterns with is the message +being replied to. +For Forward Use, the message used to compare the Pattern with is the message +being forwarded. +For Compose Use, there is no message, so the parts of the Pattern which depend +on a message (everything other than Current Folder Type) are ignored. +In all cases, the Current Folder is checked if defined. +If there is a match then this role will either be used without confirmation +or will be the default when confirmation is asked for, depending on +which of the two options is selected. +If confirmation is requested, you will have a chance to +choose No Role instead of the offered role, or to +change the role to any one of your other roles (with the ^T command). + +<H3>Role Patterns</H3> + +In order to determine whether or not a message matches a role the message is +compared with the Role Pattern. +These Patterns are the same for use with Roles, Filtering, Index Coloring, +Scoring, Other Rules, and Search Rules, so are described in only one place, +"<A HREF="#patterns-section">here</A>". +<P> +Since header patterns, AllText patterns, and BodyText patterns which are unset are ignored, +a role which has all header patterns unset, the AllText pattern unset, +the BodyText pattern unset, +the Score Interval unset, and the Current Folder Type set to +"Any" may be used as a default role. +It should be put last in the list of roles since the matching +starts at the beginning and proceeds until one of the roles is a match. +If no roles at all match, then <EM>Alpine</EM> will +use its regular methods of defining the role. +If you wanted to, you could define a different "default" role +for Replying, Forwarding, and Composing by setting the +"Use" fields appropriately. + +<H3>Role Actions</H3> + +Once a role match is found, the role's Actions are taken. +For each role there are several possible actions that may be defined. +They are actions to set the From address, the Reply-To address, +the Fcc, the Signature file, and the Template file. + +<H4>Initialize Settings Using Role</H4> + +This is a power user feature. +You will usually want to leave this field empty. +The value of this field is the nickname of another one of your roles. +The Action values from that other role +are used as the initial values of the Action items for this role. +If you put something in any of the action fields for this role, that will +override whatever was in the corresponding field of the initializer role. +<P> +You might use this field if the "Action" part of one of your roles +is something you want to use in more than one role. +Instead of filling in those action values again for each role, you +may give the nickname of the role where the values are filled in. +It's just a shortcut way to define Role Actions. +<P> +Here's an example to help explain how this works. +Suppose you have a role with nickname "role1" and role1 has +(among other things) +<P> +<CENTER><SAMP>Set Reply-To = The Pres <president@example.com></SAMP></CENTER> +<P> +set. +If in "role2" you set "Initialize settings using role" to +"role1", then role2 will inherit the Set Reply-To value +from role1 by default (and any of the other inheritable action values +that are set). +So if role2 had +<P> +<CENTER><SAMP>Set Reply-To = <No Value Set></SAMP></CENTER> +<P> +defined, the Reply-To used with role2 would be "The Pres <president@example.com>" +However, if role2 had +<P> +<CENTER><SAMP>Set Reply-To = VP <vicepresident@example.com></SAMP></CENTER> +<P> +defined, then the Reply-To used with role2 would be "VP <vicepresident@example.com>" instead. +<P> +If you wish, +you may choose a nickname from your list of roles by using the +"T" command. +If the role you are using to initialize also has a role it initializes from, +then that initialization happens first. +That is, inheritance works as expected with the grandparent and +great-grandparent (and so on) roles having the expected effect. + +<H4>Set From</H4> + +This field consists of a single address which will be used as the From +address on the message you are sending. +This should be a fully-qualified address like +<P> +<CENTER><SAMP>Full Name <user@domain></SAMP></CENTER> +<P> +or just +<P> +<CENTER><SAMP>user@domain</SAMP></CENTER> +<P> +If this is left blank, then the normal From address will be used. + +<H4>Set Reply-To</H4> + +The Reply-To address is the address used on the Reply-To line of the message +you are sending. +You don't need a Reply-To address unless it is different from the From address. +This should be a fully-qualified address like +<P> +<CENTER><SAMP>Full Name <user@domain></SAMP></CENTER> +<P> +or just +<P> +<CENTER><SAMP>user@domain</SAMP></CENTER> +<P> +If this is left blank, then there won't be a Reply-To address unless +you have configured one specially with the +<A HREF="#cust-hdr"><EM>customized-hdrs</EM></A> +configuration option. + +<H4>Set Other-Hdrs</H4> + +This field gives you a way to set values for headers besides +"From" and "Reply-To". +If you want to set either of those, use the specific +"Set From" and "Set Reply-To" settings. +<P> +This field is similar to the +<A HREF="#cust-hdr"><EM>customized-hdrs</EM></A> option. +Each header you specify here must include the header tag +("To:", "Approved:", etc.) +and may optionally include a value for that header. +In order to see these headers when you compose using this role you +must use the rich header command. +Here's an example which shows how you might set the To address. +<P> +<CENTER><SAMP>Set Other Hdrs = To: Full Name <user@domain></SAMP></CENTER> +<P> +Headers set in this way are different from headers set with the +customized-hdrs option in that the value you give for a header here +will replace any value that already exists. +For example, if you are Replying to a message there will already be at +least one address in the To header (the address you are Replying to). +However, if you Reply using a role which sets the To header, that role's +To header value will be used instead. +The customized-hdrs headers are defaults. +<P> +Limitation: Because commas are used to separate the list of +Other Headers, it is not possible to have the value of a +header contain a comma; +nor is there currently an "escape" mechanism provided +to make this work. + +<H4>Set Fcc</H4> + +This field consists of a single folder name which will be used in +the Fcc field of the message you are sending. +You may put anything here that you would normally type into the Fcc +field from the composer. +<P> +In addition, an fcc of "" (two double quotation marks) means +no Fcc. +<P> +A blank field here means that <EM>Alpine</EM> will use its normal rules for deciding +the default value of the Fcc field. +For many roles, perhaps most, it may make more sense for you to use the +other <EM>Alpine</EM> facilities for setting the Fcc. +In particular, if you want the Fcc to depend on who you are sending the +message to then the <A HREF="#fcc-name-rule"><EM>fcc-name-rule</EM></A> +is probably more useful. +In that case, you would want to leave the Fcc field here blank. +However, if you have a role that depends on who the message you are replying +to was From, or what address that message was sent to; +then it might make sense to set the Fcc for that role here. + +<H4>Set LiteralSig</H4> + +This field contains the actual text for your signature, as opposed to +the name of a file containing your signature. +If this is defined it takes precedence over any value set in the +<EM>Set Signature</EM> field. +<P> +This is simply a different way to store the signature. +The signature is stored inside your Alpine configuration file instead of in +a separate signature file. +Tokens work the same way they do with <EM>Set Signature</EM>. +<P> + +The two character sequence \n (backslash followed by +the character n) will be used to signify a line-break in your signature. +You don't have to enter the \n, but it will be visible in the +CHANGE THIS ROLE RULE window after you are done editing the signature. + +<H4>Set Signature</H4> + +The Signature is the name of a file to be used as the signature file when +this role is being used. +If the filename is followed by a vertical bar (|) then instead +of reading the contents of the file the file is assumed to be a +program which will produce the text to be used on its standard output. +The program can't have any arguments and doesn't receive any input from <EM>Alpine</EM>, +but the rest of the processing works as if the contents came from a file. + +<P> +Signature files may be stored remotely on an IMAP server. +In order to do that you just give the file a remote name. +This works just like the regular +<A HREF="#sig-file">signature-file</A> +option which is configured from the Setup/Configuration screen. +A remote signature file name might look like: +<P> +<CENTER><SAMP>{myimaphost.myschool.k12.wa.us}mail/sig3</SAMP></CENTER> +<P> +or, if you have an SSL-capable version of <EM>Alpine</EM>, you might try +<P> +<CENTER><SAMP>{myimaphost.myschool.k12.wa.us/user=loginname/ssl}mail/sig3</SAMP></CENTER> +<P> +Once you have named the remote signature file you create its +contents by using the "F" "editFile" command when the +cursor is on the "Set Signature" +line of the role editor. + +<P> +Besides containing regular text, a signature file may also +contain (or a signature program may produce) tokens which are replaced with text +which depends on the message you are replying to or forwarding. +The tokens all look like _word_ (a word surrounded by underscores). +For example, if the token +<P> +<CENTER><SAMP>_DATE_</SAMP></CENTER> +<P> +is included in the text of the signature file, then when you reply to +or forward a message, the token will be replaced with the actual date +the message you are replying to or forwarding was sent. +<P> +If you use a role which has a signature file for a plain composition +(that is, not a reply or forward) then there is no original message, so +any tokens which depend on the message will be replaced with nothing. +So if you want a signature file to be useful for new compositions it +shouldn't include any of the tokens which depend on the message being +replied to or forwarded. +<P> +The list of available tokens is +<A HREF="#index-tokens">here</A>. +<P> +Actually, for the adventurous, there is a way to conditionally include text based +on whether or not a token would result in specific replacement text. +For example, you could include some text based on whether or not +the _NEWS_ token would result in any newsgroups if it was used. +It's explained in detail +<A HREF="#reply-token-conditionals">here</A>. +<P> +In the very unlikely event that you want to include a literal token in +a signature file, you must precede it with a backslash character. +For example, to include the literal text _DATE_ you must actually use +\_DATE_. +It is not possible to have a literal backslash followed by an expanded token. +<P> +A blank field here means that <EM>Alpine</EM> will use its normal rules for deciding +which file (if any) to use for the signature file. + +<H4>Set Template</H4> + +A Template is the name of a file to be included in the message when this +role is being used. +The template file is a file which is included at the top of the message you +are composing. +<P> +If the filename is followed by a vertical bar (|) then instead +of reading the contents of the file the file is assumed to be a +program which will produce the text to be used on its standard output. +The program can't have any arguments and doesn't receive any input from <EM>Alpine</EM>, +but the rest of the processing works as if the contents came from a file. +<P> +Template files may be stored remotely on an IMAP server. +In order to do that you just give the file a remote name. +This works just like the regular +<A HREF="#sig-file">signature-file</A> +option which is configured from the Setup/Configuration screen. +A remote template file name might look like: +<P> +<CENTER><SAMP>{myimaphost.myschool.k12.wa.us}mail/templ3</SAMP></CENTER> +<P> +or, if you have an SSL-capable version of <EM>Alpine</EM>, you might try +<P> +<CENTER><SAMP>{myimaphost.myschool.k12.wa.us/user=loginname/ssl}mail/templ3</SAMP></CENTER> +<P> +Once you have named the remote template file you create its +contents by using the "F" "editFile" command when the +cursor is on the "Set Template" +line of the role editor. +<P> +Besides containing regular text, a template file may also +contain (or a template file program may produce) tokens which are replaced with text +which depends on the message you are replying to or forwarding. +The tokens all look like _word_ (a word surrounded by underscores). +For example, if the token +<P> +<CENTER><SAMP>_DATE_</SAMP></CENTER> +<P> +is included in the text of the template file, then when you reply to +or forward a message, the token will be replaced with the actual date +the message you are replying to or forwarding was sent. +<P> +If you use a role which has a template file for a plain composition +(that is, not a reply or forward) then there is no original message, so +any tokens which depend on the message will be replaced with nothing. +So if you want a template file to be useful for new compositions it +shouldn't include any of the tokens which depend on the message being +replied to or forwarded. +<P> +The list of available tokens is +<A HREF="#index-tokens">here</A>. +<P> +Actually, for the adventurous, there is a way to conditionally include text based +on whether or not a token would result in specific replacement text. +For example, you could include some text based on whether or not +the _NEWS_ token would result in any newsgroups if it was used. +It's explained in detail +<A HREF="#reply-token-conditionals">here</A>. +<P> +In the very unlikely event that you want to include a literal token in +a template file, you must precede it with a backslash character. +For example, to include the literal text _DATE_ you must actually use +\_DATE_. +It is not possible to have a literal backslash followed by an expanded token. +<P> +A blank field here means that <EM>Alpine</EM> will not use a template file when +this role is being used. + +<H4>Use SMTP Server</H4> + +If this field has a value, then it will be used as the SMTP server +to send mail when this role is being used (unless the SMTP server variable +is set in the system-wide fixed configuration file). +It has the same semantics as the +<A HREF="#smtp-server"><EM>smtp-server</EM></A> +variable in the Setup/Config screen. +When you postpone the composition this SMTP server list will be saved +with the postponed composition and it cannot be changed later. +Because of that, you may want to make this a list of SMTP servers +with the preferred server at the front of the list and alternate servers +later in the list. + +<P> +If any of the actions are left unset, then the action depends on what +is present in the "Initialize settings using role" field. +If you've listed the nickname of another one of your roles there, then the +corresponding action from that role will be used here. +If that action is also blank, or if there is no nickname specified, +then <EM>Alpine</EM> will do whatever it normally does to set these actions. +This depends on other configuration options and features you've set. + +<H2><A NAME="filter-config"></A>Filtering Configuration</H2> + +The software which actually delivers mail (the stuff that happens +before <EM>Alpine</EM> is involved) for you is in a better position to do mail filtering +than <EM>Alpine</EM> itself. +If possible, you may want to look into using that sort of mail filtering to +deliver mail to different folders, delete it, or forward it. +However, if you'd like <EM>Alpine</EM> to help with this, <EM>Alpine</EM>'s filtering is for you. +<P> +Filtering is a way to automatically move certain messages from one folder +to another or to delete messages. +It can also be used to set message status bits (Important, Deleted, New, +Answered). +<EM>Alpine</EM> doesn't have the ability to forward mail to another address. +<P> +Each filtering rule has a "Pattern" and a "Filter Action". +When a folder is opened, when new mail arrives in an open folder, or +when mail is Expunged from a folder; each +message is compared with the Patterns of your filtering rules. +The comparisons start with the first rule and keep going until there +is a match. +If a match is found, the message may be deleted or moved, depending on +the setting of the Filter Action. +If the message is not deleted, it may have its status altered. +<P> +For efficiency, each message is usually only checked once. +When new mail arrives, the new messages are checked but not the old. +There are some exceptions to this rule. +The expunge command will cause all messages to be rechecked, as will +editing of the filtering rules. + +<P> +<EM>NOTE:</EM> +When setting up a Pattern used to delete messages, +it is recommended that you test the Pattern first with a "Move" +folder specified in +case unintended matches occur. Messages that are deleted will be removed +from the folder and <EM>unrecoverable</EM> from within <EM>Alpine</EM> after the +next Expunge command or once the folder being filtered has been closed. + +<H3>Filter Patterns</H3> + +In order to determine whether or not a message matches a filter the message is +compared with the Filter's Pattern. +These Patterns are the same for use with Roles, Filtering, Index Coloring, +Scoring, Other Rules, and Search Rules, so are described in only one place, +"<A HREF="#patterns-section">here</A>". +<P> +Since filtering is a potentially destructive action, if you have a filtering +Pattern with nothing other than Current Folder Type set, that filtering +rule is ignored. + +<H3>Filter Actions</H3> + +Once a filter match is found for a particular message, there are some actions +which may be taken. +First, the message may have its status changed. +This is the same message status that you can manipulate manually using the +Flag Command. +There are four elements of message status that you can control. +You can set or clear the Important status, the New status, the Deleted +status, and the Answered status. +Of course, if the filter is going to delete the message, +then there is no point in setting message status. +You may also set or clear user-defined +<A HREF="#keywords">keywords</A> for a message. +<P> +Second, the filter may delete or move the message. +Deleting the message marks it Deleted and removes it from view. +It is effectively gone forever (though it technically is still there until +the next expunge command, which may happen implicitly). +Moving the message moves it from the open folder into the folder +listed on the "Folder List" line of the filter configuration. +If you list more than one folder name (separated by commas) then the message +will be copied to each of those folders. +In any case, if "Delete" or "Move" is set then the +message is removed from the current folder. +If you just want to set the messages status without deleting it from +the folder, then set the filter action to +"Just Set Message Status". +<P> +(There is no way to do a Copy instead of a Move, due to the difficulties +involved in keeping track of whether or not a message has +already been copied by a previous <EM>Alpine</EM> session.) + +<H4><A NAME="move-only-if-not-deleted"></A>Move-only-if-not-deleted option</H4> + +If you have specified a Move to Folder to filter messages into, then this +option has an effect. +If this option is set then messages will only be moved into the specified folder +if they aren't already marked deleted. +This might be useful if you have more than one <EM>Alpine</EM> session running +simultaneously and you don't want messages to be filtered into a folder +more than once. +This method is not foolproof. +There may be cases where a message gets marked deleted and so it is never +filtered into the folder. +For example, if you deleted it in another <EM>Alpine</EM> or +another mail program that didn't know about the filtering rule. +<P> +This option has no effect if the Filter Action is not set to Move. + +<H4><A NAME="dont-quit-even-if-rule-matches"></A>Dont-quit-even-if-rule-matches option</H4> + +If this option is set then this is a non-terminating rule. +Usually, for each message, <EM>Alpine</EM> searches through the filter rules until +a match is found and then it performs the action associated with that rule. +Rules following the match are not considered. +If this option is set then the search for matches will continue at the next +rule. +<P> +If a non-terminating rule matches then the actions associated with +that rule, except for any implied deletion of the message, are performed +before the match for the next rule is checked. +For example, if the non-terminating rule sets the Important status, then that +status will be set when the next rule is considered. +However, if the non-terminating rule Moves the message, the message will +actually be copied instead of copied and deleted so that it is still there +for the next rule. +A moved message is deleted after all the relevant rules have been checked. +The name of the "Move" action is confusing in this case because +a single message can be moved to more than one folder. +It turns the Move into a Copy instead, but it is still followed by a deletion +at the end. +<P> +This option may be useful if you want to have a single message filtered to +two different folders because it matches two different Patterns. +For example, suppose you normally filter messages to a particular mailing +list into one folder, and messages addressed directly to you into a second +folder. +If a message is sent to both you and the list (and you can tell that by +looking at the headers of the message) this option may give you a convenient +way to capture a copy to each folder. +(It may also cause you to capture two copies to each folder, +depending on whether your mail system delivers one or two copies of the +message to you and on how the list works.) + +<H2><A NAME="scoring-config"></A>Scoring Configuration</H2> + +Most people will not use scores at all, but if you do use them, here's how +they work in Alpine. +Using this screen, you may define Scoring rules. +The score for a message is calculated by looking at every Score rule defined +and adding up the Score Values for the ones which match the message. +If there are no matches for a message, it has a score of zero. +Message scores may be used a couple of ways in Alpine. + +<H3>Sorting by Score</H3> + +One of the methods you may use to sort message indexes is to sort by +score. +The scores of all the messages in a folder will be calculated and then +the index will be ordered by placing the messages in order of ascending or +descending score. + +<H3>Scores for use in Patterns</H3> + +The Patterns used for Roles, Index Line Coloring, and Filtering have a +category labeled "Score Interval". +When a message is being compared with a Pattern to check for a match, if +the Score Interval is set only messages which have a score somewhere in +the interval are a match. + +<H3>Scoring Rule Patterns</H3> + +In order to determine whether or not a message matches a scoring rule +the message is compared with the rule's Pattern. +These Patterns are the same for use with Roles, Filtering, Index Coloring, +Scoring, Other Rules, and Search Rules, so are described in only one place, +"<A HREF="#patterns-section">here</A>". + +<P> +Actually, Scoring rule Patterns are slightly different from the other types of +Patterns because Scoring rule Patterns don't contain a Score Interval. +In other words, when calculating the score for a message, which is done +by looking at the Scoring rule Patterns, scores aren't used. + +<H3>Score Value</H3> + +This is the value that will be added to the score for a message if the +rule's Pattern is a match. +Each individual Score Value is an integer between -100 and 100, and the +values from matching rules are added together to get a message's score. +There is also a way to extract the value from a particular header of each +message. See the help text for Score Value for further information. + +<H2><A NAME="other-config"></A>Other Rules Configuration</H2> + +Using this screen, you may define configuration Rules which don't fit +nicely into the other Rules categories. + +<H3>Other Rule Patterns</H3> + +Other Rules are a little different from the rest of the Rules because +they depend only on the current folder, and not on a particular message. +In order to determine whether or not a rule's actions should be applied +the current folder is compared with the rule's Pattern, which consists +of only the Current Folder Type. +Current Folder Type works the same for Other Rules as it does for Roles, +Filtering, Index Coloring, and Scoring. +Keep in mind that the only part of the Pattern which applies to Other +Rules is the Current Folder Type when looking at the description of +Patterns given +"<A HREF="#patterns-section">here</A>". + +<H3>Other Rule Actions</H3> + +Once a pattern match is found, the rule's Actions are taken. +Neither of the following two rule's depends on a message for its match. +That means that all the parts of the Pattern which depend on matching an +attribute of a message are ignored. +So the only part of the Pattern that matters for these Actions is +the Current Folder Type. + +<H4>Set Sort Order</H3> + +When you enter a new folder, these rules will be checked to see if you +have set a sort order which is different from your default sort order. +The default is set in the Setup/Config screen with +the <A HREF="#sort-key">Sort-Key</A> option. +If the Sort Order action is set, then the folder will be displayed sorted in +that sort order instead of in the default order. +<P> +A possible point of confusion arises when you change the configuration +of the Sort Order for the currently open folder. +The folder will normally be re-sorted when you go back to viewing the +index. +However, if you have manually sorted the folder with the +Sort command, it will not be re-sorted. + +<H4>Set Index Format</H3> + +When you enter a new folder, these rules will be checked to see if you +have set an Index Format which is different from your default Index Format, +which is set with the +<A HREF="#index-format"><EM>Index-Format</EM></A> option. +If so, the index will be displayed with this format instead of the default. + +<H4>Set Startup Rule</H4> + +When you enter a new folder, these rules will be checked to see if you +have set a startup rule which is different from the default startup rule. +The default for incoming folders is set in the Setup/Config screen with +the "incoming-startup-rule" option. +The default for folders other than INBOX that are not part of your +incoming collection +(see <A HREF="#enable-incoming-folders">enable-incoming-folders</A> feature) +is to start with the last message in the folder. +If the Startup Rule is set to something other than "default", +then the rule will determine which message will be the current message when +the folder is first opened. +<P> +The various startup rule possibilities work the same here as they do in +the incoming collection, except that the folder can be any specific +folder or any folder type. + +<H2><A NAME="search-rules-config"></A>Search Rules Configuration</H2> + +One of the commands that becomes available when that feature is turned on +is the "; Select" command, which is used in the MESSAGE INDEX +screen to select a set of messages. +One way of selecting messages is to use a Rule. +All of the messages which match (or don't match if you wish) +a Rule's Pattern will be selected. +<P> +Any of your Rules may be used for this purpose. +You might already have Rules set up for filtering, index line color, scores, or roles; +and you may use any of those Rules with the Select command. +However, you might find it more convenient to set up a separate set of Rules +just for this purpose without having to worry about what other effects +they may cause. +That is the purpose of these Select Rules. + +<H3>Rule Patterns</H3> + +In order to determine whether or not a message is selected by a rule the +message is +compared with the rule's Pattern. +These Patterns are the same for use with Roles, Filtering, Index Coloring, +Scoring, Other Rules, and Search Rules, so are described in only one place, +"<A HREF="#patterns-section">here</A>". +<P> +There is no action associated with these Search Rules. +Only their Patterns are used. + +<H2><A NAME="patterns-section"></A>Patterns</H2> + +Patterns are used with Roles, Filtering, Index Coloring, +Scoring, Other Rules, and Search Rules. +Patterns are compared with a message to see if there is a match. +For Filtering, the messages being checked are all the messages in the +folder, one at a time. +For Index Line Coloring, each message that is visible on the screen is +checked for matches with the Index Coloring Patterns. +Roles are used with the Reply, Forward, and Compose commands. +For Reply, the message used to compare the Pattern with is the message +being replied to; +for Forward, the message used to compare the Pattern with is the message +being forwarded; +and for Compose, there is no message, so the parts of the Pattern which depend +on a message (everything other than Current Folder Type and the +Beginning of Month and Year) +are not used. +Only the Current Folder Type matters for Compose (plus the Beginning of +Month or Year, which you wouldn't usually use for a Role). +For Scoring, the message being scored is compared with all of the Score +Patterns, and the Score Values from the ones that match are added together to +get the message's score. +For Other Rules, there is no message. Only the Current Folder Type is checked +for Other Rules. +<P> +Each Pattern has several possible parts, all of which are optional. +In order for there to be a match, <EM>ALL</EM> of the +<EM>defined</EM> parts of the Pattern must match the message. +If a part is not defined it is considered a match. +For example, if the To pattern is not defined it will be +displayed as +<P> +<CENTER>To pattern = <No Value Set></CENTER> +<P> +That is considered a match because it is not defined. +This means that the Pattern with nothing defined is a match if the +Current Folder Type matches, but there is an exception. +Because filtering is a potentially destructive action, filtering Patterns +with nothing other than Current Folder Type defined are ignored. +If you really want a filtering Pattern to match all messages (subject to +Current Folder Type) the best way to do it is to define a Score interval +which includes all possible scores. +This would be the score interval <SAMP>(-INF,INF)</SAMP>. +This can be used even if you haven't defined any rules to Set Scores. +<P> +There are six predefined header patterns called the To, From, Sender, Cc, News, +and Subject patterns. +Besides those six predefined header patterns, you may add +additional header patterns with header fieldnames of your choosing. +You add an extra header pattern by placing the cursor on one of the +patterns while in the role editor and using the "eXtraHdr" command. +The Recip pattern is a header pattern which stands for Recipient (To OR Cc) +and the Partic pattern is a header pattern which stands for +Participant (From OR To OR Cc). +(Defining the Recip pattern does not have the same effect as defining both +the To and Cc patterns. Recip is To <EM>OR</EM> Cc, not To <EM>AND</EM> Cc.) +Similar to the header patterns are the AllText pattern and the BodyText pattern. +Instead of comparing this pattern's text against only the contents of +a particular header field, the text for the AllText pattern is compared +with text anywhere in the message's header or body, and the text for the +BodyText pattern is compared with text anywhere in the message's body. +<P> +Any of the header patterns, the AllText pattern, or the BodyText pattern may be negated with the +"!" "toggle NOT" command. +You can tell that <EM>NOT</EM> has been turned on by looking for the character +"!" at the beginning of the pattern line. +When the "!" is present, it reverses the meaning of the match. +That is, if the pattern matches then it is considered to NOT be a match, and +if it does not match it is considered to be a match. +<P> +Don't make the mistake of putting the "!" in the data field for +a pattern. +For example, if you type the characters "!urgent" into the Subject +pattern, the pattern will look like: +<P> +<PRE> + Subject pattern = !urgent +</PRE> +<P> +This means you want to match the 7 character sequence "!urgent". +In order to match messages which do not have "urgent" in +their Subject field, first type the characters "urgent" followed +by carriage return for the value of the Subject pattern, then negate it +by typing the "!" command. +It should look like +<P> +<PRE> + ! Subject pattern = urgent +</PRE> +<P> +The contents of each of these header patterns (or the AllText or BodyText patterns) may +be a complete email address, part of an address, or a random set of +characters to match against. +It may also be a list of such patterns, which means you +are looking for a match against the first pattern in the list <EM>OR</EM> +the second pattern <EM>OR</EM> the third and so on. +For example, a Subject pattern equal to +<P> +<PRE> + Subject pattern = urgent + emergency + alert +</PRE> +<P> +would match all messages with a subject which contained at least one +of those words. +It would also match subjects containing the words "alerts" or +"Urgently". +<P> +The same example with "NOT" turned on would be +<P> +<PRE> + ! Subject pattern = urgent + emergency + alert +</PRE> +<P> +which would match all messages with a subject which did NOT contain any of +those words. +You can use the "Add Value" command to add new words to the list, +or you can enter them as a comma-separated list. +<P> +(It is not possible to specify two patterns which must <EM>BOTH</EM> be +present for a match. +It is only possible to specify that <EM>EITHER</EM> pattern1 <EM>OR</EM> +pattern2 must be present, +and that is exactly what using a list does.) +<P> +The "Current Folder Type" and the "Score Interval" are +also part of the Pattern, although the "Score Interval" is not used +when checking for matches for Scoring. +There are five similar settings which relate to the status of the message. +These settings rely on the message being New or not, Deleted or not, +Answered or not, Important or not, and Recent or not. +There are also some other miscellaneous settings. +The first is the Age of the message in days. +Another is the Size of the message in bytes. +The third is a setting which detects whether or not the Subject of a +message contains raw 8-bit characters (unencoded characters with the most +significant bit set). +There is a setting which detects whether or not this is the first time +<EM>Alpine</EM> has been run this month (doesn't depend on individual messages), +and another which detects whether or not this is the first time <EM>Alpine</EM> has +been run this year. +Other parts of the Pattern detect whether or not the From address of a +message appears in your address book, whether or not certain keywords +are set for a message, and whether or not certain character sets are +used in a message. + +<H3>Parts of a Pattern</H3> + +<H4>Header patterns</H4> + +A header pattern is simply text which is searched for in the corresponding +header field. +For example, if a Pattern has a From header pattern with the value +"@company.com", then only messages which have a From header +which contains the text "@company.com" will be possible +matches. +Matches don't have to be exact. +For example, if the relevant field of a message contains the text +"mailbox@domain" somewhere +in it, then header patterns of "box", or "x@d", or +"mailbox@domain" are all matches. +<P> +All parts of the Pattern must match so, for example, +if a message matches a defined +From pattern, it still must be checked against the other parts of the +Pattern which have been defined. +The To header pattern is a slightly special case. +If the message being checked has a Resent-To header +and the feature <A HREF="#use-resent-to-in-rules">Use-Resent-To-in-Rules</A> is turned on, the addresses +there are used in place of the addresses in the To header. +This is only true for the To header. +Resent-cc and Resent-From headers are never used unless you add them +with the eXtraHdrs command. +<P> +The meaning of a header pattern may be negated with the +"!" "toggle NOT" command. +You can tell that <EM>NOT</EM> has been turned on by looking for the character +"!" at the beginning of the pattern line. +It would look something like +<P> +<PRE> + ! From pattern = susan@example.com +</PRE> +<P> +When the "!" is present, it reverses the meaning of the match. +<P> +If you want to check for the presence of a header field but don't care +about its value, then +the empty pattern which you get by entering a pair of +double quotes ("") should match any message which +has the corresponding header field. + +<H4><A NAME="pattern_alltext">AllText patterns</A></H4> + +AllText patterns are just like header patterns except that the text is +searched for anywhere in the message's headers or body, not just in the +contents of a particular header field. +<P> + +<H4><A NAME="pattern_bodytext">BodyText patterns</A></H3> + +BodyText patterns are just like header patterns except that the text is +searched for anywhere in the message's body, not just in the +contents of a particular header field. +<P> + +If there is more than one header pattern or AllText pattern or BodyText pattern +for which you want to take the +same action there is a shorthand notation which may be used. +Any of these patterns may be a list of patterns instead of +just a single pattern. +If any one of the patterns in the list matches the message +then it is considered a match. +For example, if "company1" and "company2" both required +you to use the same role when replying to messages, you might have +a To pattern which looks like +<P> +<PRE> + To pattern = company1.com + company2.com +</PRE> +<P> +This means that if the mail you are replying to was addressed to +either "anything@company1.com" or "anything@company2.com", +then this Pattern is a match and the same actions will be taken. +<P> +The meaning of an AllText or BodyText pattern may be negated with the +"!" "toggle NOT" command. +You can tell that <EM>NOT</EM> has been turned on by looking for the character +"!" at the beginning of the pattern line. +When the "!" is present, it reverses the meaning of the match. +<P> +A technicality: Since comma is the character used to separate multiple values +in any of the fields which may have multiple values (such as header patterns, +AllText patterns, BodyText patterns, keywords, folder lists, and so on), +you must escape comma with a +backslash (\) if you want to include a literal comma in one of those fields. +In other words, if you type a backslash followed by a comma it will +be interpreted as a comma by <EM>Alpine</EM>, instead of as a separator between +pattern values. +All other backslashes (those not followed by a comma) are literal +backslashes and should not be escaped. +It's unlikely you'll ever need to enter a literal comma or backslash in +any of the patterns. + +<H4>Current Folder Type</H4> + +The "Current Folder Type" may be set to one of four different +values: "Any", "News", "Email", or +"Specific". +If the value is set to "News", then the +Pattern will only match if the currently open folder is a newsgroup. +The value "Email" only matches if the current folder is not news and +the value "Any" causes any folder to match. +If the value of "Current Folder Type" is set to "Specific", +then you must fill in a value for "Folder", which is on the line +below the "Specific" line. +In this case you will only get a match if the currently open folder is +the specific folder you list. +You may give a list of folders instead of just a single +folder name, in which case the Pattern will match if the open folder is +any one of the folders in the list. +The name of each folder in the list may be either "INBOX", +the technical specification +of the folder (like what appears in your configuration file) or, if the +folder is one of your incoming folders, it may be the nickname you've given +the folder. +Here are some samples of specific folder names: +<P> +<CENTER><SAMP>{monet.art.example.com}mail/art-class</SAMP></CENTER> +<P> +<CENTER><SAMP>{news.example.com/nntp}#news.comp.mail.pine</SAMP></CENTER> +<P> +<CENTER><SAMP>mail/local-folder</SAMP></CENTER> +<P> +The easiest way to fill in the "Folder" field is to use +the "T" command which is available when the "Folder" line is +hilighted, or to use the "Take" command with the configuration +feature +<A HREF="#enable-rules-under-take">"enable-rules-under-take"</A> +turned on. +<P> +When reading a newsgroup, there may be a performance penalty +incurred when collecting the information necessary to check whether +or not a Pattern matches a message. +For this reason, the default Current Folder Type is set to "Email". +If you have Patterns with a Current Folder Type of either +"Any" or "News" and those Patterns are used for +Index Line Coloring or Scoring, you may experience +slower screen redrawing in the MESSAGE INDEX screen when in a newsgroup. + +<H4>Age Interval</H4> + +The "Age Interval" may be set to an interval of message +ages which should be considered a match. +Like the other parts of the Pattern, if it is unset it will be ignored. +The Age Interval looks like +<P> +<CENTER><SAMP>(min_age,max_age)</SAMP></CENTER> +<P> +where "min_age" and "max_age" are integers greater +than or equal to zero. +The special value "INF" may be used for +the max value. It represents infinity. +<P> +Actually, this option may be defined as a list of intervals instead +of just a single interval. +The list is separated by commas. +It can look like +<P> +<CENTER><SAMP>(min_age1,max_age1),(min_age2,max_age2),...</SAMP></CENTER> +<P> +When there is an Age Interval defined, it is a match if the age, in days, of +the message is contained in any of the intervals. +The intervals include both endpoints. +<P> +Even though this option is called Age, it isn't actually +the <EM>age</EM> of the message. +Instead, it is how many days ago the message arrived in one of your folders. +If the current time is a little past midnight, then a message that arrived +just before midnight arrived yesterday, even though the message is only +a few minutes old. +By default, the date being used is not the date in the Date +header of the message. +It is the date that the message arrived in one of your folders. +When you Save a message from one folder to another that arrival date +is preserved. +If you would like to use the date in the Date header that is possible. +Turn on the option +<EM>use-date-header-for-age</EM> +near the bottom of the rule definition. +<P> +A value of 0 is today, 1 is yesterday, 2 is the day before yesterday, and so on. + +<H4><A NAME="pattern_size_interval">Size Interval</A></H3> + +The "Size Interval" may be set to an interval of message +sizes which should be considered a match. +Like the other parts of the Pattern, if it is unset it will be ignored. +The Size Interval looks like +<P> +<CENTER><SAMP>(min_size,max_size)</SAMP></CENTER> +<P> +where "min_size" and "max_size" are integers greater +than or equal to zero. +The special value "INF" may be used for +the max value. It represents infinity. +<P> +Actually, this option may be defined as a list of intervals instead +of just a single interval. +The list is separated by commas. +It can look like +<P> +<CENTER><SAMP>(min_size1,max_size1),(min_size2,max_size2),...</SAMP></CENTER> +<P> +When there is a Size Interval defined, it is a match if the size, in bytes, of +the message is contained in any of the intervals. +The intervals include both endpoints. + +<H4>Score Interval</H4> + +The "Score Interval" may be set to an interval of message +scores which should be considered a match. +Like the other parts of the Pattern, if it is unset it will be ignored. +The Score Interval looks like +<P> +<CENTER><SAMP>(min_score,max_score)</SAMP></CENTER> +<P> +where "min_score" and "max_score" are integers between +-32000 and 32000. +The special values "-INF" and "INF" may be used for +the min and max values to represent negative and positive infinity. +<P> +Actually, a list of intervals may be used if you wish. +A list would look like +<P> +<CENTER><SAMP>(min_score1,max_score1),(min_score2,max_score2),...</SAMP></CENTER> +<P> +When there is a Score Interval defined, it is a match if the score for +the message is contained in any of the intervals in the list. +The intervals include the endpoints. +The score for a message is calculated by looking at every Score rule defined and +adding up the Score Values for the ones which match the message. +When deciding whether or not a Pattern matches a message for purposes of +calculating the score, the Score Interval is ignored. + +<H4>Message Status</H4> + +There are five separate message status settings. +By default, all five are set to the value "Don't care", which +will match any message. +The value "Yes" means that the particular status must be true +for a match, and the value "No" means that the particular +status must not be true for a match. +For example, one of the five Message Status settings is whether a message +is marked Important or not. +A "Yes" means that the message must be Important to be +considered a match and "No" means that the message must not be +Important to be considered a match. +The same is true of the other four message status settings which depend +on whether or not the message is New; whether the message has +been Answered or not; whether the message has been Deleted or not, and +whether the message is Recent or not. +<P> +The nomenclature for New and Recent is a bit confusing: +<P> +New means that the message is Unseen. +It could have been in your mailbox for a long time but if you haven't looked +at it, it is still considered New. +That matches the default <EM>Alpine</EM> index display that shows an N for such a +message. +<P> +Recent means that the message was added to this folder since the last time +you opened the folder. +<EM>Alpine</EM> also shows an N by default for these types of messages. +If you were to run two copies of <EM>Alpine</EM> that opened a folder one right after +the other, a message would only show up as Recent in (at most) the first +<EM>Alpine</EM> session. + +<H4>Message Keywords</H4> + +Keywords are similar to Message Status, but they are chosen by the user. +Provided the mail server allows for it, you may add a set of possible keywords +to a folder and then you may set those keywords or not for each message +in the folder. +The syntax of this part of the Pattern is similar to the header patterns. +It is a list of keywords. +The Keyword part of the Pattern is a match if the message has any of +the keywords in the list set. +Like other parts of the Pattern, if this is unset it will be ignored. + +<H4>Message Character Set</H4> + +A message may use one or more character sets. +This part of the Pattern matches messages which make use of one or more of +the character sets specified in the pattern. +It will be considered a match if a message uses any of the character +sets in the list you give here. +The syntax of this part of the Pattern is similar to the header patterns +and the Message Keywords pattern. +It is a list of character sets. + +<P> +Besides actual character set names (for example, ISO-8859-7, KOI8-R, or +GB2312) you may also use some shorthand names that <EM>Alpine</EM> provides. +These names are more understandable shorthand names for sets of +character set names. +Two examples are "Cyrillic" and "Greek". +Selecting one of these shorthand names is equivalent to selecting all of +the character sets that make up the set. +You can see all of these shorthand names and the lists of character sets +they stand for by typing the "T" command with the Character +Set pattern highlighted. +The Character Set part of the Pattern is a match if the message uses any +of the character sets in the list. +Like other parts of the Pattern, if this is unset it will be ignored. + +<H4>Raw 8-bit in Subject</H4> + +It seems that lots of unwanted email contains unencoded 8-bit characters +in the Subject. +Normally, characters with the 8th bit set are not allowed in the Subject +header unless they are MIME-encoded. +This option gives you a way to match messages which have Subjects which +contain unencoded 8-bit characters. +Setting this option will affect performance in large folders because the +subject of each message in the folder has to be checked. + +<H4>Beginning of Month</H4> + +This option gives you a way to take some action once per month. +The value "Yes" means that this must be the first time <EM>Alpine</EM> has +been run this month in order to count as a match, + +<H4>Beginning of Year</H4> + +This option gives you a way to take some action once per year. +The value "Yes" means that this must be the first time <EM>Alpine</EM> has +been run this year in order to count as a match, + +<H4>From or Reply-To address in Address Books</H4> + +This option gives you a way to match messages which have a From or +a Reply-To address +which is in one of your address books. +Only the simple entries in your address books are searched. +Address book distribution lists are ignored! +Setting this option will affect performance in large folders because the +From and Reply-To of each message in the folder have to be checked. + +<H4>Categorizer Command</H4> + +This is a command that is run with its standard input set to the message +being checked and its standard output discarded. +The full directory path should be specified. +The command will be run and then its exit status will be checked against +the Exit Status Interval, which defaults to just the value zero. +If the exit status of the command falls in the interval, it is considered +a match, otherwise it is not a match. +<P> + +This option may actually be a list of commands. +The first one that exists and is executable is used. +That makes it possible to use the same configuration with Unix <EM>Alpine</EM> and +<EM>PC-Alpine</EM>. +<P> + +If none of the commands in the list exists and is executable then the rule +is <EM>not</EM> a match. +If it is possible that the command may not exist, you should be careful +to structure your rules so that nothing destructive +happens when the command does not exist. +For example, you might have a filter that filters away spam when there is +a match but does nothing when there is not a match. +That would continue to work correctly if the command didn't exist. +However, if you have a filter which filters away spam when there is not +a match and keeps it when there is a match, that would filter everything +if the categorizer command didn't exist. + +<H3><A NAME="help-for-pattern-config"></A>Help Configuring Pattern Fields</H3> + +<DL COMPACT> + +<DT> <A NAME="role-nickname"><EM>Nickname</EM></A> + +<DD> This is a nickname to help you. +You should have a different nickname for each role you define. +The nickname will be used in the SETUP ROLE RULES screen to allow you to +pick a role to edit. +It will also be used when you send a message to let you know you are +sending with a different role than you use by default, and +it will be useful for choosing a role when composing with the Role command +or when composing with one of the Role Uses set to With Confirmation. +This field is not used in the outgoing message. +<P> + +<DT> <A NAME="role-comment"><EM>Comment</EM></A> + +<DD> This is a comment to help you. +This comment does not play any functional role, it is simply an optional +comment to help you remember what the rule is for. +<P> + +<DT> <A NAME="to-pattern"><EM>To pattern</EM></A> + +<DD> If this pattern is non-blank, then for this role to be considered a +match, at least one of the recipients from +the To line of the message being replied to or forwarded +must match this pattern. +In the case of the Compose command, this pattern and the other header +patterns are ignored. +If this pattern is a list of patterns, then at least one of the +recipients must match at least one of the patterns. +(Any other non-blank parts of the Pattern must match, too.) +If the message being replied to or forwarded has a Resent-To header line, +then that is used in place of the To line. +(Note that this special Resent rule only applies to the To header. The +Resent-From, Resent-Subject, and so on are not consulted.) +<P> +It is possible to add a <EM>NOT</EM> to the To Pattern meaning with the +"!" "toggle NOT" command. +This changes the meaning of the To pattern so that it has the opposite meaning. +It will be considered a match if there are no matches between the +addresses in the To: line and the list of To patterns. +<P> +Don't make the mistake of putting the "!" in the data field for +the pattern. +For example, if you type the characters "!frizzle" into the To +pattern, the pattern will look like: +<P> +<PRE> + To pattern = !frizzle +</PRE> +<P> +This means you want to match the 8 character sequence "!frizzle". +In order to match messages which do not have "frizzle" in +their To field, first type the characters "frizzle" followed +by carriage return for the value of the To pattern, then negate it +by typing the "!" command. +It should end up looking like +<P> +<PRE> + ! To pattern = frizzle +</PRE> +<P> + +<DT> <A NAME="from-pattern"><EM>From pattern</EM></A> + +<DD> This is just like the +<A HREF="#to-pattern"><EM>To pattern</EM></A> +except that it is compared with +the address from the From header of the message being replied to or forwarded instead +of the addresses from the To header. +<P> + +<DT> <A NAME="sender-pattern"><EM>Sender pattern</EM></A> + +<DD> This is just like the +<A HREF="#to-pattern"><EM>To pattern</EM></A> +except that it is compared with +the address from the Sender header of the message being replied to or forwarded instead +of the addresses from the To header. +If there is no Sender header, then the From header is used instead. +<P> + +<DT> <A NAME="cc-pattern"><EM>Cc pattern</EM></A> + +<DD> This is just like the +<A HREF="#to-pattern"><EM>To pattern</EM></A> +except that it is compared with +the address from the CC header of the message being replied to or forwarded instead +of the addresses from the To header. +<P> + +<DT> <A NAME="news-pattern"><EM>News pattern</EM></A> + +<DD> If this pattern is non-blank, then for this role to be considered a +match, at least one of the newsgroups from +the Newsgroups line of the message must match this pattern. +If this pattern is a list of patterns, then at least one of the +newsgroups must match at least one of the patterns. +(Any other non-blank parts of the Pattern must match, too.) +<P> + +<DT> <A NAME="subject-pattern"><EM>Subject pattern</EM></A> + +<DD> This is similar to the other header patterns. +It is compared with +the contents from the Subject of the message being replied to or forwarded. +<P> +If you enter non-ascii characters in this field then the search will be +done using the character set you have defined with the +<A HREF="#char-set">Character-Set</A> +configuration variable. +(The truly sophisticated may use an alternate character set for a search +by entering the MIME encoding of the header string here.) +<P> + +<DT> <A NAME="extra-header-patterns"><EM>Extra header patterns</EM></A> + +<DD> There isn't actually a field called Extra header patterns, but you +may add extra header patterns by moving the cursor to one of the header +patterns and using the "eXtraHdr" command to add a new header +pattern. +You would do this if the six predefined header patterns don't cover the +header you want to use for pattern matching. +Once you've added an extra header pattern, you use it just like the +Subject pattern. +Of course, it is compared with +the contents from the particular header field of the message being replied +to or forwarded rather than the contents from the subject field. +To remove an extra header pattern from a role, use the "RemoveHdr" +command on the highlighted extra header. +<P> +If you enter non-ascii characters in this field then the search will be +done using the character set you have defined with the +<A HREF="#char-set">Character-Set</A> +configuration variable. +(The truly sophisticated may use an alternate character set for a search +by entering the MIME encoding of the header string here.) +<P> + +<DT> <A NAME="recip-pattern"><EM>Recipient pattern</EM></A> + +<DD> This is just like the +<A HREF="#to-pattern"><EM>To pattern</EM></A> +except that it is compared with +the addresses from both the To header and the Cc header +instead of just the addresses from the To header. +It's equivalent to having two different rules; +one with a To pattern and the other with the same Cc pattern. +<P> + +<DT> <A NAME="partic-pattern"><EM>Participant pattern</EM></A> + +<DD> This is just like the +<A HREF="#to-pattern"><EM>To pattern</EM></A> +except that it is compared with +the addresses from the To header, the Cc header, and the From header +instead of just the addresses from the To header. +It's equivalent to having three different rules; +one with a To pattern, another with the same Cc pattern, and another +with the same From pattern. +<P> + +<DT> <A NAME="alltext-pattern"><EM>AllText pattern</EM></A> + +<DD> This is similar to the header patterns. +Instead of comparing with text in a particular header field it is compared with +all of the text in the message header and body. +<P> +If you enter non-ascii characters in this field then the search will be +done using the character set you have defined with the +<A HREF="#char-set">Character-Set</A> +configuration variable. +(The truly sophisticated may use an alternate character set for a search +by entering the MIME encoding of the header string here.) +<P> + +<DT> <A NAME="bodytext-pattern"><EM>BodyText pattern</EM></A> + +<DD> Just like AllText, except it is compared only with the body of the +message, not the body and header. + +<P> +If you enter non-ascii characters in this field then the search will be +done using the character set you have defined with the +<A HREF="#char-set">Character-Set</A> +configuration variable. +(The truly sophisticated may use an alternate character set for a search +by entering the MIME encoding of the header string here.) +<P> + +<DT> <A NAME="age-interval"><EM>Age Interval</EM></A> + +<DD>The Age Interval, if defined, is part of the Pattern. +If you use this, it should be set to something like: +<P> +<CENTER><SAMP>(min_age,max_age)</SAMP></CENTER> +<P> +where "min_age" and "max_age" are non-negative integers. +The special value "INF" may be used for the max value. +It represents infinity. +<P> +In rare cases it may be useful to use the more general form of the value, +which is a comma-separated list of intervals. +It would look something like: +<P> +<CENTER><SAMP>(min_age1,max_age1),(min_age2,max_age2),...</SAMP></CENTER> +<P> +When there is an Age Interval defined, it is a match if the age, in days, of +the message is contained in the interval. +The interval includes both endpoints. +If the option is set to a list of intervals then it is a match if the +age of the message is contained in any of the intervals. +<P> +Even though this option is called Age, it isn't actually +the <EM>age</EM> of the message. +Instead, it is how many days ago the message arrived in one of your folders. +If the current time is a little past midnight, then a message that arrived +just before midnight arrived yesterday, even though the message is only +a few minutes old. +By default, the date being used is not the date in the Date +header of the message. +It is the date that the message arrived in one of your folders. +When you Save a message from one folder to another that arrival date +is preserved. +If you would like to use the date in the Date header that is possible. +Turn on the option +<EM>use-date-header-for-age</EM> +near the bottom of the rule definition. +<P> +A value of 0 is today, 1 is yesterday, 2 is the day before yesterday, and so on. +The age interval +<P> +<CENTER><SAMP>(2,2)</SAMP></CENTER> +<P> +matches all messages that arrived on the day before yesterday. +The interval +<P> +<CENTER><SAMP>(180,INF)</SAMP></CENTER> +<P> +matches all messages that arrived at least 180 days before today. +The interval +<P> +<CENTER><SAMP>(0,1)</SAMP></CENTER> +<P> +matches all messages that arrived today or yesterday. +<P> + +<DT> <A NAME="score-interval"><EM>Score Interval</EM></A> + +<DD> The Score Interval, if defined, is part of the Pattern. +If you use this, it should be set to something like: +<P> +<CENTER><SAMP>(min_score,max_score)</SAMP></CENTER> +<P> +where "min_score" and "max_score" are integers between +-32000 and 32000. +The special values "-INF" and "INF" can be used for +the min and max values. +These represent negative and positive infinity. +<P> +Actually, the value may be a list of intervals rather than just a +single interval if that is useful. +The elements of the list are separated by commas like: +<P> +<CENTER><SAMP>(min_score1,max_score1),(min_score2,max_score2),...</SAMP></CENTER> +<P> +When there is a Score Interval defined, it is a match if the score for +the message is contained in any of the intervals. +The intervals include both endpoints. +The score for a message is calculated by looking at every scoring rule +defined and adding up the Score Values for the rules which match the message. +<P> + +<DT> <A NAME="keyword-pattern"><EM>Keyword pattern</EM></A> + +<DD> A folder may have user-defined keywords. +These are similar to the Important flag which the user may set using the +Flag command. +The difference is that the Important flag is always present for each folder. +User-defined keywords are picked by the user. +You may add new keywords by defining them in the +<A HREF="#keywords">Keywords</A> option in the Setup/Config screen. +After you have added a potential keyword with the Keywords option, +the Flag command may be used to set or clear the keyword on individual messages. +If you have given a keyword a nickname when configuring it, +that nickname may be used instead of the actual keyword. + +<P> +When filling in a value for this field, it may be easiest to use +the "T" command, which presents you with a list of the keywords +you have defined to choose from. + +<P> +This part of the Pattern matches messages with certain keywords set. +It will be considered a match if a message has any of the keywords in the +list set. + +<P> +It is possible to add a <EM>NOT</EM> to the Keyword Pattern meaning with the +"!" "toggle NOT" command. +This changes the meaning of the Keyword pattern so that it has the opposite meaning. +It will be considered a match if none of the keywords in the list are set +for a message. +<P> +Don't make the mistake of putting the "!" in the data field for +the pattern. +For example, if you type the characters "!frizzle" into the Keyword +pattern, the pattern will look like: +<P> +<PRE> + Keyword pattern = !frizzle +</PRE> +<P> +This means you want to match the 8 character sequence "!frizzle". +In order to match messages which do not have the keyword "frizzle" +set, first type the characters "frizzle" followed +by carriage return for the value of the Keyword pattern, then negate it +by typing the "!" command. +It should end up looking like +<P> +<PRE> + ! Keyword pattern = frizzle +</PRE> +<P> + +<DT> <A NAME="charset-pattern"><EM>Character Set pattern</EM></A> + +<DD> A message may use one or more character sets. +This part of the Pattern matches messages which make use of +certain specified character sets. +It will be considered a match if a message uses any of the character +sets in the list you give here. + +<P> +When filling in a value for this field, you may use +the "T" command, which presents you with a large list of +possible character sets to choose from. +You may also just type in the name of a character set, and it need not +be one that Alpine knows about. + +<P> +Besides actual character set names (for example, ISO-8859-7, KOI8-R, or +GB2312) you may also use some shorthand names that Alpine provides. +These names are more understandable shorthand names for sets of +character set names. +Two examples are "Cyrillic" and "Greek". +Selecting one of these shorthand names is equivalent to selecting all of +the character sets that make up the set. +You can see all of these shorthand names and the lists of character sets +they stand for by typing the "T" command. + +<P> +For the purposes of this Pattern, +<EM>Alpine</EM> will search through a message for all of the text parts and +collect the character sets declared for each part. +It will also look in the Subject line for a character set used there. +<EM>Alpine</EM> does not actually look at the text of the message or the text +of the Subject to determine if a declared character set is actually +used, it looks only at the declarations themselves in the MIME part headers +and in the Subject. + +<P> +It is possible to add a <EM>NOT</EM> to the Character Set Pattern meaning with the +"!" "toggle NOT" command. +This changes the meaning of the Character Set pattern so that +it has the opposite meaning. +It will be considered a match if none of the character sets in the +list are used in a message. +<P> +Don't make the mistake of putting the "!" in the data field for +the pattern. +For example, if you type the characters "!GB2312" into the +Character Set pattern, the pattern will look like: +<P> +<PRE> + Charset pattern = !GB2312 +</PRE> +<P> +This means you want to match the 7 character sequence "!GB2312". +In order to match messages which do not have the +character set "GB2312" +set, first type the characters "GB2312" followed +by carriage return for the value of the Character Set pattern, then negate it +by typing the "!" command. +It should end up looking like +<P> +<PRE> + ! Charset pattern = GB2312 +</PRE> +<P> +A technicality: Since comma is the character used to separate multiple +values in a pattern field, you have to escape comma with a backslash (\) if +you want to include a literal comma in the field. +In other words, if you type a backslash followed by a comma it will +be interpreted as a comma by <EM>Alpine</EM>, instead of as a separator between +pattern values. +All other backslashes are literal backslashes and should not be escaped. +<P> + +<DT> <A NAME="current-folder-type"><EM>Current Folder Type</EM></A> + +<DD> The Current Folder Type is part of the Pattern. +It refers to the type of the currently open folder, which is the folder +you were last looking at from the MESSAGE INDEX or MESSAGE TEXT screen. +In order for a pattern to be considered a match, the current folder must +be of the type you set here. +The three types "Any", "News", and "Email" are +all what you might think. +<P> +If the Current Folder Type for a Pattern is set to "News", for +example, then +that will only be a match if the current folder is a newsgroup and +the rest of the Pattern matches. +The value "Specific" may be used when you want to limit the match +to a specific folder (not just a specific type of folder), or to a list of +specific folders. +In order to match a specific folder you must Select the "Specific" +button <EM>AND</EM> you must fill in +the name (or list of names) of +the folder in the "Folder" field. +If the current folder is any of the folders in the list, that is considered +a match. +The name of each folder in the list may be either "INBOX", the technical specification +of the folder (like what appears in your configuration file) or, if the +folder is one of your incoming folders, it may be the nickname you've given +the folder. +Here are a couple samples of specific folder names: +<P> +<CENTER><SAMP>{monet.art.example.com}mail/art-class</SAMP></CENTER> +<P> +<CENTER><SAMP>{news.example.com/nntp}#news.comp.mail.pine</SAMP></CENTER> +<P> +The easiest way to fill in the "Folder" field is to use +the T command which is available when the "Folder" line is +hilighted. +Note that you won't be able to edit the "Folder" line unless the +Current Folder Type is set to "Specific", and any value that +"Folder" has is ignored unless the type +is set to "Specific". +<P> +When reading a newsgroup, there may be a performance penalty +incurred when collecting the information necessary to check a Pattern. +For this reason, the default Current Folder Type is set to "Email". +For example, a role with a non-Normal Index Line Color +and a Current Folder Type of +"Any" or "News" may cause the MESSAGE INDEX +screen to draw more slowly when in a newsgroup. +<P> + +<DT> <A NAME="message-status-important"><EM>Message Status Important</EM></A> + +<DD> This part of the Pattern may have one of three possible values. +The default value is "Don't care", which matches any message. +The other two values are "Yes", which means the message must be +flagged "Important" in order to be a match; or "No", which +means the message must <EM>not</EM> be flagged "Important" in order +to be considered a match. +<P> + +<DT> <A NAME="message-status-new"><EM>Message Status New</EM></A> + +<DD> This part of the Pattern may have one of three possible values. +The default value is "Don't care", which matches any message. +The other two values are "Yes", which means the message must be +"New" in order to be a match; or "No", which +means the message must <EM>not</EM> be "New" in order +to be a match. +"New" is the same as <EM>Unseen</EM> and not "New" is the +same as <EM>Seen</EM>. +<P> +The nomenclature for New and Recent is a bit confusing: +<P> +New means that the message is Unseen. +It could have been in your mailbox for a long time but if you haven't looked +at it, it is still considered New. +That matches the default <EM>Alpine</EM> index display that shows an N for such a +message. +<P> +Recent means that the message was added to this folder since the last time +you opened the folder. +<EM>Alpine</EM> also shows an N by default for these types of messages. +If you were to run two copies of <EM>Alpine</EM> that opened a folder one right after +the other, a message would only show up as Recent in (at most) the first +<EM>Alpine</EM> session. +<P> + +<DT> <A NAME="message-status-recent"><EM>Message Status Recent</EM></A> + +<DD> This part of the Pattern may have one of three possible values. +The default value is "Don't care", which matches any message. +The other two values are "Yes", which means the message must be +"Recent" in order to be a match; or "No", which +means the message must <EM>not</EM> be "Recent" in order +to be a match. +"Recent" means that the message was added to the folder since +the last time the folder was opened. +If more than one mail client has the folder opened, the message will +appear to be "Recent" to only one of the clients. +<P> +The nomenclature for New and Recent is a bit confusing: +<P> +New means that the message is Unseen. +It could have been in your mailbox for a long time but if you haven't looked +at it, it is still considered New. +That matches the default <EM>Alpine</EM> index display that shows an N for such a +message. +<P> +Recent means that the message was added to this folder since the last time +you opened the folder. +<EM>Alpine</EM> also shows an N by default for these types of messages. +If you were to run two copies of <EM>Alpine</EM> that opened a folder one right after +the other, a message would only show up as Recent in (at most) the first +<EM>Alpine</EM> session. +<P> + +<DT> <A NAME="message-status-deleted"><EM>Message Status Deleted</EM></A> + +<DD> This part of the Pattern may have one of three possible values. +The default value is "Don't care", which matches any message. +The other two values are "Yes", which means the message must be +marked "Deleted" in order to be a match; or "No", which +means the message must <EM>not</EM> be marked "Deleted" in order +to be a match. +<P> +If you are thinking of using this part of the Pattern as a way to prevent +messages from being filtered more than once in a Filter Pattern, +take a look at the Filter Option +<A HREF="#move-only-if-not-deleted">"move-only-if-not-deleted"</A> +instead. +It should work better than using this field since it will hide the filtered +messages even if they are already Deleted. +<P> + +<DT> <A NAME="message-status-answered"><EM>Message Status Answered</EM></A> + +<DD> This part of the Pattern may have one of three possible values. +The default value is "Don't care", which matches any message. +The other two values are "Yes", which means the message must be +marked "Answered" in order to be a match; or "No", which +means the message must <EM>not</EM> be marked "Answered" in order +to be a match. +<P> + +<DT> <A NAME="subject-contains-raw-8bit"><EM>Subject Contains Raw 8-bit</EM></A> + +<DD> This part of the Pattern may have one of three possible values. +The default value is "Don't care", which matches any message. +The other two values are "Yes", which means the Subject of +the message must contain unencoded 8-bit characters (characters with the +most significant bit set) +in order to be a match; or "No", which +means the Subject must <EM>not</EM> +contain unencoded 8-bit characters in order to be a match. +<P> + +<DT> <A NAME="beginning-of-month"><EM>Beginning of Month</EM></A> + +<DD> This part of the Pattern may have one of three possible values. +The default value is "Don't care", which matches any message. +The other two values are "Yes", which means this is the first +time <EM>Alpine</EM> has been run this month; +or "No", which +means this is <EM>not</EM> the first time <EM>Alpine</EM> has been run this month. +The way that <EM>Alpine</EM> decides if it is the beginning of the month or not is +to compare today's date with the date stored in the +<A HREF="#last-time">Last-Time-Prune-Questioned</A> +variable in the config file. +If the month of today's date is later than the month stored in the variable, +then this is considered to be the first time you have run Alpine this month, and +that turns the Beginning of the Month option on. +<P> + +<DT> <A NAME="beginning-of-year"><EM>Beginning of Year</EM></A> + +<DD> This part of the Pattern may have one of three possible values. +The default value is "Don't care", which matches any message. +The other two values are "Yes", which means this is the first +time <EM>Alpine</EM> has been run this year; +or "No", which +means this is <EM>not</EM> the first time <EM>Alpine</EM> has been run this year. +The way that <EM>Alpine</EM> decides if it is the beginning of the year or not is +to compare today's date with the date stored in the +<A HREF="#last-time">Last-Time-Prune-Questioned</A> +variable in the config file. +If the year of today's date is later than the year stored in the variable, +then this is considered to be the first time you have run Alpine this year, and +that turns the Beginning of the Year option on. +<P> + +<DT> <A NAME="from-in-abook"><EM>From or Reply-To in Address Book</EM></A> + +<DD> This part of the Pattern may have one of five possible values. +The default value is "Don't care", which matches any message. +The value "Yes, in any address book" means either the From address +or the Reply-To address of the message must be in at least one of your +address books in order to be a match. +The value "No, not in any address book" +means neither the From nor the Reply-To addresses may +be in any of your address books in order to be a match. +<P> +The values "Yes, in specific address books" and +"No, not in any of specific address books" are similar but instead +of depending on all address books you are allowed to give a list of address +books to look in. +Usually this would be a single address book but it may be a +list of address books as well. +For each of these "specific" address book options you Select which +of the Specific options you want (Yes or No) <EM>AND</EM> fill in the +name (or list of names) of the address book in the +"Abook List" field. +The names to be used are those that appear in the ADDRESS BOOK LIST screen. +The easiest way to fill in the Abook List field it to use +the "T" command which is available when the "Abook List" +line is highlighted. +Note that you won't be able to edit the "Abook List" line unless the +option is set to one of the two "Specific", values. +<P> + +<DT> <A NAME="categorizer-cmd-explained"><EM>Categorizer Command</EM></A> + +<DD> This is a command that is run with its standard input set to the message +being checked and its standard output discarded. +The full directory path should be specified. +The command will be run and then its exit status will be checked against +the <EM>Exit Status Interval</EM>, which defaults to just the value zero. +If the exit status of the command falls in the interval, it is considered +a match, otherwise it is not a match. +<P> + +This option may actually be a list of commands. +The first one that exists and is executable is used. +That makes it possible to use the same configuration with Unix <EM>Alpine</EM> and +<EM>PC-Alpine</EM>. +<P> + +If none of the commands in the list exists and is executable then the rule +is <EM>not</EM> a match. +If it is possible that the command may not exist, you should be careful +to structure your rules so that nothing destructive +happens when the command does not exist. +For example, you might have a filter that filters away spam when there is +a match but does nothing when there is not a match. +That would continue to work correctly if the command didn't exist. +However, if you have a filter which filters away spam when there is not +a match and keeps it when there is a match, that would filter everything +if the categorizer command didn't exist. +<P> + +The categorizer command is run and the result is the exit status of +that command. +If that exit status falls in the <EM>Exit Status Interval</EM> +then it is considered a match, otherwise it is not a match. +Of course for the entire rule to match, it must also be checked against +the other defined parts of the Pattern. +<P> +The <EM>Exit Status Interval</EM> defaults to the single value 0 (zero). +If you define it, it should be set to something like: +<P> +<CENTER><SAMP>(min_exit_value,max_exit_value)</SAMP></CENTER> +<P> +where "min_exit_value" and "max_exit_value" are integers. +The special values "INF" and "-INF" may be used for large +positive and negative integers. +<P> +Actually, a list of intervals may be used if you wish. +A list would look like +<P> +<CENTER><SAMP>(min_exit_value1,max_exit_value1),(min_exit_value2,max_exit_value2),...</SAMP></CENTER> +<P> +When there is an <EM>Exit Status Interval</EM> defined, it is a match if the exit status +of the categorizer command is contained in any of the intervals. +The intervals include both endpoints. +<P> +The default interval is +<P> +<CENTER><SAMP>(0,0)</SAMP></CENTER> +<P> +and it matches only if the command exits with exit status equal to zero. +<P> +It is also possible to set a <EM>Character Limit</EM> for the categorizer command. +Setting this option makes it possible to limit how much of the message +is made available to the categorizer command as input. +The default value (-1) means that the entire message is fed to the +command. +A value of 0 (zero) means that only the headers of the message are +made available. +A positive integer means that the headers plus that many characters from +the body of the message are passed to the categorizer. +<P> + +</DL> + +<H2><A NAME="configuring-news"></A>Configuring News</H2> + +<EM>Alpine</EM> can access news folders in any one of three different ways: +<DL> +<DT>REMOTE NNTP</DT> +<DD>Using the Network News Transport Protocol (NNTP) to +access news on a remote news server. In this case the newsrc file is +stored on the machine where <EM>Alpine</EM> is running. + +<P> +To specify a remote news-collection accessed via NNTP use the +SETUP/collectionList screen's "Add" command. Set the +Server: value to the NNTP server's hostname appended with the +communication method "/service=NNTP", and set the Path: +value to the "#news." namespace (without the quotes). +<P> +Instead of specifying a news-collection, you may simply set the +<A HREF="#nntp-server">nntp-server</A> +option, which will cause <EM>Alpine</EM> to create a default news-collection for you. +Another NNTP option which may be of interest is +<A HREF="#nntp-range">nntp-range</A>. + +<DT>REMOTE IMAP</DT> +<DD>Using the Internet Message Access Protocol (IMAP) to +access news on a remote news server. In this case, your newsrc file is +stored on the news server, in your home directory, so you must have an +account on the news server, but you would be running <EM>Alpine</EM> on a different +machine. The news server must be running an IMAPd server process. + +<P> +To specify a remote news-collection accessed via IMAP use the +SETUP/collectionList screen's "Add" command. Set the +Server: value to the IMAP server's hostname, and set the Path: value +to the "#news." namespace (without the quotes). + +</DD> + +<DT>LOCAL</DT> +<DD>Using local file access to the news database. In this +case, your newsrc file is stored on the news server, in your home +directory, so you must have an account on the news server, and you would +be running <EM>Alpine</EM> on the same machine. + +<P> +To specify a local news-collection use the SETUP/collectionList +screen's "Add" command. Leave the Server: value blank, and +set the Path: value to the "#news." namespace (without the +quotes). + +</DD> +</DL> + +<P> + +NOTE: Should no news-collection be defined as above, <EM>Alpine</EM> will +automatically create one using the Setup/Config screen's +"nntp-server" variable's value if defined. The collection +will be created as a "Remote NNTP" as described above. + +<P> + +If you are a <EM>PC-Alpine</EM> user, either option 1 (NNTP) or option 2 (IMAP) is +possible. If you don't have an account on the news server, or if the news +server is not running an IMAP daemon, then you must use NNTP. (If you are not +sure, ask your service provider, university, or company for help.) In +this case, your Unix .newsrc file can be transferred to your PC. A good +place to put it would be in the same directory as your PINERC file, under +the name NEWSRC, but you can +<A HREF="#newsrc-path">specify a different location</A>. + +<P> +Other configuration features related to news are +<A HREF="#enable-8bit-nntp-posting">Enable-8bit-Nntp-Posting</A>. +<A HREF="#compose-sets-newsgroup-without-confirm">Compose-Sets-Newsgroup-Without-Confirm</A>, +<A HREF="#news-approximates-new-status">News-Approximates-New-Status</A>, +<A HREF="#news-deletes-across-groups">News-Deletes-Across-Groups</A>, +<A HREF="#news-offers-catchup-on-close">News-Offers-Catchup-On-Close</A>, +<A HREF="#news-post-without-validation">News-Post-Without-Validation</A>, +<A HREF="#news-read-in-newsrc-order">News-Read-in-Newsrc-Order</A>, and +<A HREF="#quell-extra-post-prompt">Quell-Extra-Post-Prompt</A>. + +<HR> + +<!-- pnuts --> + +</BODY> +</HTML> diff --git a/doc/tech-notes/for.pnuts b/doc/tech-notes/for.pnuts new file mode 100644 index 00000000..ca60d61d --- /dev/null +++ b/doc/tech-notes/for.pnuts @@ -0,0 +1,9 @@ +index.html +introduction.html +background.html +installation.html +cmd-line.html +config.html + config-notes.html +low-level.html +porting.html diff --git a/doc/tech-notes/index.html b/doc/tech-notes/index.html new file mode 100644 index 00000000..92240e86 --- /dev/null +++ b/doc/tech-notes/index.html @@ -0,0 +1,122 @@ +<HTML> +<HEAD><TITLE>Alpine Technical Notes</TITLE></HEAD> +<BODY> +<H1>Alpine Technical Notes</H1> + +Version 2.10, January 2013 + +<H2><A NAME="TOC">Table of Contents</A></H2><P> + +<H3><A HREF="introduction.html">Introduction</A></H3> + +<UL> +<LI><A HREF="introduction.html#design">Design Goals</A><BR> +<LI><A HREF="introduction.html#components">Alpine Components</A><BR> +</UL> + +<H3><A HREF="background.html">Background Details</A></H3> + +<UL> +<LI><A HREF="background.html#DNS">Domain Names</A><BR> +<LI><A HREF="background.html#rfc2822">RFC 2822 Compliance</A><BR> +<LI><A HREF="background.html#SMTP">SMTP and Sendmail</A><BR> +<LI><A HREF="background.html#IMAP">Internet Message Access Protocol (IMAP)</A><BR> +<LI><A HREF="background.html#MIME">Multipurpose Internet Mail Extensions (MIME)</A><BR> +<LI><A HREF="background.html#collections">Folder Collections</A><BR> +</UL> + +<H3><A HREF="installation.html">Building and Installation</A></H3> + +<UL> +<LI><A HREF="installation.html#compile">Compile-time Options</A><BR> +<LI><A HREF="installation.html#ldap-compile">Including LDAP Functionality</A><BR> +<LI><A HREF="installation.html#krb5-compile">Including Kerberos 5 Functionality</A><BR> +<LI><A HREF="installation.html#pine-compile">Other Alpine Compile-time Options</A><BR> +<LI><A HREF="installation.html#imapd-compile">IMAPd Compile-time Options</A><BR> +<LI><A HREF="installation.html#build">Building the Alpine Programs</A><BR> +<LI><A HREF="installation.html#install-unix">Installing Alpine and Pico on UNIX Platforms</A><BR> +<LI><A HREF="installation.html#install-pc">Installing PC-Alpine</A><BR> +<LI><A HREF="installation.html#install-imapd">Installing IMAPd</A><BR> +<LI><A HREF="installation.html#files-unix">Support Files and Environment Variables: UNIX Alpine</A><BR> +<LI><A HREF="installation.html#files-pc">Support Files, Environment Variables, and Registry Values: PC-Alpine</A><BR> +</UL> + +<H3><A HREF="cmd-line.html">Command Line Arguments</A></H3> + +<UL> +<LI><A HREF="cmd-line.html#alpine">Alpine</A><BR> +<LI><A HREF="cmd-line.html#pico">Pico</A><BR> +<LI><A HREF="cmd-line.html#pilot">Pilot</A><BR> +</UL> + +<H3><A HREF="config.html">Configuration and Preferences</A></H3> + +<UL> +<LI><A HREF="config.html#pine-conf">Alpine Configuration</A><BR> +<LI><A HREF="config.html#gen-conf">General Configuration Variables</A><BR> +<LI><A HREF="config.html#features-conf">Configuration Features</A><BR> +<LI><A HREF="config.html#hidden-config">Hidden Config Variables and Features</A><BR> +<LI><A HREF="config.html#ret-var">Retired Variables</A><BR> +<LI><A HREF="config.html#index-tokens">Tokens for Index and Replying</A><BR> +<LI><A HREF="config.html#reply-token-conditionals">Conditional Inclusion of Text for Reply-Leadin, Signatures, and Templates</A><BR> +<LI><A HREF="config.html#per-server-ldap-config">Per Server Directory Configuration</A><BR> +<LI><A HREF="config.html#color-config">Color Configuration</A><BR> +<LI><A HREF="config.html#index-color-config">Index Line Color Configuration</A><BR> +<LI><A HREF="config.html#role-config">Role Configuration</A><BR> +<LI><A HREF="config.html#filter-config">Filtering Configuration</A><BR> +<LI><A HREF="config.html#scoring-config">Scoring Configuration</A><BR> +<LI><A HREF="config.html#other-config">Other Rules Configuration</A><BR> +<LI><A HREF="config.html#search-rules-config">Search Rules Configuration</A><BR> +<LI><A HREF="config.html#patterns-section">Patterns</A><BR> +<LI><A HREF="config.html#configuring-news">Configuring News</A><BR> + +<H4><A HREF="config-notes.html">Configuration Notes</A></H4> + +<UL> +<LI><A HREF="config-notes.html#fkey">Alpine in Function Key Mode</A><BR> +<LI><A HREF="config-notes.html#domain">Domain Settings</A><BR> +<LI><A HREF="config-notes.html#collections">Syntax for Collections</A><BR> +<LI><A HREF="config-notes.html#remote-folders">Syntax for Folder Names</A><BR> +<LI><A HREF="config-notes.html#server-name-syntax">Server Name Syntax</A><BR> +<LI><A HREF="config-notes.html#folder-namespaces">Folder Namespaces</A><BR> +<LI><A HREF="config-notes.html#maildrop">What is a Mail Drop?</A><BR> +<LI><A HREF="config-notes.html#sorting">Sorting a Folder</A><BR> +<LI><A HREF="config-notes.html#alt-ed">Alternate Editor</A><BR> +<LI><A HREF="config-notes.html#signature">Signatures and Signature Placement</A><BR> +<LI><A HREF="config-notes.html#feature-list">Feature List Variable</A><BR> +<LI><A HREF="config-notes.html#config-inheritance">Configuration Inheritance</A><BR> +<LI><A HREF="config-notes.html#env-variables">Using Environment Variables</A><BR> +<LI><A HREF="config-notes.html#smtp-server">SMTP Servers</A><BR> +<LI><A HREF="config-notes.html#mime.types">MIME.Types file</A><BR> +<LI><A HREF="config-notes.html#color-config-notes">Color Details</A><BR> +<LI><A HREF="config-notes.html#smime-general">S/MIME Overview</A><BR> +<LI><A HREF="config-notes.html#pc-notes">Additional Notes on PC-Alpine</A><BR> +</UL> + +</UL> + +<H3><A HREF="low-level.html">Behind the Scenes</A></H3> + +<UL> +<LI><A HREF="low-level.html#addrbook">Address Books</A><BR> +<LI><A HREF="low-level.html#remote-config">Remote Configuration</A><BR> +<LI><A HREF="low-level.html#checkpoint">Checkpointing</A><BR> +<LI><A HREF="low-level.html#debug">Debug Files</A><BR> +<LI><A HREF="low-level.html#INBOX">INBOX and Special Folders</A><BR> +<LI><A HREF="low-level.html#help">Internal Help Files</A><BR> +<LI><A HREF="low-level.html#char-set">International Character Sets</A><BR> +<LI><A HREF="low-level.html#interrupt">Interrupted and Postponed Messages</A><BR> +<LI><A HREF="low-level.html#status">Message Status</A><BR> +<LI><A HREF="low-level.html#MIME-read">MIME: Reading a Message</A><BR> +<LI><A HREF="low-level.html#MIME-send">MIME: Sending a Message</A><BR> +<LI><A HREF="low-level.html#new-mail">New Mail Notification</A><BR> +<LI><A HREF="low-level.html#NFS">NFS</A><BR> +<LI><A HREF="low-level.html#print">Printers and Printing</A><BR> +<LI><A HREF="low-level.html#save">Save and Export</A><BR> +<LI><A HREF="low-level.html#sent-mail">Sent Mail</A><BR> +<LI><A HREF="low-level.html#spell">Spell Checker</A><BR> +<LI><A HREF="low-level.html#terminal">Terminal Emulation and Key Mapping</A><BR> +</UL> + +</BODY> +</HTML> diff --git a/doc/tech-notes/installation.html b/doc/tech-notes/installation.html new file mode 100644 index 00000000..d36214ae --- /dev/null +++ b/doc/tech-notes/installation.html @@ -0,0 +1,577 @@ +<HTML><HEAD><TITLE>Alpine Technical Notes: Building and Installation</TITLE></HEAD><BODY> +<H1>Building and Installation</H1> + +<H2><A NAME="compile">Compile-time Options</A></H2> + +<EM>Alpine</EM>'s UNIX build environment +is based on Autotools (the GNU Build System). +Once you've unpacked the source distribution find the file +<CODE>configure</CODE> in the top-level directory. +You may look at the many options available by typing +<P> +<CENTER><SAMP> + ./configure --help +</SAMP></CENTER> + +<P> +or you could just try building with the command +<P> +<CENTER><SAMP> + ./configure +</SAMP></CENTER> + +<P> + +followed by + +<P> +<CENTER><SAMP> + make +</SAMP></CENTER> + +<P> + +Note, while the UW IMAP Toolkit (whose c-client +library <EM>Alpine</EM> uses for mailbox access) build is not based on +Autotools, <EM>Alpine</EM>'s configure script should set an +appropriate make target and compilation options for most systems. + +<P> + +Some of the following can only be set when you build. Others, +however, can be overridden by command-line flags to <EM>Alpine</EM> or settings in +<EM>Alpine</EM>'s user or system configuration files. +Some of the options which can be set when building: + +<H3><A NAME="ldap-compile">Including LDAP Functionality</A></H3> + +By default, the configure script will attempt to find the LDAP library +support for you. +If you are having trouble with LDAP take a look at the configure options +<DL COMPACT> +<DT> --with-ldap-dir=DIR +<DD> Specify the root of the LDAP lib/include path. +<DT> --with-ldap-include-dir=DIR +<DD> Specify the LDAP include path. +<DT> --with-ldap-lib-dir=DIR +<DD> Specify the LDAP library path. +<DT> --without-ldap +<DD> Disable LDAP support. +</DL> <P> + +<EM>Alpine</EM> uses LDAPv3 protocol. +When using the LDAPv3 protocol, the results are assumed to be in the +UTF-8 character set, which <EM>Alpine</EM> handles well. +If the LDAP server returns non-ascii data which is not encoded as UTF-8 +you will probably run into problems. +<P> + +<H3><A NAME="krb5-compile">Including Kerberos 5 Functionality</A></H3> + +This works analogously to the LDAP build. +By default, the configure script will attempt to find the Kerberos library +support for you. +If you are having trouble with Kerberos take a look at the configure options +<DL COMPACT> +<DT> --with-krb5-dir=DIR +<DD> Specify the root of the Kerberos lib/include path. +<DT> --with-krb5-include-dir=DIR +<DD> Specify the Kerberos include path. +<DT> --with-krb5-lib-dir=DIR +<DD> Specify the Kerberos library path. +<DT> --without-krb5 +<DD> Disable Kerberos support. +</DL> <P> + +<H3><A NAME="pine-compile">Other Alpine Compile-time Options</A></H3> + +<DL COMPACT> + +<DT> --disable-nls +<DD> Do not use Native Language Support. NLS refers to the use of GNU +gettext utilities to localize a program, in the sense that English +is translated to some other language. +At the time this was written the low-level support for NSL is included +in <EM>Alpine</EM> but no translations have been done. +If there is no translation available, that means that disabling NLS +will make no difference. If you have trouble building which is due +to gettext or libintl you could try this option, or one of the following. + +<DT> --with-libintl-prefix[=DIR] +<DT> --without-libintl-prefix + +<DT> --with-ssl-dir=DIR +<DD> Specify the root of the SSL lib/include path (OpenSSL). +<DT> --with-ssl-include-dir=DIR +<DD> Specify the SSL include path. +<DT> --with-ssl-lib-dir=DIR +<DD> Specify the SSL library path. +<DT> --with-ssl-certs-dir=DIR +<DD> Specify the path to the SSL certificates directory. +<DT> --without-ssl +<DD> Disable SSL support. + +<DT> --without-pthread +<DD> Do not test for nor build with POSIX thread support, which is used +only for the Busy-Cue in the status line at this time. + +<DT> --without-smime +<DD> Disable S/MIME support. + +<DT> --disable-debug +<DD> Never create debug files. + +<DT> --with-smtp-msa=PATH +<DD> Local Mail Submission Agent (sendmail, by default). +<DT> --with-smtp-msa-flags=FLAGS +<DD> MSA flags for SMTP on stdin/stdout (-bs -odb -oem). + +</DL> <P> + +There are many more options which you can see using the +<P> +<CENTER><SAMP> + ./configure --help +</SAMP></CENTER> + +<P> +command. +<P> + +<H3><A NAME="imapd-compile">IMAPd Compile-time Options</A></H3> + +There are no options or settings required for the version of <EM>IMAPd</EM> +distributed with <EM>Alpine</EM>. 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 <A +HREF="ftp://ftp.cac.washington.edu"><CODE>ftp.cac.washington.edu</CODE></A> +in the directory <CODE>mail</CODE>. The file is called <A +HREF="ftp://ftp.cac.washington.edu/mail/imap.tar.Z"><CODE>imap.tar.Z</CODE></A>. +Unless it has changed since <EM>Alpine</EM> was released, the directory +<CODE>imap</CODE> in the <EM>Alpine</EM> distribution is the IMAP +development package. +<P> +The c-client library has not been converted to use the +GNU Build System's autotools. +The <EM>Alpine</EM> configure script will try to correctly guess +the arguments needed for the c-client make command and will build +the library, but if you need to change anything you should take a +look at <CODE>imap/docs/BUILD</CODE> for more detailed instructions. +<P> + +<HR> + +<H2><A NAME="build">Building the Alpine Programs</A></H2> + +You may have already compiled <EM>Alpine</EM> 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: <P> + +<OL> + +<LI> Make sure you're in the root of the <EM>Alpine</EM> source. When you type +<CODE>ls</CODE> you should see the following files and directories (or +something close to it): + +<PRE> +aclocal.m4 config.sub imap Makefile.am packages web +alpine configure include Makefile.in pico +build.bat configure.ac install-sh mapi pith +build.cmd contrib LICENSE missing po +config.guess depcomp ltmain.sh mkinstalldirs README +config.rpath doc m4 NOTICE VERSION +</PRE> +<P> + +<LI> Give the command <CODE>./configure</CODE> +Configure should grind away for a few minutes. <P> + +<LI> When configure is complete, give the command <CODE>make</CODE>. +If make stops and asks + +<P> +<CENTER><SAMP> + Do you want to build with IPv6 anyway? Type y or n please: +</SAMP></CENTER> + +<P> +you should answer with a 'y'. +The compiler should grind away for a few minutes. The <EM>Alpine</EM> +binary will end up in <CODE>.../alpine/alpine</CODE> and the +Pico and Pilot binaries in <CODE>.../pico/pico</CODE> +and <CODE>.../pico/pilot</CODE>. Other binaries you may be interested +in are <CODE>.../alpine/rpdump</CODE> and <CODE>.../alpine/rpload</CODE> +and c-client binaries in the directories <CODE>.../imap/imapd</CODE>, +<CODE>.../imap/ipopd</CODE>, <CODE>.../imap/mailutil</CODE>, and so on. +<P> + +<LI> If you need to try again, make sure you're getting a clean start by giving the command +<CODE>make clean</CODE>. <P> + +</OL> +<P> + +<HR> + +<H2><A NAME="install-unix">Installing Alpine and Pico on UNIX Platforms</A></H2> + +Installing <EM>Alpine</EM> and <EM>Pico</EM> is 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 +<CODE>/usr/local/bin</CODE> though sometimes they are placed in +<CODE>/usr/bin</CODE>. All the help text is compiled into <EM>Alpine</EM> so there +are no <STRONG>required</STRONG> auxiliary files. Instead of copying the +binaries manually, you may use <CODE>make install</CODE> to install +them. <P> + +There are three optional auxiliary files: +<CODE>/usr/local/lib/pine.info</CODE>, +<CODE>/usr/local/lib/pine.conf</CODE>, and +<CODE>/usr/local/lib/pine.conf.fixed</CODE>. The file +<CODE>pine.info</CODE> 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 <CODE>pine.conf</CODE> is used to set system-wide default +configurations for <EM>Alpine</EM>. The file <CODE>pine.conf.fixed</CODE> is also +used to set system-wide default configurations for <EM>Alpine</EM>. +The difference +between these two files is that configuration variables set in the +<CODE>pine.conf.fixed</CODE> file may not normally be over-ridden by a +user. See the section on <A HREF="config.html"><EM>Alpine</EM> Configuration</A> +later in this document for details about +the <CODE>pine.conf</CODE> and <CODE>pine.conf.fixed</CODE> files. <P> + +<HR> + +<H2><A NAME="install-pc">Installing PC-Alpine</A></H2> + +<P> +The PC-Alpine 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. +Following current Windows conventions, a common directory into which the files +could be extracted would be <CODE>C:\Program Files\PC-Alpine\</CODE>. + +<P> +Having extracted PC-Alpine's .zip file to the directory of choice, you can +now run that directory's alpine.exe, which is the actual PC-Alpine program. +For convenience, you could place shortcuts to it on the task bar, start +menu, etc. + +<P> +Upon first running PC-Alpine, you may be asked where you would like to +access your Configuration file (called the <I>pinerc</I>). 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 <EM>Alpine</EM> programs). + +<P> +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): + +<LI><CODE>Folder to open as inbox</CODE> (or <I>inbox-path</I>) - 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: +<CODE>{server.example.com}INBOX</CODE>. + +<LI><CODE>User-id</CODE>, <CODE>Personal name</CODE>, and +<CODE>host/domain</CODE>, which are to be used as your email address. + +<LI><CODE>SMTP server to forward message</CODE> - You must enter your SMTP +server before you can send any messages. + +<P> +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. +<HR> + +<H2><A NAME="install-imapd">Installing IMAPd</A></H2> + +When the <EM>Alpine</EM> distribution is built on a UNIX system, the IMAP server +binary, <CODE>imapd</CODE>, is compiled. Installing <CODE>imapd</CODE> +requires placing the binary in the appropriate directory, usually +<CODE>/usr/etc</CODE>, and adding entries to <CODE>/etc/services</CODE> +and <CODE>/etc/inetd.conf</CODE> or their counterparts. +<P> +Instead of including installation instructions here we'll just include +a pointer to detailed instructions in the c-client distribution. +Please take a look at the file +<CODE>imap/docs/BUILD</CODE> in the source tree. + +<HR> + +<H2><A NAME="files-unix">Support Files and Environment Variables: UNIX Alpine</A></H2> + +This section lists the various files which <EM>Alpine</EM> uses which are not email +folders. All of these are the default names of files, they may vary based +on <EM>Alpine</EM>'s configuration. + +<DL COMPACT> + +<DT> /usr/local/lib/pine.conf + +<DD> Pine's global configuration file. + +<DT> /usr/local/lib/pine.conf.fixed + +<DD> Non-overridable global configuration file. + +<DT> /usr/local/lib/pine.info + +<DD> Local pointer to system administrator. + +<DT> ~/.pinerc + +<DD> Personal configuration file for each user. + +<DT> ~/.pinercex + +<DD> Personal exceptions configuration file for each user. + +<DT> ~/.addressbook + +<DD> Personal addressbook + +<DT> ~/.newsrc + +<DD> Personal USENET subscription list. This is shared with other +newsreading programs. + +<DT> ~/.pine-debugX + +<DD> The files created for debugging <EM>Alpine</EM> problems. By default, there are +4 .pine-debug files kept at any time. + +<DT> ~/.signature + +<DD> A signature file which will be included in all outgoing email +messages. + +<DT> ~/.pine-interrupted-mail + +<DD> The text of a message which was interrupted by some unexpected error +which <EM>Alpine</EM> detected. + +<DT> ~/mail/postponed-msgs + +<DD> A folder of messages which the user chose to postpone. + +<DT> /etc/mailcap + +<DD> System-wide mail capabilities file. Only used if +<CODE>$MAILCAPS</CODE> not set. + +<DT> ~/.mailcap + +<DD> Personal mail capabilities file. Combines with system-wide mailcap. +Only used if <CODE>$MAILCAPS</CODE> not set. + +</DL> <P> + +The location of the following support files may be controlled by variables +in the personal or global <EM>Alpine</EM> configuration file: signature, addressbook +and its index file, postponed messages, and newsrc. <P> + +Unix <EM>Alpine</EM> uses the following environment variables: + +<DL COMPACT> + +<DT> TERM + +<DD> Tells <EM>Alpine</EM> what kind of terminal is being used. + +<DT> DISPLAY + +<DD> Determines if <EM>Alpine</EM> will try to display IMAGE attachments. + +<DT> TMPDIR, TMP, or TEMP + +<DD> Specifies location of temporary storage area, first one set wins + +<DT> SHELL + +<DD> If not set, default is /bin/sh + +<DT> MAILCAPS + +<DD> A semicolon delimited list of path names to mailcap files. <P> + +</DL> + +<HR> + +<H2><A NAME="files-pc">Support Files, Environment Variables, and Registry Settings: PC-Alpine</A></H2> + +This section lists the various files which <EM>PC-Alpine</EM> uses which are not +normal mail folders. All of these are the default names of files, they +may vary based on <EM>Alpine</EM>'s configuration. <P> + +<DL COMPACT> + +<DT> $PINERC or <PineRC registry value> or $HOME\PINE\PINERC or +<PINE.EXE dir>\PINERC + +<DD> Path to (required) personal configuration file. + +<DT> $PINERCEX or $HOME\PINE\PINERCEX or <PINE.EXE dir>\PINERCEX + +<DD> Path to personal exceptions configuration file. + +<DT> $PINECONF + +<DD> Path of optional global configuration file. + +<DT> <PINERC directory>\ADDRBOOK + +<DD> Personal addressbook + +<DT> <PINERC directory>\PINEDEBG.TXT + +<DD> Location of <EM>Alpine</EM> debug file. + +<DT> <PINERC directory>\MAILCAP and/or <PINE.EXE dir>\MAILCAP + +<DD> These paths are only used if $MAILCAPS not set. + +<DT> $HOME\NEWSRC or <PINERC directory>\NEWSRC + +<DD> Personal USENET subscription list. This may be shared with other +newsreading programs. + +<DT> $HOME\MAIL\INTRUPTD + +<DD> The text of a message which was interrupted by some unexpected error +which <EM>Alpine</EM> detected. + +<DT> $HOME\MAIL\POSTPOND + +<DD> A folder of messages which the user chose to postpone. + +</DL> <P> +Registry Values: +<DL COMPACT> + +<DT> HKEY_LOCAL_MACHINE\Software\University of Washington\Alpine\1.0 + +<DD> <EM>Pinedir</EM>: The directory that contains the <EM>Alpine</EM> executable. + +<DD> <EM>PineEXE</EM>: The name of the <EM>Alpine</EM> executable (most commonly +"alpine.exe"). + +<DT> HKEY_CURRENT_USER\Software\University of Washington\Alpine\1.0 + +<DD> <EM>PineRC</EM>: The path that points to the default pinerc to use. + +<DT> HKEY_LOCAL_MACHINE\Software\Clients\Mail\Alpine + +<DD> <EM>DLLPath</EM>: The path that points to <EM>Alpine</EM>'s pmapi32.dll. + +<DT> HKLM\Software\Clients\Mail\Alpine\shell\open\command + +<DD> <EM>(Default)</EM>: When set as the default mailer, this is the +command that is run by external programs. + +<DT> HKLM\Software\Clients\Mail\Alpine\Protocols\Mailto\DefaultIcon + +<DD> <EM>(Default)</EM>: This points to the icon to display in relation to +<EM>Alpine</EM>'s mailto URL rendering. + +<DT> HKLM\Software\Clients\Mail\Alpine\Protocols\Mailto\shell\open\command + +<DD> <EM>(Default)</EM>: This value is the command that gets run by external +programs when a mailto URL is run with <EM>PC-Alpine</EM> set as the +default mailer. + +<DT> HKLM\Software\Clients\News\Alpine\shell\open\command + +<DD> <EM>(Default)</EM>: When set as the default newsreader, this is the + command that is run by external programs. + +<DT> HKLM\Software\Clients\News\Alpine\Protocols\news\DefaultIcon + +<DD> <EM>(Default)</EM>: This points to the icon to display in relation to + <EM>Alpine</EM>'s news URL rendering. + +<DT> HKLM\Software\Clients\News\Alpine\Protocols\news\shell\open\command + +<DD> <EM>(Default)</EM>: This value is the command that gets run by external +programs when a news URL is run with <EM>Alpine</EM> set as the +default newsreader. + +<DT> HKLM\Software\Clients\News\Alpine\Protocols\nntp\DefaultIcon + +<DD> <EM>(Default)</EM>: This points to the icon to display in relation to +<EM>Alpine</EM>'s nntp URL rendering. + +<DT> HKLM\Software\Clients\News\Alpine\Protocols\nntp\shell\open\command + +<DD> <EM>(Default)</EM>: This value is the command that gets run by external +programs when a nntp URL is run with <EM>Alpine</EM> set as the +default newsreader. + +</DL> <P> +<EM>Alpine</EM>'s 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 <CODE>$PINERC</CODE> environment variable, or in +<CODE>$HOME\ALPINE\PINERC</CODE>, where if not set, <CODE>$HOME</CODE> +defaults to the root of the current working drive. <P> + +Most of the other support files key off of the location of the +<CODE>PINERC</CODE> file. However, in the case of the NEWSRC file, the +path <CODE>$HOME\NEWSRC</CODE> is checked first. Also, the postponed +messages and interrupted message folders are placed in the default folder +collection, normally in the directory <CODE>$HOME\MAIL</CODE>. <P> + +The location of the following support files may be controlled by variables +in the personal or global <EM>Alpine</EM> configuration file: signature, addressbook +(and its index file), postponed messages, and newsrc. <P> + +<EM>PC-Alpine</EM> uses the following environment variables: + +<DL COMPACT> + +<DT> PINERC + +<DD> Overrides default path to pinerc file. + +<DT> PINERCEX + +<DD> Overrides default path to personal exceptions configuration file. + +<DT> PINECONF + +<DD> Optional path to global <EM>Alpine</EM> config file. + +<DT> HOME + +<DD> If not set, <EM>Alpine</EM> uses the root of the current drive, e.g. C: + +<DT> TMPDIR, TMP, or TEMP + +<DD> Specifies location of temporary storage area, first one set wins + +<DT> COMSPEC + +<DD> Specifies shell for external commands. + +<DT> MAILCAPS + +<DD> A semicolon delimited list of path names to mailcap files. + +</DL> <P> + +<!-- pnuts --> + +</BODY> +</HTML> diff --git a/doc/tech-notes/introduction.html b/doc/tech-notes/introduction.html new file mode 100644 index 00000000..d7293842 --- /dev/null +++ b/doc/tech-notes/introduction.html @@ -0,0 +1,122 @@ +<HTML><HEAD><TITLE>Alpine Technical Notes: Introduction</TITLE></HEAD><BODY> +<H1>Introduction</H1> + +<H2><A NAME="design">Design Goals</A></H2> + +Throughout <EM>Alpine</EM> 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: <P> + +<DL COMPACT> + +<DT> + +<DD> - The model presented to the user has to be simple and +clear. Underlying system operation is hidden as much as possible. + +<DT> + +<DD> - 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. + +<DT> + +<DD> - 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. + +<DT> + +<DD> - <EM>Alpine</EM> must provide immediate feedback for the user with each +operation. + +<DT> + +<DD> - <EM>Alpine</EM> 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), <EM>Alpine</EM> should ask for confirmation. + +<DT> + +<DD> - 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. + +<DT> + +<DD> - The core set of <EM>Alpine</EM> functions should be kept to a +minimum so new +users don't feel "lost" in seemingly extraneous commands and concepts. +<P> + +</DL> <P> + +Just as there were goals relating to the look and feel of <EM>Alpine</EM>, +there were +equally important goals having to do with <EM>Alpine</EM>'s structure-the +things that +users never see but still rely on every time they use <EM>Alpine</EM>. +While <EM>Alpine</EM> +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, <EM>Pine</EM> (the predecessor of <EM>Alpine</EM>) was one of +the first programs to +support the Multipurpose Internet Mail Extensions (MIME) specification. +With MIME, <EM>Alpine</EM> users can reliably send any binary file to any other +person on the Internet who uses a MIME compliant email program. <P> + +The decision to use IMAP and MIME reflects the importance of +interoperability, standardization and robustness in <EM>Alpine</EM>. As you work +with <EM>Alpine</EM> more, you will see other features which reflect +the same values. +For example, <EM>Alpine</EM> enforces strict compliance with RFC 2822, implements a +strong mail folder locking mechanism and verifies a process before +overwriting any files (e.g. addressbook, expunging messages). <P> + +<H2><A NAME="components">Alpine Components</A></H2> + +If you have picked up the <EM>Alpine</EM> distribution, then you already know that +<EM>Alpine</EM> comes in a few different pieces. They are: <P> + +<DL COMPACT> + +<DT> <EM>Alpine</EM> + +<DD> The main code from which the <EM>Alpine</EM> program is compiled. <P> + +<DT> <EM>Pico</EM> + +<DD> <EM>Pico</EM> is the name for the <EM>Alpine</EM> composer. +The <EM>Pico</EM> 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 <EM>Alpine</EM> to support composition +of messages within <EM>Alpine</EM>. +<EM>Pico</EM> is <EM>Alpine</EM>'s internal editor invoked when users +need to fill in header lines or type the text of an email message. <P> + +<DT> <EM>Imap</EM> + +<DD> An API for IMAP. Includes the C-Client library, which is compiled +into <EM>Alpine</EM>, and the IMAP server <EM>IMAPd</EM>. +C-Client implements the IMAP +protocol and also negotiates all access between <EM>Alpine</EM> 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. <EM>IMAPd</EM> is a separate server that handles +IMAP connections from any IMAP-compliant email program. When <EM>Alpine</EM> +accesses a remote mailbox, the <EM>Alpine</EM> program is the IMAP client and the +<EM>IMAPd</EM> program is the IMAP server. Of course, <EM>Alpine</EM> can +use any IMAP-compliant IMAP server, not just <EM>IMAPd</EM>. <P> + +</DL> + +<!-- pnuts --> + +</BODY> +</HTML> + diff --git a/doc/tech-notes/low-level.html b/doc/tech-notes/low-level.html new file mode 100644 index 00000000..ee5264ac --- /dev/null +++ b/doc/tech-notes/low-level.html @@ -0,0 +1,975 @@ +<HTML><HEAD><TITLE>Alpine Technical Notes: Behind the Scenes</TITLE></HEAD><BODY> +<H1>Behind the Scenes</H1> + +Many people ask how certain <EM>Alpine</EM> features are implemented. This section +outlines some of the details. + +<H2><A NAME="addrbook">Address Books</A></H2> + +There are two types of address book storage. There +are <EM>local</EM> address books, which are the address books that are +stored in a local file; and there +are <EM>remote</EM> address books, which are stored on an IMAP server. + +<H4><A NAME="remote-abooks">Information About Remote Address Books</A></H4> + +<BLOCKQUOTE> +NOTE: The remote address book capability does not allow you to access an +existing local address book from a remote system! That is, you can't set +the remote address book to something like <CODE>{remote.host}.addressbook</CODE> +and expect to access the existing <CODE>.addressbook</CODE> <EM>file</EM> +on remote.host. Instead, you need to create a new remote address book in +a new, previously unused remote mail <EM>folder</EM>. Then you can use the +<EM>Select</EM> and <EM>Apply Save</EM> commands in the address book screen to +<EM>Save</EM> all of the entries from an existing local address book to +the new remote address book. +</BLOCKQUOTE> +<P> + +A remote address book is stored in a mail folder on an +IMAP server. +An <EM>Alpine</EM> remote address book is just like an <EM>Alpine</EM> local address book +in that it is not interoperable with other email clients. +The folder is a regular folder containing mail messages but +those messages are special. The first message must be an alpine remote +address book header message which contains the header <EM>x-pine-addrbook</EM>. +The last message in the folder contains the address book data. +In between the first +and the last message are old versions of the address book data. The address +book data is simply stored in the message as it would be on disk, with no MIME +encoding. When it is used the data from the last message in the folder is +copied to a local file and then that file is used exactly like a local +address book file is used. When a change is made the modified local file +is appended to the remote folder in a new message. In other words, the +local file is just a cache copy of the data in the remote folder. Each client +which uses the remote address book will have its own cache copy of the data. +Whenever a copy is done the entire address book is copied, not just the +entries which have changed. +<P> + +<EM>Alpine</EM> can tell that the remote data has changed +by one of several methods. +If the date contained in the Date header of the last message has changed then +it knows it has changed. If the UID of the last message has changed, or the +number of messages in the folder has changed, it knows that it has changed. +When <EM>Alpine</EM> discovers the folder has changed it gets +a new copy and puts it in the local cache file. +<P> + +There is a configuration file variable for remote address books called +<A HREF="config.html#remote-abook-metafile"><EM>remote-abook-metafile</EM></A>. +The variable is the name of a file in which +information about remote address books is stored. There is one line in the +metafile for each remote address book. The information stored there is the +name of the cache file and information to help figure out when the remote +folder was last changed. If the metafile or any of the cache files is deleted +then <EM>Alpine</EM> will rebuild them the next time it runs. +<P> + +Remote address books have names that look just like regular +<A HREF="config-notes.html#remote-folders">remote mail folder</A> names. +For example: + +<BLOCKQUOTE> + {host.domain}foldername<BR> +</BLOCKQUOTE> + +<EM>Alpine</EM> decides whether or not an address book is remote simply by +looking at the first character of the address book name and comparing +it to '{'. + +<H4>Information About All Address Books</H4> + +The address book is named, by default, <CODE>.addressbook</CODE> in the +user's Unix home directory, or in the case of <EM>PC-Alpine</EM>, +<CODE>ADDRBOOK</CODE>, in the same directory as the <CODE>PINERC</CODE> file. +There may be more than +one address book, and the default name can be overridden via an entry in +any of the <EM>Alpine</EM> configuration files. The two configuration variables +<A HREF="config.html#pers-abook"><EM>address-book</EM></A> +and <A HREF="config.html#glob-abook"><EM>global-address-book</EM></A> +are used to specify the names of the address books. +Each of these variables is a list +variable. The total set of address books for a user is the combination of +all the address books specified in these two lists. Each entry in the +list is an optional nickname followed by an address book name. The nickname is +everything up to the last space before the file name. The +<EM>global-address-book</EM> list will typically be configured in the +system-wide configuration file, though a user may override it like most +other variables. Address books which are listed in the +<EM>global-address-book</EM> variable are forced read-only, and are +typically shared among multiple users. <P> + +Local address books (or local cache files for remote address books) are +simple text files with lines in the format: + +<BLOCKQUOTE> + <nickname>TAB<fullname>TAB<address>TAB<fcc>TAB<comments><BR> +</BLOCKQUOTE> + +The last two fields are optional. A "line" may be made up of multiple +actual lines in the file by using continuation lines, which are lines +beginning with SPACE characters. The line breaks may be after TABs or in +between addresses in a distribution list. +Each <EM>actual</EM> line in the file must +be less than 1000 characters in length. +<P> + +Nicknames (the first field) are short names that the user types instead of +typing in the full address. There are several characters which aren't +allowed in nicknames in order to avoid ambiguity when parsing the address +(SPACE, COMMA, @, ", ;, :, (, ), [, ], <, >, \). +Nicknames aren't required. In fact, +none of the fields is required. <P> + +The <EM>fullname</EM> field is usually stored as Last_name, First_name, in order +that a sort on the fullname field comes out sorted by Last_name. +If there is an unquoted comma in the fullname, +<EM>Alpine</EM> will flip the first and last name around and get rid of +the comma when using the entry in a composition. It isn't required that +there be a comma, that's only useful if the user wants the entries to sort +on last names. <P> + +The <EM>address</EM> field takes one +of two forms, depending on whether the entry +is a single (simple) address or a distribution list. For a simple entry, +the address field is an RFC 2822 address. This could be either the +email-address part of the address, i.e., the part that goes inside the +brackets (<>), or it could be a full RFC 2822 address. The phrase part +of the address (the fullname) is used unless there is a fullname present +in the fullname field of the address book entry. In that case, the fullname +of the address book entry replaces the fullname of the address. For a +distribution list, the <address> is in the format: + +<BLOCKQUOTE> + "(" <address>, <address>, <address>, ... ")"<BR> +</BLOCKQUOTE> +<P> + +The only purpose for the parentheses around the list of addresses is to +make it easier for the parsing routines to tell that it is a simple entry +instead of a list. The two are displayed differently and treated slightly +differently in some cases, though most of the distinction has disappeared. +Each of the addresses in a list can be a full RFC 2822 address with +fullname included, or it may be just the simple email-address part of the +address. This allows the user to have a list which includes the fullnames +of all the list members. In both the simple and list cases, +addresses may also be other nicknames which appear in this address book or +in one of the other address books. (Those nicknames are searched for by +looking through the address books in the order they appear in the address +book screen, with the first match winning.) Lists may be nested. If +addresses refer to each other in a loop (for example, list A includes +list B which includes list A again) this is detected and flagged. In that +case, the address will be changed to "**** address loop ****". <P> + +The optional <EM>fcc</EM> field is a folder name, just like the fcc field in the +composer headers. If the first address in the To field of a composition +comes from an address book entry with an fcc field, then that fcc is +placed in the fcc header in the composer. <P> + +The <EM>comments</EM> field is just a free +text field for storing comments about an +entry. By default, neither the fcc nor the comments field is shown on the +screen in the address book screen. You may make those fields visible by +configuring the variable +<A HREF="config.html#abook-formats"><EM>addressbook-formats</EM></A>. +They are also searched when you use the <EM>WhereIs</EM> +command in the address book screen and are visible when you +<EM>View</EM> or <EM>Update</EM> an entry. <P> + +The address book is displayed in the order that it is stored. +When the user chooses a different sorting criterion, the data is actually +sorted and stored, as opposed to showing a sorted view of the data. <P> + +When the address book is written out, it is first written to a temporary +file and if that write is successful it is renamed. This guards +against errors writing the file that might destroy the whole address book. +The address book is re-written after each change. If the address book +is a remote address book, the file is then appended to the remote mail +folder using IMAP. <P> + +The end-of-line character(s) in the address book file are those native to +the system writing it. So it is <LF> on Unix and +<CR><LF> on PC's. However, both Unix and PC versions of <EM>Alpine</EM> +can read either format, so it should be possible to share a read-only +address book among the two populations (using NFS, for example). +<P> + +<HR> + +<H3><A NAME="addrbook-lu">Address Book Lookup File</A></H3> + +<EM>Pine</EM> used an additional file for each address book, called +the LookUp file. It had the same name as the address book file +with the suffix ".lu" appended. +<EM>Alpine</EM> no longer uses a lookup file. +<P> + +<H4>Validity Checking of Address Books</H4> + +There is no file locking done on <EM>Alpine</EM> address books, however, there +is considerable validity checking done to make sure that the address book +hasn't changed unexpectedly. Whenever the address book is about to be changed, +a check is made to see if the file is newer than when we read it or the +remote address book folder has changed since we last copied it. If either +of these is true, the change is aborted. +<P> + +There is an automatic, behind-the-scene check that happens every so often, +also. For example, if someone else changes one of the address books that +you have configured, your <EM>Alpine</EM>'s copy of the address book will usually +be updated automatically without you noticing. This checking happens at the +same time as new mail checking takes place, unless you are actively using +the address book, in which case it happens more frequently. +<P> + +<HR> + +<H2><A NAME="remote-config">Remote Configuration</A></H2> + +Configuration information may be stored remotely. +Remote configuration information is stored in a folder on an IMAP server. +This should be a folder which is used only for storing the configuration +information. +In other words, it should be a folder which didn't exist before. +<P> +Remote configuration folders are very similar to remote address book folders. +They both consist of a header message, which serves to identify the type +of folder; the last message, which contains the data; and intermediate +messages, which contain old versions of the data. +The first message must contain the header <EM>x-pine-pinerc</EM>. +<P> +When a remote configuration is being used, the folder is checked to make +sure it is a remote configuration folder, then the data contained in the +last message is copied to a temporary file. +That file is treated just like any regular local configuration file from +that point on. +Whenever a configuration change is made, the entire file is copied back +to the IMAP server and is appended to the folder as a new message. +<P> +Because remote configuration folders are so similar to remote address books, +the configuration variable +<A HREF="config.html#remote-abook-metafile"><EM>remote-abook-metafile</EM></A> +is used by both. +<P> +Remote configuration folders have names that look just like regular +<A HREF="config-notes.html#remote-folders">remote mail folder</A> names. +For example: + +<BLOCKQUOTE> + {host.domain}mypinerc<BR> +</BLOCKQUOTE> + +<EM>Alpine</EM> decides whether or not a configuration file is remote simply by +looking at the first character of the name and comparing +it to '{'. +<P> + +<HR> + +<H2><A NAME="checkpoint">Checkpointing</A></H2> + +Periodically <EM>Alpine</EM> will save the whole +mail folder to disk to prevent loss +of any mail or mail status in the case that it gets interrupted, +disconnected, or crashes. The period of time <EM>Alpine</EM> waits to do the +checkpoint is calculated to be minimally intrusive. The timing can be +changed (but usually isn't) at compile time. Folder checkpointing happens +for both local folders and those being accessed with IMAP. The delays are +divided into three categories: <P> + +<BLOCKQUOTE> +The exact algorithm given below is no longer correct. +It has gotten more complicated over time. +However, this gives the general idea <EM>Alpine</EM> uses +when deciding whether or not to do a checkpoint. +</BLOCKQUOTE> + +<DL COMPACT> + +<DT> Good Time: + +<DD> This occurs when <EM>Alpine</EM> has been idle for more than 30 seconds. In +this case <EM>Alpine</EM> will checkpoint if 12 changes +to the file have been made or +at least one change has been made and a checkpoint hasn't been done for +five minutes. <P> + +<DT> Bad Time: + +<DD> This occurs just after <EM>Alpine</EM> has +executed some command. <EM>Alpine</EM> will +checkpoint if there are 36 outstanding changes to the mail file or at +least one change and no checkpoint for ten minutes. <P> + +<DT> Very Bad Time: + +<DD> Done when composing a message. In this case, <EM>Alpine</EM> will only +checkpoint if at least 48 changes have been made or at least one change has been +made in the last twenty minutes with no checkpoint. <P> + +</DL> + +<HR> + +<H2><A NAME="debug">Debug Files</A></H2> + +If UNIX <EM>Alpine</EM> is compiled with the compiler +<EM>DEBUG</EM> option on (the default), +then <EM>Alpine</EM> will produce debugging output to a file. +This can be disabled at compile-time with the --disable-debug configure option, +or at run-time with the command line flag -d0. +The file is +normally <CODE>.pine-debugX</CODE> in the user's home directory where +<EM>X</EM> goes from 1 to 4. Number 1 is always the most recent session +and 4 the oldest. Four are saved because often the user has gone in and +out of <EM>Alpine</EM> a few times after a problem has occurred before the expert +actually gets to look at it. The amount of output in the debug files +varies with the debug level set when <EM>Alpine</EM> is +compiled and/or as a command +line flag. The default is level 2. This shows very general things and +records errors. Level 9 produces copious amounts of output for each +keystroke. <P> + +Similarly, <EM>PC-Alpine</EM> creates debug files +named <CODE>pinedebg.txtX</CODE> in the +same directory as the <CODE>PINERC</CODE> file. <P> + +<HR> + +<H2><A NAME="INBOX">INBOX and Special Folders</A></H2> + +The <EM>INBOX</EM> folder is treated specially. It is normally kept open +constantly so that the arrival of new mail can be detected. The name +<EM>INBOX</EM> refers to wherever new mail is retrieved on the system. If +the <A HREF="config.html#inbox-path"><EM>inbox-path</EM></A> variable is set, +then <EM>INBOX</EM> refers to +that. IMAP servers understand the concept of <EM>INBOX</EM>, so +specifying the folder <EM>{imap.u.example.edu}INBOX</EM> is meaningful. +The case of the word <EM>INBOX</EM> is not important, +but <EM>Alpine</EM> tends to display it in all capital letters. <P> + +The folders for <A HREF="config.html#def-fcc">sent mail</A> +and <A HREF="config.html#def-save">saved messages</A> folders are +also somewhat special. +They are automatically created if they are absent and recreated +if they are deleted. <P> + +<HR> + +<H2><A NAME="help">Internal Help Files</A></H2> + +The file <CODE>pine.hlp</CODE> in the <CODE>alpine</CODE> subdirectory of the +distribution contains all the help text for <EM>Alpine</EM>. +It is compiled right into the <EM>Alpine</EM> binary as strings. +This is done to simplify installation and configuration. +The <CODE>pine.hlp</CODE> file is in a +special format that is documented at the beginning of the file. +It is divided into sections, each with a name that winds up being referenced as +a global variable. This file is processed during the build process and +turned into a C file that is compiled into <EM>Alpine</EM>. <P> + +<HR> + +<H2><A NAME="char-set">International Character Sets</A></H2> + +<EM>Alpine</EM> uses Unicode characters internally and +it is a goal for <EM>Alpine</EM> to handle email in many different languages. +<EM>Alpine</EM> will properly display only left-to-right character sets +in a fixed-width font. Specifically, <EM>Alpine</EM> assumes that a fixed-width +font is in use, in the sense that +characters are assumed to take up zero, one, or two character cell +widths from left to right on the screen. This is true even in <EM>PC-Alpine</EM>. +<P> + +<EM>Alpine</EM> recognizes some local character sets which are right-to-left +(Arabic, Hebrew, and Thai) or not representable in a fixed-width font +(Arabic) and properly converts texts in these character sets to/from +Unicode; however, there are known display bugs with these character +sets. +<P> + +There are three possible configuration character settings and some +environment variable settings which can affect how <EM>Alpine</EM> +handles international characters. +The first two of these are only available in UNIX <EM>Alpine</EM>. +The three configuration options are +<EM>display-character-set</EM>, +<EM>keyboard-character-set</EM>, and +<EM>posting-character-set</EM>. +The <EM>keyboard-character-set</EM> defaults to being the same value +as the <EM>display-character-set</EM>, and that is usually correct, because +the keyboard almost always produces characters in the same character set +as the display displays. +The <EM>display-character-set</EM> is the character set that <EM>Alpine</EM> +will attempt to use when sending characters to the display. +<P> +Besides those variables there is also +<A HREF="config.html#use-system-translation"><EM>use-system-translation</EM></A> +which can be used instead of these. +That usage is only lightly tested and is not recommended. +<P> + +By default, the <EM>display-character-set</EM> variable is not set and UNIX <EM>Alpine</EM> +will attempt to get this information from the environment. +In particular, the <CODE>nl_langinfo(CODESET)</CODE> call is used. +This usually depends on the setting of the environment variables LANG or LC_CTYPE. +An explicit configuration setting for <EM>display-character-set</EM> will, +of course, override any default setting. +<P> +For <EM>PC-Alpine</EM> the <EM>display-character-set</EM> +and the <EM>keyboard-character-set</EM> +are always equivalent to <CODE>UTF-8</CODE> and this is not settable. +<P> + +It is probably best to use UNIX <EM>Alpine</EM> in a terminal emulator +capable of displaying UTF-8 characters, since that will allow you to +view just about any received text that is correctly formatted (note, +however, the above comments about known index display bugs with certain +character sets). You'll need to have an emulator which uses a UTF-8 font +and you'll need to set up your environment to use a UTF-8 charmap. For +example, on a Linux system you might include +<P> +<CENTER> <CODE>setenv LANG en_US.UTF-8</CODE> </CENTER> +<P> + +or something similar in your UNIX startup files. +You'd also have to select a UTF-8 font in your terminal emulator. +<P> + +The types of values that the character set variables may be set to are +<CODE>UTF-8</CODE>, <CODE>ISO-8859-1</CODE>, or <CODE>EUC-JP</CODE>. +The <CODE>ISO-2022</CODE> character sets are not supported for input or +for display, but as a special case, <CODE>ISO-2022-JP</CODE> is supported +for use only as a <EM>posting-character-set</EM>. +In the Setup/Config screen you may choose from a list of all the +character sets <EM>Alpine</EM> knows about by using the "T" ToCharsets command. +Here is a list of many of the possible character sets: + +<P> +<TABLE> +<TR> <TD>UTF-8</TD> <TD>Unicode</TD> </TR> +<TR> <TD>US-ASCII</TD> <TD>7 bit American English characters</TD> </TR> +<TR> <TD>ISO-8859-1</TD> <TD>8 bit European "Latin 1" character set</TD> </TR> +<TR> <TD>ISO-8859-2</TD> <TD>8 bit European "Latin 2" character set</TD> </TR> +<TR> <TD>ISO-8859-3</TD> <TD>8 bit European "Latin 3" character set</TD> </TR> +<TR> <TD>ISO-8859-4</TD> <TD>8 bit European "Latin 4" character set</TD> </TR> +<TR> <TD>ISO-8859-5</TD> <TD>8 bit Latin and Cyrillic</TD> </TR> +<TR> <TD>ISO-8859-6</TD> <TD>8 bit Latin and Arabic</TD> </TR> +<TR> <TD>ISO-8859-7</TD> <TD>8 bit Latin and Greek</TD> </TR> +<TR> <TD>ISO-8859-8</TD> <TD>8 bit Latin and Hebrew</TD> </TR> +<TR> <TD>ISO-8859-9</TD> <TD>8 bit European "Latin 5" character set</TD> </TR> +<TR> <TD>ISO-8859-10</TD> <TD>8 bit European "Latin 6" character set</TD> </TR> +<TR> <TD>ISO-8859-11</TD> <TD>Latin and Thai</TD> </TR> +<TR> <TD>ISO-8859-12</TD> <TD>Reserved</TD> </TR> +<TR> <TD>ISO-8859-13</TD> <TD>8 bit European "Latin 7" character set</TD> </TR> +<TR> <TD>ISO-8859-14</TD> <TD>8 bit European "Latin 8" character set</TD> </TR> +<TR> <TD>ISO-8859-15</TD> <TD>8 bit European "Latin 9" character set</TD> </TR> +<TR> <TD>ISO-8859-16</TD> <TD>8 bit European "Latin 10" character set</TD> </TR> +<TR> <TD>KOI8-R</TD> <TD>8 bit Latin and Russian</TD> </TR> +<TR> <TD>KOI8-U</TD> <TD>8 bit Latin and Ukranian</TD> </TR> +<TR> <TD>WINDOWS-1251</TD> <TD>8 bit Latin and Russian</TD> </TR> +<TR> <TD>TIS-620</TD> <TD>8 bit Latin and Thai</TD> </TR> +<TR> <TD>VISCII</TD> <TD>8 bit Latin and Vietnamese</TD> </TR> +<TR> <TD>GBK</TD> <TD>Latin and Chinese Simplified</TD> </TR> +<TR> <TD>GB2312</TD> <TD>Latin and Chinese Simplified</TD> </TR> +<TR> <TD>CN-GB</TD> <TD>Latin and Chinese Simplified</TD> </TR> +<TR> <TD>BIG5</TD> <TD>Latin and Chinese Traditional</TD> </TR> +<TR> <TD>BIG-5</TD> <TD>Latin and Chinese Traditional</TD> </TR> +<TR> <TD>EUC-JP</TD> <TD>Latin and Japanese</TD> </TR> +<TR> <TD>SHIFT-JIS</TD> <TD>Latin and Japanese</TD> </TR> +<TR> <TD>EUC-KR</TD> <TD>Latin and Korean</TD> </TR> +<TR> <TD>KSC5601</TD> <TD>Latin and Korean</TD> </TR> +</TABLE> +<P> + +When reading incoming email, <EM>Alpine</EM> understands many different +character sets and is able to convert the incoming mail into Unicode. +The Unicode will be converted to the <EM>display-character-set</EM> +for display on your terminal. +Characters typed at the keyboard will be converted from the +<EM>keyboard-character-set</EM> to Unicode for <EM>Alpine</EM>'s internal +use. +You may find that you can read some malformed messages that do not +contain a character set label by setting the option +<A HREF="config.html#unknown-character-set"><EM>unknown-character-set</EM></A>. +<P> + +The <EM>posting-character-set</EM> is used when sending messages. +The default behavior obtained by leaving this variable unset is usually +what is wanted. In that default case, <EM>Alpine</EM> will attempt +to label the message with the most specific character set from the +rather arbitrary set +<P> +US-ASCII, ISO-8859-15, +ISO-8859-1, ISO-8859-2, VISCII, KOI8-R, KOI8-U, ISO-8859-7, ISO-8859-6, +ISO-8859-8, TIS-620, ISO-2022-JP, GB2312, BIG5, EUC-KR, and UTF-8. +<P> + +For example, if the message is made up of only US-ASCII characters, it +will be labeled US-ASCII. Otherwise, if it is all ISO-8859-15 characters, +that will be the label. If that doesn't work the same is tried for the +remaining members of the list. + +<P> +It might make sense to set <EM>posting-character-set</EM> to an +explicit value instead. +For example, if you usually send messages in Greek, setting this +option to ISO-8859-7 will result in messages being labeled as +US-ASCII if there are no non-ascii characters, ISO-8859-7 if there +are only Greek characters, or UTF-8 if there are some characters +which aren't representable in ISO-8859-7. +Another possibility is to set this option explicitly to UTF-8. +In that case +<EM>Alpine</EM> labels only ascii messages as US-ASCII and all other +messages as UTF-8. +<P> + +<HR> + +<H2><A NAME="interrupt">Interrupted and Postponed Messages</A></H2> + +If the user is composing mail and is interrupted by being disconnected +(SIGHUP, SIGTERM or end of file on the standard input), <EM>Alpine</EM> will save the +interrupted composition and allow the user to continue it when he or she +resumes <EM>Alpine</EM>. As the next <EM>Alpine</EM> session starts, a message will be given +that an interrupted message can be continued. To continue the interrupted +message, simply go into the composer. To get rid of the interrupted +message, go into the composer and then cancel the message with +<EM>^C.</EM> <P> + +Composition of half-done messages may be postponed to a later time by +giving the <EM>^O</EM> command. Other messages can be composed while +postponed messages wait. All of the postponed messages are kept in a +single folder. Postponing is a good way to quickly reference other +messages while composing. <P> + +<HR> + +<H2><A NAME="status">Message Status</A></H2> + +The c-client library allows for several flags or status marks to be set +for each message. <EM>Alpine</EM> uses four of these flags: UNSEEN, DELETED, +ANSWERED, and FLAGGED. The <CODE>N</CODE> in <EM>Alpine</EM>'s +FOLDER INDEX means that a +message is unseen-it has not been read from this folder yet. The <CODE>D</CODE> +means that a message is marked for deletion. +Messages marked with <CODE>D</CODE> are +removed when the user <EM>Expunges</EM> the folder (which usually happens +when the folder is closed or the user quits <EM>Alpine</EM>). +The <CODE>A</CODE> in <EM>Alpine</EM>'s +FOLDER INDEX means that the message has been replied-to. The <CODE>*</CODE> in +<EM>Alpine</EM>'s FOLDER INDEX means that the message has been ``flagged'' as +important. That is, the user used the <EM>Flag</EM> command to turn the +FLAGGED flag on. This flag can mean whatever the user wants it to mean. +It is just a way to mark some messages as being different from others. It +will usually probably be used to mark a message as somehow being +``important''. For Berkeley format folders, the message status is written +into the email folder itself on the header lines marked <CODE>Status:</CODE> +and <CODE>X-Status</CODE>. +<P> +It is also possible for a user to define their own flags in addition to the +standard system flags above. +In <EM>Alpine</EM> these user defined flags are called Keywords. +<P> + +<HR> + +<H2><A NAME="MIME-read">MIME: Reading a Message</A></H2> + +<EM>Alpine</EM> should be able to handle just about any MIME message. When a MIME +message is received, <EM>Alpine</EM> will display a list of all the parts, their +types and sizes. It will display the attachments when possible and +appropriate and allow users to <EM>Save</EM> all other attachments. <P> + +<EM>Alpine</EM> honors the "mailcap" +configuration system for specifying external programs for handling attachments. +The mailcap file maps MIME attachment types to the external programs +loaded on your system which can display and/or print the file. +A sample mailcap file +comes bundled with the <EM>Alpine</EM> distribution. It includes comments which +explain the syntax you need to use for mailcap. With the mailcap file, +any program (mail readers, newsreaders, WWW clients) can use the same +configuration for handling MIME-encoded data. <P> + +If a <CODE>MAILCAPS</CODE> environment variable is defined, +<EM>Alpine</EM> will use that to look +for one or more mailcap files, which are combined. In the absence of +<CODE>MAILCAPS</CODE>, Unix <EM>Alpine</EM> will look for +a personal mailcap file in <CODE>~/.mailcap</CODE> +and combine that with a system-wide file in <CODE>/etc/mailcap</CODE>. +<EM>PC-Alpine</EM> will look for a file named <CODE>MAILCAP</CODE> in the +same directory as the <CODE>PINERC</CODE> file, +and/or the directory containing the <CODE>ALPINE.EXE</CODE> executable. <P> + +Messages which include <EM>rich text</EM> or <EM>enriched text</EM> in the +main body will be displayed in a very limited way (it will show bold and +underlining). <P> + +If <EM>Alpine</EM> sees a MIME message part tagged as type IMAGE, +and <EM>Alpine</EM>'s +<A HREF="config.html#image-viewer"><EM>image-viewer</EM></A> +configuration variable is set, <EM>Alpine</EM> will attempt to +send that attachment to the named image viewing program. In the case of +UNIX <EM>Alpine</EM>, the <CODE>DISPLAY</CODE> environment variable is +checked to see if an X-terminal is being used (which can handle the images). +If the <EM>image-viewer</EM> variable is not set, +<EM>Alpine</EM> uses the <EM>mailcap</EM> +system to determine what to do with IMAGE types, just as it does for any +other non-TEXT type, e.g. type APPLICATION. For MIME's generic "catch +all" type, APPLICATION/OCTET-STREAM, the <EM>mailcap</EM> file will +probably not specify any action, but <EM>Alpine</EM> users may always +<EM>Save</EM> any MIME attachment to a file. <P> + +MIME type "text/plain" is handled a little bit differently than the +other types. If you are viewing the main body part in the MESSAGE TEXT +viewing screen, then <EM>Alpine</EM> will use its internal viewer to display it. +This happens even if there is a mailcap description which matches this +particular type. +However, if you view a part of +type "text/plain" from the ATTACHMENT INDEX screen, then <EM>Alpine</EM> will check +the mailcap database for a matching entry and use it in preference to +its internal viewer. <P> + +Some text attachments, specifically those which are just other email messages +forwarded as MIME messages, are displayed as part of the main body of the +message. This distinction allows easy display when possible (the forward +as MIME case) and use of an attachment viewer when that is desirable (the +plain text file attachment case). <P> + +If the parts of a multipart message are alternate versions of the same +thing <EM>Alpine</EM> will select and display the one best suited. +For parts of type "message/external-body", the parameters showing the +retrieval method will be displayed, and the retrieval process is automated. +Messages of type "message/partial" are not supported. <P> + +<HR> + +<H2><A NAME="MIME-send">MIME: Sending a Message</A></H2> + +There are two important factors when trying to include an attachment in a +message: encoding and labeling. +<EM>Alpine</EM> has rules for both of these which +try to assure that the message goes out in a form that is robust and can +be handled by other MIME mail readers. <P> + +MIME has two ways of encoding data-Quoted-Printable and Base64. +Quoted-Printable leaves the ASCII text alone and only changes 8-bit +characters to "=" followed by the hex digits. For example, "=09" is a +tab. It has the advantage that it is mostly readable and that it allows +for end of line conversions between unlike systems. Base64 encoding is +similar to <EM>uuencode</EM> or <EM>btoa</EM> and just encodes a raw bit +stream. This encoding is designed to get text and binary files through +even the most improperly implemented and configured gateways intact, even +those that distort uuencoded data. <P> + +<STRONG>All</STRONG> attachments are encoded using Base64 encoding. This +is so that the attachment will arrive at the other end looking exactly +like it did when it was sent. Since Base64 is completely unreadable +except by MIME-capable mailers or programs, there is an obvious tradeoff +being made here. We chose to ensure absolutely reliable transport of +attachments at the cost of requiring a MIME-capable mailer to read them. +If the user doesn't want absolute integrity he or she may always +<EM>include</EM> text (with the <EM>^R</EM> command) in the body of a +message instead of attaching it. With this policy, the only time +quoted-printable encoding is used is when the main body of a message +includes special foreign language characters. <P> + +When an attachment is to be sent, <EM>Alpine</EM> sniffs through it to try to set the +right label (content-type and subtype). An attachment with any lines +longer than 500 characters in it or more than 10% of the characters are +8-bit it will be considered binary data. <EM>Alpine</EM> will recognize (and +correctly label) a few special types including GIF, JPEG, PostScript, and +some audio formats. Another method which can be more robust and flexible for +determining the content-type and subtype is to base it on the file extension. +This method uses a <A HREF="config-notes.html#mime.types">MIME.Types File</A>. +<P> + +If it is not binary data (has only a small proportion of 8-bit characters +in it,) the attachment is considered 8-bit text. 8-bit text attachments +are labeled "text/plain" with charset set to the value of the user's +<EM>keyboard-character-set</EM> variable. If an attachment is ASCII (no 8-bit +characters) and contains no control characters +then it is considered plain ASCII text. Such attachments are given the MIME label +"text/plain; charset=US-ASCII", regardless of the setting of the user's +<EM>keyboard-character-set</EM> variable. <P> + +All other attachments are unrecognized and therefore given the generic +MIME label "application/octet-stream". <P> + +<HR> + +<H2><A NAME="new-mail">New Mail Notification</A></H2> + +<EM>Alpine</EM> checks for new mail in the <EM>INBOX</EM> and in +the currently open folder every two and a half minutes by default. +This default can be changed in the system-wide configuration file or +at compile-time with the --with-mailcheck-interval=VALUE configuration +option. +A user can change it by changing the option +<A HREF="config.html#mail-check"><EM>mail-check-interval</EM></A>. +A new mail check can be manually forced by redrawing the screen with a <EM>^L</EM>. <P> + +When there is new mail, the message(s) will appear in the index, the +screen will beep, and a notice showing the sender and subject will be +displayed. If there has been more than one new message since you last +issued a command to <EM>Alpine</EM>, the notice will show the count of new messages +and the sender of the most recent one. <P> + +<HR> + +<H2><A NAME="NFS">NFS</A></H2> + +It is possible to access mail folders on <EM>NFS</EM> mounted volumes with +<EM>Alpine</EM>, but there are some drawbacks to doing this, especially in the case +of incoming-message folders that may be concurrently updated by <EM>Alpine</EM> and +the system's mail delivery agent. One concern is that <EM>Alpine</EM>'s +user-contention locks don't work because <EM>/tmp</EM> is usually not +shared, and even if it was, <EM>flock()</EM> doesn't work across +<EM>NFS.</EM> <P> The implementation of the standard UNIX ".lock" file +locking has been modified to work with <EM>NFS</EM> as follows. Standard +hitching post locking is used so first a uniquely named file is created, +usually something like <EM>xxxx.host.time.pid.</EM> Then a link to it is +created named <EM>xxxx.lock</EM> where the folder being locked is +<EM>xxxx.</EM> This file constitutes the lock. This is a standard UNIX +locking scheme. After the link returns, a <EM>stat(2)</EM> is done on the +file. If the file has two links, it is concluded that the lock succeeded +and it is safe to proceed. <P> + +In order to minimize the risks of locking failures via <EM>NFS</EM>, we strongly +recommend using IMAP rather than <EM>NFS</EM> to access remote incoming message +folders, e.g. your <EM>INBOX</EM>. However, it is generally safe to access +personal saved-message folders via <EM>NFS</EM> since it is unlikely that +more than one process will be updating those folders at any given time. +Still, some problems may occur when two <EM>Alpine</EM> sessions try to access the +same mail folder from different hosts without using IMAP. Imagine the +scenario: <EM>Alpine</EM>-A performs a write that changes the folder. <EM>Alpine</EM>-B then +attempts to perform a write on the same folder. <EM>Alpine</EM>-B will get upset +that the file has been changed from underneath it and abort operations on +the folder. <EM>Alpine</EM>-B will continue to display mail from the folder that it +has in its internal cache, but it will not read or write any further data. +The only thing that will be lost out of the <EM>Alpine</EM>-B session when this +happens is the last few status changes. <P> + +If other mail readers besides <EM>Alpine</EM> are involved, all bets are off. +Typically, mailers don't take any precautions against a user opening a +mailbox more than once and no special precautions are taken to prevent +<EM>NFS</EM> problems. <P> + +<HR> + +<H2><A NAME="print">Printers and Printing</A></H2> + +UNIX <EM>Alpine</EM> can print to the standard UNIX line printers or to generic +printers attached to ANSI terminals using the escape sequences to turn the +printer on and off. The user has a choice of three printers in the +configuration. <P> + +The first setting, <EM>attached-to-ansi</EM>, makes use of escape +sequences on ANSI/VT100 terminals. It uses "<ESC>[5i" to begin +directing all output sent to the terminal to the printer and then +"<ESC>[4i" to return to normal. <EM>Alpine</EM> will send these escape +sequences if the printer is set to <EM>attached-to-ansi.</EM> This works +with most ANSI/VT100 emulators on Macs and PCs such as kermit, NCSA +telnet, VersaTerm Pro, and WinQVT. Various terminal emulators implement +the print feature differently. +There is also a closely +related method called <EM>attached-to-ansi-no-formfeed</EM> which is +the same except for the lack of formfeed character at the end of the +print job. +<P> +<EM>Attached-to-wyse</EM> and <EM>attached-to-wyse-no-formfeed</EM> are +very similar to "attached-to-ansi". +The only difference is in the control characters sent to turn the printer +on and off. +The Wyse version uses Ctrl-R for on, and Ctrl-T for off. +<P> + +The second selection is the standard UNIX print command. The default is +<EM>lpr</EM>, but it can be changed on a system basis to anything so +desired in <CODE>/usr/local/lib/pine.conf</CODE>. <P> + +The third selection is +the user's personal choice for a UNIX print command. The text to be +printed is piped into the command. <EM>Enscript</EM> or <EM>lpr</EM> with +options are popular choices. The actual command is retained even if one +of the other print selections is used for a while. <P> + +Both the second and third sections are actually lists of possible commands +rather than single commands. <P> + +If you have a PostScript printer attached to a PC or Macintosh, then you +will need to use a utility called <EM>ansiprt</EM> to get printouts on +your printer. <EM>Ansiprt</EM> source code and details can be found in +the <CODE>./contrib</CODE> directory of the <EM>Alpine</EM> distribution. <P> + +<HR> + +<H2><A NAME="save">Save and Export</A></H2> + +<EM>Alpine</EM> users get two options for moving +messages in <EM>Alpine</EM>: <EM>Save</EM> and <EM>Export</EM>. +<EM>Save</EM> is used when the message should remain ``in the +<EM>Alpine</EM> realm.'' Saved messages include the complete header +(including header lines normally hidden by <EM>Alpine</EM>), +are placed in a <EM>Alpine</EM> folder collection and +accumulate in a standard folder format which <EM>Alpine</EM> can read. +In contrast, the <EM>Export</EM> command is used to write the contents +of a message to a file for use outside of <EM>Alpine</EM>. +Messages which have been exported are +placed in the user's home directory (unless the feature +<A HREF="config.html#use-current-dir"><EM>use-current-dir</EM></A> is +turned on), not in a <EM>Alpine</EM> folder collection. +Unless FullHeaderMode is toggled on, all delivery-oriented headers are +stripped from the message. Even with <EM>Export</EM>, <EM>Alpine</EM> retains +message separators so that multiple messages can accumulate in a single +file and subsequently be accessed as a folder. On UNIX systems, the +<EM>Export</EM> command pays attention to the standard <EM>umask</EM> for +the setting of the file permissions. <P> + +<HR> + +<H2><A NAME="sent-mail">Sent Mail</A></H2> + +<EM>Alpine</EM>'s default behavior is to keep a copy of each outgoing message in a +special "sent mail" folder. This folder is also called the fcc for "file +carbon copy". The existence, location and name of the sent mail folder +are all configurable. Sent mail archiving can be turned off by setting +the configuration variable +<A HREF="config.html#def-fcc"><EM>default-fcc=""</EM></A>. The sent mail folder +is assumed to be in the default collection for <EM>Save</EM>s, +which is the first collection named in +<A HREF="config.html#fold-coll"><EM>folder-collections</EM></A>. +The name of the folder +can be chosen by entering a name in <EM>default-fcc</EM>. +With <EM>PC-Alpine</EM>, +this can be a bit complicated. If the default collection for <EM>Save</EM>s is +local (DOS), then the <EM>default-fcc</EM> needs to be <CODE>SENTMAIL</CODE>, +which is syntax for a DOS file. However, if the default collection +for <EM>Save</EM>s is +remote, then the <EM>default-fcc</EM> needs to be <CODE>sent-mail</CODE> +to match the UNIX syntax. <P> + +The configuration variable +<A HREF="config.html#fcc-name-rule"><EM>fcc-name-rule</EM></A> +also plays a role in selecting the folder to save sent mail in. <P> + +A danger here is that the sent mail could grow without bound. For this +reason, we thought it useful to encourage the users to periodically prune +their sent mail folder. The first time <EM>Alpine</EM> is used each month it will +offer to archive all messages sent from the month before. <EM>Alpine</EM> also +offers to delete all the sent mail archive folders which are more than 1 +month old. If the user or system has disabled sent mail archiving (by +setting the configuration variable <EM>default-fcc=""</EM>) +there will be no pruning question. +<P> + +<HR> + +<H2><A NAME="spell">Spell Checker</A></H2> + +Both UNIX <EM>Alpine</EM> and <EM>PC-Alpine</EM> +depend on the system for their spell checking and dictionary. <EM>Pico</EM>, the +text editor, uses the same spell checking scheme as <EM>Alpine</EM>. <P> + +Lines beginning with ">" (usually messages included in replies) are not +checked. The message text to be checked is on the standard input and the +incorrect words are expected on the standard output. <P> + +The default spell checker is UNIX <EM>spell</EM>. You can replace this +by setting the <A HREF="config.html#speller"><EM>speller</EM></A> configuration +variable. +A common choice for a superior replacement is <EM>ispell</EM>. + +<P> +<EM>PC-Alpine</EM> relies on the aspell library being installed. +Aspell is independent of Alpine. The Windows version has +traditionally been available at +<A HREF="http://aspell.net/win32/">http://aspell.net/win32/</A>. You'll +need to download and install both Aspell and a precompiled dictionary. +Aspell is provided in an installer package. Dictionaries, to be +installed after Aspell, are in '.exe' files to download and run. +<P> + +<HR> + +<H2><A NAME="terminal">Terminal Emulation and Key Mapping</A></H2> + +UNIX <EM>Alpine</EM> has been designed to require as little as possible from the terminal. +At the minimum, <EM>Alpine</EM> requires cursor positioning, clear to end of line, +and inverse video. Unfortunately, there are terminals that are missing +some of these such as a vt52. <EM>Alpine</EM> makes no assumptions as to whether the +terminal wraps or doesn't wrap. If the terminal has other capabilities it +may use some of them. <EM>Alpine</EM> won't run well on older terminals that require +a space on the screen to change video attributes, such as the Televideo +925. One can get around this on some terminals by using "protected field" +mode. The terminal can be made to go into protected mode for reverse +video, and then reverse video is assigned to protected mode. <P> + +<EM>Alpine</EM> handles screens of most any size and resizing on the fly. It catches +SIGWINCH and does the appropriate thing. +<P> + +On the input side of things, <EM>Alpine</EM> uses all the standard keys, most of the +control keys and (in function-key mode) the function keys. <EM>Alpine</EM> avoids +certain control keys, specifically ^S, ^Q, ^H, and <EM>^\</EM> +because they have other meanings outside of <EM>Alpine</EM> (they control data flow, +etc.) <EM>^H</EM> is treated the same as the <EM>delete</EM> key, so the +<EM>backspace</EM> or <EM>delete</EM> keys always work regardless of any +configuration. There is a feature <EM>compose-maps-delete-key-to-ctrl-d</EM> +which makes the delete key behave like ^D rather than ^H (deletes current +character instead of previous character). <P> + +Sometimes a communications program or communications server in between you +and the other end will eat certain control characters. There is a +work-around when you need it. If you type two escape characters followed +by a character that will be interpreted as the character with the control +key depressed. For example, <EM>ESC ESC T</EM> is equivalent to +<EM>^T</EM>. <P> + +When a function key is pressed and <EM>Alpine</EM> is in regular (non-function key) +mode, <EM>Alpine</EM> traps escape sequences for a number of common function keys so +users don't get an error message or have an unexpected command executed +for each character in the function key's escape sequence. <EM>Alpine</EM> expects +the following escape sequences from terminals defined as VT100: <P> + +<BLOCKQUOTE> + ANSI/VT100<BR> +F1: <ESC>OP <BR> +F2: <ESC>OQ <BR> +F3: <ESC>OR <BR> +F4: <ESC>OS <BR> +F5: <ESC>Op <BR> +F6: <ESC>Oq <BR> +F7: <ESC>Or <BR> +F8: <ESC>Os <BR> +F9: <ESC>Ot <BR> +F10: <ESC>Ou <BR> +F11: <ESC>Ov <BR> +</BLOCKQUOTE> +<P> + +Arrow keys are a special case. <EM>Alpine</EM> has the escape sequences for a number +of conventions for arrow keys hard coded and does not use <EM>termcap</EM> +to discover them. This is because <EM>termcap</EM> is sometimes +incorrect, and because many users have PC's running terminal emulators +that don't conform exactly to what they claim to emulate. +There is a feature called +<A HREF="config.html#termdef-takes-precedence"><EM>termdef-takes-precedence</EM></A> +which can be set to cause the <EM>termcap</EM> +or <EM>terminfo</EM> definitions to be used instead of the built in definitions. +Some arrow keys on old terminals send single control characters +like <EM>^K</EM> (one even sends <EM>^\</EM>). +These arrow keys will not work with <EM>Alpine</EM>. +The most popular escape sequences for arrow keys are: <P> + +<BLOCKQUOTE> +Up: <ESC>[A <ESC>?x <ESC>A <ESC>OA<BR> +Down: <ESC>[B <ESC>?r <ESC>B <ESC>OB<BR> +Right: <ESC>[C <ESC>?v <ESC>C <ESC>OC<BR> +Left: <ESC>[D <ESC>?t <ESC>D <ESC>OD<BR> +</BLOCKQUOTE> +<P> + +</BODY> +</HTML> diff --git a/doc/tech-notes/pn4tn b/doc/tech-notes/pn4tn new file mode 100755 index 00000000..aad2b87e --- /dev/null +++ b/doc/tech-notes/pn4tn @@ -0,0 +1,7 @@ +#!/bin/ksh +echo This script will add the PNUTS generated navigation bar to the bottom +echo of the PIC Technical Notes HTML files. +echo '----------------------------------------------------------------------' +# Written by Stefan Kramer, last modified by skramer on 1995/11/02. +pnuts.4tech-notes for.pnuts +# for.pnuts is the file that specifies the sequence of HTML files diff --git a/doc/tech-notes/pnuts.4tech-notes b/doc/tech-notes/pnuts.4tech-notes new file mode 100755 index 00000000..33e8d49f --- /dev/null +++ b/doc/tech-notes/pnuts.4tech-notes @@ -0,0 +1,134 @@ +#!/usr/local/bin/perl +################################################# +#pnuts version 0.4 part of the WN server package +################################################# +# for more info, see http://hopf.math.nwu.edu/docs/utility.html#pnuts +# Modified by Stefan Kramer for use with Pine Technical Notes +# Last modified on 1995 Nov. 02 + + +require "getopts.pl"; + +# Edit to specify what should appear as text of navigation bar. Note: +# If the HTML files processed by PNUTS will be converted to plain-text files, +# the PNUTS-generated link text will probably be stripped out, so this +# text should be unique (i.e., not expected to occur elsewhere in text). + +# This is the original link appearance, without graphic buttons +# $prevw="<b>Previous</b>"; +# $nextw="<b>Next</b>"; +# $upw="<b>Up one level</b>"; +# $topw="<b>Table of Contents</b>"; +# $searchw="<b>Search</b>"; +# $indexw="<b>Index</b>"; + +$prevw='<IMG SRC="../graphics/BPprev.gif" ALT="[Previous]">'; +$nextw='<IMG SRC="../graphics/BPnext.gif" ALT="[Next]">'; +$upw=''; # not needed and don't have a graphic for UP +$topw='<IMG SRC="../graphics/BPtoc.gif" ALT="[Table of Contents]">'; +$searchw='<IMG SRC="../graphics/BPsearch.gif" ALT="[Search]">'; +$indexw=''; # no index here and no graphic for it + + + +$VERSION = "0.4"; + + &Getopts('s:i:'); + $search = $opt_s if $opt_s ne ""; + $index = $opt_i if $opt_i ne ""; + + $file = shift; + $marker = "<!-- pnuts -->"; + + + open( LIST, "<$file") || die "Can't open file: $!"; + + + $nextfile = <LIST>; + print $nextfile; + chop( $nextfile); + $top = $nextfile; + + while ( &getnextfile() ) { + $curcopy = $currentfile."~"; + + rename( $currentfile, $curcopy) + || die "Can't rename file: $currentfile"; + open( OLDCURR, "<$curcopy" ) || die "Can't open file: $!"; + open( NEWCURR, ">$currentfile" ) || die "Can't open file: $!"; + while ( $line = <OLDCURR>) { + if ( $line =~ "^$marker") { + &pnutline(); + } + else { + print NEWCURR $line; + } + } + close( OLDCURR); + close( NEWCURR); + } + + +close( LIST); +exit(0); + +sub pnutline { + printf( NEWCURR "$marker"); + printf( NEWCURR "<P><HR>"); + if ( $previous ) { + printf( NEWCURR " <a href=\"%s\">$prevw</a>", $previous); + } + if ( $nextfile ) { + printf( NEWCURR " <a href=\"%s\">$nextw</a>", $nextfile); + } + if ( $up[$curlevel - 1] ) { + printf( NEWCURR " <a href=\"%s\">$upw</a>", + $up[$curlevel-1]); + } + if ( $top && ( $top ne $currentfile) ) { + printf( NEWCURR " <a href=\"%s\">$topw</a>", $top); + } + if ( $search ) { + printf( NEWCURR " <a href=\"%s\">$searchw</a>", $search); + } + if ( $index ) { + printf( NEWCURR " <a href=\"%s\">$indexw</a>", $index); + } + printf( NEWCURR "\n"); +} + +sub getnextfile { + if ( $nextfile eq "") { + return 0; + } + $previous = $currentfile; + $up[$curlevel] = $currentfile; + + $currentfile = $nextfile; + while ( 1 ) { + ($nextfile = <LIST>) || ($nextfile = ""); + $nextfile =~ s/(\t*)//; + last if $nextfile eq ""; + print $nextfile; + chop( $nextfile); + if ( -d $nextfile ) { + print "$nextfile is directory, ignoring it\n"; + next; + } + last; + } + $curlevel = $nextlevel; + $nextlevel = length( $1); + return 1; +} + + + + + + + + + + + diff --git a/doc/tech-notes/porting.html b/doc/tech-notes/porting.html new file mode 100644 index 00000000..14025372 --- /dev/null +++ b/doc/tech-notes/porting.html @@ -0,0 +1,336 @@ +<HTML><HEAD><TITLE>Pine Technical Notes: Notes for Porting and Modification</TITLE></HEAD><BODY> +<H1>Notes for Porting and Modification</H1> + +<H2><A NAME="new-port">Porting Pine to Other Platforms</A></H2> + +Substantial effort has gone into making <EM>Pine</EM>/<EM>Pico</EM> portable. +There are +still, of course, a number of machine dependencies. Some of the ports are +well-tested and some are untested. In particular, the most heavily used +ports are the Ultrix, AIX, NeXT, Windows, and Dec Unix ports. <P> + +Each platform is given a three letter name (see the file +<CODE>doc/pine-ports</CODE>). Make up a new one for your new port. We've +attempted to bring all potential platform dependencies into the files: +<CODE>{pico,pine}/osdep/os-xxx.h</CODE>, +<CODE>{pico,pine}/osdep/os-xxx.ic</CODE>, +and <CODE>{pico,pine}/makefile.xxx</CODE>, where <EM>xxx</EM> +is the three letter name of the port. Thus any new port will hopefully +just result in new versions of these files and some notes for the +<EM>pine-ports</EM> file. +There are separate dependencies in the c-client source, but that +is handled in separate documentation there. +Regrettably, the source code is also full of instances of <EM>ifdef DOS</EM>. +Most of these are due to memory limit problems on <EM>DOS</EM> as +opposed to actual system dependencies. <P> + +The makefiles are kept as simple and straight-forward as possible, because +many previous attempts at automatically figuring out what to do seem to +have become complex and ineffective in what they set out to do: which is +to make compiling and installing the program easy. Each port is for a +specific hardware/software platform, also because past attempts to +generalize on versions of Unix or some CPU architecture don't seem to have +gained much. Thus, there is a separate makefile for each platform that +calls the appropriate compiler and linker with the appropriate flags. +Most of these makefiles are pretty similar. The makefile also specifies +which of the <EM>os-xxx.c</EM> and <EM>os-xxx.h</EM> files to use. +It is +the root from which most platform dependencies are selected. In most cases +the makefile also defines a symbol named after the platform on which there +can be dependencies in the source code, though we've tried to minimize +relying on this where reasonable. +When different "ports" are very similar, it is sometimes possible to use +the same pine code (for example) with only a small change in the c-client +or pico code. In those cases, that kind of dependency is reflected in +the top-level <EM>build</EM> script. +The <EM>build</EM> script can usually be +used to invoke the various makes correctly. +It may set some variables before running make so look to see what <EM>build</EM> +does before trying a make in one of the subdirectories. This is especially true +if LDAP is being included. <P> + +It is almost always easier to start with an existing port when trying to port +to a new system. There is a port called <EM>gen</EM> (generic) which may be +a good starting point. On the other hand, if another port is close to what +you want, start with it instead. +<P> + +The file <CODE>pico/osdep/os-xxx.h</CODE> contains most of the general +platform dependent <EM>#include</EM>'s and <EM>#defines</EM>. +There are a number +of <EM>Pine</EM> configuration settings that are defined in +<CODE>pine/osdep/os-xxx.h</CODE>, as well, such as the +place it looks for certain files, defaults for the printer and folder +names, the maximum screen size, and so on. +Start by looking at the generic <CODE>pico/osdep/os-gen.h</CODE> file +and comparing it to some of the specific <CODE>os-xxx.h</CODE> files there. <P> + +The <CODE>osdep/os-xxx.c</CODE> files contain functions that are potentially +platform dependent. Again, the idea is to gather all the dependencies in +one place. +We use a complicated looking method to produce +the <EM>os-xxx.c</EM> files from a set of included files. Each included +file usually contains a single implementation method and we've +found that there are +usually only two or three different methods in the +ports we've done so far. Hopefully, coming up with an <CODE>os-xxx.c</CODE> +for a new port will usually be a matter of including the right set of +these already written functions. This is done by writing a new +<CODE>os-xxx.ic</CODE> file in the <CODE>osdep</CODE> subdirectories. +Starting with the generic <CODE>os-gen.ic</CODE>, as you did with +the <CODE>os-gen.h</CODE> file above, may be a useful strategy. <P> + +We strongly encourage that no changes be made to the general source when +porting and that all changes be contained in the system +dependent files if possible. The object is to maintain source code +integrity and assimilate ports to new platforms rapidly. The more +conventional way to do this is with a large collection of +<EM>#ifdefs</EM>. The problem with this is that adding a port for a new +platform implies changing the source code for all the other platforms and +thereby risks breaking them. (We readily admit that there are still too +many <EM>ifdefs</EM> in the code.) <P> + +If you do port <EM>Pine</EM> to a new platform we hope that you will send us the +changes required so that we may attempt to include it in a later release. +Thanks! <P> + +<HR> + +<H2><A NAME="checklist">Test Checklist</A></H2> + +The following is a checklist of some things to check when testing a new +port: <P> + +<DL COMPACT> +<DT> + ___ +<DD> +Sending mail, check that headers are correct +<DT> + ___ +<DD> +Sending mail with attachments +<DT> + ___ +<DD> +Sending mail with SMTP server +<DT> + ___ +<DD> +Sending mail without SMTP server +<DT> + ___ +<DD> +Sending mail with list of two SMTP servers, first one doesn't answer +<DT> + ___ +<DD> +Replying to and forwarding a message +<DT> + ___ +<DD> +Postponing messages under composition +<DT> + ___ +<DD> +Composer operations +<DT> + ___ +<DD> +Alternate editor, <EM>enable-alternate-editor-implicitly</EM> +<DT> + ___ +<DD> +Make sure local user names are expanded +<DT> + ___ +<DD> +Test spelling checker +<DT> + ___ +<DD> +Catching of SIGHUP while message is being composed +<DT> + ___ +<DD> +Setting of variables in <CODE>.pinerc</CODE> +<DT> + ___ +<DD> +New mail notification. Should happen with <EM>Pine</EM> idle to check timeouts +<DT> + ___ +<DD> +Reading mail (attachments, MIME, MIME with mailcap viewers) +<DT> + ___ +<DD> +Deleting, undeleting, expunging, sorting +<DT> + ___ +<DD> +Expunge to empty folder +<DT> + ___ +<DD> +Make sure that <EM>~</EM> expansion works in config files +<DT> + ___ +<DD> +Make sure that $VAR expansion works in config files +<DT> + ___ +<DD> +Save message to folder, check error conditions such as permission denied +<DT> + ___ +<DD> +Export message with FullHeaderMode on and off +<DT> + ___ +<DD> +Checkpointing (see the section on checkpointing) +<DT> + ___ +<DD> +Open IMAP and RIMAP folders +<DT> + ___ +<DD> +Default-fcc on remote IMAP server +<DT> + ___ +<DD> +Fcc-name-rule, fcc in addrbook (while composing) +<DT> + ___ +<DD> +Test opening bogus folders: invalid format, no permission +<DT> + ___ +<DD> +Open a USENET news group, list in folder-lister, read news, post news +<DT> + ___ +<DD> +Command line arguments +<DT> + ___ +<DD> +Change password +<DT> + ___ +<DD> +Lock keyboard +<DT> + ___ +<DD> +Address book operations (edit, delete, add, lists, whereis, composeto) +<DT> + ___ +<DD> +ReadOnly address book +<DT> + ___ +<DD> +Look at addrbook, change addrbook-sort-rule in Config, go back to +addrbook screen +<DT> + ___ +<DD> +No permission to write in same directory as addrbook, should create +addrbook.lu in a temp directory +<DT> + ___ +<DD> +Multiple address books +<DT> + ___ +<DD> +Address book loops from one addrbook to another and back +<DT> + ___ +<DD> +TakeAddr command with one address, with multiple addresses +<DT> + ___ +<DD> +TakeAddr command with ReadOnly address books +<DT> + ___ +<DD> +TakeAddr command with one of two address books ReadOnly +<DT> + ___ +<DD> +Send mail with empty address book +<DT> + ___ +<DD> +Config Screen operation, does pinerc get written? +<DT> + ___ +<DD> +Make sure SIGTSTP, ^Z works +<DT> + ___ +<DD> +Sent-mail pruning (set back <EM>last-time-prune-questioned</EM> variable) +<DT> + ___ +<DD> +Printing using all three printer configurations, various screens +<DT> + ___ +<DD> +View help text and news +<DT> + ___ +<DD> +Folder list operations (rename, create, delete...) +<DT> + ___ +<DD> +Saved-msg-name-rule +<DT> + ___ +<DD> +Screen redrawing in various screens (^L) +<DT> + ___ +<DD> +Window resizing in various screens +<DT> + ___ +<DD> +Error messages for incorrect terminal types (try "foo" and "vt52") +<DT> + ___ +<DD> +Reading of <CODE>/usr/local/lib/pine.conf</CODE> +<DT> + ___ +<DD> +Fixing variables and features in <CODE>/usr/local/lib/pine.conf.fixed</CODE> +<DT> + ___ +<DD> +Flag command (check message status changed in mail folder) +<DT> + ___ +<DD> +Initial-keystroke-list +<DT> + ___ +<DD> +Aggregate operations (save, delete, export, takeaddr, ...) +<DT> + ___ +<DD> +Build xxx from scratch, build clean +</DL> + +<!-- pnuts --> + +</BODY> +</HTML> |