Configuration and Preferences

Pine Configuration

The syntax of a non-list configuration variable is this:

<variable> = <value>

<variable> = <value> [, <value> , ... ]

For UNIX Pine, there are five ways in which a variable can be set. In decreasing order of precedence they are:

1. the system-wide fixed configuration file
2. a command line argument
3. the personal configuration file (which is usually set from the Config screen)
4. the system-wide configuration file
5. default in the source code.

So, system-wide fixed settings always take precedence over command line flags, which take precedence over per-user settings, which take precedence over system-wide configuration settings, which take precedence over source code defaults. PC-Pine has the same precedence, but it does not use a system-wide fixed configuration file.

You may get a sample/fresh copy of the system configuration file by running pine -conf. The result will be printed on the standard output with short comments describing each variable. (The online help in the Setup/Config screen provides longer comments.) If you need to fix some of the configuration variables, you would use the same template for the fixed configuration file as for the regular system-wide configuration file. (If it isn't clear, the purpose of the fixed configuration file is to allow system administrators to restrict the configurability of Pine. It is by no means a bullet-proof method.) Pine will automatically create the personal configuration file the first time it is run, so there is no need to generate a sample. Pine reads and writes the personal configuration file occasionally during normal operation. Users will not normally look at their personal configuration file, but will use the Setup/Config screen from within Pine to set the values in this file. If a user does add additional comments to the personal configuration file they will be retained. Pine always writes this file at least once when running, so you can tell when a user last invoked Pine by checking the date on this file.

References to environment variables may be included in the Pine configuration files. The format is $variable or ${variable}. The character ~ will be expanded to the $HOME environment variable.

When environment variables are used for Pine settings which take lists, you must have an environment variable set for each member of the list. That is, Pine won't properly recognize an environment variable which is set equal to a comma-delimited list. It is OK to reference unset environment variables in the Pine configuration file, which will expand to nothing.

General Configuration Variables

addrbook-sort-rule

This variable sets up the default address book sorting. Currently, Pine will accept the values dont-sort, fullname-with-lists-last, fullname, nickname-with-lists-last, and nickname. The default is to sort by fullname with lists last.

address-book

A list of personal address books. Each entry in the list is an optional nickname followed by a pathname or file name relative to the home directory. This list will be added to the global-address-book list to arrive at the complete set of address books.

addressbook-formats

This option specifies the format that address books are displayed in. Normally, 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.

alt-addresses

This option provides a place for you to list alternative email addresses you may have. If set, the option affects the behavior of the Reply command and the "+" symbol in the Folder Index, which denotes that a message has been addressed specifically to you.

With respect to Reply, the reply-to-all option will exclude addresses listed here.

bugs-additional-data

System-wide configuration file only. Program/Script used by "Report Bug" command. Output from the program/script is captured and attached to the bug report.

bugs-nickname, bugs-fullname, bugs-address, local-fullname, local-address, suggest-fullname, and suggest-address

System-wide configuration file only. These are used by the Report Bug command.

character-set

This sets the character set used by the terminal. Currently appropriate values are US-ASCII, ISO-8859-1 through ISO-8859-9 and ISO-2022-JP. See the section on international character sets for more details. The default is US-ASCII.

composer-wrap-column

This option specifies an aspect of Pine's Composer. This gives the maximum width that auto-wrapped lines will have. It's also the maximum width of lines justified using the ^J Justify command. The normal default is "74". The largest allowed setting is normally "80" in order to prevent very long lines from being sent in outgoing mail. When the mail is actually sent, trailing spaces will be stripped off of each line.

customized-hdrs

Add these custom headers when composing. Also possible to add default values to these custom headers or to any of the standard headers. This is a list variable. Each entry in the list is a header name (the actual header name that will appear in the message) followed by an optional colon and value. For example, if a Reply-to header was needed because it was different from the From address, that could be accomplished with:

    customized-hdrs=Reply-to: fred_flintstone@bedrock.net 

default-composer-hdrs

Show only these headers (by default) when composing a message. This list may include headers defined in the customized-hdrs list.

default-fcc

The name of the folder to which all outgoing mail goes is set here. The compiled-in default is sent-mail (UNIX) or sentmail (PC). It can be set to "" (two double quotes with nothing between them) to turn off saving copies of outgoing mail. If the default-fcc is a relative file name, then it is relative to your default collection for saves (see folder-collections).

default-saved-msg-folder

This option determines the default folder name for Saves... If this is not a path name, it will be in the default collection for saves. Any valid folder specification, local or IMAP, is allowed. This default folder only applies when the saved-msg-name-rule (see later in this configuration screen) doesn't override it. Unix Pine default is normally "saved-messages" in the default folder collection. PC-Pine default is "SAVEMAIL" (normally stored as SAVEMAIL.MTX).

display-filters

This option defines a list of text-filtering commands (programs or scripts) that may be used to filter text portions of received messages prior to their use (e.g., presentation in the "MESSAGE TEXT" display screen). For security reasons, the full path name of the filter command must be specified. See the online help text for further details.

download-command

This option affects the behavior of the Export command. It specifies a Unix program name, and any necessary command line arguments, that Pine can use to transfer the exported message to your personal computer's disk.

download-command-prefix

This option is used in conjunction with the Download-command option. It defines text to be written to the terminal emulator (via standard output) immediately prior to starting the download command. This is useful for integrated serial line file transfer agents that permit command passing (e.g., Kermit's APC method).

editor

UNIX Pine only. Sets the name of the alternate editor for composing mail (message text only, not headers). It will be invoked with the "^_" command or it will be invoked automatically if the enable-alternate-editor-implicitly feature is set.

fcc-name-rule

Determines default folder name for fcc when composing. Currently, Pine will accept the values default-fcc, by-recipient, or last-fcc-used. If set to default-fcc, then Pine will use the value defined in the default-fcc variable (which itself has a default) for the Fcc header field. If set to by-recipient, then Pine will use the name of the recipient as a folder name for the fcc. The relevant recipient is the first address in the To field. If set to "last-fcc-used", then Pine will offer to fcc to whatever folder you used previously. In all cases, the field can still be edited after it is initially assigned. If the fcc field in the address book is set for the first To address, that value over-rides any value derived from this rule.

feature-list

This is a list of features (options) which may be turned on. You may also turn features off (the default) by prepending the characters no- to any of the features. The feature-list is additive. That is, first the system-wide feature-list is read and then the user's feature-list 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. However, some of the documentation assumes that all of the features are off by default, so use this with care. In Unix Pine, features can be individually fixed on or off by setting the feature on or off in the system-wide fixed configuration file. Descriptions for most features are omitted here. See the online help for descriptions of each feature (in the Setup/Config screen).

Here is the current list of possible features.

allow-talk
assume-slow-link
auto-move-read-msgs
auto-open-next-unread
auto-unzoom-after-apply
auto-zoom-after-select
compose-cut-from-cursor
compose-maps-delete-key-to-ctrl-d
compose-rejects-unqualified-addrs
compose-send-offers-first-filter
compose-sets-newsgroup-without-confirm
delete-skips-deleted
disable-keyboard-lock-cmd
disable-keymenu
disable-config-cmd
disable-password-cmd
disable-signature-edit-cmd
disable-update-cmd
enable-8bit-esmtp-negotiation
enable-8bit-nntp-posting
enable-aggregate-command-set
enable-alternate-editor-cmd
enable-alternate-editor-implicitly
enable-bounce-cmd
enable-cruise-mode
enable-cruise-mode-delete
enable-dot-files
enable-dot-folders
enable-flag-cmd
enable-flag-screen-implicitly
enable-full-header-cmd
enable-incoming-folders
enable-jump-shortcut
enable-mail-check-cue
enable-mouse-in-xterm
enable-suspend
enable-tab-completion
enable-unix-pipe-cmd
enable-verbose-smtp-posting
expanded-view-of-addressbooks
expanded-view-of-folders
expunge-without-confirm
fcc-on-bounce
include-attachments-in-reply
include-header-in-reply
include-text-in-reply
news-post-without-validation
news-read-in-newsrc-order
pass-control-characters-as-is
preserve-start-stop-characters
print-formfeed-between-messages
print-offers-custom-cmd-prompt
print-index-enabled
quell-dead-letter-on-cancel
quell-lock-failure-warnings
quell-status-message-beeping
quit-without-confirm
reply-always-uses-reply-to
save-aggregates-copy-sequence
save-will-quote-leading-froms
save-will-not-delete
save-will-advance
select-without-confirm
show-cursor
show-selected-in-boldface
signature-at-bottom
single-column-folder-list
tab-visits-next-new-message-only
use-current-dir
use-function-keys
use-sender-not-x-sender
user-lookup-even-if-domain-mismatch

The four disable- features and the use-function-keys feature are intentionally suppressed from the Config screen, as they are intended for use by system administrators in the system-wide fixed config file. Their meaning should be self-explanatory.

The save-aggregates-copy-sequence feature is suppressed from the config screen. This feature will optimize an aggregate copy operation, if possible, by issuing a single COPY command with a list of the messages to be copied. This may save network traffic when the source and destination folders are on the same IMAP server. However, many IMAP servers (including the UW IMAP server) do not preserve the order of messages when this optimization is applied. If this feature is not enabled, or if the folders are on different IMAP servers, or the folders are local and in different formats, Pine will copy each message individually.

folder-collections

This is a list of one or more collections where saved mail is stored. See the sections describing folder collections and collection syntax for more information. The first collection in this list is the default collection for saves, including default-fcc's.

font-name

Winsock version of PC Pine only.

font-size

Winsock version of PC Pine only.

forced-abook-entry

System-wide Pine configuration file only. Force these address book entries into all writable personal address books.

global-address-book

A list of shared address books. Each entry in the list is an optional nickname followed by a pathname or file name relative to the home directory. This list will be added to the address-book list to arrive at the complete set of address books. Global address books are defined to be readonly.

goto-default-rule

This value affects Pine's behavior when you use the Goto command. There are three possible values for this option:

inbox-or-folder-in-recent-collection

If your current folder is "Inbox", Pine will offer the last open folder as the default. If the current folder is other than "Inbox", "Inbox" is offered as the default.

inbox-or-folder-in-first-collection

The second accepted value is a variation on the default which again offers "Inbox" if it isn't currently open, but otherwise offers the most recent folder in the first collection found in the "FOLDER LIST" screen.

most-recent-folder

The last accepted value simply causes the most recently opened folder to be offered as the default regardless of the currently opened folder.

NOTE: The default while a newsgroup is open remains the same; the last open newsgroup.

image-viewer

This variable names the program to call for displaying parts of a MIME message that are of type IMAGE. If your system supports the mailcap system, you don't need to set this variable.

inbox-path

This specifies the name of the folder to use for the INBOX. Normally this is unset so the system's default is used. The most common reason for setting this is to open an IMAP mailbox for the INBOX. For example, {imap5.u.example.edu}inbox will open the user's standard INBOX on the mail server, imap5.

incoming-archive-folders

This is like Read-Message-Folder, only more general. This is a list of folder pairs, with the first separated from the second in the pair by a space. The first folder in a pair is the folder you want to archive, and the second folder is the folder that read messages from the first should be moved to. Depending on how you define the "auto-move-read-messages" setting in the "feature-list", you may or may not be asked when you leave the first folder if you want read messages to be moved to the second folder. In either case, moving the messages means they will be deleted from the first folder.

If these are not path names, they will be in the default collection for saves. Any valid folder specification, local or remote (via IMAP), is allowed. There is no default.

incoming-folders

This is a list of one or more folders other than INBOX that may receive new messages. This list is slightly special in that it is always expanded in the folder lister. In the future, it may become more special. For example, it would be nice if Pine would monitor the folders in this list for new mail.

index-format

This option specifies the format that folder indexes are displayed in. Normally, the system figures out reasonable defaults for the widths of the columns of the index display. A non-standard display format can be used by listing special tokens in the order you want them to display. The tokens are STATUS, FULLSTATUS, MSGNO, DATE, SIZE, DESCRIPSIZE, SUBJECT, FROMORTO, FROM, and TO. The tokens are separated by spaces. Each of the tokens may also be optionally followed by parentheses with either a number or a percentage inside the parentheses.

initial-keystroke-list

This is a comma-separated list of keystrokes which Pine executes on startup. Items in the list are usually just characters, but there are some special values. SPACE, TAB, and CR mean a space character, tab character, and a carriage return, respectively. F1 through F12 stand for the twelve function keys. UP, DOWN, LEFT, and RIGHT stand for the arrow keys. Control characters are represented with ^<char>. A restriction is that you can't mix function keys and character keys in this list even though you can, in some cases, mix them when running Pine. A user can always use only character keys in the startup list even if he or she is using function keys normally, or vice versa.

kblock-passwd-count

System-wide Pine configuration file only. number of times a user will have to enter a password when they run the keyboard lock command in the main menu.

last-time-prune-questioned

Personal configuration file only. This variable records the month the user was last asked if his or her sent-mail folders should be pruned. The format is yy.mm. This is automatically updated by Pine when the the pruning is done or declined. If a user wanted to make Pine stop asking this question he or she could set this time to something far in the future.

last-version-used

Personal configuration file only. This is set automatically by Pine. It is used to keep track of the last version of Pine that was run by the user. Whenever the version number increases, a new version message is printed out.

mail-check-interval

This option specifies, in seconds, how often Pine will check for new mail. If set to zero, new-mail checking is disabled. There is a minimum value, normally 15 seconds.

mail-directory

This variable was more important in previous versions of Pine. Now it is used only as the default for storing personal folders (and only if there are no folder-collections defined). The default value is ~/mail on UNIX and $HOME\MAIL on a PC.

mailcap-search-path

This variable is used to replace Pine'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.

mimetype-search-path

This variable is used to replace Pine'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 Pine's usage of the MIME.Types File.

new-version-threshold

When a new version of Pine 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 Pine. It takes as its value a Pine version number. Pine version less than the specified value will supress this special screen while versions equal to or greater than that specified will behave normally.

news-active-file-path

This option tells Pine where to look for the "active file" for newsgroups when accessing news locally, rather than via NNTP. The default path is usually "/usr/lib/news/active".

news-collections

This is a list of collections where news folders are located. See the section describing collections for more information.

news-spool-directory

This option tells Pine where to look for the "news spool" for newsgroups when accessing news locally, rather than via NNTP. The default path is usually "/usr/spool/news".

newsrc-path

This option overrides the default name Pine uses for your "newsrc" news status and subscription file. If set, Pine will take this value as the full pathname for the desired newsrc file.

nntp-server

One or more NNTP servers (host name or IP address) which Pine will use for outgoing news. If you read and post news to and from a single NNTP server, you can get away with only setting the nntp-server variable and leaving the news-collections variable unset.

normal-background-color

PC-Pine only. Currently, Pine will accept the colors black, blue, green, cyan, red, magenta, yellow, or white.

normal-foreground-color

PC-Pine only. See normal-background-color for possible colors.

operating-dir

System-wide Pine configuration file only. This names the root of the tree to which the user is restricted when reading and writing folders and files.

personal-name

Personal configuration file only (not applicable in global config. file). User's full personal name. On UNIX systems, the default is taken from the accounts data base (/etc/passwd).

personal-print-command

UNIX personal configuration file only. This corresponds to item 3 in the printer menu. This variable retains the value of personal-print-command when the printer is set to something other than item 3. The personal-print-command can be set within Pine using the printer setup menu.

postponed-folder

The folder where postponed messages are stored. The default is postponed-msgs (Unix) or POSTPOND (PC).

printer

UNIX Pine only. This is the current setting for a user's printer. This variable is set from Pine's printer-setup function. The value must be either

• "attached-to-ansi" -or-
• the value of personal-print-command -or-
• the value of standard-printer from the system-wide configuration.

pruned-folders

This variable allows you to define a list of one or more folders that Pine will offer to prune for you in the same way it automatically offers to prune your "sent-mail" folder each month. That is, once a month for each folder listed, Pine 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. Pine will then look for any such date-appended folder names created for a previous month, and offer each one it finds for deletion. If you decline the first offer, no mail is moved and no new folder is created. Folders listed are assumed to exist, and the archive folders will be created, in the first collection defined by the "folder-collections" variable.

read-message-folder

If set, mail in the INBOX 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 Pine.

reply-indent-string

This variable specifies an aspect of Pine's Reply command. When a message is replied to and the text of the message is included, that text usually has the string "> " prepended to each line to indicate quoting.

This variable 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.

You can also include the sender's name in the prepended string. The first occurrence of "_FROM_" in the reply-indent-string will be replaced with the "username" portion of the address being replied to.

The normal default is "> ".

reverse-background-color

PC-Pine only. See normal-background-color for possible colors.

reverse-foreground-color

PC-Pine only. See normal-background-color for possible colors.

saved-msg-name-rule

Determines default folder name when saving. Currently, Pine will accept the values "default-folder", "by-sender", "by-from", "by-recipient", or "last-folder-used". If set to default-folder, then Pine will offer the folder "saved-messages" (UNIX) or "SAVEMAIL" (PC) for saving messages. If set to by-from, then Pine will offer to save the message in a folder with the same name as the From, if there is one, or the Sender otherwise. If set to by-sender, then Pine will offer to save the message in a folder with the same name as the Sender, if there is one, or the From otherwise. If set to by-recipient, then Pine will offer to save the message in a folder with the same name as the recipient, which is the newsgroup if this was sent to a newsgroup or the To address if not. If set to "last-folder-used", then Pine will offer to save in whatever folder you used previously.

sending-filters

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 ^X (Send) 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. See the online help text for further details.

sendmail-path

System-wide Pine configuration file only. This names the path to an alternative program, and any necessary arguments, to be used in posting mail messages.

signature-file

Names the file to be included as the signature. This defaults to ~/.signature on UNIX and <PINERC directory>\PINE.SIG on a PC.

smtp-server

One or more SMTP servers (host name or IP address) which Pine will use for outgoing mail. If not set, Pine passes outgoing email to the sendmail program on the local machine. PC-Pine users must have this variable set in order to send mail as they have no sendmail program. An alternate port may be specified by appending :port to the host name or IP address. See the SMTP Servers section for details.

sort-key

This variable sets up the default index sorting. The default is to sort by arrival order. It has the same functionality as the -sort command line argument and the $ command in the folder index. If a sort-key is set, then all folders open during the session will have that as the default sort order.

speller

This option affects the behavior of the ^T (spell check) command in the Composer. It specifies the program invoked by ^T in the Composer. By default, Pine uses the system's "spell" command. Pine will use the command defined by this option (if any) instead. When invoking the spell-checking program, Pine appends a tempfile name (where the message is passed) to the command line.

standard-printer

System-wide configuration file only. Specifies the command for printer selection number 2 on the printer menu. Unix only.

status-message-delay

If this 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 show-cursor feature is also turned on.

upload-command

This option affects the behavior of the Composer's "Read File" (^R in the message body) and "Attach File" (^J in the header) commands. It specifies a Unix program name, and any necessary command line arguments, that Pine can use to transfer files from your personal computer into messages that you are composing.

upload-command-prefix

This option is used in conjunction with the Upload-command option. It defines text to be written to the terminal emulator (via standard output) immediately prior to starting upload command. This is useful for integrated serial line file transfer agents that permit command passing (e.g., Kermit's APC method).

use-only-domain-name

Can be set to yes or no. At this point anything but yes means no. If set to yes 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 carson.u.example.edu and this variable is set to yes, then u.example.edu will be used on outgoing mail. Only meaningful if user-domain is NOT set.

user-domain

Sets the domain or host name for the user, overriding the system host or domain name. See the domain name section.

user-id

PC-Pine only. Sets the username that is placed on all outgoing messages.

viewer-hdrs

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 "viewer-hdrs" list are present in the message, then they will be shown. The order of the headers you list will be honored. If the special value "all-except" is included as the first header in the "viewer-hdrs" list, then all headers in the message except those in the list will be shown. The values are all case insensitive.

viewer-overlap

This option specifies an aspect of Pine's Message Viewing screen. When the space bar is used to page forward in a message, the number of lines specified by the "viewer-overlap" 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".

window-position

Winsock version of PC Pine 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.

Retired Variables

elm-style-save

Replaced by saved-msg-name-rule

feature-level

Replaced by feature-list.

header-in-reply

Replaced by include-header-in-reply in the feature-list.

old-style-reply

Replaced by signature-at-bottom in the feature-list.

save-by-sender

Replaced by saved-msg-name-rule.

show-all-characters

No replacement, it always works this way now.