debug ANSI_X3.4-1968
debug ANSI_X3.4-1968
                               Behind the Scenes

   Many  people  ask  how  certain  Pine  features  are implemented. This
   section outlines some of the details.

Address Books

   Beginning  with Pine 4.00 there are two types of address book storage.
   There  are  local  address books, which are the address books that are
   stored in a local file (the address books Pine has had all along); and
   there are remote address books, which are stored on an IMAP server.

    Information About Remote Address Books

     NOTE:  The  remote  address  book  capability does not allow you to
     access  an  existing  local address book from a remote system! That
     is,  you  can't  set  the  remote  address  book  to something like
     {remote.host}.addressbook   and   expect  to  access  the  existing
     .addressbook file on remote.host. Instead, you need to create a new
     remote address book in a new, previously unused remote mail folder.
     Then  you can use the Select and Apply Save commands in the address
     book  screen  to  Save  all  of  the entries from an existing local
     address book to the new remote address book.

   Beginning  with Pine 4.00 there is a new type of address book called a
   remote  address book. A remote address book is stored in a mail folder
   on  an  IMAP  server.  A  Pine remote address book is just like a Pine
   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 a pine remote
   address book header message which contains the header x-pine-addrbook.
   The  last  message  in  the  folder contains the address book data. In
   between the first and the last message are old versions of the address
   book data. The address book data is simply stored in the message as it
   would be on disk, with no MIME encoding. When it is used the data from
   the last message in the folder is copied to a local file and then that
   file  is  used  exactly like a local address book file is used. When a
   change  is  made  the  modified  local  file is appended to the remote
   folder  in  a  new  message.  In other words, the local file is just a
   cache  copy  of  the data in the remote folder. Each client which uses
   the  remote  address  book  will  have its own cache copy of the data.
   Whenever  a  copy  is done the entire address book is copied, not just
   the entries which have changed.

   Pine  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 Pine discovers the folder
   has changed it gets a new copy and puts it in the local cache file.

   There  is  a  new configuration file variable for remote address books
   called  remote-abook-metafile.  The  variable is the name of a file in
   which  information  about remote address books is stored. There is one
   line  in  the  metafile  for each remote address book. The information
   stored  there  is  the  name of the cache file and information to help
   figure  out when the remote folder has changed. If the metafile or any
   of  the  cache  files  is deleted then Pine will rebuild them the next
   time it runs.

   Remote  address  books  have  names that look just like regular remote
   mail folder names. For example:

     {host.domain}foldername

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

    Information About All Address Books

   The address book is named, by default, .addressbook in the user's Unix
   home  directory,  or  in  the  case  of PC-Pine, ADDRBOOK, in the same
   directory as the PINERC file. There may be more than one address book,
   and the default name can be overridden via an entry in any of the Pine
   configuration  files. The two configuration variables address-book and
   global-address-book  are  used  to  specify  the  names of the address
   books.  Each  of  these variables is a list variable. The total set of
   address  books  for a user is the combination of all the address books
   specified  in  these  two lists. Each entry in the list is an optional
   nickname  followed by an address book name. The nickname is everything
   up  to  the  last  space before the file name. The global-address-book
   list  will  typically  be  configured in the system-wide configuration
   file, though a user may override it like most other variables. Address
   books  which are listed in the global-address-book variable are forced
   read-only, and are typically shared among multiple users.

   Local  address  books  (or local cache files for remote address books)
   are simple text files with lines in the format:

     <nickname>TAB<fullname>TAB<address>TAB<fcc>TAB<comments>

   The  last two fields are optional. A "line" may be made up of multiple
   actual  lines in the file by using continuation lines, which are lines
   beginning  with SPACE characters. The line breaks may be after TABs or
   in  between  addresses in a distribution list. Each actual line in the
   file must be less than 1000 characters in length.

   Nicknames  (the  first  field)  are  short  names  that the user types
   instead  of  typing  in the full address. There are several characters
   which  aren't  allowed  in  nicknames in order to avoid ambiguity when
   parsing  the  address (SPACE, COMMA, @, ", ;, :, (, ), [, ], <, >, \).
   Nicknames aren't required. In fact, none of the fields is required.

   The  fullname  field  is  usually  stored as Last_name, First_name, in
   order that a sort on the fullname field comes out sorted by Last_name.
   If  there  is  an  unquoted  comma in the fullname, Pine will flip the
   first  and  last  name  around and get rid of the comma when using the
   entry  in  a  composition.  It  isn't  required that there be a comma,
   that's  only  useful  if  the  user  wants the entries to sort on last
   names.

   The  address  field  takes  one of two forms, depending on whether the
   entry  is  a  single  (simple)  address  or a distribution list. For a
   simple  entry,  the address field is an RFC 822 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 822 address. The
   phrase  part  of  the address (the fullname) is used unless there is a
   fullname  present  in the fullname field of the address book entry. In
   that  case,  the  fullname  of  the  address  book  entry replaces the
   fullname  of the address. For a distribution list, the <address> is in
   the format:

     "(" <address>, <address>, <address>, ... ")"

   The  only  purpose for the parentheses around the list of addresses is
   to make it easier for the parsing routines to tell that it is a simple
   entry instead of a list. The two are displayed differently and treated
   slightly differently in some cases, though most of the distinction has
   disappeared.  Each  of  the  addresses in a list can be a full RFC 822
   address  with  fullname  included,  or  it  may  be  just  the  simple
   email-address part of the address. This allows the user to have a list
   which  includes  the  fullnames  of  all the list members. In both the
   simple  and  list  cases,  addresses may also be other nicknames which
   appear  in  this  address  book  or in one of the other address books.
   (Those nicknames are searched for by looking through the address books
   in  the  order  they appear in the address book screen, with the first
   match  winning.) Lists may be nested. If addresses refer to each other
   in  a  loop (for example, list A includes list B which includes list A
   again) this is detected and flagged. In that case, the address will be
   changed to "**** address loop ****".

   The  optional  fcc  field is a folder name, just like the fcc field in
   the  composer  headers.  If  the  first  address  in the To field of a
   composition  comes  from an address book entry with an fcc field, then
   that fcc is placed in the fcc header in the composer.

   The  comments  field  is  just  a free text field for storing comments
   about  an entry. By default, neither the fcc nor the comments field is
   shown  on  the  screen  in the address book screen. You may make those
   fields  visible  by configuring the variable addressbook-formats. They
   are also searched when you use the WhereIs command in the address book
   screen and are visible when you View or Update an entry.

   The address book is displayed in the order that it is stored. When the
   user  chooses  a  different  sorting  criterion,  the data is actually
   sorted and stored, as opposed to showing a sorted view of the data.

   When  the  address  book  is  written  out,  it  is first written to a
   temporary  file  and  if  that write is successful it is renamed. This
   guards  against  errors  writing the file that might destroy the whole
   address book. The address book is re-written after each change. If the
   address  book  is  a remote address book, the file is then appended to
   the remote mail folder using IMAP.

   The end-of-line character(s) in the address book file are those native
   to  the system writing it. So it is <LF> on Unix and <CR><LF> on PC's.
   However,  both Unix and PC versions of Pine can read either format, so
   it  should be possible to share a read-only address book among the two
   populations  (using  NFS,  for example). The end-of-line character for
   the LookUp file is always just <LF>, even on a PC.
     _________________________________________________________________

  Address Book Lookup File

   Starting  in  3.90  there is an additional file for each address book,
   called  the  LookUp  file. It usually has the same name as the address
   book  file  with the suffix ".lu" appended. (It might have a different
   name  if  a  file  name length restriction prohibited that name.) This
   file  is  created  and maintained by Pine. If it is deleted, Pine will
   recreate  it next time it runs. Its purpose is to speed up lookups for
   large  address  books  and  to  reduce  memory  requirements for large
   address  books.  A  fairly  detailed  description of how it is used is
   given in src/pine/adrbklib.h.

   The  lookup  file changes whenever the address book itself is changed.
   If  it doesn't exist, Pine attempts to create it. If Pine doesn't have
   permission  to  create the lookup file with the standard name, it will
   create a temporary version in a temp directory. You want to avoid this
   since  it  would  have  to  be  rebuilt  every  time Pine was run, and
   rebuilding  takes  a significant time for a large address book. So, if
   you're  going  to have a shared address book in a read-only directory,
   it  is  highly  desirable  to create the lookup file so that the users
   sharing  it  won't have to each create a copy in a temp directory. You
   can  do  that  by  running Pine and accessing the address book under a
   user  id  which does have permission to write the file or by using the
   -create_lu  command  line  argument  to  Pine. If users may be using a
   shared  address  book  that needs updating, it is best to move the old
   address  book  to  another  name rather than copying over it since the
   file  may  be  opened  by  running  Pines. It is also best to make the
   lookup file for the new addrbook before moving it and the address book
   file   into  place,  otherwise  users  may  get  stuck  attempting  to
   initialize  the  new lookup file. The lookup file contains a timestamp
   which  records the mtime of the address book file when the lookup file
   was  last  updated. Whenever a user runs Pine the current mtime of the
   address  book  is  checked  against this timestamp and if they differ,
   Pine will want to rebuild the lookup file. Because of this, it isn't a
   good  idea to build the lookup file and then copy the address book and
   lookup  file  into  place.  You  should move it or copy it in some way
   which preserves the address book file's mtime (e.g., use mv or tar).

    Validity Checking of Address Books

   There is no file locking done on Pine 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.

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

   Another  sort  of  validity  check  is that the lookup file contains a
   timestamp  internally  that  is  supposed  to  match the time that the
   address  book  file  itself  was  last  modified.  If  the lookup file
   timestamp  doesn't  match  the  date  of  the address book file, a new
   lookup  file  is  built. If you are having trouble, it is always ok to
   remove  the  lookup  file and restart. Pine will automatically rebuild
   the lookup file.

   One  other  validity  check  happens  when  looking up an entry in the
   address  book  file.  An entry is looked up by first getting an offset
   into  the  address  book  file  from  the  lookup file. A seek to that
   location is done and then the entry is read. An entry should be at the
   start  of  a  line. If it isn't, something is wrong. In that case, the
   lookup file is rebuilt and the operation is repeated if possible.
     _________________________________________________________________

Remote Configuration

   Beginning  with  Pine  4.30,  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.

   Remote  configuration  folders are very similar to remote address book
   folders.  They  both  consist  of  a  header  message, which serves to
   identify  the  type  of  folder;  the last message, which contains the
   data;  and  intermediate  messages,  which contain old versions of the
   data. The first message must contain the header x-pine-pinerc.

   When  a  remote  configuration is being used, the folder is checked to
   make sure it is a remote configuration folder, then the data contained
   in  the  last  message  is  copied  to  a temporary file. That file is
   treated just like any regular local configuration file from that point
   on. Whenever a configuration change is made, the entire file is copied
   back  to  the  IMAP  server  and  is  appended  to the folder as a new
   message.

   Because  remote configuration folders are so similar to remote address
   books,  the  configuration  variable  remote-abook-metafile is used by
   both.

   Remote  configuration  folders  have names that look just like regular
   remote mail folder names. For example:

     {host.domain}mypinerc

   Pine  decides  whether or not a configuration file is remote simply by
   looking at the first character of the name and comparing it to '{'.
     _________________________________________________________________

Checkpointing

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

   Good Time:
          This  occurs  when Pine has been idle for more than 30 seconds.
          In  this  case  Pine  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.
   Bad Time:
          This  occurs  just  after  Pine has executed some command. Pine
          will checkpoint if there are 36 outstanding changes to the mail
          file or at least one change and no checkpoint for ten minutes.
   Very Bad Time:
          Done  when  composing  a  message. In this case, Pine 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.
     _________________________________________________________________

Debug Files

   If  Unix  Pine  is  compiled  with  the  compiler DEBUG option on (the
   default),  then Pine will produce debugging output to a file. The file
   is  normally  .pine-debugX  in  the user's home directory where X goes
   from  1  to  4.  Number  1 is always the most recent session and 4 the
   oldest.  Four  are saved because often the user has gone in and out of
   Pine  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 Pine 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.

   PC-Pine  creates  a  single  debug file named PINEDEBG.TXT in the same
   directory as the PINERC file.
     _________________________________________________________________

Filters

   Pine  is not designed to process email messages as they are delivered;
   rather  Pine  depends  on  the fact that some other program (sendmail,
   etc)  will  deliver  messages  and Pine simply reads the email folders
   which  that other program creates. For this reason, Pine cannot filter
   incoming email into different folders. It can, however, work alongside
   most  of  the  programs available over the Internet which perform this
   task.  Pine  is  known  to  operate  successfully  with the Elm filter
   program and with procmail.

   Pine  allows  users  to  specify  a set of incoming-folders. Pine will
   separate  out  all  the  folders  listed as incoming-folders and offer
   convenient  access  to  these. We hope that in the future Pine will be
   able  to offer new message counts for all of the incoming folders, but
   we haven't done this so far because of the performance penalty.
     _________________________________________________________________

Folder Formats and Name Extensions

   A  folder is a group of messages. The default format used by Unix Pine
   is  the  Berkeley  mail  format.  It is also used by the standard mail
   command  and  by  elm.  Unix  Pine also understands message folders in
   other formats, such as Tenex, MH, MMDF, and Netnews.

   PC-Pine  reads  and  writes  local  (PC)  folders  in a special format
   similar  to the Tenex format. Near as we can tell, PC-Pine is the only
   program  to  use  this  format.  Beginning  with version 3.90, PC-Pine
   includes  a  ReadOnly  driver  for  the  Berkeley  mailbox  format  in
   addition.  That  means that you can import Unix mail folders, or mount
   them via NFS or SMB, and PC-Pine can read them --but not modify them.

   Extensions. In the past, file name extensions have been significant in
   both  Unix Pine and PC-Pine, but this has caused more problems than it
   solved.  Therefore, on Unix Pine extensions no longer have any special
   meaning, and this is the trend for PC-Pine as well.

   By  default, PC-Pine adds ".MTX" to the name of any local (PC) folders
   that  are  referenced,  and  suppresses the extension from the "Folder
   List"  display. Now that PC-Pine can read more than one folder format,
   the  MTX  extension  no  longer  implies  a  particular format, and is
   largely  irrelevant.  By  using  the  folder_extension option, you can
   change  this  behavior. In particular, you may set folder-extension to
   the  "null  string"  (a  pair of double quotes) which tells PC-Pine to
   neither add nor hide-from-view any folder name extension.

   The  reason you might wish to over-ride the MTX default is that recent
   versions  of PC-Pine have the ability to open (albeit ReadOnly) normal
   Unix  mail  folders.  Since  it might be inconvenient to rename all of
   them  to  have  an  MTX  extension, it is possible with this option to
   switch  PC-Pine's  behavior  so  that  such  folders  can  be seen and
   accessed  without changing their names. However, doing this means that
   your existing PC-Pine local folders will have apparently changed their
   names.  For example, if you had a local folder named "FOO" it will now
   appear  in  the  "Folder  List"  as  "FOO.MTX".  If  you  wish to save
   additional  messages  to  that folder, you will need to enter the full
   name, "FOO.MTX" at the Save prompt. Likewise for GoTo.

   If  you  wish  to  permanently  avoid  having to deal with folder name
   extensions,  you  will  need  to set this option to the null string by
   entering  two  double-  quote  marks, and you will need to rename your
   existing  local  folders to not have an MTX extension. In DOS this can
   be  done in one command, once you have changed to your mail directory:
   RENAME *.MTX *.

   We  don't  know  why  you  might  wish to, but you could also use this
   option  to  tell  PC-Pine  to use an extension other than MTX. In this
   case,  enter  the three characters you desire to use in lieu of "MTX".
   Note  that your existing folders will need to be renamed to correspond
   to this new extension.

   Berkeley Mail Format
          This  format  comes  to  us from the ancient UNIX mail program,
          /bin/mail.  (Note  that  this  doesn't have anything to do with
          Berkeley, but we call it the Berkeley mail file format anyway.)
          This  program  was  actually used to interactively read mail at
          one  time,  and  is  still  used  on  many systems as the local
          delivery  agent.  In  the  Berkeley  mail format, a folder is a
          simple text file. Each message (including the first) must start
          with a separator line which takes approximately the form:

     From juser@u.example.edu Wed Aug 11 14:32:33 1993
          Each  message  ends  with  two  blank lines. There are actually
          several  different  variations  in the date part of the string,
          twenty  at last count. Because of the format of the separators,
          lines  in  the  mail  message  beginning  with  "From  ", space
          included,  risk being confused as message separator lines. Some
          mail programs will interpret any line beginning with "From " as
          a  message  separator, while others --including Pine-- will not
          be  confused  unless  the  line  really  looks  like  a message
          separator,  complete  with address and date. Such lines will be
          modified  to  begin  with  ">From ". In deference to other mail
          programs,  you  may  also set the save-will-quote-leading-froms
          feature,  in which case any line beginning with "From " will be
          modified  as  above.  If  you see this occasionally in incoming
          mail messages, the culprit is not Pine but the message delivery
          program being used at your site.
          You  can  fool  Pine  into  thinking a file is a mail folder by
          copying  a suitable message separator from a real folder to the
          beginning of the file and wherever you want message boundaries.
          The  vast  majority of INBOXes Pine reads and folders it writes
          are of this format.
   Tenex and MTX Formats
          Like the Berkeley format, the Tenex folder format uses a single
          file per folder. Historically, the name of Tenex-format folders
          ended  with .txt, but this rule is no longer enforced. The file
          format  consists  of a header line followed by the message text
          for each message. The header is in one of two forms:

     dd-mmm-yy hh:mm:ss-zzz,n;ffffffffffff
     dd-mmm-yyyy hh:mm:ss sssss,n;ffffffffffff
          and  is  immediately  followed  by  a  newline (and the message
          text). The fields in the formats are:

        dd      two-digit day of month (leading space if a single-digit day)

        mmm     three-letter English month name (Jan, Feb, etc.)

        yy      two-digit year in 20th century (obsolete)

        yyyy    four-digit year

        hh      two-digit hour in 24-hour clock (leading zero if single-digit)

        mm      two-digit minute (leading zero)

        ss      two-digit second (leading zero)

        zzz     three-letter North American time zone (obsolete)

        sssss   signed four-digit international time zone as in RFC 822

        n       one or more digits of the size of the following message in

                bytes

        ffffffffffff

                twelve-digit octal flags value

          Punctuation is as given above.
          The  time in the header is the time that message was written to
          the  folder.  The  flags  are  interpreted as follows: the high
          order  30  bits  are  used to indicate user flags, the next two
          bits  are reserved for future usage, the low four bits are used
          for  system  flags  (010  = answered, 04 = flagged urgent, 02 =
          deleted, 01 = seen).
          If  a  Tenex-format  (or empty) file named mail.txt exists in a
          Pine user's home directory, this triggers special processing in
          Pine.  When  INBOX  is opened, mail is automatically moved from
          /var/spool/mail into mail.txt in the user's home directory.
          The  format  used  by PC-Pine is identical to the Tenex format,
          with  two exceptions: the folder name ends with .MTX instead of
          .txt  (this  is a requirement in the MTX format), and DOS-style
          CR/LF newlines are used instead of UNIX-style LF newlines.
   Netnews Format
          The  netnews format is a ReadOnly format which uses directories
          under  /var/spool/news  as folders. The /var/spool/news/ prefix
          is  removed  and  all  subsequent  ``/'' (slash) characters are
          changed to ``.'' (period). For example, the netnews folder name
          comp.mail.misc     refers     to     the     directory     name
          /var/spool/news/comp/mail/misc.  In  addition,  the news folder
          name  must appear in the file /var/lib/news/active for it to be
          recognized.  Individual  messages  are  stored as files in that
          directory,  with  file  names  being the ASCII form of a number
          assigned  to  that  message. The default locations above can be
          changed  with  the  config  variables  news-spool-directory and
          news-active-file-path.
     _________________________________________________________________

Folder Locking

   There  are  two  kinds  of  locking which Pine has to worry about. The
   first  might  be  called  program-contention locking. This affects the
   times  when  a  program  is  performing actual updates on a folder. An
   update  might  be  a  message  delivery  program  appending  a message
   (sendmail   delivering   a   message  to  an  INBOX),  status  changes
   (checkpoints  by  Pine  every few minutes) or deletion of messages (an
   expunge  in  Pine). For moderate sized mail messages, these operations
   should  not  last  for  more  than  a  few seconds. The second kind of
   locking  has  to do with user-contention situations. This would be the
   case  when  one folder is shared by a group of people or even when one
   person  starts  multiple  email  sessions all of which access the same
   folders and INBOX.

   There    are    two   standard   locking   mechanisms   which   handle
   program-contention  locking.  To  be on the safe side, Pine implements
   both  of them. The older mechanism places a file xxxx.lock (where xxxx
   is  the  name  of  the file being locked) in the same directory as the
   file  being  locked.  This  makes  use  of  the  fact  that  directory
   operations  are  atomic in UNIX and mostly works across NFS. There are
   involved  algorithms  used to determine if a lock has been held for an
   excessive   amount   of   time   and  should  be  broken.  The  second
   program-contention  locking  mechanism uses the flock() system call on
   the mailbox. This is much more efficient and the locks can't get stuck
   because  they go away when the process that created them dies. This is
   usually found on 4BSD and related machines.

   In  addition  to  these,  Pine--through the c-client library--provides
   robust  locking  which prevents several users (or several instances of
   the  same  user)  having  a  mail file open (for update) at once. This
   user-contention  lock  is  held  the entire time that the folder is in
   use.

   With  IMAPd  7.3(63) and Pine 3.84 and higher, the second Pine session
   which  attempts  to open a particular folder (usually INBOX) with Pine
   will  ``win''. That is to say, the second session will have read/write
   access  to  the folder. The first user's folder will become read-only.
   (Note  that this is exactly the opposite of the behavior prior to Pine
   3.84  where  the  second open was read-only. Having the latest open be
   read-write  seems  to match more closely with what users would like to
   have  happen  in  this  situation.)  Pine's additional locking is only
   effective  against  multiple  uses of Pine or other programs using the
   c-client  library,  such  as  MailManager, ms, IMAPd and a few others.
   Beginning  with  Pine  3.85,  there  is  a  -o  command  line  flag to
   intentionally open a mailbox read-only.

   Pine  locking  on UNIX systems works by creating lock files in /tmp of
   the  form \usr\spool\mail\joe. The system call flock() is then used on
   these  files;  the  existence  of the file alone does not constitute a
   lock.  This  lock  is  created when the folder is opened and destroyed
   when  it  is  closed.  When  the folder is actually being written, the
   standard UNIX locks are also created.

   If  a folder is modified by some other program while Pine has it open,
   Pine  will  give  up on that mail file, concluding it's best not to do
   any  further  reads  or writes. This can happen if another mailer that
   doesn't observe Pine's user-contention locks (e.g. elm or mail) is run
   while  Pine has the mail folder open. Pine checkpoints files every few
   minutes, so little data can be lost in these situations.

   PC-Pine  does not do any folder locking. It depends on IMAP servers to
   handle  locking  of  remote  folders. It is assumed that only one Pine
   session  can be running on the PC at a time, so there is no contention
   issue around folders on the PC itself.
     _________________________________________________________________

INBOX and Special Folders

   The  INBOX  folder  is  treated  specially.  It  is normally kept open
   constantly  so  that the arrival of new mail can be detected. The name
   INBOX  refers  to wherever new mail is retrieved on the system. If the
   inbox-path  variable  is  set, then INBOX refers to that. IMAP servers
   understand   the   concept   of   INBOX,   so  specifying  the  folder
   {imap.u.example.edu}INBOX is meaningful. The case of the word INBOX is
   not important, but Pine tends to display it in all capital letters.

   The folders for sent mail and saved messages folders are also somewhat
   special.  They  are  automatically  created  if  they  are  absent and
   recreated if they are deleted.
     _________________________________________________________________

Internal Help Files

   The  file  pine.hlp  in  the  pine  subdirectory  of  the distribution
   contains  all  the  help  text for Pine. On UNIX, it is compiled right
   into the Pine binary as strings. This is done to simplify installation
   and  configuration.  The  pine.hlp file is in a special format that is
   documented  at the beginning of the file. It is divided into sections,
   each  with a name that winds up being referenced as a global variable.
   This file is processed by two awk scripts and turned into C files that
   are compiled into Pine.

   PC-Pine,  which  tries  to  run  on machines with as little as 640k of
   memory,  leaves  the  Pine  help text out of the executable. PINE.EXE,
   PINE.HLP, and PINE.NDX are all needed for PC-Pine's help system.
     _________________________________________________________________

International Character Sets

   While   Pine   was   designed   in   the  U.S.  and  used  mostly  for
   English-language correspondence, it is a goal for Pine to handle email
   in  almost  any  language.  Many sites outside of the U.S. run Pine in
   their native language. The default character set for Pine is US-ASCII.
   That  can be changed in the personal or system-wide configuration file
   with the variable character-set.

   When  reading  incoming  email, Pine allows all character sets to pass
   through.  Pine  doesn't  actually  display  the  characters but simply
   passes them through; it is up to the actual display device to show the
   characters  correctly. When composing email, Pine will accept input in
   any  language  and  tag  the  message  according  to the character-set
   variable.  Again, it is up to the input device to generate the correct
   sequences for the character set being used.

   With  the  exception  of  UNICODE-1-1-UTF-7,  the  outgoing message is
   checked  to  see  if  it  is all US-ASCII text (and contains no escape
   characters).  In  that case, the text will be labeled as US-ASCII even
   if  the character-set variable is set to something else. The theory is
   that  every  reasonable  character set will have US-ASCII as a subset,
   and   that   it   makes   sense   to   label   the   text   with   the
   lowest-common-denominator  label  so that more mailers will be able to
   display  it.  Text  in  the  UNICODE-1-1-UTF-7  character set is never
   re-labeled  as  US-ASCII.  If the outgoing message is not all US-ASCII
   text,  then  it will be labeled with the character-set variable set by
   the  user.  If the user has not set the character-set variable then it
   will be labeled as X-UNKNOWN.

   BUG:  If  you  prepare  a  UNICODE-1-1  document  and read it into the
   composer  with  ^R,  Pine  may  mistreat  it.  If  your document, when
   misviewed  as  8-bit  bytes,  does  not  contain  any individual bytes
   greater  than  0x7f  base  16,  then  Pine will re-label your outgoing
   message  as  US-ASCII,  even  if  your  message  is  really in Unicode
   Cyrillic,  Arabic,  or  Thai.  On the other hand, if your UNICODE-1-1,
   when  misviewed  as  8-bit bytes, does contain at least one individual
   byte   greater   than   0x7f   base  16,  as  is  likely  for  Unicode
   French/German/Spanish,  Greek,  Japanese,  and Chinese, then Pine will
   retain the UNICODE-1-1 label.

   The character sets are:

     US-ASCII Standard 7 bit English characters
     ISO-8859-1 8 bit European "latin 1" character set
     ISO-8859-2 8 bit European "latin 2" character set
     ISO-8859-3 8 bit European "latin 3" character set
     ISO-8859-4 8 bit European "latin 4" character set
     ISO-8859-5 8 bit Latin and Cyrillic
     ISO-8859-6 8 bit Latin and Arabic
     ISO-8859-7 8 bit Latin and Greek
     ISO-8859-8 8 bit Latin and Hebrew
     ISO-8859-9 8 bit European "latin 5" character set
     ISO-8859-10 8 bit European "latin 6" character set
     KOI8-R 8 bit Latin and Russian
     VISCII 8 bit Latin and Vietnamese
     ISO-2022-JP Latin and Japanese
     ISO-2022-KR Latin and Korean
     UNICODE-1-1 Unicode
     UNICODE-1-1-UTF-7 Mail-safe Unicode
     ISO-2022-JP-2 Multilingual

   Earlier versions of Pine made use of the character set tags associated
   with  text  in  MIME to decide if the text should be displayed or not.
   Depending  on  the character set tag and the character-set variable in
   Pine,  the  text  was  either  displayed  as  is,  displayed with some
   characters  filtered out, or not displayed at all. The current version
   uses  a  much  simpler  algorithm in order to maximize the chance that
   useful  contents  are  readable  by  the  user. It simply displays all
   messages  of  type  text and makes no attempt to filter out characters
   that  may  be  in  the  wrong  character set. If the text is tagged as
   something other than US-ASCII and the tag does not match the character
   set that the character-set variable is set to, then an attempt is made
   to convert the incoming characters into the character set given in the
   character-set  variable. Characters which are not representable in the
   character  set of the display will be converted to question marks. The
   feature  disable-charset-conversions  may  be  used  to  turn off this
   automatic conversion. A warning is printed at the start of the message
   and  the  characters  are sent to the display. It is possible that the
   text will be displayed incorrectly.

   There  is  special-case  code  which  attempts to handle Japanese text
   (ISO-2022-JP).  Incoming  ISO-2022-JP text will be converted to EUC in
   UNIX  Pine  and  to  Shift-JIS  in  PC-Pine  before  it is sent to the
   display. Conversely, when sending mail UNIX Pine will convert EUC into
   ISO-2022-JP  and  PC-Pine will convert Shift-JIS into ISO-2022-JP. The
   feature  disable-2022-jp-conversions  may  be  used  to  turn off this
   automatic conversion.

   There used to be a facility in PC-Pine to map between various DOS Code
   Pages  and  standard  character  sets.  That  facility,  including the
   CP_TO_ISO and ISO_TO_CP hooks, was broken for several versions of Pine
   and is now entirely removed. We hope that the character set conversion
   that  happens  automatically  before  displaying a message will handle
   most  of  what  the  Code Page code used to do. For example, a Russian
   user  would probably set the character-set variable in the PINERC file
   to  the value KOI8-R. That would cause outgoing messages to be labeled
   as  KOI8-R.  If  an incoming message was labeled with the Windows-1251
   character  set,  Pine  should  be  able  to  convert  the Windows-1251
   characters to KOI8-R before sending them to the display.
     _________________________________________________________________

Interrupted and Postponed Messages

   If the user is composing mail and is interrupted by being disconnected
   (SIGHUP, SIGTERM or end of file on the standard input), Pine will save
   the  interrupted composition and allow the user to continue it when he
   or  she  resumes Pine. As the next Pine 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 ^C.

   Composition  of half-done messages may be postponed to a later time by
   giving  the ^O command. Other messages can be composed while postponed
   messages  wait.  All  of  the  postponed messages are kept in a single
   folder.  Postponing  is a good way to quickly reference other messages
   while composing.
     _________________________________________________________________

Message Status

   The  c-client  library  allows for several flags or status marks to be
   set  for each message. Pine uses four of these flags: UNSEEN, DELETED,
   ANSWERED,  and  FLAGGED.  The  N  in  Pine's FOLDER INDEX means that a
   message  is  unseen-it  has  not been read from this folder yet. The D
   means  that  a  message is marked for deletion. Messages marked with D
   are  removed  when the user Expunges the folder (which usually happens
   when  the  folder  is  closed or the user quits Pine). The A in Pine's
   FOLDER  INDEX  means  that  the  message has been replied-to. The * in
   Pine's  FOLDER  INDEX  means  that the message has been ``flagged'' as
   important. That is, the user used the Flag command to turn the FLAGGED
   flag  on. This flag can mean whatever the user wants it to mean. It is
   just  a  way  to mark some messages as being different from others. It
   will  usually  probably  be  used  to  mark a message as somehow being
   ``important''.  For  Berkeley  format  folders,  the message status is
   written  into  the  email  folder  itself  on  the header lines marked
   Status:  and  X-Status. In Tenex and PC-Pine's MTX folder formats, the
   status goes into the 36-bit octal flags.
     _________________________________________________________________

MIME: Reading a Message

   Pine should be able to handle just about any MIME message. When a MIME
   message  is received, Pine 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 Save all other attachments.

   Starting  with  version  3.90, Pine 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 Pine distribution. It
   includes  comments  which  explain  the  syntax  you  need  to use for
   mailcap.   With   the   mailcap   file,  any  program  (mail  readers,
   newsreaders,  WWW clients) can use the same configuration for handling
   MIME-encoded data.

   If  a  MAILCAPSenvironment  variable is defined, Pine will use that to
   look for one or more mailcap files, which are combined. In the absence
   of  MAILCAPS,  Unix  Pine  will  look  for  a personal mailcap file in
   ~/.mailcap  and  combine that with a system-wide file in /etc/mailcap.
   PC-Pine  will  look  for a file named MAILCAP in the same directory as
   the   PINERC  file,  and/or  the  directory  containing  the  PINE.EXE
   executable.

   Messages  which  include  rich  text or enriched text in the main body
   will  be  displayed  in  a  very  limited  way  (it will show bold and
   underlining).

   If  Pine  sees  a  MIME  message part tagged as type IMAGE, and Pine's
   image-viewer  configuration variable is set, Pine will attempt to send
   that  attachment  to  the  named image viewing program. In the case of
   UNIX  Pine,  the  DISPLAY environment variable is checked to see if an
   X-terminal  is  being  used  (which  can  handle  the  images). If the
   image-viewer  variable  is  not  set,  Pine uses the mailcap system to
   determine  what  to do with IMAGE types, just as it does for any other
   non-TEXT  type,  e.g. type APPLICATION. For MIME's generic "catch all"
   type,  APPLICATION/OCTET-STREAM,  the  mailcap  file will probably not
   specify any action, but Pine users may always Save any MIME attachment
   to a file.

   MIME  type  "text/plain"  is handled a little bit differently than the
   other types. If you are viewing the main body part in the MESSAGE TEXT
   viewing  screen, then Pine will use its internal viewer to display it.
   This happens even if there is a mailcap description which matches this
   particular type. If it is labeled as having a character set other than
   the  one  you  are  using,  it will still be displayed by the internal
   viewer  (perhaps  incorrectly),  though you will get a warning message
   prepended to the message in the viewing screen. However, if you view a
   part  of type "text/plain" from the ATTACHMENT INDEX screen, then Pine
   will  check  the  mailcap  database for a matching entry and use it in
   preference to its internal viewer.

   Some  text  attachments, specifically those which are just other email
   messages forwarded as MIME messages, are displayed as part of the main
   body  of  the  message.  This  distinction  allows  easy  display when
   possible  (the  forward  as MIME case) and use of an attachment viewer
   when that is desirable (the plain text file attachment case).

   If the parts of a multipart message are alternate versions of the same
   thing  Pine  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 currently supported.
     _________________________________________________________________

MIME: Sending a Message

   There  are  two important factors when trying to include an attachment
   in  a message: encoding and labeling. Pine 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.

   MIME  has  two  ways  of  encoding  data-Quoted-Printable  and Base64.
   Quoted-Printable  leaves  the  ASCII text alone and only changes 8-bit
   characters  to "=" followed by the hex digits. For example, "=09" is a
   tab.  It  has  the  advantage  that  it is mostly readable and that it
   allows  for  end  of  line  conversions between unlike systems. Base64
   encoding  is  similar  to  uuencode or btoa and just encodes a raw bit
   stream. This encoding is designed to get text and binary files through
   even  the  most improperly implemented and configured gateways intact,
   even those that distort uuencoded data.

   All attachments are encoded using Base64 encoding. This is so that the
   attachment  will  arrive  at the other end looking exactly like it did
   when  it  was  sent.  Since  Base64 is completely unreadable except by
   MIME-capable  mailers  or programs, there is an obvious tradeoff being
   made  here.  We  chose  to  ensure  absolutely  reliable  transport of
   attachments  at  the  cost  of requiring a MIME-capable mailer to read
   them. If the user doesn't want absolute integrity he or she may always
   include text (with the ^R command) in the body of a message instead of
   attaching  it.  With  this  policy,  the  only  time  quoted-printable
   encoding  is  used is when the main body of a message includes special
   foreign language characters.

   When an attachment is to be sent, Pine 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. Pine will
   recognize  (and  correctly  label)  a few special types including GIF,
   JPEG,  PostScript, and some audio formats. Another method which can be
   more  robust and flexible for determining the content-type and subtype
   is  to  base  it  on the file extension. This method uses a MIME.Types
   File.

   If  it  is  not  binary  data  (has  only  a small proportion of 8-bit
   characters in it,) the attachment is considered 8-bit text. 8-bit text
   attachments  are labeled "text/plain" with charset set to the value of
   the user's character-set variable. If an attachment is ASCII (no 8-bit
   characters)  and  contains  no  ESCAPE,  ^N,  or  ^O  characters  (the
   characters  used  by  some  international  character sets), 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 character-set variable.

   All other attachments are unrecognized and therefore given the generic
   MIME label "application/octet-stream".
     _________________________________________________________________

