                    Notes on Configuration and Preferences

Pine in Function Key Mode

   The  standard Pine 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.

   Pine  can  also  operate  in a function-key mode. To go into this mode
   invoke  pine -k or (on some UNIX systems) pinef. On a UNIX system, you
   can  link  or  copy  the  Pine  executable  to pinef to install pinef.
   Alternatively,   users   and   systems   administrators  can  set  the
   use-function-keys   feature   in  the  personal  or  system-wide  Pine
   configuration file. The command menus at the bottom of the screen will
   show  F1-F12 instead of the alphabetic commands. In addition, the help
   screens  will  be written in terms of function keys and not alphabetic
   keys.

   One  of  the  results of using Pine 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.
     _________________________________________________________________

Domain Settings

   Pine  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 Pine to check
   if an address is that of the current Pine user.

   Pine  determines  the  domain  name according to whichever of these it
   finds. The list here is in decreasing order of precedence.
    1. Value   of   the   variable   user-domain   in  the  system  fixed
       configuration file
    2. Value  of  the  variable user-domain in the personal configuration
       file
    3. Value of the variable user-domain in the system-wide configuration
       file
    4. Value from an external database (DNS, /etc/hosts, NIS) as modified
       by  a  system fixed configuration file if use-only-domain-name set
       to yes
    5. Value from an external database (DNS, /etc/hosts, NIS) as modified
       by  a  personal  configuration file if use-only-domain-name set to
       yes
    6. Value from an external database (DNS, /etc/hosts, NIS) as modified
       by a system configuration file if use-only-domain-name set to yes
    7. Unmodified value (host name) from an external database

   The  easiest way for this system to work is for PC-Pine users and UNIX
   Pine  system  administrators  to  set  the  user-domain  variable. The
   variable    use-only-domain-name    is    helpful    if    your   site
   supports/requires  hostless  addressing, but for some reason you don't
   want to use the user-domain variable.
     _________________________________________________________________