New Mail Notification

   Pine checks for new mail in the INBOX and in the currently open folder
   every  two  and  a  half  minutes by default. It used to be 30 seconds
   instead  of  150  seconds,  but we increased it in order to reduce the
   load  on  large  systems  with  lots  of  Pine users. The value can be
   changed  at  compile-time  in  the  pine/os.h  file. This value can be
   changed with the variable mail-check-interval. A new mail check can be
   forced by redrawing the screen with a ^L.

   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  Pine,  the  notice  will show the count of new
   messages and the sender of the most recent one.

   Questions  have arisen about the interaction between Pine and external
   mail   notification   routines   (biff,   csh,   login).  Firstly  and
   unfortunately,  we  have found no PC based program that will check for
   email  on an IMAP server when PC-Pine is not running. If you find one,
   please tell us.

   The  UNIX  case  is  more  complicated. Pine sets the modification and
   access time on a file every time it performs a write operation (status
   change  or  expunge).  You  need  to  see  which  of  these your email
   notification  program  is  looking  at to know how it will behave with
   Pine.
     _________________________________________________________________

NFS

   It  is  possible  to  access  mail folders on NFS mounted volumes with
   Pine,  but  there  are some drawbacks to doing this, especially in the
   case  of  incoming-message folders that may be concurrently updated by
   Pine  and the system's mail delivery agent. One concern is that Pine's
   user-contention  locks  don't work because /tmp is usually not shared,
   and even if it was, flock() doesn't work across NFS.

   The  implementation of the standard UNIX ".lock" file locking has been
   modified  to  work with NFS as follows. Standard hitching post locking
   is  used  so first a uniquely named file is created, usually something
   like  xxxx.host.time.pid. Then a link to it is created named xxxx.lock
   where the folder being locked is xxxx. This file constitutes the lock.
   This  is  a  standard  UNIX  locking scheme. After the link returns, a
   stat(2)  is  done  on  the  file.  If  the  file  has two links, it is
   concluded that the lock succeeded and it is safe to proceed.

   In  order  to  minimize  the  risks  of  locking  failures via NFS, we
   strongly  recommend  using  IMAP  rather  than  NFS  to  access remote
   incoming  message  folders,  e.g. your INBOX. However, it is generally
   safe  to  access  personal  saved-message  folders via NFS since it is
   unlikely  that more than one process will be updating those folders at
   any  given time. Still, some problems may occur when two Pine sessions
   try  to access the same mail folder from different hosts without using
   IMAP.  Imagine  the scenario: Pine-A performs a write that changes the
   folder.  Pine-B  then  attempts to perform a write on the same folder.
   Pine-B  will  get upset that the file has been changed from underneath
   it and abort operations on the folder. Pine-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  Pine-B  session when this happens is the last few status
   changes.

   If  other  mail  readers  besides Pine are involved, all bets are off.
   Typically, mailers don't take any precautions against a user opening a
   mailbox more than once and no special precautions are taken to prevent
   NFS problems.
     _________________________________________________________________

Printers and Printing

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

   The  first setting, attached-to-ansi, makes use of escape sequences on
   ANSI/VT100 terminals. It uses "<ESC>[5i" to begin directing all output
   sent  to  the terminal to the printer and then "<ESC>[4i" to return to
   normal. Pine will send these escape sequences if the printer is set to
   attached-to-ansi.  This  works  with most ANSI/VT100 emulators on Macs
   and  PCs  such  as  kermit,  NCSA  telnet,  VersaTerm Pro, and WinQVT.
   Various  terminal  emulators  implement the print feature differently.
   For  example,  NCSA  telnet requires "capfile = PRN" in the config.tel
   file.  Attached-to-ansi  printing  doesn't work at all with the telnet
   provided  with  PC-NFS.  There is also a closely related method called
   attached-to-ansi-no-formfeed  which is the same except for the lack of
   formfeed character at the end of the print job.

   Attached-to-wyse  and attached-to-wyse-no-formfeed are very similar to
   "attached-to-ansi".  The  only difference is in the control characters
   sent  to turn the printer on and off. The Wyse version uses Ctrl-R for
   on, and Ctrl-T for off.

   The  second  selection is the standard UNIX print command. The default
   is lpr, but it can be changed on a system basis to anything so desired
   in /etc/pine.conf.

   The  third  selection  is  the user's personal choice for a UNIX print
   command. The text to be printed is piped into the command. Enscript or
   lpr  with  options are popular choices. The actual command is retained
   even if one of the other print selections is used for a while.

   Both  the  second  and  third  sections are actually lists of possible
   commands rather than single commands.

   If  you  have a PostScript printer attached to a PC or Macintosh, then
   you will need to use a utility called ansiprt to get printouts on your
   printer. Ansiprt source code and details can be found in the ./contrib
   directory of the Pine distribution.

   The  three  printer  choices  are for UNIX Pine only. PC-Pine can only
   print to the locally attached printer. All printing on PC-Pine is done
   via  ROM  BIOS Print Services (Int 17h). After verifying the existence
   of  a  local printer via the BIOS Equipment-List Service (Int 11h), it
   simply  sends  the  message text, character by character, to the first
   printer  found  using ASCII CR and LF at the end of lines and followed
   by  an  ASCII  FF. Note, some system adjustments using the PC's "MODE"
   command  may  be  required if the printer is not on the first parallel
   port.  PC-Pine  cannot generate PostScript, so printing to exclusively
   PostScript printers does not work.

   PC-Pine  for  Winsock  uses  the  MS-Windows printer interface. A Pine
   print command will bring up a standard MS-Windows printer dialog box.
     _________________________________________________________________