Syntax for Collections

   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  Pine,  access  to these archives is just as
   simple as access to folders on Pine's local disk.

   "Collection"  is the word we use in Pine 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 Pine will adjust its menus and
   prompts to help navigate them.

   The way collections are defined in Pine is with the folder-collections
   variable  in  the  Pine configuration file. Folder-collections takes a
   list  of  one  or  more  collections,  each (optionally) preceded by a
   user-defined  logical name (label). Once collections are defined, Pine
   adjusts its menus and behavior to allow choosing files by their simple
   name within the collection.

   Consider the following:
   folder-collections=  Local-Mail      C:\MAIL\[],
                        Remote-Mail     {imap.u.example.edu}mail/[]

   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). Pine 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.

   The  collection specifier can be thought of as an extended IMAP format
   (see  the  Remote  Folders  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.

   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:
        M-Mail          C:MAIL/[m*]

   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.

   From  within Pine, the "Folder List" display will be adjusted to allow
   browsing  of  the folders in any defined collection. Even more, you'll
   notice  in the Goto and Save 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.

   The  first  collection specified in the folder-collections 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  Save a message, the default collection for saves
   will  be  used. Also, if the default-fcc is a relative file name, then
   it  is  relative  to  the  default  collection  for  saves.  (See also
   saved-msg-name-rule.

   The  notion  of  collections  encompasses  both email folders and news
   reading.  The variable news-collections uses nearly the same format as
   folder-collections.  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.

   An example pinerc entry might be:
     news-collections=  Remote-State    {news.u.example.edu}#news.[],
                        Local-State     {news.u.example.edu/nntp}#news.[]

   Only  newsgroups  to  which  you  are  subscribed  are included in the
   collection.

   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:
                        Newsfeed-News   {news.u.example.edu/nntp}#news.[clari.*
]

   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 Pine configuration file you get
   simple management of multiple folders in diverse locations.

   As    of   Pine   4.00,   collection   setup   is   handled   by   the
   Setup/collectionList  screen  instead of requiring hand editing of the
   configuration file.
     _________________________________________________________________

Syntax for Folder Names

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

   The full syntax for a Pine folder name looks like

     [{<remote-specification>}][#<namespace>]<namespace-specific-part>

   The square brackets ([]) mean that the part is optional.

   If   there  is  no  remote-specification,  then  the  folder  name  is
   interpreted  locally  on the computer running Pine. Local folder names
   depend  on  the operating system used by the computer running Pine, as
   well   as   the   configuration   of   that   system.   For   example,
   "C:\PINE\FOLDERS\OCT-94"     might     exist     on    a    PC,    and
   "~/mail/september-1994"  might be a reasonable folder name on a system
   running Unix.

   Pine  users  have the option of using folders which are stored on some
   other  computer.  Pine  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  Pine,  the  remote  host  must  be  running the appropriate server
   software  (imapd  or nntpd) and you must correctly specify the name of
   the  folder  to Pine, including the domain name of the remote machine.
   For example,

                        {monet.art.example.com}INBOX

   could be a remote folder specification, and so could

              {unixhost.art.example.com}~/mail/september-1994

   and

                  {winhost.art.example.com}\mymail\SEP-94

   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, not by the operating system of the computer on which you are
   running Pine.

   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 Server
   Name  Syntax  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
   Pine.

   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 Pine how to
   interpret the name that follows.

   So,  for example, Pine can be used to access a newsgroup that might be
   available on your computer using:

                            #news.comp.mail.pine

   The  sharp  sign  indicates  the  folder name is outside your personal
   folder  area.  The "news." phrase after it tells Pine to interpret the
   remainder of the name as a newsgroup.

   Similarly,  to  access  a newsgroup on your IMAP server, you might use
   something like:

               {wharhol.art.example.com}#news.comp.mail.misc

   There   are  a  number  of  such  special  phrases  (or  "namespaces")
   available. For a more detailed explanation read about Namespaces.

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

Server Name Syntax for Folders

   This  section  describes  the  syntax which may be used for the server
   name associated with a remote folder.

   A  server  name is the hostname of the server. It's a good idea to use
   the host's fully-qualified network name.

                              foo.example.com

   However, IP addresses are allowed if surrounded with square-brackets.

                                [127.0.0.1]

   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.

                            foo.example.com:port

   Besides  server  name and optional port number, various other optional
   parameters  may  be  supplied  that  alter Pine'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  not  case  sensitive.
   Currently supported parameters include:

   User
          This parameter requires an associated value, and is intended to
          provide  the  username  identifier  with which to establish the
          server connection. An example might be:

                                /user=katie

   SSL
          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). Pine must
          be   linked   with  an  SSL  library  for  this  option  to  be
          operational.

                                    /ssl

   NoValidate-Cert
          Do  not validate certificates (for TLS or SSL connections) from
          the  server.  This  is  needed  if  the server uses self-signed
          certificates  or  if  Pine  cannot validate the certificate for
          some other known reason.

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

                                 /anonymous

   Secure
          This  is  a  unary parameter indicating that the connection use
          the  most  secure  authentication  method mutually supported by
          Pine   and  the  server.  Pine  is  capable  of  authenticating
          connections  to  the  server using several methods. By default,
          Pine  will  attempt  each  method  until either a connection is
          established or the list of methods is exhausted. This parameter
          causes  Pine  to  instead  fail  the  connection  if  the first
          (generally most "secure") method fails.

                                  /secure

   Debug
          This  is  a  unary  parameter indicating that the connection be
          established in a verbose mode. Basically, it causes Pine to log
          the  communication  with  the  server  in  Pine's  debug  file.
          Normally, the pine -d command-line flag would be used instead.

   NoRsh
          By default, Pine 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.

   Service
          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
          http://www.imap.org/docs/rfc3501.html).  Other  service  values
          include:

        NNTP
                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

                               /service=NNTP

                or just

                                   /NNTP

                is the way to specify NNTP access.

        POP3
                This  value indicates communication with the server takes
                place via the Post Office Protocol 3 protocol.

                               /service=POP3

                or just

                                   /POP3

                Note  that there are several important issues to consider
                when selecting this option:

              1. POP3 provides access to only your INBOX. In other words,
                 secondary  folders  such  as  your  "saved-messages" are
                 inaccessible.
              2. Pine's  implementation  of  POP3  does  not  follow  the
                 traditional  POP  model  and will leave your mail on the
                 server.  Refer  to  the  Mail  Drop  functionality for a
                 possible way around this problem.
              3. See   the   discussion   about   new-mail   checking  in
                 Folder-Reopen-Rule.

   Note  that  it  is  possible  to  include more than one parameter in a
   server specification by concatenating the parameters. For example:

           foo.example.com:port/user=katie/novalidate-cert/debug
     _________________________________________________________________

Folder Namespaces

   A Pine folder name looks like

    [{<remote-specification>}][#<namespace>][<namespace-specific-part>]

   The  local  part  of  a  folder name has an optional "Namespace" which
   tells Pine how to interpret the rest of the name.

   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.

   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.

   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:

   #news.
          This  specifies  a  set  of folders in the newsgroup namespace.
          Newsgroup  names  are  hierarchically  defined  with each level
          delimited by a period.

                            #news.comp.mail.pine

   #public/
          This  specifies a folder area that the server may export to the
          general public.

   #shared/
          This  specifies  a  folder  area  that the folder may export to
          groups of users.

   #ftp/
          This  specifies  a  folder area that is the same as that it may
          have exported via the "File Transfer Protocol".

   #mh/
          This specifies the personal folder area associated with folders
          and directories that were created using the MH message handling
          system.

   #move/
          This  namespace  is  interpreted  locally  by  Pine.  It has an
          unusual interpretation and format.

           #move<DELIM><MailDropFolder><DELIM><DestinationFolder>

          The  #move  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 MailDropFolder name. The
          meaning  of  #move  is  that  mail  will  be  copied  from  the
          MailDropFolder  to  the  DestinationFolder and then deleted (if
          possible) from the MailDropFolder. Periodic checks at frequency
          Mail-Check-Interval, but with a minimum time between checks set
          by  MailDrop-Check-Minimum,  are  made for new mail arriving in
          the  MailDropFolder.  An  example  which copies mail from a POP
          inbox to a local folder follows

          #move+{popserver.example.com/pop3/ssl}inbox+local folder

          To  you  it  appears  that mail is being delivered to the local
          folder  when it is copied from the MailDropFolder, and you read
          mail from the local folder.

          Note  that  if  the  DestinationFolder  does not exist then the
          messages are not copied from the MailDropFolder. A #move folder
          may  only  be  used as an Incoming folder 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 Pine configuration. The same is
          true  when you edit the Inbox-Path option in Setup/Config. Each
          of   these   configuration   methods   will   also  create  the
          DestinationFolder  if  it  doesn't  already  exist.  If you are
          having problems, make sure the DestinationFolder exists.

   In  addition,  the  server may support access to other user's folders,
   provided you have suitable permissions. Common methods use a prefix of
   either  "~user/", or "/user/" to indicate the root of the other user's
   folder area.
     _________________________________________________________________

What is a Mail Drop?

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

   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 Pine move mail from there to a
   local  (on  the  same  machine Pine is running on) destination folder,
   where you'll read it.

   A Mail Drop may only be used as your Inbox or as an Incoming folder.

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

   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  Pine  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 Pine will periodically re-open the Mail
   Drop  to  check  for  new mail. The new mail checks will happen at the
   frequency  set with the Mail-Check-Interval option, but with a minimum
   time  (MailDrop-Check-Minimum) 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 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.

   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.

   The actual syntax used by Pine for a folder that uses a Mail Drop is:

           #move<DELIM><MailDropFolder><DELIM><DestinationFolder>

   The brackets are not literal.

                                  <DELIM>

   is  a  single  character  which  does not appear in the MailDropFolder
   name.  If  the  name  doesn't  contain  spaces  then it can be a space
   character.  The  two  folder  names are full technical folder names as
   used  by  Pine. Here are a couple examples to give you an idea what is
   being talked about:

            #move {popserver.example.com/pop3}inbox localfolder

           #move+{nntpserver.example.com/nntp}inbox+local folder

   A  #move  folder  may  only be used as an Incoming folder 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 Pine configuration. The same is true when you edit the
   Inbox-Path option in Setup/Config.
   if it doesn't already exist. If you are having problems, make sure the
   DestinationFolder exists.
     _________________________________________________________________

Sorting a Folder

   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 $
   command  will  prompt  the user for the sort order. The sort order can
   also  be  specified  on  the  command  line  with  the  -sort  flag or
   (equivalently)  with  the sort-key variable in the pinerc file. When a
   user changes folders, the sort order will go back to the original sort
   order.   The   command   line   (-sort)  or  configuration  file  sort
   specification (sort-key) changes the original sort order.

   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 INBOX, since the INBOX
   will have to be re-sorted whenever new mail arrives.

   The  sorts  are all independent of case and ignore leading or trailing
   white  space. There are actually two forms of subject sort. One called
   Subject  and  the  other called OrderedSubj. They both ignore "Re:" at
   the  beginning  and  "(fwd)" at the end of the subjects. Subject sorts
   all   the  subjects  alphabetically.  OrderedSubj  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 Thread was added after OrderedSubj
   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.

   Sorting large mail folders can be very slow since it requires fetching
   all  the  headers of the mail messages. With UNIX Pine, only the first
   sort is slow since Pine 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. Pine will show progress as it is sorting.
     _________________________________________________________________

Alternate Editor

   In the Pine composer you can use any text editor, such as vi or emacs,
   for  composing  the message text. The addresses and subject still must
   be edited using the standard Pine composer. If you include the feature
   enable-alternate-editor-cmd  in  your  pinerc you can type ^_ while in
   the  body  of  the  message  in  the  composer and be prompted for the
   editor.  If  you  also  set the editor variable in your pinerc then ^_
   will invoke the configured editor when you type it.

   Turning   on   the   feature  enable-alternate-editor-implicitly  will
   automatically  invoke  the  editor  you  have  defined with the editor
   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.

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

Signatures and Signature Placement

   If  the  file  ~/.signature  (UNIX) or <PINERCdirectory>\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  signature-file  variable  in  the pinerc. If the feature
   enable-sigdashes  is  turned  on then the line consisting of the three
   characters  "-- " is prepended to the signature file. When Replying or
   Forwarding a message different signatures my be automatically included
   by  configuring  them  in the Roles setup screen. It's easy to include
   different  signatures  by  hand,  by  having  multiple signature files
   (.sig1,  .sig2,  .sig3,  etc)  and  choosing  to  include  (^R  in the
   composer) the correct one for the message being sent.

   Pine'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 signature-at-bottom
   feature. The signature will then be appended to the end of the message
   after  any included text. This feature applies when Replying, not when
   Forwarding.
     _________________________________________________________________

Feature List Variable

   Pine  used  to have feature levels for users with different amounts of
   experience.  We  found  that  this was too restrictive. Pine now has a
   feature-list  instead.  Each  user  may pick and choose which features
   they  would  like  enabled  (simple to do in the Setup/Config screen).
   There  is a short description of each in Configuration Features. There
   is  also  a  short  on-line  help explaining the effect of each of the
   features in the Setup/Config screen. When the cursor is highlighting a
   feature,  the  ?  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.

   The  feature-list  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 added to the set of features turned on in
   the  system-wide  configuration  file.  (With  all other configuration
   variables,   the   user's  values  replace  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.

   The  treatment  of feature-list in the system-wide fixed 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.

   Because  feature-list 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 quit-without-confirm
   feature  set,  the  user  can  over-ride  that  (and  turn  it off) by
   including  no-quit-without-confirm  in the personal configuration file
   or by giving the command line argument
   -feature-list=no-quit-without-confirm. More features (options) will no
   doubt continue to be added.
     _________________________________________________________________

Configuration Inheritance

   We  start  with  an explanation of how configuration works in hopes of
   making it easier to describe how inheritance works.

   Pine   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:

    1. the system-wide configuration file.
    2. the personal configuration file
    3. the personal exceptions file
    4. a command line argument
    5. the system-wide fixed configuration file (Unix Pine only)

   The fixed configuration file is normally /etc/pine.conf.fixed.

   The system-wide configuration file is normally /etc/pine.conf for Unix
   Pine  and  is  normally  not  set  for  PC-Pine.  For  PC-Pine, if the
   environment   variable   $PINECONF  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.

   For  Unix  Pine,  the personal configuration file is normally the file
   .pinerc  in the user's home directory. This can be changed with the -p
   command  line flag. For PC-Pine, the personal configuration file is in
   $PINERC or <PineRC registry value> or ${HOME}\PINE\PINERC or <PINE.EXE
   dir>\PINERC.  This can be changed with the -p command line flag. If -p
   or $PINERC is used, the configuration data may be in a local file or a
   remote config folder.

   For Unix Pine, 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, Pine
   will  look  for  the file ".pinercex" in the same local directory that
   the  regular  config file is located in. If the regular config file is
   remote then Unix Pine looks in the home directory for ".pinercex".

   For  PC-Pine,  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 $PINERCEX 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
   $PINERCEX is not set, PC-Pine will look for the file "PINERCEX" in the
   same  local  directory  that the regular config file is located in. If
   the  regular  config  file  is  remote then PC-Pine looks in the local
   directory   specified  by  the  "-aux  local_directory"  command  line
   argument,  or  the  directory ${HOME}\PINE, or in <PINE.EXE directory>
   for a file named "PINERCEX".

   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.

   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.

   Finally  we  get  to  inheritance. For configuration options which are
   lists,  like  "smtp-server"  or  "incoming-folders",  the  inheritance
   mechanism  makes  it  possible  to  combine  the values from different
   locations  instead  of  replacing  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).

   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.

   Here is an example which may make it clearer. Suppose we have:

 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>

   This would result in an effective smtp-server option of

 smtp-server = smtp1.corp.com, smtp2.corp.com, mysmtp.home

   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:

 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>

   This would result in:

 smtp-server = smtp1.corp.com, smtp2.corp.com, mysmtp.home, yoursmtp.org

   Unset  variables  are  skipped  over  (the  default  value  is carried
   forward) so that, for example:

 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>

   produces:

 smtp-server = smtp1.corp.com, smtp2.corp.com, yoursmtp.org

   If  any later configuration location has a value set (for a particular
   list  option)  which  does  not  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.

 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>

   results in:

 smtp-server = yoursmtp.org

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

Using Environment Variables

   The  values  of  Pine  configuration  options  may include environment
   variables  which are replaced by the value of the variable at the time
   Pine  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

                                    $VAR

   appears in the value of a Pine configuration option it is looked up in
   the  environent (using getenv("VAR")) and its looked-up value replaces
   the  $VAR  part of the option value. That 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

                         PERSNAME="Fred Flintstone"

                              export PERSNAME

   Now, if you use Pine's Setup/Config screen to set

                          personal-name=$PERSNAME

   the  $PERSNAME would be replaced by Fred Flintstone so that this would
   be equivalent to

                       personal-name=Fred Flintstone

   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.

   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

                                   ${VAR}

   It is always ok to use the braces even if you don't need to.

   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

                           ${VAR:-default value}

   If the config file contains

                   personal-name=${VAR:-Fred Flintstone}

   then when Pine is run VAR will be looked up in the environment. If VAR
   is  found  then personal-name will have the value that VAR was set to,
   otherwise,  personal-name  will be set to Fred Flintstone, the default
   value.

   An  example  where  an  environment  variable  might  be useful is the
   variable  inbox-path  in  the  global configuration file. Suppose most
   users used the server

                           imapserver.example.com

   but that there were some exceptions who used

                         altimapserver.example.com

   In  this  case, the system manager might include the following line in
   the systemwide default Pine configuration file

              inbox-path=${IMAPSERVER:-imapserver.example.com}

   For the exceptional users adding

                    IMAPSERVER=altimapserver.example.com

   to their environment should work.

   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

                             smtp-server=$SMTP

   or  perhaps  a  default  value could be given. Note that, as mentioned
   above, the variable SMTP cannot contain a list of SMTP servers.
     _________________________________________________________________

SMTP Servers

   It  is  sometimes  desirable  to  set smtp-server=localhost instead of
   setting  sendmail-path  to  overcome  the inability to negotiate ESMTP
   options when sendmail is invoked with the -t option. Sendmail can also
   be  subject  to  unacceptable delays due to slow DNS lookups and other
   problems.

   It is sometimes desireable 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 sendmail directly.

   A typical configuration would consist of
     * A program that implements the SMTP or ESMTP protocol via stdio.
     * An entry in /etc/services for the alternate service.
     * An entry in /etc/inetd.conf for the alternate service.
     * An entry in /etc/pine.conf, /etc/pine.conf.fixed or ~/.pinerc.
     _________________________________________________________________

MIME.Types file

   Pine's  MIME-TYPE support is based on code contributed by Hans Drexler
   &LT;drexler@mpi.nl&GT;.  Pine  assigns MIME Content-Types according to
   file    name    extensions    found    in    the   system-wide   files
   /usr/local/lib/mime.types  and  /etc/mime.types,  and  a user specific
   ~/.mime.types file.

   In  DOS  and OS/2, Pine looks in the same directory as the PINERC file
   and  the  same  dir as PINE.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
   mimetype-search-path variable in the user or system-wide configuration
   or by setting the MIMETYPES environment variable.

   These  files  specify file extensions that will be connected to a mime
   type. Lines beginning with a '#' character are treated as comments and
   ignored.  All  other  lines are treated as a mime type definition. The
   first  word  is  a type/subtype specification. All following words are
   file extensions 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:

image/gif         gif
text/html         html htm
video/mpeg        mpeg mpg mpe
     _________________________________________________________________

Color Details

   UNIX  Pine  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  color-style  option and setting it to the value force-ansi-8color
   or  force-ansi-16color.  If  instead  you'd like Pine to automatically
   detect  whether or not you are on a color terminal, set color-style to
   use-termdef   and   configure  the  termcap  entry  to  describe  your
   terminal's color capabilities.

   If  the  color-style  option  is set to use-termdef, Pine looks in the
   terminal  capabilities database, TERMINFO or TERMCAP, depending on how
   Pine  was  compiled, to decide whether or not your terminal is capable
   of  color. For TERMINFO compiled Pines, 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,
   Pine  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 Pines, 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.

   Here are some short descriptions of the capabilities listed above. The
   TERMINFO name is listed, followed by the TERMCAP name in parentheses.
   colors (Co)
          The number of different colors.
   setaf (AF)
          Set ANSI foreground color.
   setab (AB)
          Set ANSI background color.
   setf (Sf)
          Set foreground color. Alternate form of setaf.
   setb (Sb)
          Set background color. Alternate form of setab.
   op (op)
          Set default pair to its original value.
   bce (ut)
          Screen  is  erased  with  current  background  color instead of
          default background.

   A  standard  ANSI  terminal  which supports color will have a TERMINFO
   entry which contains:
  colors#8
  setaf=\E[3%p1%dm
  setab=\E[4%p1%dm
  op=\E[39;49m
  bce

   or the TERMCAP equivalent:
  Co#8
  AF=\E[3%dm
  AB=\E[4%dm
  op=\E[39;49m
  ut

   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. Pine 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  Pines,  because of the arithmetic, which is not supported by
   TERMCAP.
  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

   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:
  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

   and here is the termcap equivalent:
  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

   This  is  a  terminfo  entry  for  16  colors that also does the color
   flipping:
  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

   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 Pine and PC-Pine, 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.
     _________________________________________________________________

Additional Notes on PC-Pine

   Below  are  a  few  odds and ends worth mentioning about PC-Pine. They
   have  to  do  with  DOS-specific  behavior that is either necessary or
   useful (and sometimes both!).

   As  PC-Pine  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 PC-Pine:
        X-Sender: <userid>@<imap.host>

   By  popular demand of system administrators, PC-Pine has been modified
   to  prevent  sending  messages  until the user has successfully logged
   into  a  remote  mail server. Even though PC-Pine 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 X-Sender 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.

   Hand  in  hand with authentication and accounting is user information.
   Since   PC-Pine   has   no  user  database  to  consult  for  user-id,
   personal-name,  etc.,  necessary  information  must be provided by the
   user/installer  before  PC-Pine  can  properly  construct  the  "From"
   address  required  for  outbound  messages.  PC-Pine will, by default,
   prompt  for  the requisite pieces as they are needed. This information
   corresponds   to   the   PINERC   variables   user-id,  personal-name,
   user-domain, and smtp-server.

   The  user  is  then  asked  whether  or  not  this  information should
   automatically  be  saved  to  the  PINERC.  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 PINERC 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 Pine session, and no opportunity to save
   them in the PINERC will be offered.

   Along  similar  lines,  a  feature  allowing  automatic  login  to the
   imap-server  containing the user's INBOX has also been requested. This
   feature  is  not enabled by default, but requires the existence of the
   file named PINE.PWD in the same directory as the PINERC. Even with the
   existence  of  this  file,  the  user  must still acknowledge a prompt
   before  the password is saved to the file. If PC-Pine is configured to
   access  several  different IMAP servers, each password entered will be
   kept  (associated  with  the corresponding host name) in memory during
   the  current  session, and optionally, in the PINE.PWD file for use in
   subsequent sessions.

   WARNING!  Use  this  feature  with  caution!  It effectively makes the
   user's  mail  no more secure than the physical security of the machine
   running  PC-Pine. What's more, while the password is cloaked by a mild
   (some  might say, feeble) encryption scheme, it is nonetheless sitting
   in  a  file  on  the  PC's disk and subject to cracking by anyone with
   access to it. BEWARE!

   Another  feature  of  DOS  is  the  lack  of standard scratch area for
   temporary  files.  During the course of a session, PC-Pine 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. PC-Pine observes the TMPDIR, TMP,
   and  TEMP  environment  variables,  and creates temporary files in the
   directory specified by either. In their absence, PC-Pine 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.