Save and Export

   Pine  users  get  two  options  for  moving messages in Pine: Save and
   Export.  Save  is  used  when  the message should remain ``in the Pine
   realm.''  Saved messages include the complete header (including header
   lines normally hidden by Pine), are placed in a Pine folder collection
   and  accumulate  in  a  standard folder format which Pine can read. In
   contrast,  the  Export  command  is  used  to  write the contents of a
   message  to  a  file for use outside of Pine. Messages which have been
   exported  are  placed in the user's home directory (unless the feature
   use-current-dir is turned on), not in a Pine folder collection. Unless
   FullHeaderMode  is  toggled  on,  all  delivery-oriented  headers  are
   stripped  from  the  message.  Even  with Export, Pine retains message
   separators  so  that multiple messages can accumulate in a single file
   and  subsequently be accessed as a folder. On UNIX systems, the Export
   command  pays  attention  to the standard umask for the setting of the
   file permissions.
     _________________________________________________________________

Sent Mail

   Pine'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  default-fcc="".  The  sent mail
   folder  is assumed to be in the default collection for Saves, which is
   the  first  collection  named  in  folder-collections. The name of the
   folder  can be chosen by entering a name in default-fcc. With PC-Pine,
   this  can be a bit complicated. If the default collection for Saves is
   local  (DOS),  then  the  default-fcc  needs  to be SENTMAIL, which is
   syntax for a DOS file. However, if the default collection for Saves is
   remote,  then  the default-fcc needs to be sent-mail to match the UNIX
   syntax.

   The   configuration  variable  fcc-name-rule  also  plays  a  role  in
   selecting the folder to save sent mail in.

   A danger here is that the sent mail could grow without bound. For this
   reason,  we  thought  it useful to encourage the users to periodically
   prune  their  sent mail folder. The first time Pine is used each month
   it will offer to archive all messages sent from the month before. Pine
   also offers to delete all the sent mail archive folders which are more
   than  1  month  old.  If  the  user  or  system has disabled sent mail
   archiving (by setting the configuration variable default-fcc="") there
   will be no pruning question.
     _________________________________________________________________

Spell Checker

   Spell  checking  is available for UNIX Pine only. We could not find an
   appropriate  PC  based  spell  checker to hook into PC-Pine. Even UNIX
   Pine  depends  on  the  system  for its spell checking and dictionary.
   Pico, the text editor, uses the same spell checking scheme as Pine.

   Lines  beginning  with  ">" (usually messages included in replies) are
   not  checked.  The message text to be checked is on the standard input
   and the incorrect words are expected on the standard output.

   The  default  spell  checker  is  UNIX  spell. You can replace this by
   setting  the  speller  configuration  variable. Pine also respects the
   environment  variable SPELL. The spelling checker reads its words from
   a   standard  dictionary  on  the  system.  Below  is  a  description,
   contributed  by  Bob  Hurt,  of  how  you can create your own personal
   dictionary with additional ``correct'' words.

   Step 1:
          Make  a file with all the words you want to include in your new
          dictionary.  I  did mine with one word per line in alphabetical
          order. Caps don't matter at all, as far as I know.
   Step 2:
          At   the   UNIX   prompt,  type  "cat  [word  file]  |  spellin
          /usr/dict/hlista  >  [new  dict name]" where [word file] is the
          file  you  just  created and [new dict name] is the name of the
          new  dictionary  that Pine will look at instead of the standard
          /usr/dict/hlista.  I  named  my  word  file  .bobwords  and  my
          dictionary .bobspell so I don't have to see them when I do a ls
          command  (ls  doesn't  list  "dot" files). I also put the above
          command  into  my  .alias file as the command makedict so I can
          add  a  word to my word file and easily recreate my dictionary.
          NOTE:  the  new  dictionary  is  in something called a "hashed"
          format, and can't be read normally.
   Step 3:
          Check  your new dictionary. At the UNIX prompt, type "cat [word
          file]  |  spellout  [new  dict  name]"  If  you  did everything
          correctly,  it should just give you another prompt. If it lists
          any of the words in your file, something is wrong. I can try to
          help if all else fails.
   Step 4:
          Now you have to tell UNIX to use your dictionary instead of the
          standard  one  by  setting  the  environment  variable SPELL to
          access  your  dictionary. Go into your .login or .cshrc file in
          your home directory (it doesn't seem to make a difference which
          one you use) and add the line

     setenv SPELL "spell -d [new dict name]"
          I  also  created  an alias for SPELL in my .alias file so I can
          use  the  UNIX  spell  command to spell-check a file outside of
          Pine.  (The  .alias  line  is:  alias spell 'spell -d [new dict
          name]')
   Step 5:
          Now you need to logoff and log back on to let UNIX look at your
          .login (or .cshrc) file.

   Here is an alternative method suggested by Zachary Leber:

          Create a list (e.g. .zachwords) with the upper case followed by
          lower case words, sorted alphabetically.
          Add this line to .cshrc:

     setenv SPELL 'spell +/home/ie/rsa/.zachwords'
          The  limitation  here  is  that the path must be absolute (e.g.
          +~/.zachwords doesn't work).
          My man pages for spell show this + flag to be an easy way to do
          the exception list. This way you don't have to bother with hash
          lists  or  rehashing,  and  it  seems  to  work  across several
          platforms.
     _________________________________________________________________

Terminal Emulation and Key Mapping

   Pine  has  been  designed  to  require  as little as possible from the
   terminal.  At  the minimum, Pine 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.  Pine 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. Pine 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.

   Pine  handles  screens  of  most  any size and resizing on the fly. It
   catches  SIGWINCH  and  does  the appropriate thing. A screen one line
   high  will  display  only  the new mail notification. Screens that are
   less  than ten columns wide don't format very nicely or work well, but
   will function fine again once resized to something large. Pine sets an
   internal  maximum  screen  size (currently 170x200) and decides to use
   either termcap or terminfo when it is compiled.

   On  the input side of things, Pine uses all the standard keys, most of
   the  control  keys  and (in function-key mode) the function keys. Pine
   avoids  certain  control keys, specifically ^S, ^Q, ^H, and ^\ because
   they  have  other  meanings  outside  of Pine (they control data flow,
   etc.)  ^H  is  treated the same as the delete key, so the backspace or
   delete  keys  always works regardless of any configuration. There is a
   feature  compose-maps-delete-key-to-ctrl-d  which makes the delete key
   behave  like  ^D  rather than ^H (deletes current character instead of
   previous character).

   Sometimes a communications program or communications server in between
   you  and the other end will eat certain control characters. There is a
   work-around  when  you  need  it.  If  you  type two escape characters
   followed by a character that will be interpreted as the character with
   the control key depressed. For example, ESC ESC T is equivalent to ^T.

   When  a  function  key is pressed and Pine is in regular (non-function
   key) mode, Pine 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.
   Pine  expects the following escape sequences from terminals defined as
   VT100:

     ANSI/VT100
     F1: <ESC>OP
     F2: <ESC>OQ
     F3: <ESC>OR
     F4: <ESC>OS
     F5: <ESC>Op
     F6: <ESC>Oq
     F7: <ESC>Or
     F8: <ESC>Os
     F9: <ESC>Ot
     F10: <ESC>Ou
     F11: <ESC>Ov

   Arrow  keys  are  a  special case. Pine has the escape sequences for a
   number  of  conventions  for  arrow  keys  hard coded and does not use
   termcap  to  discover  them.  This  is  because  termcap  is sometimes
   incorrect, and because many users have PC's running terminal emulators
   that  don't  conform  exactly  to  what they claim to emulate. In some
   versions  of  Pine  before  4.00 there was a compile-time macro called
   TERMCAP_WINS  which  could  be  set  to  cause the termcap or terminfo
   definitions  to be used instead of the built in definitions. Beginning
   with  4.00 there is a hidden runtime feature which can be turned on to
   accomplish     the    same    thing.    The    feature    is    called
   termdef-takes-precedence  and  it  can  be  set  in  any  of  the Pine
   configuration  files.  Some  arrow  keys  on old terminals send single
   control  characters like ^K (one even sends ^\). These arrow keys will
   not  work  with Pine. The most popular escape sequences for arrow keys
   are:

     Up: <ESC>[A <ESC>?x <ESC>A <ESC>OA
     Down: <ESC>[B <ESC>?r <ESC>B <ESC>OB
     Right: <ESC>[C <ESC>?v <ESC>C <ESC>OC
     Left: <ESC>[D <ESC>?t <ESC>D <ESC>OD

   It  is  possible  to  configure  an NCD X-terminal so that some of the
   special keys operate. Brad Greer contributes these instructions:

   1.
          In  your .Xdefaults file, include the following "translations",
          using lower hex values:

     Pine*VT100.Translations: #override \n\
     <Key>Delete: string(0x04) \n\
     <Key>End: string(0x05) \n\
     <Key>Escape: string(0x03) \n\
     <Key>Home: string(0x01) \n\
     <Key>Next: string(0x16) \n\
     <Key>Prior: string(0x19) \n\
     <Key>KP_Enter: string(0x18) \n\
   2.
          Start  up  Pine  from  an xterm, and specify a "resource name".
          This resource name will allow the user to specify resources for
          Pine (that deviate from the defaults). For example, xterm -name
          Pine  -e  pine  &  (the  resource  name Pine corresponds to the
          translations just added in the .Xdefaults file).
