






                    Pine Technical Notes
9                 Version 3.91, October 1994



9













































9

9










          Pine and Pico are trademarks of the University  of
          Washington

          Copyright 1989-1994  University of Washington

          PC-Pine and  UNIX  Pine  are  still  under  active
          development.  Pine 3.90, released August 1994, was
          a major release with many new features.  Pine 3.91
          is a maintenance release that corrects a number of
          bugs reported after the  3.90  release.   However,
          there are also two new features:

            preserve-start-stop-characters
            compose-rejects-unqualified-addrs

          The first one was needed to cause Pine  to  revert
          to  its  pre-3.90  behavior  for  sites  that  use
          software flow-control (usually via  XON  and  XOFF
          characters).   Version  3.90 was changed to ignore
          those characters so that a  mis-typed  "control-S"
          or XOFF character would not cause Pine to mysteri-
          ously and silently freeze, but this change  caused
          problems  for  sites  using software flow-control.
          The second  new  feature  was  needed  locally  to
          reduce  the  probability  of mis-typed addressbook
          nicknames resulting in mid-directed email.

          Other than the above, and  a  few  clarifications,
          these  Tech  Notes are essentially the same as the
          version 3.90 Tech Notes.

          Permission to use, copy,  modify,  and  distribute
          this  software  and its documentation for any pur-
          pose and without fee to the University of Washing-
          ton  is  hereby  granted,  provided that the above
          copyright notice appears in all  copies  and  that
          both  the  above copyright notice and this permis-
          sion notice appear  in  supporting  documentation,
          and  that the name of the University of Washington
          not be used in advertising or publicity pertaining
          to  distribution of the software without specific,
          written prior permission.  This software  is  made
          available as is.

          THE UNIVERSITY OF WASHINGTON DISCLAIMS ALL WARRAN-
          TIES,  EXPRESS  OR  IMPLIED,  WITH  REGARD TO THIS
          SOFTWARE, INCLUDING WITHOUT LIMITATION ALL IMPLIED
          WARRANTIES  OF  MERCHANTABILITY  AND FITNESS FOR A
          PARTICULAR PURPOSE, AND  IN  NO  EVENT  SHALL  THE
          UNIVERSITY  OF  WASHINGTON  BE LIABLE FOR ANY SPE-
          CIAL, INDIRECT OR  CONSEQUENTIAL  DAMAGES  OR  ANY
          DAMAGES  WHATSOEVER  RESULTING  FROM  LOSS OF USE,
          DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,













          TORT  (INCLUDING  NEGLIGENCE) OR STRICT LIABILITY,
          ARISING OUT OF OR IN CONNECTION WITH  THE  USE  OR
          PERFORMANCE OF THIS SOFTWARE.

















































9

9







                  - Pine Technical Notes -


                       _S_e_c_t_i_o_n _1 - _I_n_t_r_o_d_u_c_t_i_o_n



          _H_i_s_t_o_r_y _a_n_d _D_e_s_i_g_n _G_o_a_l_s

          Pine was originally conceived in 1989 as a simple,
          easy-to-use mailer for administrative staff at the
          University of Washington in Seattle.  This consti-
          tuency  had previously been using a very nice mail
          system derived from UCLA's "Ben"  mailer  for  the
          MVS  operating  system, but when the cost of main-
          taining our  MVS  system  became  prohibitive,  we
          needed  to find a Unix-based mailer that preserved
          the user-interface strengths of "Ben".   Our  goal
          was to provide a mailer that naive users could use
          without fear of making  mistakes.   We  wanted  to
          cater  to users who were less interested in learn-
          ing the mechanics of using electronic mail than in
          doing  their jobs; users who perhaps had some com-
          puter anxiety.  We felt the way to do this was  to
          have a system that didn't do surprising things and
          provided immediate feedback on each  operation;  a
          mailer  that  had  a  limited  set  of  carefully-
          selected functions.

          At that time, we could not find  any  Unix  mailer
          (commercial  or  freely  available)  that  met our
          requirements.  Consequently, we  reluctantly  con-
          cluded that we would need to develop our own.  The
          Elm mailer seemed like a reasonable starting point
          since  its source code was freely available, so we
          started modifying it.  Today there is virtually no
          Elm  code  left, and Pine has evolved so that many
          "power-user" features may be (optionally) enabled.
          We  have tried to remain true to our original sim-
          plicity  and  ease-of-use   goals   by   providing
          *optional*  features  for sophisticated users.  In
          fact, if none of Pine's options are  enabled,  the
          latest  version  has almost the same look-and-feel
          as the very first version.

          One of the greatest problems with most mailers  on
          Unix  systems  is  the  editor.   One can normally
          choose between emacs and vi.  We experimented with
          some  versions  of  emacs  and settled on a hacked
          version  of  micro  emacs.  Eventually  it  became
          heavily  modified  and tightly integrated with the
          rest of Pine.  One of the main features of  having
          a  tightly coupled editor is that it can guide the
          user through editing the header  of  the  message,
          and Pine takes great care to do this.  A very sim-
          ple and efficient  interface  to  the  Unix  spell


                           - 1 -







                  - Pine Technical Notes -


          command  was  also  added.   The  emacs- style key
          bindings were retained, though most of  the  other
          wild  and wonderful emacs functions were not.  The
          Pine composition editor is  also  available  as  a
          very simple stand alone editor named "pico".

          Also working at the University  of  Washington  is
          the original author of the Internet Message Access
          Protocol (IMAP).  IMAP is a functional superset of
          POP, and provides a way to manipulate mailboxes on
          remote servers as if they  were  local.   Specific
          advantages  of  IMAP over POP include: support for
          inbox access from multiple  computers,  access  to
          more  than  one remote folder, selective access to
          MIME message parts, and support  for  disconnected
          operation.

          Not long after the Pine project  began,  The  IMAP
          author had finished writing the "c-client" library
          as an interface to IMAP and as  a  switch  between
          drivers  for  IMAP  mailboxes, Berkeley mail files
          and Tenex mail files.  In time, "c-client"  became
          a  full  messaging  API  with  support for RFC-822
          parsing, MIME parsing and decoding, SMTP and  NNTP
          drivers,  and  so  forth.  Great care was taken to
          make  the  code  writing  the  mail  files  robust
          against  disks filling up, and inter-process lock-
          ing in order to guarantee mail  file  consistency.
          It  was clear that Pine would benefit greatly from
          using the c-client to access mail storage  so  the
          original  low-level Elm code was replaced by calls
          to c-client library  routines.  Consequently  Pine
          can  write  and access a variety of different mail
          file formats and new ones can be added by creating
          a  simple driver.  In addition the c-client does a
          very careful job of doing all the RFC  822  header
          parsing  and  achieves the highest compliance with
          the RFC.

          Most of the work done on Pine from  6/92  to  6/93
          focused  on changes needed to support a truly dis-
          tributed electronic  messaging  environment  (e.g.
          remote  folder  manipulation), and getting Pine to
          run on DOS (which was a *lot* of work).  The first
          version  of  PC-Pine  (3.84)  was released in July
          1993, and included first steps toward  integrating
          news  and email access in Pine. Doing the DOS port
          was very difficult for a variety of  reasons,  but
          especially  because  of  DOS memory management (or
          lack thereof).  However, simply porting Pine  3.07
          to  DOS  was not sufficient.  For a desktop mailer
          such as PC-Pine to be useful at UW, it was  neces-
          sary  to fully support access to existing *remote*


                           - 2 -







                  - Pine Technical Notes -


          saved-message folders, as well as local  (desktop)
          folders  --  and  of  course,  the  remote  INBOX.
          Accomplishing this required extensions to IMAP,  a
          new  version  of the IMAPd server code, and exten-
          sive work in Pine to support multiple  collections
          of folders.

          The principal reason for porting Unix Pine to  DOS
          was  to  obviate the need for PC users to transfer
          files between their PC and the Unix system running
          Pine.    Now  it  is  possible  to  save  messages
          directly to the PC's filesystem, and  to  directly
          include  PC  files in outgoing messages.  And with
          Pine's MIME capability, binary  files  (e.g.  word
          processing  documents,  spreadsheets, image files,
          executables) may be directly attached to your mes-
          sages.

          With Pine 3.90, significant new functionality  has
          been added, notably aggregate operations for mani-
          pulating groups of messages  at  once,  the  first
          (alpha) release of PC-Pine for the Winsock network
          interface standard, and  greatly  improved  Usenet
          (News)  support.  One of the early interpretations
          of the name "Pine" was "Pine  Is  No-longer  Elm";
          today  a  "Program  for  Internet  News and Email"
          seems more apropos.

          Throughout Pine development, we have had to strike
          a  balance  between  the  need to include features
          which advanced users require and the need to  keep
          things simple for beginning users.  To strike this
          balance, we have tried to adhere to  these  design
          principles:


               - The underlying model presented to the  user
               has  to be simple and clear.  Underlying sys-
               tem operation is hidden as much as possible.

               - It's better to have a few easily understood
               commands  that  can  be repeated than to have
               some more sophisticated command that will  do
               the job all at once.

               - Whenever the user has to select a  command,
               file  name, address, etc., the user should be
               given (or can get) a menu from which to  make
               the  selection.  Menus  need  to be complete,
               small, organized and well thought out.

               - Pine must provide  immediate  feedback  for
               the user with each operation.


                           - 3 -







                  - Pine Technical Notes -


               - Pine must be very tolerant of user  errors.
               Any  time  a  user  is  about  to  perform an
               irreversible act  (send  a  message,  expunge
               messages  from a folder), Pine should ask for
               confirmation.

               - Users should be able to learn  by  explora-
               tion  without  fear  of doing anything wrong.
               This is an important feature so the user  can
               get started quickly without reading any manu-
               als and so fewer manuals are required.

               - The core set of Pine  functions  should  be
               kept  to  a  minimum  so new users don't feel
               "lost" in seemingly extraneous  commands  and
               concepts.


          Just as there were goals relating to the look  and
          feel  of  Pine, there were equally important goals
          having to do with Pine's structure-the things that
          users  never see but still rely on every time they
          use Pine.  While Pine can be used as a stand-alone
          mail  user  agent,  one of its strongest assets is
          its use of the Internet  Message  Access  Protocol
          (IMAP)  for  accessing  remote  email folders.  In
          addition, Pine was one of the  first  programs  to
          support  the Multipurpose Internet Mail Extensions
          (MIME) specification.  With MIME, Pine  users  can
          reliably  send any binary file to any other person
          on the Internet who uses a  MIME  compliant  email
          program.

          The decision to use  IMAP  and  MIME  reflect  the
          importance  of  interoperability,  standardization
          and robustness in Pine.  As  you  work  with  Pine
          more,  you  will  see other features which reflect
          the same values. For example, Pine enforces strict
          compliance  with RFC 822, implements a strong mail
          folder locking mechanism and  verifies  a  process
          before  overwriting  any  files (e.g. addressbook,
          expunging messages).




          _P_i_n_e _C_o_m_p_o_n_e_n_t_s

          If you have picked up the Pine distribution,  then
          you  already  know  that  Pine comes in a few dif-
          ferent pieces.  They are:

9

9                           - 4 -







                  - Pine Technical Notes -


          _P_i_n_e This main code from which the Pine program is
               compiled.


          _P_i_c_o Pico is the name for the Pine composer.   The
               Pico  code  is  used  in two ways:  (1) it is
               compiled on its own to be a stand-alone  edi-
               tor  or (2) compiled as a library for Pine to
               support composition of messages within  Pine.
               Pico  is  Pine's internal editor invoked when
               users need to fill in header  lines  or  type
               the text of an email message.


          _I_m_a_p An  API  for  IMAP.   Includes  the  C-Client
               library, which is compiled into Pine, and the
               IMAP server IMAPd.  C-Client  implements  the
               IMAP  protocol and also negotiates all access
               between Pine and the mail folders it operates
               on.  The C-Client routines are used for email
               folder parsing  and  interpreting  MIME  mes-
               sages.  IMAPd  is a separate server that han-
               dles IMAP connections from any IMAP-compliant
               email  program.   When Pine accesses a remote
               mailbox, the Pine program is the IMAP  client
               and the IMAPd program is the IMAP server.


























9

9                           - 5 -







                  - Pine Technical Notes -


                      _S_e_c_t_i_o_n _2 - _B_a_c_k_g_r_o_u_n_d _D_e_t_a_i_l_s




          _D_o_m_a_i_n _N_a_m_e_s

          Domain names are used to uniquely name  each  host
          on  the  Internet.   A domain name has a number of
          parts separated by periods.  Each label represents
          a  level  in  the hierarchy.  An example of a name
          is:

                       _o_l_i_v_e._c_a_c._w_a_s_h_i_n_g_t_o_n._e_d_u

          In this domain name the top-level  label  is  _e_d_u,
          indicating  it  is  at an educational institution,
          the second-level label is  _w_a_s_h_i_n_g_t_o_n,  indicating
          the  University  of Washington.  _c_a_c is a specific
          department within the  University  of  Washington,
          and  _o_l_i_v_e  is the host name.  The top-level names
          are assigned by Internet organizations, and  other
          names  are assigned at the appropriate level.  The
          Domain Name Service, DNS, is the distributed data-
          base used to look up these names.

          Pine relies on domain names in multiple places.  A
          domain  name  is embedded into the message-id line
          generated for each piece of email.  A domain  name
          is  needed to contact an IMAP server to get access
          to remote INBOXes and folders.  Most  importantly,
          domain  names  are  needed  to construct the From:
          line of your outgoing messages so that  people  on
          the  Internet  will  be  able to get email back to
          you.

          On UNIX systems, you can set the  domain  via  the
          _u_s_e_r-_d_o_m_a_i_n  variable  in  the  Pine configuration
          file, or rely on the file /_e_t_c/_h_o_s_t_s which usually
          sets  the  name of the local host.  While Pine can
          often deliver email without the domain name  being
          properly  configured,  it is best to have this set
          right. Problems can usually be solved by adjusting
          the  system's  entry  in the /_e_t_c/_h_o_s_t_s file.  The
          fully-qualified name should be listed  before  any
          abbreviations.

              128.95.112.99   olive.cac.washington.edu   olive

                          is preferred over

              128.95.112.99   olive   olive.cac.washington.edu
9

9                           - 6 -







                  - Pine Technical Notes -


          On PCs, the task of configuring the domain name is
          a  bit  different.   Often  times, PCs do not have
          domain names-they have _I_P _a_d_d_r_e_s_s_e_s.  IP addresses
          are the numbers which uniquely identify a computer
          on the network.  The way  you  configure  your  IP
          address  depends  on the networking software which
          you use on the PC.  You can refer to the  documen-
          tation which came with your networking software or
          see the PC specific installation  notes  for  help
          configuring  the  IP  address  with  your  network
          software.

          With PCs, it is vital that users set the  variable
          _u_s_e_r-_d_o_m_a_i_n   in   the   Pine  configuration  file
          (_P_I_N_E_R_C).

          Details on configuring Pine  with  correct  domain
          names  can be found in the Domain Settings section
          of this document.


          _R_F_C _8_2_2 _C_o_m_p_l_i_a_n_c_e

          Pine tries to adhere to  RFC  822  a  little  more
          strongly  than  some  other  mailers  and uses the
          "full name <address>" format rather than the older
          "address  (full  name)" format.  The intent of the
          standard is that parentheses should  only  be  for
          comments.   Pine  displays and generates the newer
          format, but will parse the old format and  attempt
          to turn it into the new one.

          As  far  as  outgoing  email  is  concerned,  Pine
          fully-qualifies addresses whenever possible.  They
          are even displayed in fully-qualified form on  the
          terminal  as  the  user  composes a message.  This
          makes addresses more clear and gives a hint to the
          user  that  the  network  extends beyond the local
          organization.   Pine  implements   fully-qualified
          domain names by tacking on the local domain to all
          unqualified addresses which a user types in.   Any
          address which does not contain a "@" is considered
          unqualified.

          The newer format for addresses  allow  for  spaces
          and  special  characters  in  the  full name of an
          address.  For this reason, commas are required  to
          separate  addresses.  If any special characters as
          defined in RFC 822 appear in the full name, quotes
          are required around the address.  Pine will insert
          the quotes automatically.  The common cases  where
          this  happens  are with periods after initials and
          parentheses.


                           - 7 -







                  - Pine Technical Notes -


          Because Pine fully complies with RFC  822,  it  is
          sometimes  difficult  to  use non-Internet address
          formats  such  as  UUCP's  _h_o_s_t!_u_s_e_r  or  DECNet's
          _U_S_E_R::_H_O_S_T  with  Pine.   People  who  run Pine on
          these systems have  made  local  modifications  to
          Pine  or  to  the mail transport agent (e.g. send-
          mail) to make things work for them.  Another  spe-
          cial  case  that  Pine  does not allow for are the
          sites in the  United  Kingdom  which  require  two
          "local"     domains     (one     in    the    form
          _m_a_c_h_i_n_e._s_i_t_e._a_c._u_k for use outside the UK and  the
          other  _u_k._a_c._s_i_t_e._m_a_c_h_i_n_e  for use inside the UK).
          This special case requires local modifications  to
          Pine.

          Pine expects dates to be in the standard  RFC  822
          format which is something like:

               [www, ] dd mmm yy hh:mm[:ss] [timezone]

          It will attempt to parse dates  that  are  not  in
          this  format.   When an unparsable date is encoun-
          tered it is displayed as _x_x_x _x_x when shown in  the
          FOLDER INDEX screen.



          _S_M_T_P _a_n_d _S_e_n_d_m_a_i_l

          Pine is a _u_s_e_r _a_g_e_n_t not a _m_e_s_s_a_g_e _t_r_a_n_s_f_e_r _a_g_e_n_t.
          In  plain  English,  that means Pine does not know
          how to interact with other computers on the Inter-
          net  to  deliver  or receive email. What Pine does
          know how to do is help users  read,  organize  and
          create  email.  The "dirty work" of delivering and
          accepting email is handled by other programs.

          All outgoing email is delivered to a mail transfer
          program  or  to  an  SMTP server.  The most common
          mail transfer program is _s_e_n_d_m_a_i_l.  When Pine on a
          UNIX  computer  uses  the local _s_e_n_d_m_a_i_l, it first
          writes the message to a temporary  file  in  /_t_m_p.
          Then Pine runs a shell in the background that runs
          _s_e_n_d_m_a_i_l on the temporary file  and  then  removes
          it.   This  is done with a shell in the background
          so the user doesn't have to wait for  _s_e_n_d_m_a_i_l  to
          finish.   By default, _s_e_n_d_m_a_i_l is invoked with the
          -_t flag to cause it to read and parse  the  header
          to  determine  the  recipients;  the  -_o_e_m flag to
          cause errors to be mailed back; and the  -_o_i  flag
          to  ignore  dots  in  incoming  messages.  Systems
          administrators can choose to configure Pine to use
          a different mail transfer program or even _s_e_n_d_m_a_i_l


                           - 8 -







                  - Pine Technical Notes -


          with different flags.  See  the  section  on  UNIX
          Pine  Compile-time  Options  for  more  details on
          this.

          Pine can also operate  as  an  SMTP  client.  SMTP
          stands  for  _S_i_m_p_l_e  _M_a_i_l  _T_r_a_n_s_f_e_r  _P_r_o_t_o_c_o_l;  it
          specifies the rules  by  which  computers  on  the
          Internet pass email to one another.  In this case,
          Pine passes outgoing email messages  to  a  desig-
          nated  SMTP  server  instead of to a mail transfer
          program on the local machine.  A  program  on  the
          server  then takes care of delivering the message.
          To make Pine operate as an SMTP client, the  _s_m_t_p-
          _s_e_r_v_e_r  variable  must be set to the IP address or
          host name of the SMTP server within your organiza-
          tion.   This  variable  accepts  a comma separated
          list of servers, so you can specify multiple  SMTP
          servers.  PC-Pine only runs as an SMTP client.


          _I_n_t_e_r_n_e_t _M_e_s_s_a_g_e _A_c_c_e_s_s _P_r_o_t_o_c_o_l (_I_M_A_P)

          IMAP is  a  remote  access  protocol  for  message
          stores.  Pine  uses  IMAP  to  get at messages and
          folders which  reside  on  remote  machines.  With
          IMAP,  all  messages  are  kept on the server.  An
          IMAP client (such as Pine)  can  request  specific
          messages,  headers,  message structures, etc.  The
          client can also issue commands which  delete  mes-
          sages  from folders on the server.  IMAP's closest
          kin is POP, the Post Office Protocol, which  works
          by  transferring  an  entire mailbox to the client
          where all the mail is kept. For  a  complete  com-
          parison of IMAP and POP, see the paper .i "Compar-
          ing Two Approaches to Remote Mailbox Access:  IMAP
          vs. POP" by Terry Gray.  The paper can be found as
          the file doc/imap.vs.pop in the standard Pine dis-
          tribution.

          IMAP Features:

               Allows access to mail folders from more  than
               one client computer.

               Works well over low-bandwidth  lines  because
               information is sent in small pieces as needed
               by the user. For example, only header  infor-
               mation  is  sent to build index lists, and if
               someone sends a 2MB audio file via MIME,  you
               can  choose when (or if) you want to get that
               part of the message.

9

9                           - 9 -







                  - Pine Technical Notes -


               Email can be delivered and stored on a  well-
               maintained   and  reliable  server  which  is
               "always-up".

               Folders can be accessed and manipulated  from
               anywhere on the Internet.

               Users can get to messages stored on different
               folders within the same Pine session.

               Allows use of IMAP server for  searching  and
               parsing.

               The latest revision of IMAP (IMAP4) also pro-
               vides  for  disconnected operation, including
               resynchronization of  message  state  between
               mail  servers  and message caches on clients.
               Pine does not yet  support  this  capability,
               however.


          IMAP2 is defined in RFC 1176.  IMAP4, the proposed
          revision  to  IMAP2,  is described in the document
          "latest-imap-draft"  in  the  /mail  directory  of
          ftp.cac.washington.edu.   IMAP4  will  be formally
          documented in an upcoming RFC.  Pine  3.90  is  an
          IMAP2bis client, but does not yet implement all of
          the IMAP4 extensions.  (IMAP2bis  was  an  interim
          specification  superseded  by  IMAP4.)  Pine takes
          advantage of the extensions  defined  in  IMAP2bis
          for  efficient  and  selective access to MIME body
          parts.  We expect the next major release  of  Pine
          (probably version 4.0) to be fully compatible with
          the IMAP4 specification.



          _M_u_l_t_i_p_u_r_p_o_s_e _I_n_t_e_r_n_e_t _M_a_i_l _E_x_t_e_n_s_i_o_n_s (_M_I_M_E)

          MIME is a way  of  encoding  a  multipart  message
          structure  into a standard Internet email message.
          The parts may be nested and may be of  seven  dif-
          ferent types:  Text, Audio, Image, Video, Message,
          Application  and  Multipart  (nested).   The  MIME
          specification  allows  email programs such as Pine
          to  reliably  and  simply  exchange  binary   data
          (images, spreadsheets, etc.) MIME includes support
          for international  character  sets,  tagging  each
          part  of  a  message  with the character set it is
          written in, and providing 7-bit encoding of  8-bit
          character  sets.  It  also  provides a simple rich
          text format for marking text as bold,  underlined,
          and  so  on.  There  is  a mechanism for splitting


                           - 10 -







                  - Pine Technical Notes -


          messages into multiple parts and reassembling them
          at the receiving end.

          The MIME standard was officially published in June
          of  1992  as  RFC 1341 and subsequently revised in
          RFC 1521 when it became a full Internet  Standard.
          Pine  3.0  was  one of the first email programs to
          Implement MIME.  Now, there are dozens of  commer-
          cial  and freely available MIME-capable email pro-
          grams. In addition, MIME is being added  to  news-
          readers so MIME messages can be posted and read in
          USENET newsgroups.

          An actual MIME message looks something like this:

              From lgl@olive.cac.washington.edu Tue Jul 14 17:55:17 1992
              Date: Tue, 14 Jul 1992 17:55:17 -0700 (PDT)
              From: Laurence Lundblade <lgl@cac.washington.edu>
              Subject: Test MIME message
              To: Laurence Lundblade <lgl@cac.washington.edu>

              --16820115-1435684063-711161753:#2306
              Content-Type: TEXT/PLAIN; charset=US-ASCII

              The text of the message would go here. It is readable if
              one doesn't mind wading around a little bit of the MIME
              formatting. After this is a binary file in base 64
              encoding. It has been shortened for this example. The
              Base 64 stuff looks dorky in PostScript because
              troff -me doesn't have a fixed font like courier.

              Laurence Lundblade
                lgl@cac.washington.edu
                   Computing and Communications, University of Washington

              --16820115-1435684063-711161753:#2306
              Content-Type: TEXT/plain; name=login
              Content-Transfer-Encoding: BASE64
              Content-Description: NeXT login program

              AYAAAABAAAAAQAAAAQAAAL4AAAAAQAAAAEAAAJYAAAAAAAAAAAA
              AAAAAAAABfsAAADFAAAFswAAAAHAAAABwAAAAgAAAAAX190ZXh0
              AAAAF9fVEVYVAAAAAAAAAAAAAAAAAAAAAAQpAAAAxQAAAABAAAA
              AAAAAAAAAAAAABfX2Z2bWxpYl9pbml0MAAAX19URVhUAAAAAAAA
              KQAAAEwAAATuAAAAAIAAAAAAAAAAAAAAAAAAAAAAAAAAF9fZnZt
              XQxAABfX1RFWFQAAAAAAAAAAAAAAAAR1AAAAAAAABToAAAAAgAA
              AAAAAAAAAAAAAAAX19jc3RyaW5nAAAAAAAAAF9fVEVYVAAAAAAA
              BHUAAADQQAAFOgAAAAAAAAAAAAAAAAAAAACAAAAAAAAAABfX2Nv
              AAAAAAAX19URVhUAAAAAAAAAAAAAAAAFRgAAACsAAAYLAAAAAIA
              AAAAAAAAAAAAAAAAF9fZGF0YQAAAAAAAAAAAABfX0RBVEEAAAAA
              AAVxAAAAQgAABjYAAAAAgAAAAAAAAAAAAAAAAAAAAAAAAAAX19i
              AAAAAAAAF9fREFUQQAAAAAAAAAAAAAAABbMAAAADAAAAAAAAAAC
              AAAAAABAAAAAAAAAABfX2NvbW1vbgAAAAAAAAAAX19EQVRBAAAA


                           - 11 -







                  - Pine Technical Notes -


              CAlcwAlZCBMT0dJTiBGQUlMVVJFJXMgT04gJXMsICVzAHN1AGxv
              Wxsb2Mgb3V0IG9mIG1lbW9yeQoAJXMgdG9vIGxvbmcNCgAvZXRj
              3Vzci9hZG0vd3RtcAAAAABAKCMpUFJPR1JBTTpsb2dpbiAgUFJP
              WRzLTQyICBERVZFTE9QRVI6cm9vdCAgQlVJTFQ6U3VuIE5vdiAx
              zoyMSBQU1QgMTk5MAoAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
              AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
              AAAAAAAAAAAAAAAAAAAAAAAAAAAQCgjKSBDb3B5cmlnaHQgKGMp
              DE5ODcsIDE5ODggVGhlIFJlZ2VudHMgb2YgdGhlIFVuaXZlcnNp
              2FsaWZvcm5pYS4KIEFsbCByaWdodHMgcmVzZXJ2ZWQuCgBAKCMp
              wk1LjQwIChCZXJrZWxleSkgNS85Lzg5AAAAABHUAAAR1f//////
              wAAEdQAABHUAAAR1AAAEdQAAAEsAxwREwT/GhkSDxcWAAAR2gAA
              AAR5gAAEeoAABHuAAAR8gAAEfYAABH6AAAR/gAAEgIAABIGAAAA
              AAB

              --16820115-1435684063-711161753:#2306--



          For more information about MIME, see RFC  1521  or
          the  FAQ  in  the  newsgroup comp.mail.mime or the
          paper _M_I_M_E _O_v_e_r_v_i_e_w by Mark Grand.  You  can  find
          the  paper  via  ftp  on adad.premenos.sf.ca.us as
          pub/mime.ps or /pub/mime.txt.  For  details  about
          Pine's  implementation  of  MIME, see the two MIME
          sections later in this document.


          _F_o_l_d_e_r _C_o_l_l_e_c_t_i_o_n_s

          Folder Collections are Pine's way of dealing  with
          more  than a single group of folders.  With advent
          of PC-Pine and the  development  of  tools  within
          IMAP to better manage remote folders, the time was
          ripe to provide a mechanism for defining  a  group
          of  remote  folders.   PC-Pine forced the issue in
          that many potential PC-Pine users would be migrat-
          ing  from  UNIX pine in a time-sharing environment
          and, thus, would have  some  investment  in  their
          archived messages on that host.

          Currently, Pine has no way to  dynamically  create
          or  define  collections,  but  there  is much work
          still going on in this area.  The hope is to  pro-
          vide a general way to define, display and navigate
          remote folder  collections  in  a  consistent  way
          across  platforms  and  applications.   Especially
          important to this goal will be the hierarchy  sup-
          port  provisions in the IMAP4 specification.  Stay
          tuned!

          For a more complete description of Folder  Collec-
          tions,  see  the  section  on  "Syntax for Collec-
          tions".


                           - 12 -







                  - Pine Technical Notes -


                _S_e_c_t_i_o_n _3 - _B_u_i_l_d_i_n_g _a_n_d _I_n_s_t_a_l_l_a_t_i_o_n



          The Pine distribution is designed  to  require  as
          little configuration and effort at compile time as
          possible.  Still, there are  some  Pine  behaviors
          which  are  set at the time you compile Pine.  For
          each of these, there is a reasonable (our opinion)
          default  built  into  the  code,  so  most systems
          administrators will have no need for these steps.



          _U_N_I_X _P_i_n_e _C_o_m_p_i_l_e-_t_i_m_e _O_p_t_i_o_n_s

          The   files   you   may   need   to   modify   are
          ./_p_i_n_e/_m_a_k_e_f_i_l_e._x_x_x    and   ./_p_i_n_e/_o_s_d_e_p/_o_s-_x_x_x._h
          where "xxx" is the 3-letter code  for  your  plat-
          form.   You can give the command _b_u_i_l_d _h_e_l_p to see
          the list of ports incorporated into Pine and their
          associated     3-letter     codes.     The    file
          ./_p_i_n_e/_m_a_k_e_f_i_l_e._x_x_x is where you  would  set  your
          compiler  options.   By default, Pine will be com-
          piled with debugging on, optimization and  profile
          off.   Note  that  if  you compile with DEBUG off,
          then Pine will not create its normal debug  files,
          no  matter  how  the debug-level and debug command
          line flag are set.

          Most of Pine's  behaviors  are  set  in  the  file
          ./_p_i_n_e/_o_s_d_e_p/_o_s-_x_x_x._h,   which  includes  comments
          that explain each setting.  Some of these can only
          be  set when you compile.  Others, however, can be
          overridden by command-line flags to Pine  or  set-
          tings  in  Pine's  user  or  system  configuration
          files.  Some of the options which can be set  when
          compiling:

               USE_QUOTAS:  Determines  whether  quotas  are
               checked  on startup.  Default is to not check
               the quota.

               ALLOW_CHANGING_FROM:    Determines    whether
               users  are allowed to modify the From line on
               outgoing mail.  Even  with  this  turned  on,
               users  will  have  to  include  From in their
               _d_e_f_a_u_l_t-_c_o_m_p_o_s_e_r-_h_d_r_s or  _c_u_s_t_o_m_i_z_e_d-_h_d_r_s  in
               order  to  be  able  to  edit  the From line.
               Default is to not allow any changing.

               DEFAULT_DEBUG:  Sets the level  of  debugging
               output   created   in   Pine's  debug  files.


                           - 13 -







                  - Pine Technical Notes -


               Default is level 2.

               NEW_MAIL_TIME:   Interval  between   new-mail
               checks. Default is 150 seconds.

               OVERLAP:  Number of lines overlap  when  user
               views the next page of a message.  Default is
               2 lines.

               USE_TERMINFO:  Instructs Pine to use the ter-
               minfo  database  instead of termcap.  Default
               varies by system.

               SENDMAIL and SENDMAILFLAGS:   Sets  the  name
               and  flags for the local program that will be
               called to handle outgoing email.  Default  is
               /_u_s_r/_l_i_b/_s_e_n_d_m_a_i_l -_o_i -_o_e_m -_t.

               SYSTEM_PINERC:  The name of  the  file  which
               holds  Pine configuration information for all
               users on the system.  Default on UNIX systems
               is /_u_s_r/_l_o_c_a_l/_l_i_b/_p_i_n_e._c_o_n_f.

               SYSTEM_PINERC_FIXED:  The name  of  the  file
               which  holds  the same type of information as
               for SYSTEM_PINERC,  but  only  for  variables
               that  the  administrator wants to keep fixed.
               That is, users  are  not  allowed  to  change
               variables  that  are  specified  in the FIXED
               file.    Default   on   UNIX    systems    is
               /_u_s_r/_l_o_c_a_l/_l_i_b/_p_i_n_e._c_o_n_f._f_i_x_e_d.

          There are a couple of more obscure  options  which
          are  in  the source code because a few people have
          asked for them or because  we  changed  our  minds
          about them being a good idea in general.

               ENCODE_FROMS:  Use Quoted-printable  encoding
               so  that  _F_r_o_m'_s  at  the  beginning of lines
               don't end up being escaped by >'s.  Most peo-
               ple  seem  to  dislike  the Q-P encoding more
               than the > escapes so this is off by default.
               Once  everyone  has  MIME mail readers, we'll
               turn this on by default.

               NO_KEYBOARD_LOCK:  Disable the keyboard lock-
               ing  function  in  the  main  menu.  Keyboard
               locking is  enabled  by  default.   (Keyboard
               lock   may  also  be  turned  off  by  adding
               "disable-kblock-cmd"  to  the  feature   list
               variable in the global pine.conf file.)

9

9                           - 14 -







                  - Pine Technical Notes -


          _P_i_c_o _C_o_m_p_i_l_e-_t_i_m_e _O_p_t_i_o_n_s

               There are even fewer options needed when com-
          piling  Pico.   The  two  interesting ones are for
          UNIX Pico versions only.  The file that  may  need
          some  changing  is  ./_p_i_c_o/_o_s__u_n_i_x._h.  Whatever is
          set will effect the behavior of  the  Pico  stand-
          alone program as well as the composer within Pine.

               SPELLER:  Names  the  program  called  to  do
               "normal" spell-checking.

               TERMCAP and TERMINFO:   Determines  which  of
               these terminal databases will be used.



          _I_M_A_P_d _C_o_m_p_i_l_e-_t_i_m_e _O_p_t_i_o_n_s

          There are no options or settings required for  the
          version  of  IMAPd  distributed with Pine.  If you
          need to be doing  more  complex  modifications  to
          IMAP, then you should pick up the IMAP development
          package and work with that code.  The  developer's
          version  of  IMAP  is  available for anonymous ftp
          from _f_t_p._c_a_c._w_a_s_h_i_n_g_t_o_n._e_d_u in the directory _m_a_i_l.
          The file is called _i_m_a_p._t_a_r._Z.



          _B_u_i_l_d_i_n_g _t_h_e _P_i_n_e _P_r_o_g_r_a_m_s

               You may have already compiled Pine and  tried
          it out.  If so, great!  If not, you should be able
          to do it without too  much  trouble  by  following
          these step-by-step instructions:

          1.   Figure out what platform you're building for.
               You  can  give  the command _b_u_i_l_d _h_e_l_p to see
               the list of  ports  incorporated  into  Pine.
               What  you  need  is the three letter code for
               the platform.  Some examples are _n_x_t for  the
               Next operating system and _u_l_t for Ultrix.  If
               your platform is not in the  list  of  ports,
               then  you  might have some work ahead of you.
               First, check the file _d_o_c/_p_i_n_e-_p_o_r_t_s.  to see
               if  there  are  others  working on a port for
               your platform  or  to  see  if  the  port  is
               included  in  the  "contrib"  section  of the
               source code. Ports in the  _c_o_n_t_r_i_b  directory
               were  contributed by Pine administrators from
               around the world, but  the  Pine  development
               team  has  not been able to test the code. If


                           - 15 -







                  - Pine Technical Notes -


               Pine has not yet been ported to your platform
               at  all,  read the section on Porting Pine in
               this document.


          2.   Make sure you're in  the  root  of  the  Pine
               source.   When you type _l_s you should see the
               following files and directories (or something
               close to it):

                   README  build   doc     makefile           pine
                   bin             contrib imap    pico



          3.   Make sure you're getting  a  clean  start  by
               giving  the command _b_u_i_l_d _c_l_e_a_n.  This should
               take only a few seconds to run.


          4.   Give the command _b_u_i_l_d _x_x_x where _x_x_x  is  the
               three  letter code you picked in step 1.  The
               compiler should grind away for a few minutes.


          5.   When the compilation is complete the sizes of
               the  four binaries built (pine, mtest, imapd,
               pico) will be displayed.  The actual binaries
               are  in  the  various source directories.  In
               addition, the _b_i_n directory contains  a  link
               to  each  program compiled. You can just copy
               them out of _b_i_n or try them from there.



          _I_n_s_t_a_l_l_i_n_g _P_i_n_e _a_n_d _P_i_c_o _o_n _U_N_I_X _P_l_a_t_f_o_r_m_s

          Installing Pine and  Pico  is  remarkably  simple.
          You  take  the  program  files which you have just
          transferred or built and  you  move  them  to  the
          correct  directory on your system.  Most often the
          binaries go  in  /_u_s_r/_l_o_c_a_l/_b_i_n  though  sometimes
          they are placed in /_u_s_r/_b_i_n.  All the help text is
          compiled into Pine so there are no _r_e_q_u_i_r_e_d  auxi-
          liary files.

          There  are,  however,  three  optional   auxiliary
          files:                   /_u_s_r/_l_o_c_a_l/_l_i_b/_p_i_n_e._i_n_f_o,
          /_u_s_r/_l_o_c_a_l/_l_i_b/_p_i_n_e._c_o_n_f,                      and
          /_u_s_r/_l_o_c_a_l/_l_i_b/_p_i_n_e._c_o_n_f._f_i_x_e_d.       The     file
          _p_i_n_e._i_n_f_o contains text on how to get further help
          on the local system.  It is presented as the first
          page of the help text for the main menu and should


                           - 16 -







                  - Pine Technical Notes -


          probably  refer to the local help desk or the sys-
          tem administrator.  If this file doesn't  exist  a
          generic  version  which  suggests  "talking to the
          computer support staff at  your  site"  is  shown.
          The  file  _p_i_n_e._c_o_n_f  is  used  to set system-wide
          default  configurations  for   Pine.    The   file
          _p_i_n_e._c_o_n_f._f_i_x_e_d  is  also  used to set system-wide
          default configurations for Pine.   The  difference
          between  these  two  files  is  that configuration
          variables set in the _p_i_n_e._c_o_n_f._f_i_x_e_d file may  not
          normally  be  over-ridden by a user.  See the sec-
          tion on Pine Configuration later in this  document
          for    details    about    the    _p_i_n_e._c_o_n_f    and
          _p_i_n_e._c_o_n_f._f_i_x_e_d files.



          _I_n_s_t_a_l_l_i_n_g _P_C-_P_i_n_e

          Beginning with the Pine 3.90 release, there  is  a
          PC-Pine  version that runs under windows using the
          Winsock network interface.  For  those  who  still
          need  to run the DOS version of PC-Pine, there are
          versions for four different TCP/IP network stacks:
          FTP  Inc's PC/TCP, Novell's LAN Workplace for DOS,
          Sun's PC/NFS, and WATTCP for packet drivers.   PC-
          Pine needs to be able to interact closely with the
          stack loaded on your PC.  Most of the  time,  this
          occurs  automatically.  However, there are certain
          modifications that need be made.


          LAN Workplace for DOS Version 4.1
               Set the environment variable _E_X_C_E_L_A_N  in  the
               PC's  _A_U_T_O_E_X_E_C._B_A_T  file.   This provides the
               necessary links so that LAN Workplace for DOS
               4.1  can translate domain names to IP numbers
               correctly.  It is  needed  because  Pine  was
               developed  for   LAN  Workplace  4.0 and this
               particular variable is treated differently in
               4.1  than  in 4.0.  The _E_X_C_E_L_A_N variable must
               point to the directory in which LAN Workplace
               is installed.

          PC/TCP versions before 2.2
               You need a file called _P_C_T_C_P._I_N_I  which  con-
               tains  a  bare-minimum  2-line description of
               the PC's configuration.  It looks like this:

                                   [pctcp ifcust 0]
                                   ip-address=_x_x._x_x._x_x._x_x

9

9                           - 17 -







                  - Pine Technical Notes -


               Where _x_x._x_x._x_x._x_x is the IP  address  of  the
               PC.  Pine  also requires an environment vari-
               able, _P_C_T_C_P, which points to this file.   For
               example:

                                   set PCTCP=C:\PINE\PCTCP.INI


          Packet Drivers
               Pine needs to be made aware of the PC's  net-
               work  configuration  file.   Simply  edit the
               file _W_A_T_T_C_P._C_F_G included in the Pine  distri-
               bution.   The  file  includes 5 configuration
               settings--IP-address,    gateway,    netmask,
               nameserver(s)  and domainslist. If you have a
               network configuration file  for  NCSA  Telnet
               then  _W_A_T_T_C_P._C_F_G is just a pared down version
               of the  _C_O_N_F_I_G._T_E_L  file  you  already  made.
               Take a look at _C_O_N_F_I_G._T_E_L to find the correct
               settings for _W_A_T_T_C_P._C_F_G.  Once the configura-
               tion  file is made, the DOS environment vari-
               able _W_A_T_T_C_P._C_F_G needs to point  at  it.   For
               example:

                                   set WATTCP.CFG=C:\PINE



          In addition to  networking  software  issues,  you
          might  need  to worry about setting the time zone.
          PC-Pine includes the time zone as part of outgoing
          email.  There is a generic way for PC applications
          to get the time zone, but, because PC-Pine is  one
          of  a  very  few  applications which requires this
          information, time zone  might  not  be  previously
          configured.

          The trick is to add an environment  variable,  _T_Z,
          to your PC's _A_U_T_O_E_X_E_C._B_A_T file. The format for the
          _T_Z environment variable is as follows:

                         ZZZ[+H]H[:MM:SSTTT]


          First is the 3-letter code for your standard time,
          then  a  "+" or a "-" for direction of offset from
          GMT, then the amount of  offset  (hours,  minutes,
          seconds)  and  finally  the 3-letter code for your
          summer- or daylight savings time.   Everything  in
          [] brackets is optional.

          The default time zone is "PST-8PDT" (U.S.  Pacific
          Time).  Coincidentally, Microsoft is headquartered


                           - 18 -







                  - Pine Technical Notes -


          in that time zone.

          As an example, people in the Eastern part  of  the
          US  should  add  this  line  to their _A_U_T_O_E_X_E_C._B_A_T
          files:

                             TZ=EST-5EDT



          _I_n_s_t_a_l_l_i_n_g _I_M_A_P_d

          When the Pine distribution is built on a UNIX sta-
          tion,  the IMAP server binary, _i_m_a_p_d, is compiled.
          Installing _i_m_a_p_d requires placing  the  binary  in
          the  appropriate  directory, usually /_u_s_r/_e_t_c, and
          adding    entries     to     /_e_t_c/_s_e_r_v_i_c_e_s     and
          /_e_t_c/_i_n_e_t_d._c_o_n_f  or  their counterparts.  The fol-
          lowing line is appropriate for /_e_t_c/_s_e_r_v_i_c_e_s:

            _i_m_a_p         _1_4_3/_t_c_p         # _M_a_i_l _t_r_a_n_s_f_e_r

          and   the   next   line   is    appropriate    for
          /_e_t_c/_i_n_e_t_d._c_o_n_f:

            _i_m_a_p     _s_t_r_e_a_m     _t_c_p         _n_o_w_a_i_t      _r_o_o_t
          /_u_s_r/_e_t_c/_i_m_a_p_d _i_m_a_p_d

          The /_e_t_c/_i_n_e_t_d._c_o_n_f file entry may  vary  on  dif-
          ferent  versions  of  UNIX.   Some have a slightly
          different set of fields.   Also  the  pathname  in
          /_e_t_c/_i_n_e_t_d._c_o_n_f must match the path where _i_m_a_p_d is
          installed.

          With this  configuration,  the  IMAP  server  runs
          without pre-authentication.  Each new IMAP connec-
          tion requires a  correct  username  and  password.
          IMAP can also be run with pre-authentication based
          on the standard _r_s_h mechanism.   To  enable  this,
          the user account on the IMAP server must contain a
          valid file  which  grants  access  to  the  client
          machine.  Enabling _r_i_m_a_p authentication is done by
          creating  a  link  called  /_e_t_c/_r_i_m_a_p_d  to  _i_m_a_p_d.
          Basically,  what is happening is that Pine is tak-
          ing advantage of the ability that _r_s_h has  to  use
          privileged  TCP ports so it doesn't have to run in
          privileged  mode.   If  the  _r_i_m_a_p  authentication
          fails  it will drop back to plain password authen-
          tication.

          PC-Pine cannot take advantage of _r_i_m_a_p authentica-
          tion.   Also,  if  your  system uses a distributed
          configuration database, like NIS, Yellow Pages  or


                           - 19 -







                  - Pine Technical Notes -


          Netinfo,  be sure that appropriate steps are taken
          to  ensure  the  above  mentioned  information  is
          updated.



          _S_u_p_p_o_r_t _F_i_l_e_s  _a_n_d  _E_n_v_i_r_o_n_m_e_n_t  _V_a_r_i_a_b_l_e_s:   _U_N_I_X
          _P_i_n_e

          This section lists the various  files  which  Pine
          uses  which  are  not email folders.  All of these
          are the default names  of  files,  they  may  vary
          based on Pine's configuration.

          /usr/local/lib/pine.conf
               Pine's global configuration file.

          /usr/local/lib/pine.conf.fixed
               Non-overridable global configuration file.

          /usr/local/lib/pine.info
               Local pointer to system administrator.

          ~/.pinerc
               Personal configuration file for each user.

          ~/.addressbook
               Personal addressbook

          ~/.addressbook.lu
               Personal address book lookup file (index file
               to speed up lookups).

          ~/.newsrc
               Personal USENET subscription list.   This  is
               shared with other newsreading programs.

          ~/.pine-debugX
               The files created for  debugging  Pine  prob-
               lems.  By  default,  there  are 4 .pine-debug
               files kept at any time.

          ~/.signature
               A signature file which will  be  included  in
               all outgoing email messages.

          ~/.pine-interrupted-mail
               The text of a message which  was  interrupted
               by some unexpected error which Pine detected.

          ~/mail/postponed-msgs
               A folder of messages which the user chose  to
               postpone.


                           - 20 -







                  - Pine Technical Notes -


          /etc/mailcap
               System-wide  mail  capabilities  file.   Only
               used if $MAILCAPS not set.

          ~/.mailcap
               Personal mail  capabilities  file.   Combines
               with   system-wide  mailcap.   Only  used  if
               $MAILCAPS not set.

          The location of the following support files may be
          controlled  by variables in the personal or global
          Pine configuration  file:  signature,  addressbook
          and   its  index  file,  postponed  messages,  and
          newsrc.

          Unix Pine uses  the  following  environment  vari-
          ables:

          TERM
               Tells Pine what kind  of  terminal  is  being
               used.

          DISPLAY
               Determines if Pine will try to display  IMAGE
               attachments.

          SHELL
               If not set, default is /bin/sh

          MAILCAPS
               A semicolon delimited list of path  names  to
               mailcap files.



          _S_u_p_p_o_r_t  _F_i_l_e_s  _a_n_d  _E_n_v_i_r_o_n_m_e_n_t  _V_a_r_i_a_b_l_e_s:   _P_C-
          _P_i_n_e

          This section lists the various files which PC-Pine
          uses  which  are  not normal mail folders.  All of
          these are the default names  of  files,  they  may
          vary based on Pine's configuration.


          <PINE.EXE directory>\PINE.HLP
               File containing Pine's internal help text.

          <PINE.EXE directory>\PINE.NDX
               Index of Pine's help text used by PC-Pine  to
               locate entries.

          $PINERC   or   $HOME\PINE\PINERC   or    <PINE.EXE
               dir>\PINERC


                           - 21 -







                  - Pine Technical Notes -


               Path  to  (required)  personal  configuration
               file.

          $PINECONF
               Path of optional global configuration file.

          <PINERC directory>\ADDRBOOK
               Personal addressbook

          <PINERC directory>\ADDRBOOK.LU
               Personal address book lookup file (index file
               to speed up lookups).

          <PINERC directory>\PINE.SIG
               A signature file which will  be  included  in
               all outgoing email messages.

          <PINERC directory>\PINE.PWD
               A  file  containing  encrypted  password  for
               remote mail server.

          <PINERC directory>\PINEDEBG.TXT
               Location of Pine debug file.

          <PINERC  directory>\MAILCAP    and/or    <PINE.EXE
               dir>\MAILCAP
               These paths are only used  if  $MAILCAPS  not
               set.

          $HOME\NEWSRC or <PINERC directory>\NEWSRC
               Personal USENET subscription list.  This  may
               be shared with other newsreading programs.

          $HOME\MAIL\INTRUPTD
               The text of a message which  was  interrupted
               by some unexpected error which Pine detected.

          $HOME\MAIL\POSTPOND
               A folder of messages which the user chose  to
               postpone.

          PC-Pine's help text and help text index  file  are
          expected  to  reside  in the same directory as the
          _P_I_N_E._E_X_E  executable,  as  they  are   essentially
          extensions of the executable.  The personal confi-
          guration file may be in the same directory as  the
          executable, or if that is inconvenient because the
          executable is on a shared or read-only drive, then
          it  can be in a file named by the $_P_I_N_E_R_C environ-
          ment variable, or in $_H_O_M_E\_P_I_N_E\_P_I_N_E_R_C,  where  if
          not set, $_H_O_M_E defaults to the root of the current
          working drive.
9

9                           - 22 -







                  - Pine Technical Notes -


          Most of the other support files  key  off  of  the
          location of the _P_I_N_E_R_C file.  However, in the case
          of the  NEWSRC  file,  the  path  $_H_O_M_E\_N_E_W_S_R_C  is
          checked  first.   Also, the postponed messages and
          interrupted message  folders  are  placed  in  the
          default  folder collection, normally in the direc-
          tory $_H_O_M_E\_M_A_I_L.

          The location of the following support files may be
          controlled  by variables in the personal or global
          Pine configuration  file:  signature,  addressbook
          (and  its  index  file),  postponed  messages, and
          newsrc.

          PC-Pine uses the following environment variables:

          PINERC
               Overrides default path to pinerc file.

          PINECONF
               Optional path to global pine config file.

          HOME If not set, Pine uses the root of the current
               drive,  e.g.  C:.ip   TMP  or  TEMP Specifies
               location of temporary storage area

          COMSPEC
               Specifies shell for external commands.

          MAILCAPS
               A semicolon delimited list of path  names  to
               mailcap files.




















9

9                           - 23 -







                  - Pine Technical Notes -


                    _S_e_c_t_i_o_n _4 - _C_o_m_m_a_n_d _L_i_n_e _A_r_g_u_m_e_n_t_s



          Pine and PC-Pine can accept quite a  few  command-
          line  arguments.   Many of these arguments overlap
          with variables in the Pine configuration file.  If
          there is a difference, then a flag set in the com-
          mand line takes precedence.  Both Pine and PC-Pine
          expect  command  line  arguments to be preceded by
          the "-" (dash) as normally used by UNIX programs.


          [_a_d_d_r_e_s_s]
               Send-to:  If you put  an  unqualified  string
               (or  strings) in the command line, Pine reads
               them as email addresses.  Pine  will  startup
               in the composer with a message started to the
               person/people specified.  Once the message is
               sent, the Pine session closes.


          -a   Special anonymous mode for UWIN*.


          -conf
               Configuration:  Prints a sample system confi-
               guration  file to the screen or standard out-
               put.


          -create_lu _a_d_d_r_b_o_o_k _s_o_r_t-_o_r_d_e_r
               Create  auxiliary  index  (LookUp)  file  for
               _a_d_d_r_b_o_o_k  and  sort  _a_d_d_r_b_o_o_k  in _s_o_r_t-_o_r_d_e_r,
               which may be _d_o_n_t-_s_o_r_t,  _n_i_c_k_n_a_m_e,  _f_u_l_l_n_a_m_e,
               _n_i_c_k_n_a_m_e-_w_i_t_h-_l_i_s_t_s-_l_a_s_t,  or  _f_u_l_l_n_a_m_e-_w_i_t_h-
               _l_i_s_t_s-_l_a_s_t.  Only useful when creating global
               or shared address books.


          -d _d_e_b_u_g-_l_e_v_e_l
               Debug Level:  Sets  the  level  of  debugging
               information  written by Pine. _d_e_b_u_g-_l_e_v_e_l can
               be set to any integer 0-9.  A debug level  of
               0   turns  off  debugging  for  the  session.
               (Actually there are some levels  higher  than
               9,  now,  but  you probably don't want to see
               them.)


          -f _f_o_l_d_e_r
               Startup folder:  Pine will open  this  folder
               in place of the standard INBOX.


                           - 24 -







                  - Pine Technical Notes -


          -F _f_i_l_e
               Open named text file  and  view  with  Pine's
               browser.


          -h   Help:  Prints the list of available  command-
               line arguments to the screen.


          -i   Pine will start up in the FOLDER INDEX screen
               instead  of  the  MAIN  MENU.   Configuration
               equivalent:  _i_n_i_t_i_a_l-_k_e_y_s_t_r_o_k_e-_l_i_s_t=_i


          -I _a,_b,_c,...
               Initial Keystrokes:  Pine will  execute  this
               comma-separated  sequence  of  commands  upon
               startup.  This allows users to  get  Pine  to
               start  in any of its menus/screens.  You can-
               not include any input to the composer in  the
               initial  keystrokes.   The  key  <Return>  is
               represented by a "CR" in the keystroke  list;
               the  spacebar  is  designated  by the letters
               "SPACE".   Control  keys  are  two  character
               sequences  beginning  with "^", such as "^I".
               A tab character is "TAB".  Function keys  are
               "F1"  -  "F12"  and  the arrow keys are "UP",
               "DOWN", "LEFT", and  "RIGHT".   Configuration
               equivalent:  _i_n_i_t_i_a_l-_k_e_y_s_t_r_o_k_e-_l_i_s_t


          -k   Function-Key Mode:  When invoked in this way,
               Pine  expects  the  input  of  commands to be
               function-keys.    Otherwise,   commands   are
               linked to the regular character keys.  Confi-
               guration    equivalent:     _u_s_e-_f_u_n_c_t_i_o_n-_k_e_y_s
               included in _f_e_a_t_u_r_e-_l_i_s_t.


          -l   Folder-List:   With  "-l"  set,   Pine   will
               default  to  an  expanded  folder  list. This
               means that the FOLDER LIST screen will always
               show all folders in all collections.  Default
               is to show the folders in the current collec-
               tion    only.     Configuration   equivalent:
               _e_x_p_a_n_d_e_d-_v_i_e_w-_o_f-_f_o_l_d_e_r_s in _f_e_a_t_u_r_e-_l_i_s_t.


          -n _n Message-Number:  When specified, Pine  starts
               up  in  the  FOLDER  INDEX  screen  with  the
               current message being the designated  message
               number.
9

9                           - 25 -







                  - Pine Technical Notes -


          -nr  Special mode for UWIN*.


          -o _f_o_l_d_e_r
               Opens the INBOX (or a  folder  specified  via
               the -f argument) ReadOnly.


          -p _f_i_l_e
               Uses the named file as  the  personal  confi-
               guration  file  instead  of  ~/_p_i_n_e_r_c  or the
               default PINERC search sequence PC-Pine uses.


          -P _f_i_l_e
               Uses the named file as the system wide confi-
               guration        file        instead        of
               /_u_s_r/_l_o_c_a_l/_l_i_b/_p_i_n_e._c_o_n_f.  UNIX Pine only.


          -pinerc _f_i_l_e
               Output fresh pinerc  configuration  to  _f_i_l_e,
               preserving the settings of variables that the
               user has made.  Use _f_i_l_e set to "-"  to  make
               output go to standard out.


          -r   Restricted Mode:  For UNIX Pine  only.   Pine
               in  restricted  mode  can  only send email to
               itself.  Save and export are limited.


          -sort _k_e_y
               Sort-Key:  Specifies the order messages  will
               be  displayed in for the FOLDER INDEX screen.
               _K_e_y can have the following values:   subject,
               arrival,  date,  from, size, subject/reverse,
               arrival/reverse, date/reverse,  from/reverse,
               size/reverse.     The    default   value   is
               "arrival".   The   _k_e_y   value   reverse   is
               equivalent  to  arrival/reverse.  This option
               will be expanded in the future to allow sort-
               ing   on   "to"   and   "cc".   Configuration
               equivalent:  _s_o_r_t-_k_e_y.


          -z   Enable Suspend:  When run with this flag, the
               key  sequence  ctrl-z  will  suspend the Pine
               session.  Configuration equivalent:   _e_n_a_b_l_e-
               _s_u_s_p_e_n_d included in _f_e_a_t_u_r_e-_l_i_s_t.


9

9                           - 26 -







                  - Pine Technical Notes -


          -_o_p_t_i_o_n=_v_a_l_u_e
               Assign _v_a_l_u_e to  the  config  option  _o_p_t_i_o_n.
               For   example,   -_s_i_g_n_a_t_u_r_e-_f_i_l_e=_s_i_g_1   or  -
               _f_e_a_t_u_r_e-_l_i_s_t=_s_i_g_n_a_t_u_r_e-_a_t-_b_o_t_t_o_m       (Note:
               feature-list values are additive).


               * UWIN = University of Washington Information
          Navigator











































9

9                           - 27 -







                  - Pine Technical Notes -


              _S_e_c_t_i_o_n _5 - _C_o_n_f_i_g_u_r_a_t_i_o_n _a_n_d _P_r_e_f_e_r_e_n_c_e_s




          _P_i_n_e _C_o_n_f_i_g_u_r_a_t_i_o_n

          There  is  very  little  in  Pine  which  requires
          compile-time  configuration.  In  most  cases, the
          compiled-in  preferences  will  suit   users   and
          administrators  just  fine. When running Pine on a
          UNIX system, the  default  built-in  configuration
          can  be changed by setting variables in the system
          configuration file, /_u_s_r/_l_o_c_a_l/_l_i_b/_p_i_n_e._c_o_n_f. Both
          Pine  and  PC-Pine  also use personal (user-based)
          configuration files. On UNIX  machines,  the  per-
          sonal  configuration  file  is the file ~/._p_i_n_e_r_c.
          For PC-Pine systems,  the  personal  configuration
          file   is   in  $_P_I_N_E_R_C  or  $_H_O_M_E\_P_I_N_E\_P_I_N_E_R_C  or
          <_P_I_N_E._E_X_E _d_i_r>\_P_I_N_E_R_C.

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

              <variable> = <value>

          If the value is absent then the variable is unset.
          To set a variable to the empty value the syntax is
          "".  This is equivalent to an absent value  except
          that  it  overrides any system-wide value that may
          be set.  Quotes may be used around any value.  All
          values  are strings and end at the end of the line
          or the closing quote.  Leading and trailing  space
          is  ignored  unless  it is included in the quotes.
          For some variables the only appropriate values are
          _y_e_s  and _n_o.  There is also a second type of vari-
          able, lists.  A list is a comma-separated list  of
          values.  The syntax for a list is:

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

          A list can be continued  on  subsequent  lines  by
          beginning  the  line  with  white-space.  Both the
          per-user and global configuration files  may  con-
          tain comments which are lines beginning with a #.

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

              (1) the system-wide _f_i_x_e_d configuration file
              (2) a command line argument
              (3) the personal configuration file (which is usually set from the Config screen)


                           - 28 -







                  - Pine Technical Notes -


              (4) the system-wide configuration file
              (5) default in the source code.

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

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

          References  to  environment   variables   may   be
          included  in  the  Pine  configuration files.  The
          format is $_v_a_r_i_a_b_l_e or ${_v_a_r_i_a_b_l_e}.  The character
          ~  will be expanded to the $_H_O_M_E environment vari-
          able.

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

9                           - 29 -







                  - Pine Technical Notes -


          _G_e_n_e_r_a_l _C_o_n_f_i_g_u_r_a_t_i_o_n _V_a_r_i_a_b_l_e_s

          The following is a list of all Pine  configuration
          variables,  in  alphabetical order.  Note that not
          all variables apply to all versions  of  Pine  and
          that  some variables are only applicable in a sys-
          tem configuration file and some are only  applica-
          ble in a personal configuration file.


          _a_d_d_r_b_o_o_k-_s_o_r_t-_r_u_l_e
               This variable sets  up  the  default  address
               book  sorting.   Currently,  Pine will accept
               the  values  _d_o_n_t-_s_o_r_t,  _f_u_l_l_n_a_m_e-_w_i_t_h-_l_i_s_t_s-
               _l_a_s_t, _f_u_l_l_n_a_m_e, _n_i_c_k_n_a_m_e-_w_i_t_h-_l_i_s_t_s-_l_a_s_t, and
               _n_i_c_k_n_a_m_e.  The default is to sort by fullname
               with lists last.


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


          _b_u_g_s-_n_i_c_k_n_a_m_e, _b_u_g_s-_f_u_l_l_n_a_m_e _a_n_d _b_u_g_s-_a_d_d_r_e_s_s
               System-wide configuration file  only.   These
               are used by the Report Bug command.


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


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


                           - 30 -







                  - Pine Technical Notes -


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


          _d_e_f_a_u_l_t-_c_o_m_p_o_s_e_r-_h_d_r_s
               Show only these  headers  (by  default)  when
               composing  a  message.  This list may include
               headers defined in the _c_u_s_t_o_m_i_z_e_d-_h_d_r_s list.


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


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


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


          _f_e_a_t_u_r_e-_l_i_s_t
               This is a list of  features  (options)  which


                           - 31 -







                  - Pine Technical Notes -


               may be turned on.  You may also turn features
               off (the default) by prepending  the  charac-
               ters   _n_o-  to  any  of  the  features.   The
               _f_e_a_t_u_r_e-_l_i_s_t is additive.  That is, first the
               system-wide _f_e_a_t_u_r_e-_l_i_s_t is read and then the
               user's _f_e_a_t_u_r_e-_l_i_s_t is read.  This  makes  it
               possible  for the system manager to turn some
               of the features on  by  default  while  still
               allowing  the  user  to  cancel that default.
               However, some of  the  documentation  assumes
               that  all of the features are off by default,
               so  use  this  with  care.   In  Unix   Pine,
               features  can be individually fixed on or off
               by setting the  feature  on  or  off  in  the
               system-wide    _f_i_x_e_d    configuration   file.
               Descriptions  are  omitted  here.   See   the
               online  help for descriptions of each feature
               (in the Setup/Config screen).  Exception: the
               four   _d_i_s_a_b_l_e-  features  are  intentionally
               suppressed from the Config  screen,  as  they
               are intended for use by system administrators
               in the system-wide fixed config  file.  Their
               meaning should be self-explanatory.  Also the
               _u_s_e-_f_u_n_c_t_i_o_n-_k_e_y_s feature is hidden from  the
               config  screen.   Here is the current list of
               possible features.

                   assume-slow-link
                   auto-move-read-msgs
                   auto-open-next-unread
                   compose-rejects-unqualified-addrs
                   compose-sets-newsgroup-without-confirm
                   delete-skips-deleted
                   disable-keyboard-lock-cmd
                   disable-config-cmd
                   disable-password-cmd
                   disable-update-cmd
                   enable-aggregate-command-set
                   enable-alternate-editor-cmd
                   enable-alternate-editor-implicitly
                   enable-bounce-cmd
                   enable-flag-cmd
                   enable-full-header-cmd
                   enable-incoming-folders
                   enable-jump-shortcut
                   enable-mail-check-cue
                   enable-suspend
                   enable-tab-completion
                   enable-unix-pipe-cmd
                   expanded-view-of-addressbooks
                   expanded-view-of-folders
                   expunge-without-confirm
                   include-attachments-in-reply


                           - 32 -







                  - Pine Technical Notes -


                   include-header-in-reply
                   include-text-in-reply
                   news-post-without-validation
                   news-read-in-newsrc-order
                   preserve-start-stop-characters
                   quit-without-confirm
                   save-will-quote-leading-froms
                   save-will-not-delete
                   save-will-advance
                   select-without-confirm
                   show-selected-in-boldface
                   signature-at-bottom
                   use-current-dir
                   use-function-keys
                   user-lookup-even-if-domain-mismatch



          _f_o_l_d_e_r-_c_o_l_l_e_c_t_i_o_n_s
               This is a list of  one  or  more  collections
               where saved mail is stored.  See the sections
               describing folder collections and  collection
               syntax  for more information.  The first col-
               lection in this list is the  default  collec-
               tion for saves, including _d_e_f_a_u_l_t-_f_c_c's.


          _f_o_n_t-_n_a_m_e
               Winsock version of PC Pine only.


          _f_o_n_t-_s_i_z_e
               Winsock version of PC Pine only.


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


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

9

9                           - 33 -







                  - Pine Technical Notes -


          _i_n_b_o_x-_p_a_t_h
               This specifies the name of the folder to  use
               for the INBOX.  Normally this is unset so the
               system's default is used.   The  most  common
               reason  for  setting  this is to open an IMAP
               mailbox  for   the   INBOX.    For   example,
               {_i_m_a_p_5._u._e_x_a_m_p_l_e._e_d_u}_i_n_b_o_x   will   open  the
               user's standard _I_N_B_O_X  on  the  mail  server,
               imap5.


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


          _i_n_i_t_i_a_l-_k_e_y_s_t_r_o_k_e-_l_i_s_t
               This is a comma-separated list of  keystrokes
               which Pine executes on startup.  Items in the
               list are usually just characters,  but  there
               are  some special values.  _S_P_A_C_E, _T_A_B, and _C_R
               mean a space character, tab character, and  a
               carriage  return,  respectively.   _F_1 through
               _F_1_2 stand for the twelve function keys.   _U_P,
               _D_O_W_N,  _L_E_F_T,  and  _R_I_G_H_T  stand for the arrow
               keys.   Control  characters  are  represented
               with  ^<_c_h_a_r>.   A  restriction  is  that you
               can't mix function keys and character keys in
               this list even though you can, in some cases,
               mix them  when  running  Pine.   A  user  can
               always use only _c_h_a_r_a_c_t_e_r keys in the startup
               list even if he or she is using _f_u_n_c_t_i_o_n keys
               normally, or vice versa.


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


9

9                           - 34 -







                  - Pine Technical Notes -


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


          _m_a_i_l-_d_i_r_e_c_t_o_r_y
               This variable was more important in  previous
               versions of Pine.  Now it is used only as the
               default for  storing  personal  folders  (and
               only   if  there  are  no  _f_o_l_d_e_r-_c_o_l_l_e_c_t_i_o_n_s
               defined).  The default  value  is  ~/_m_a_i_l  on
               UNIX and $_H_O_M_E\_M_A_I_L on a PC.


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


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


          _n_o_r_m_a_l-_b_a_c_k_g_r_o_u_n_d-_c_o_l_o_r
               PC-Pine only.  Currently,  Pine  will  accept
               the  colors  _b_l_a_c_k,  _b_l_u_e,  _g_r_e_e_n, _c_y_a_n, _r_e_d,
               _m_a_g_e_n_t_a, _y_e_l_l_o_w, or  _w_h_i_t_e.


          _n_o_r_m_a_l-_f_o_r_e_g_r_o_u_n_d-_c_o_l_o_r
               PC-Pine  only.   See  _n_o_r_m_a_l-_b_a_c_k_g_r_o_u_n_d-_c_o_l_o_r
               for possible colors.


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


9

9                           - 35 -







                  - Pine Technical Notes -


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


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


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

                   "attached-to-ansi"      -or-
                   the value of _p_e_r_s_o_n_a_l-_p_r_i_n_t-_c_o_m_m_a_n_d         -or-
                   the value of _s_t_a_n_d_a_r_d-_p_r_i_n_t_e_r from the system-wide configuration



          _r_e_a_d-_m_e_s_s_a_g_e-_f_o_l_d_e_r
               If set, mail in the _I_N_B_O_X that has been  read
               but not deleted is moved here, or rather, the
               user is asked whether or not he or she  wants
               to move it here upon quitting Pine.


          _r_e_v_e_r_s_e-_b_a_c_k_g_r_o_u_n_d-_c_o_l_o_r
               PC-Pine  only.   See  _n_o_r_m_a_l-_b_a_c_k_g_r_o_u_n_d-_c_o_l_o_r
               for possible colors.


          _r_e_v_e_r_s_e-_f_o_r_e_g_r_o_u_n_d-_c_o_l_o_r
               PC-Pine  only.   See  _n_o_r_m_a_l-_b_a_c_k_g_r_o_u_n_d-_c_o_l_o_r
               for possible colors.


          _s_a_v_e_d-_m_s_g-_n_a_m_e-_r_u_l_e
               Determines default folder name  when  saving.
               Currently,   Pine   will  accept  the  values
               "default-folder",   "by-sender",   "by-from",
               "by-recipient",  or  "last-folder-used".   If
               set to _d_e_f_a_u_l_t-_f_o_l_d_e_r, then Pine  will  offer
               the   folder   "saved-messages"   (UNIX)   or
               "SAVEMAIL" (PC) for saving messages.  If  set


                           - 36 -







                  - Pine Technical Notes -


               to  _b_y-_f_r_o_m, then Pine will offer to save the
               message in a folder with the same name as the
               From,  if  there is one, or the Sender other-
               wise.  If set to _b_y-_s_e_n_d_e_r,  then  Pine  will
               offer  to  save  the message in a folder with
               the same name as the Sender, if there is one,
               or   the  From  otherwise.   If  set  to  _b_y-
               _r_e_c_i_p_i_e_n_t, then Pine will offer to  save  the
               message in a folder with the same name as the
               recipient, which is the newsgroup if this was
               sent to a newsgroup or the To address if not.
               If set to "last-folder-used", then Pine  will
               offer  to  save  in  whatever folder you used
               previously.


          _s_i_g_n_a_t_u_r_e-_f_i_l_e
               Names the file to be included as  the  signa-
               ture.   This defaults to ~/._s_i_g_n_a_t_u_r_e on UNIX
               and <_P_I_N_E_R_C _d_i_r_e_c_t_o_r_y>\_P_I_N_E._S_I_G on a PC.


          _s_m_t_p-_s_e_r_v_e_r
               One or more SMTP servers  (host  name  or  IP
               address)  which  Pine  will  use for outgoing
               mail.  If not set, Pine passes outgoing email
               to the _s_e_n_d_m_a_i_l program on the local machine.
               PC-Pine users must have this variable set  in
               order  to  send mail as they have no _s_e_n_d_m_a_i_l
               program.


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


          _s_t_a_n_d_a_r_d-_p_r_i_n_t_e_r
               System-wide configuration file only.   Speci-
               fies the command for printer selection number
               2 on the printer menu.  Unix only.


          _u_s_e-_o_n_l_y-_d_o_m_a_i_n-_n_a_m_e
               Can be set to _y_e_s or _n_o.  At this point  any-
               thing  but  _y_e_s  means _n_o.  If set to _y_e_s the
               first label in the host name will  be  lopped
               off  to  get  the  domain name and the domain


                           - 37 -







                  - Pine Technical Notes -


               name will be used for outgoing mail and such.
               That    is,    if    the    host    name   is
               _c_a_r_s_o_n._u._e_x_a_m_p_l_e._e_d_u and this variable is set
               to  _y_e_s,  then  _u._e_x_a_m_p_l_e._e_d_u will be used on
               outgoing  mail.   Only  meaningful  if  _u_s_e_r-
               _d_o_m_a_i_n is NOT set.


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


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


          _w_i_n_d_o_w-_p_o_s_i_t_i_o_n
               Winsock version  of  PC  Pine  only.   Window
               position in the format:  CxR+X+Yn Where C and
               R are the window size in characters and X and
               Y  are  the  screen  position of the top left
               corner of the window.



          _R_e_t_i_r_e_d _V_a_r_i_a_b_l_e_s

          Variables that are no longer used by  the  current
          Pine   version.   When  an  obsolete  variable  is
          encountered, its  value  is  applied  to  any  new
          corresponding  setting  and  a  comment  is  place
          before it noting that it is  no  longer  in  used.
          The  replaced  values at the time of this document
          include:


          _e_l_m-_s_t_y_l_e-_s_a_v_e
               Replaced by _s_a_v_e_d-_m_s_g-_n_a_m_e-_r_u_l_e


          _f_e_a_t_u_r_e-_l_e_v_e_l
               Replaced by _f_e_a_t_u_r_e-_l_i_s_t.


          _h_e_a_d_e_r-_i_n-_r_e_p_l_y
               Replaced by  _i_n_c_l_u_d_e-_h_e_a_d_e_r-_i_n-_r_e_p_l_y  in  the
               _f_e_a_t_u_r_e-_l_i_s_t.


9

9                           - 38 -







                  - Pine Technical Notes -


          _o_l_d-_s_t_y_l_e-_r_e_p_l_y
               Replaced  by   _s_i_g_n_a_t_u_r_e-_a_t-_b_o_t_t_o_m   in   the
               _f_e_a_t_u_r_e-_l_i_s_t.


          _s_a_v_e-_b_y-_s_e_n_d_e_r
               Replaced by _s_a_v_e_d-_m_s_g-_n_a_m_e-_r_u_l_e.


          _s_h_o_w-_a_l_l-_c_h_a_r_a_c_t_e_r_s
               No replacement, it always works this way now.



          _P_i_n_e _i_n _F_u_n_c_t_i_o_n _K_e_y _M_o_d_e

          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  con-
          trol  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 _p_i_n_e -_k or (on some UNIX
          systems) _p_i_n_e_f.  On a UNIX system, you can link or
          copy  the  _p_i_n_e  executable  to  _p_i_n_e_f  to install
          _p_i_n_e_f.  Alternatively, users and systems  adminis-
          trators  can  set the _u_s_e-_f_u_n_c_t_i_o_n-_k_e_y_s feature in
          the personal  or  system-wide  Pine  configuration
          file.   The  command  menus  at  the bottom of the
          screen will show _F_1-_F_1_2 instead of the  alphabetic
          commands.   In  addition, the help screens will be
          written in terms of function keys and  not  alpha-
          betic 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  34  commands are opera-
          tional; function-key users can get to all of them,
          just not all at once.


9

9                           - 39 -







                  - Pine Technical Notes -


          _D_o_m_a_i_n _S_e_t_t_i_n_g_s

          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).  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 _u_s_e_r-_d_o_m_a_i_n in  the
               system fixed configuration file

               (2) Value of the variable _u_s_e_r-_d_o_m_a_i_n in  the
               personal configuration file

               (3) Value of the variable _u_s_e_r-_d_o_m_a_i_n is  the
               system-wide configuration file

               (4) Value from  an  external  database  (DNS,
               /_e_t_c/_h_o_s_t_s,  NIS)  as  modified  by  a system
               fixed configuration file if  _u_s_e-_d_o_m_a_i_n-_n_a_m_e-
               _o_n_l_y set to "yes"

               (5) Value from  an  external  database  (DNS,
               /_e_t_c/_h_o_s_t_s,  NIS)  as  modified by a personal
               configuration  file  if  _u_s_e-_d_o_m_a_i_n-_n_a_m_e-_o_n_l_y
               set to "yes"

               (6) Value from  an  external  database  (DNS,
               /_e_t_c/_h_o_s_t_s, NIS) as modified by a system con-
               figuration file if  _u_s_e-_d_o_m_a_i_n-_n_a_m_e-_o_n_l_y  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  _u_s_e_r-_d_o_m_a_i_n  variable.   The  variable
          _u_s_e-_o_n_l_y-_d_o_m_a_i_n-_n_a_m_e   is  helpful  if  your  site
          supports/requires  hostless  addressing,  but  for
          some  reason you don't want to use the _u_s_e_r-_d_o_m_a_i_n
          variable.

9

9                           - 40 -







                  - Pine Technical Notes -


          A new feature in 3.90 is called  _u_s_e_r-_l_o_o_k_u_p-_e_v_e_n-
          _i_f-_d_o_m_a_i_n-_m_i_s_m_a_t_c_h.   This will cause the personal
          name field to be looked up from the password  file
          even if the domain of an address isn't a substring
          of the local host name.  See the  online  help  in
          the Setup/Config screen for full information.



          _S_y_n_t_a_x _f_o_r _C_o_l_l_e_c_t_i_o_n_s

          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 col-
          lections 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 _f_o_l_d_e_r-_c_o_l_l_e_c_t_i_o_n_s variable in the Pine confi-
          guration file.  _F_o_l_d_e_r-_c_o_l_l_e_c_t_i_o_n_s takes a list of
          one  or  more  collections, each (optionally) pre-
          ceded 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.  Collec-
          tions are  always  defined  in  the  configuration
          file;  there  is no time that Pine will ever ask a
          question which requires a user to input a  collec-
          tion  specifier.   This might change in the future
          if/when the Goto  command  is  extended  to  allow
          jumping  to  a  collection/directory as well as an
          individual folder.

          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


                           - 41 -







                  - Pine Technical Notes -


          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 fold-
          ers 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  direc-
          tory.   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  _f_o_l_d_e_r-
          _c_o_l_l_e_c_t_i_o_n_s has special significance.  That folder
          is the "default collection for saves".   In  cases
          where  the  user does not specify which collection
          should be used to save a message, the default col-
          lection  for  saves  will  be  used.  Also, if the
          _d_e_f_a_u_l_t-_f_c_c is a relative file name,  then  it  is
          relative to the default collection for saves.

          The notion of collections encompasses  both  email
          folders  and  news  reading.   The  variable _n_e_w_s-
          _c_o_l_l_e_c_t_i_o_n_s  uses  nearly  the  same   format   as


                           - 42 -







                  - Pine Technical Notes -


          _f_o_l_d_e_r-_c_o_l_l_e_c_t_i_o_n_s.  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 main-
          tained on it.  The downside is that  each  client,
          for  now, must individually maintain news environ-
          ment state.

          An example pinerc entry might be:

                   news-collections=  Remote-State    *{news.u.example.edu}[],
                                      Local-State     *{news.u.example.edu/nntp}[]

          Note that each news collection must be preceded by
          a  '*'  to  indicate  non-mail access.  Only news-
          groups 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}[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.



          _S_y_n_t_a_x _f_o_r _R_e_m_o_t_e _F_o_l_d_e_r_s

          Remote folders are distinguished from local  fold-
          ers  by  a  leading host name bracketed by '{' and
          '}'.  The path and folder name immediately follow-
          ing  the  closing  bracket, '}', is interpreted by
          the IMAP server and is in a form  compatible  with
          that server (i.e., path delimiters and naming syn-
          tax relative to that server).

          Typically, a folder name without any path descrip-
          tion  is  understood to reside in the user's "home
          directory" (i.e., in some way the user's personal,


                           - 43 -







                  - Pine Technical Notes -


          writable file area), as are incomplete path desig-
          nations.  However, the IMAP specification does not
          require  that  unqualified  folder  names  live in
          one's home directory, so  some  IMAP  servers  may
          require  fully  qualified  names.  An example of a
          remote folder specification would be,

                      {mailhost.cac.washington.edu}mail/saved-messages

          This  example  simply  specifies  a  folder  named
          "saved-messages"     on     the     imap    server
          "mailhost.cac.washington.edu", in the "mail"  sub-
          directory  of  the  user's  home  directory.  Easy
          isn't it?

          To confuse things a bit, qualifiers are  permitted
          within  the  brackets  following  the  host  name.
          These qualifiers consist of a slash, '/' character
          followed  by a keyword or keyword and value equal-
          ity, and have the effect of modifying how the con-
          nection is made to the host specified.  An example
          of such a specification might be,

                      *{pine.cac.washington.edu/anonymous}updates

          Another example might be,

                      *{news.u.washington.edu/nntp}comp.mail.mime


          Both of  these  examples  illustrate  a  different
          qualifier.    The  first,  specifying  "anonymous"
          access     to     the     IMAP      server      on
          "pine.cac.washington.edu".     The    second    is
          interesting in that  it  specifies  an  altogether
          different  access  method:  access via the Network
          News Transport  Protocol  (NNTP).   Both  examples
          bring  to light one remaining subtlety.  The lead-
          ing "*" tells pine to treat the remote folder as a
          Bulletin-Board  (i.e.,  typically  a shared, read-
          only resource) and to adjusts its behavior accord-
          ingly.


          _S_o_r_t_i_n_g _a _F_o_l_d_e_r

          The mail index may be  sorted  by  subject,  size,
          sender,  date,  or arrival 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  -
          _s_o_r_t  flag  or  (equivalently)  with  the _s_o_r_t-_k_e_y
          variable in the ._p_i_n_e_r_c file.  When a user changes


                           - 44 -







                  - Pine Technical Notes -


          folders, the sort order will go back to the origi-
          nal sort order.  The command line (-_s_o_r_t) or  con-
          figuration   file  sort  specification  (_s_o_r_t-_k_e_y)
          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 actu-
          ally two forms of subject sort.  One called  "Sub-
          ject"  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.  The sort by sender sorts  by  the  userid,
          not  the full name.  The arrival sort is basically
          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 exam-
          ined.  Pine will show progress as it is sorting.


          _A_l_t_e_r_n_a_t_e _E_d_i_t_o_r

          In the Pine composer you can use any text  editor,
          such  as  _v_i  or  _e_m_a_c_s, for composing the message
          text.  The addresses and  subject  still  must  be
          edited  using  the standard Pine composer.  If you
          include the feature _e_n_a_b_l_e-_a_l_t_e_r_n_a_t_e-_e_d_i_t_o_r-_c_m_d in
          your  ._p_i_n_e_r_c you can type ^_ while in the body of
          the message in the composer and  be  prompted  for
          the  editor.   If you also set the _e_d_i_t_o_r variable
          in your ._p_i_n_e_r_c then ^_ will invoke the configured
          editor when you type it.

9

9                           - 45 -







                  - Pine Technical Notes -


          Turning on  the  feature  _e_n_a_b_l_e-_a_l_t_e_r_n_a_t_e-_e_d_i_t_o_r-
          _i_m_p_l_i_c_i_t_l_y  will  automatically  invoke the editor
          you have defined with the _e_d_i_t_o_r 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 alter-
          nate 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.


          _S_i_g_n_a_t_u_r_e_s _a_n_d _S_i_g_n_a_t_u_r_e _P_l_a_c_e_m_e_n_t

          If    the    file    ~/._s_i_g_n_a_t_u_r_e    (UNIX)     or
          <_P_I_N_E_R_Cdirectory>\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 set-
          ting the _s_i_g_n_a_t_u_r_e-_f_i_l_e variable in  the  ._p_i_n_e_r_c.
          There  is  no  way  to have Pine include different
          signatures in different outgoing messages automat-
          ically.  You can do this by hand, however, by hav-
          ing multiple signature files (._s_i_g_1, ._s_i_g_2, ._s_i_g_3,
          _e_t_c)  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 conven-
          tions, 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   _s_i_g_n_a_t_u_r_e-_a_t-_b_o_t_t_o_m
          feature  in  the _f_e_a_t_u_r_e-_l_i_s_t.  The signature will
          then be appended to the end of the  message  after
          any  included  text.   This  feature  applies when
          replying, not when forwarding.



9

9                           - 46 -







                  - Pine Technical Notes -


          _F_e_a_t_u_r_e _L_i_s_t _V_a_r_i_a_b_l_e

          Pine used to have _f_e_a_t_u_r_e _l_e_v_e_l_s  for  users  with
          different  amounts  of  experience.  We found that
          this  was  too  restrictive.   Pine  now   has   a
          _f_e_a_t_u_r_e-_l_i_s_t  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 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 _f_e_a_t_u_r_e-_l_i_s_t 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  per-
          sonal  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 _f_e_a_t_u_r_e-_l_i_s_t in  the  system-wide
          _f_i_x_e_d  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 _f_e_a_t_u_r_e-_l_i_s_t 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 per-
          sonal configuration value  on  the  command  line.
          For example, if the system-wide default configura-
          tion has the _q_u_i_t-_w_i_t_h_o_u_t-_c_o_n_f_i_r_m feature set, the
          user  can  over-ride  that  (and  turn  it off) by
          including _n_o-_q_u_i_t-_w_i_t_h_o_u_t-_c_o_n_f_i_r_m in the  personal
          configuration  file  or by giving the command line
          argument    -_f_e_a_t_u_r_e-_l_i_s_t=_n_o-_q_u_i_t-_w_i_t_h_o_u_t-_c_o_n_f_i_r_m.
          More  features (options) will no doubt continue to
          be added.


                           - 47 -







                  - Pine Technical Notes -


          _A_d_d_i_t_i_o_n_a_l _N_o_t_e_s _o_n _P_C-_P_i_n_e

          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 addi-
          tional 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 host name included in the X-Sender line  pro-
          vide  some level of traceability by the recipient.
          However, this should not be considered a  rigorous
          form  of  authentication.   It is extremely light-
          weight, and is not a replacement for true  authen-
          tication.

          Hand in hand with authentication and accounting is
          user  information. Since PC-Pine has no user data-
          base to consult for _u_s_e_r-_i_d, _p_e_r_s_o_n_a_l-_n_a_m_e,  etc.,
          necessary  information  must  be  provided  by the
          user/installer before PC-Pine  can  properly  con-
          struct  the  "From"  address required for outbound
          messages. PC-Pine will, by default, prompt for the
          requisite  pieces as they are needed.  This infor-
          mation corresponds to the _P_I_N_E_R_C  variables  _u_s_e_r-
          _i_d, _p_e_r_s_o_n_a_l-_n_a_m_e, _u_s_e_r-_d_o_m_a_i_n, and _s_m_t_p-_s_e_r_v_e_r.

          The user is then asked whether or not this  infor-
          mation   should  automatically  be  saved  to  the
          _P_I_N_E_R_C.  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 _P_I_N_E_R_C 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 _P_I_N_E_R_C will be offered.

9

9                           - 48 -







                  - Pine Technical Notes -


          Along similar lines, a feature allowing  automatic
          login  to  the  imap-server  containing the user's
          _I_N_B_O_X has also been requested.   This  feature  is
          not enabled by default, but requires the existence
          of the file named _P_I_N_E._P_W_D in the  same  directory
          as  the  _P_I_N_E_R_C.   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 _P_I_N_E._P_W_D file for use  in  subsequent  ses-
          sions.

          _W_A_R_N_I_N_G!  Use this feature with caution! It effec-
          tively  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.  _B_E_W_A_R_E!

          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
          _T_M_P  and  _T_E_M_P  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.

















9

9                           - 49 -







                  - Pine Technical Notes -


                     _S_e_c_t_i_o_n _6-_B_e_h_i_n_d _t_h_e _S_c_e_n_e_s



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



          _A_d_d_r_e_s_s _B_o_o_k_s

          The  address  book  file  is  named,  by  default,
          ._a_d_d_r_e_s_s_b_o_o_k in the user's Unix home directory, or
          in the case of  PC-Pine,  _A_D_D_R_B_O_O_K,  in  the  save
          directory  as  the _P_I_N_E_R_C file.  There may be more
          than one address book, and the default name can be
          over-ridden via an entry in any of the Pine confi-
          guration files.  The two  configuration  variables
          _a_d_d_r_e_s_s-_b_o_o_k  and  _g_l_o_b_a_l-_a_d_d_r_e_s_s-_b_o_o_k are used to
          specify the file 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 a file name.  The nickname is
          everything up to the last space  before  the  file
          name.  The _g_l_o_b_a_l-_a_d_d_r_e_s_s-_b_o_o_k list will typically
          be configured  in  the  system-wide  configuration
          file,  though  a  user  may over-ride it like most
          other variables.  Address books which  are  listed
          in  the  _g_l_o_b_a_l-_a_d_d_r_e_s_s-_b_o_o_k  variable  are forced
          read-only, and are typically shared among multiple
          users.

          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  begin-
          ning  with  SPACE characters.  The line breaks may
          be after TABS or in between addresses in a distri-
          bution list.

          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  (for  example:
          spaces, commas, "@", ...).


                           - 50 -







                  - Pine Technical Notes -


          The fullname field is usually stored as Last_name,
          First_name,  in  order that a sort on the fullname
          field comes out right.  If there is a 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,  depend-
          ing  on  whether  the  entry  is a single (simple)
          address or a  distribution  list.   For  a  simple
          entry, the address field is the email-address part
          of the address, i.e., the part  that  goes  inside
          the  brackets  (<>).   It  is  combined  with  the
          fullname field to form the complete address.   For
          a  distribution list, the <address> is in the for-
          mat:

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


          Unlike  the  simple  entry  case,  each   of   the
          addresses  in a list can be a full RFC 822 address
          with fullname included, or it may be just the same
          as  in  the  simple case.  This way you can 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  this  is
          detected and flagged.  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.  Neither the fcc
          nor the comments field is normally  shown  on  the
          screen  in  the address book screen.  You can only
          see them by Editing them.   You  may  also  search
          them with the WhereIs command.

9

9                           - 51 -







                  - Pine Technical Notes -


          The address book is displayed in the order that it
          is  sorted  in  the file.  When the user chooses a
          different sorting criterion, the file is  actually
          sorted, not just the view of the file.

          When the address book is written out, it is  first
          written  to  a temporary file and if that write is
          successful it is renamed correctly.   This  guards
          against errors writing the file that might destroy
          the whole address book.  The address book  is  re-
          written after each change.

          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.   How-
          ever,  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 charac-
          ter  for the LookUp file is always just <LF>, even
          on a PC.  There is not currently any method  built
          into Pine to access a remote address book (through
          IMAP or something like that).   The  only  sharing
          possible  is  via some external remote file system
          or copying.  It is very likely that a future  ver-
          sion of Pine will be able to access remote address
          books using IMSP, when that  becomes  standardized
          and available.


          _A_d_d_r_e_s_s _B_o_o_k _L_o_o_k_u_p _F_i_l_e

          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.  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  per-
          mission  to  create the lookup file with the stan-
          dard 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


                           - 52 -







                  - Pine Technical Notes -


          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 (root, for example) or by using the
          -_c_r_e_a_t_e__l_u command line argument to Pine (as root,
          still).   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 copy-
          ing over it.  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 initializing the new file.

          An effort is made to detect that an  address  book
          has  been changed by another process.  If a change
          is detected, the address book will be closed  down
          and  a  new  open  will  be attempted.  If the new
          lookup file is in place when the open is tried, it
          will  work smoothly.  In normal operation (lookups
          and browsing the address book) the check to see if
          it  has  changed  is just a heuristic to notice if
          things seem right.  It isn't more rigorous because
          it  needs  to  be fast.  When a lookup is done, an
          offset into the address book is  gotten  from  the
          LookUp  file  and  a seek into the address book is
          done.  It will check to see if the preceding char-
          acter is an end-of-line character, which it should
          be.  If it isn't, it figures it needs  to  rebuild
          the LookUp file.  When an address book is about to
          be changed,  a  more  fool-proof  check  is  made.
          Several things in the file are checked to see that
          it is a LookUp file (magic number, size, ...)  and
          that it is whole.  Then, a timestamp in the LookUp
          file is compared to the mtime of the address book.
          If  the  timestamp is later than the mtime, every-
          thing is ok, otherwise, the address book has  been
          changed and the new change is aborted.

          The address book code has been completely  rewrit-
          ten for 3.90 and production experience with shared
          address books is nil at the time of this  writing.
          We  expect there may be some changes as experience
          is gained, and that  some  new  tools  may  emerge
          (scripts  to  convert  password  files  to  shared
          address books, for example).




9

9                           - 53 -







                  - Pine Technical Notes -


          _C_h_e_c_k_p_o_i_n_t_i_n_g

          Periodically Pine will save the whole mail  folder
          to disk to prevent loss of any mail or mail status
          in the case that Pine  gets  interrupted,  discon-
          nected, 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 hap-
          pens  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  out-
                         standing  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 check-
                         point if at least 48  changes  have
                         been  made  or  one change has been
                         made in  the  last  twenty  minutes
                         with no checkpoint.



          _D_e_b_u_g _F_i_l_e_s

          If UNIX Pine is compiled with the  compiler  _D_E_B_U_G
          option  on  (the  default), then Pine will produce
          debugging output to a file. The file  is  normally
          ._p_i_n_e-_d_e_b_u_g_X  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


                           - 54 -







                  - Pine Technical Notes -


          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
          _P_I_N_E_D_E_B_G._T_X_T  in  the same directory as the _P_I_N_E_R_C
          file.


          _F_i_l_t_e_r_s

          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 pro-
          gram and with Procmail.

          Design changes introduced in Pine 3.8x  facilitate
          Pine users filtering email.  You still have to get
          a filtering program and  configure  it  correctly,
          but  Pine  now  allows  users  to specify a set of
          _i_n_c_o_m_i_n_g-_f_o_l_d_e_r_s.  Pine will separate out all  the
          folders  listed as _i_n_c_o_m_i_n_g-_f_o_l_d_e_r_s and offer con-
          venient access to these.   We  hope  that  in  the
          future  Pine  will  be  able  to offer new message
          counts for all of the incoming folders.



          _F_o_l_d_e_r _F_o_r_m_a_t_s _a_n_d _N_a_m_e _E_x_t_e_n_s_i_o_n_s

          A folder is a group of messages.  The default for-
          mat used by Unix Pine is the Berkeley mail format.
          It is also used by the standard _m_a_i_l  command  and
          by  _e_l_m.  Unix Pine also understands message fold-
          ers in other formats, such  as  Tenex,  MH,  MMDF,
          Carmel,  and  Netnews. (For more information about
          the   carmel    format,    see    the    directory
          ./_c_o_n_t_r_i_b/_c_a_r_m_e_l in the Pine distribution.)

          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 Read-Only driver for the Berkeley mail-
          box  format  in addition.  That means that you can


                           - 55 -







                  - Pine Technical Notes -


          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"  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 READ-ONLY) 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 com-
          mand, once you have changed to  your  mail  direc-
          tory:  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


                           - 56 -







                  - Pine Technical Notes -


          "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,  /_b_i_n/_m_a_i_l.   (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 varia-
               tions in the date part of the string,  twenty
               at  last  count. Because of the format of the
               separators, lines in the mail message  begin-
               ning with "From ", space included, risk being
               confused as message  separator  lines.   Some
               mail  programs will interpret any line begin-
               ning 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 modi-
               fied  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 for-
               mat.

9

9                           - 57 -







                  - Pine Technical Notes -


          Tenex and MTX Formats
               Like the Berkeley format,  the  Tenex  folder
               format  uses  a single file per folder.  His-
               torically, the name of  Tenex-format  folders
               ended  with  ._t_x_t, 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  mes-
               sage  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
               _m_a_i_l._t_x_t  exists in a Pine user's home direc-
               tory, this  triggers  special  processing  in
               Pine. When INBOX is opened, mail is automati-
               cally   moved   from   /_u_s_r/_s_p_o_o_l/_m_a_i_l   into
               _m_a_i_l._t_x_t in the user's home directory.

9

9                           - 58 -







                  - Pine Technical Notes -


               The format used by PC-Pine  is  identical  to
               the  Tenex  format, with two exceptions:  the
               folder name ends with ._M_T_X  instead  of  ._t_x_t
               (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  read-only  format
               which  uses directories under /usr/spool/news
               as folders.  The /_u_s_r/_s_p_o_o_l/_n_e_w_s/  prefix  is
               removed  and all subsequent "/" (slash) char-
               acters are changed to "." (period). For exam-
               ple,  the  netnews folder name _c_o_m_p._m_a_i_l._m_i_s_c
               refers     to     the     directory      name
               /_u_s_r/_s_p_o_o_l/_n_e_w_s/_c_o_m_p/_m_a_i_l/_m_i_s_c.  In addition,
               the news folder name must appear in the  file
               /usr/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  mes-
               sage.




          _F_o_l_d_e_r _L_o_c_k_i_n_g

          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 (_s_e_n_d_m_a_i_l 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  mes-
          sages,  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 _x_x_x_x._l_o_c_k (where
          _x_x_x_x is the name of the file being locked) in  the
          same  directory  as  the  file  being locked. This


                           - 59 -







                  - Pine Technical Notes -


          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 _f_l_o_c_k() sys-
          tem call on the mailbox.  This is much more  effi-
          cient  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 par-
          ticular folder  (usually  INBOX)  with  Pine  will
          "win"and  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  _M_a_i_l_M_a_n_a_g_e_r, _m_s, _I_M_A_P_d and a few others.
          Beginning with Pine 3.85, there is an  -_o  command
          line  flag  to  intentionally open a mailbox read-
          only.

          Pine locking on UNIX  systems  works  by  creating
          lock     files     in    /_t_m_p    of    the    form
          \_u_s_r\_s_p_o_o_l\_m_a_i_l\_j_o_e.  The system call  _f_l_o_c_k()  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.  _e_l_m or _m_a_i_l) is run while


                           - 60 -







                  - Pine Technical Notes -


          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.



          _I_N_B_O_X _a_n_d _S_p_e_c_i_a_l _F_o_l_d_e_r_s

          The _I_N_B_O_X folder is treated specially.  It is nor-
          mally  kept open constantly so that the arrival of
          new mail can be detected.  The name  _I_N_B_O_X  refers
          to  wherever  new mail is retrieved on the system.
          If the _i_n_b_o_x-_p_a_t_h  variable  is  set,  then  _I_N_B_O_X
          refers  to that.  IMAP servers understand the con-
          cept  of   _I_N_B_O_X,   so   specifying   the   folder
          {_i_m_a_p._u._e_x_a_m_p_l_e._e_d_u}_I_N_B_O_X  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 fold-
          ers are also somewhat special.  They are automati-
          cally created if they are absent and recreated  if
          they are deleted.



          _I_n_t_e_r_n_a_l _H_e_l_p _F_i_l_e_s

          The file _p_i_n_e._h_l_p in the _p_i_n_e 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 _p_i_n_e._h_l_p file is in a spe-
          cial 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.  Some special formatting rules are  used
          to keep things lined up and to allow for substitu-
          tions in the help text depending  on  whether  the
          Pine  session  uses  function keys or the standard
          alphabetic/mnemonic keys.  This file is  processed
          by  two  awk  scripts and turned into C files that
          are compiled into Pine.

          This scheme can increase efficiency  because  Pine
          can  be  compiled  to  have the strings as part of


                           - 61 -







                  - Pine Technical Notes -


          shared, read-only text.  Rather than each  process
          having  to  read in the help text from a file, the
          strings are shared by all executing  processes  on
          the  machine  and  demand  paged.   This  works on
          machines that have separate instruction  and  data
          space,  but  is only fully implemented in the NeXT
          (tested) and Dynix (not tested) ports.

          PC-Pine, which tries to run on  machines  with  as
          little  as  640k  of  memory, leaves the Pine help
          text out of the executable.   _P_I_N_E._E_X_E,  _P_I_N_E._H_L_P,
          and  _P_I_N_E._N_D_X  are  all  needed for PC-Pine's help
          system.



          _I_n_t_e_r_n_a_t_i_o_n_a_l _C_h_a_r_a_c_t_e_r _S_e_t_s

          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 _c_h_a_r_a_c_t_e_r-_s_e_t.


          When reading incoming email, Pine allows all char-
          acter 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  _c_h_a_r_a_c_t_e_r-_s_e_t
          variable.   Again, it is up to the input device to
          generate the correct sequences for  the  character
          set  being  used.  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  _c_h_a_r_a_c_t_e_r-_s_e_t
          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.

          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


                           - 62 -







                  - Pine Technical Notes -


              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


          In all of these except Japanese, the lower 7  bits
          are  the  same as US-ASCII.  Even in Japanese, the
          character set is the same as  US-ASCII  unless  it
          has been shifted to an alternate interpretation.

          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 _c_h_a_r_a_c_t_e_r-_s_e_t vari-
          able 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 _c_h_a_r_a_c_t_e_r-_s_e_t variable is set to, then a warn-
          ing  is  printed  at the start of the message.  In
          that case, it is possible that the  text  will  be
          displayed  incorrectly.   For example, if the text
          is one variant of ISO-8859 and the display  device
          is  another  variant,  some  of the characters may
          show up on the screen as the wrong character.   Or
          if  the text is Japanese and the display device is
          not, some  parts  of  the  message  may  be  total
          gibberish  (which will look like ASCII gibberish).
          On the other hand, the parts of the Japanese  mes-
          sage  that really are US-ASCII will be readable in
          the midst of the gibberish.

          In the case of PC-Pine, the character values  can-
          not  be passed through to the display device unal-
          tered  since  MS-DOS  uses  various   non-standard


                           - 63 -







                  - Pine Technical Notes -


          character sets called "Code Pages".

          The mapping between DOS  Code  Page  and  standard
          character set is controlled by the "character-set"
          variable in the PINERC file and the PC's installed
          Code  Page.  PC-Pine will automatically map common
          characters in IBM Code Pages 437, 850,  860,  863,
          and 865 to ISO-8859-1 and back when the PINERC has
          "character-set=ISO-8859-1".  Pine  will  also  map
          common  characters  for  IBM Code Page 866 to ISO-
          8859-5 and back  when  "character-set=ISO-8859-5".
          The  mappings  are  bi-directional, and applied to
          all saved text attachments in the defined  charac-
          ter set, messages exported, etc.

          Alternatively, the translation tables can be  con-
          figured  externally  and applied at run time when-
          ever the "character-set=" variable is set to some-
          thing  other  then  "US-ASCII" (the default).  PC-
          Pine looks in the text  file  pointed  to  by  the
          environment  variable "ISO_TO_CP" for the table to
          use for mapping text matching the type defined  by
          the  "character-set=" variable into the local Code
          Page  value.   PC-Pine  looks  in  the  text  file
          pointed to by the environment variable "CP_TO_ISO"
          for the table to use for mapping text in the local
          Code  Page  into  outbound  text  tagged  with the
          "character-set=" variable's value.

          A text file containing  a  character  set  mapping
          table  is  expected  to contain 256 elements where
          each element is a decimal  number  separated  from
          the  next  element  by  white-space (space, tab or
          newline, but no commas!).  The index of  the  ele-
          ment  is the character's value in the source char-
          acter  set,  and  the  element's  value   is   the
          corresponding character's value in the destination
          character set.



          _I_n_t_e_r_r_u_p_t_e_d _a_n_d _P_o_s_t_p_o_n_e_d _M_e_s_s_a_g_e_s

          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 con-
          tinue 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  con-
          tinue  the interrupted message, simply go into the
          composer.  To get rid of the interrupted  message,
          go  into  the composer and then cancel the message


                           - 64 -







                  - Pine Technical Notes -


          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.


          _M_e_s_s_a_g_e _S_t_a_t_u_s

          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 _e_x_p_u_n_g_e_s
          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 _F_l_a_g com-
          mand 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  dif-
          ferent  from  others.  It will usually probably be
          used to mark a message as  somehow  being  "impor-
          tant".   For  Berkeley format folders, the message
          status is written into the email folder itself  on
          the  header lines marked _S_t_a_t_u_s: and _X-_S_t_a_t_u_s.  In
          Tenex and PC-Pine's MTX folder formats, the status
          goes into the 36-bit octal flags.



          _M_I_M_E-_R_e_a_d_i_n_g _a _M_e_s_s_a_g_e

          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 "mail-
          cap"  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


                           - 65 -







                  - Pine Technical Notes -


          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  han-
          dling MIME-encoded data.

          If a $MAILCAPS environment  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 _M_A_I_L_C_A_P in the  same  direc-
          tory as the _P_I_N_E_R_C file, and/or the directory con-
          taining the _P_I_N_E._E_X_E executable.

          Messages which include _r_i_c_h _t_e_x_t or _e_n_r_i_c_h_e_d  _t_e_x_t
          in  the main body will be displayed in a very lim-
          ited way (it will show bold and underlining).

          If Pine sees a MIME message part  tagged  as  type
          IMAGE,   and  Pine's  _i_m_a_g_e-_v_i_e_w_e_r.  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
          _i_m_a_g_e-_v_i_e_w_e_r  variable  is  not set, Pine uses the
          _m_a_i_l_c_a_p 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
          _m_a_i_l_c_a_p file will probably not specify any action,
          but Pine users may always Save any MIME attachment
          to a file.

          If  an  attachment  is  just  text  (tagged   with
          "text/plain"  in  the MIME header), then Pine will
          use an  internal  viewer  module  to  display  the
          attachment.    International   character  sets  in
          attachments are handled in the same  way  as  they
          are  in regular email messages.  Some text attach-
          ments, 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  attach-
          ment viewer when that is desirable (the plain text
          file attachment case).

9

9                           - 66 -







                  - Pine Technical Notes -


          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,  but  the
          retrieval  process is not yet automated.  Messages
          of type "message/partial" are not  currently  sup-
          ported.



          _M_I_M_E-_S_e_n_d_i_n_g _a _M_e_s_s_a_g_e

          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 encod-
          ing  is  similar  to  _u_u_e_n_c_o_d_e  or  _b_t_o_a  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 attach-
          ments  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 _i_n_c_l_u_d_e
          text (with the ^_R command) in the body of  a  mes-
          sage  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


                           - 67 -







                  - Pine Technical Notes -


          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.

          If it is not binary data (has only a small propor-
          tion 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  _c_h_a_r_a_c_t_e_r-_s_e_t  variable.   If  an
          attachment is ASCII (no 8-bit characters) and con-
          tains no _E_S_C_A_P_E, ^_N, or ^_O characters (the charac-
          ters  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 _c_h_a_r_a_c_t_e_r-_s_e_t variable.

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



          _N_e_w _M_a_i_l _N_o_t_i_f_i_c_a_t_i_o_n

          Pine checks for new mail in the _I_N_B_O_X and  in  the
          currently  open  folder  at  least every two and a
          half minutes.  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.  If you really  don't  want
          to wait you can force a new mail check by pressing
          _N _N_e_x_t with the cursor on the last message of  the
          message  index  or  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 rou-
          tines (biff,  csh,  login).   Firstly  and  unfor-
          tunately,  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


                           - 68 -







                  - Pine Technical Notes -


          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.


          _N_F_S

          It is possible  to  access  mail  folders  on  _N_F_S
          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  /_t_m_p  is  usually  not
          shared,  and  even if it was, _f_l_o_c_k() doesn't work
          across _N_F_S.

          The implementation of the  standard  UNIX  ".lock"
          file locking has been modified to work with _N_F_S as
          follows.  Standard hitching post locking  is  used
          so first a uniquely named file is created, usually
          something like _x_x_x_x._h_o_s_t._t_i_m_e._p_i_d.  Then a link to
          it  is  created  named  _x_x_x_x._l_o_c_k where the folder
          being locked is _x_x_x_x.  This file  constitutes  the
          lock.   This  is  a  standard UNIX locking scheme.
          After the link returns, a _s_t_a_t(_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  fold-
          ers,  e.g.  your  INBOX.  However, it is generally
          safe to access personal saved-message folders  via
          _N_F_S  since  it is unlikely that more than one pro-
          cess 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 per-
          form a write on the same folder.  Pine-B will  get
          upset  that  the file has been changed from under-
          neath 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


                           - 69 -







                  - Pine Technical Notes -


          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 _N_F_S problems.



          _P_r_i_n_t_e_r_s _a_n_d _P_r_i_n_t_i_n_g

          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, _a_t_t_a_c_h_e_d-_t_o-_a_n_s_i, 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>[6i" to
          return to normal.  Pine  will  send  these  escape
          sequences  if  the  printer is set to _a_t_t_a_c_h_e_d-_t_o-
          _a_n_s_i.  This works with most  ANSI/VT100  emulators
          on  Macs and PCs such as kermit, NCSA telnet, Ver-
          saTerm Pro, and WinQVT.  Various  terminal  emula-
          tors implement the print feature differently.  For
          example, NCSA telnet requires "capfile =  PRN"  in
          the  _c_o_n_f_i_g._t_e_l  file.   Attached-to-ansi printing
          doesn't work at all with the telnet provided  with
          PC-NFS.

          The second selection is the  standard  UNIX  print
          command.   The  default  is  _l_p_r,  but  it  can be
          changed on a system basis to anything  so  desired
          in /_u_s_r/_l_o_c_a_l/_l_i_b/_p_i_n_e._c_o_n_f.

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

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

          The three printer choices are for UNIX Pine  only.
          PC-Pine  for  DOS  can  only  print to the locally


                           - 70 -







                  - Pine Technical Notes -


          attached printer.  All printing on  PC-Pine  (DOS)
          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  char-
          acter,  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.


          _S_a_v_e _a_n_d _E_x_p_o_r_t

          Pine users get two options for moving messages  in
          Pine:   _s_a_v_e  and  _e_x_p_o_r_t.   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 _e_x_p_o_r_t 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  _u_s_e-_c_u_r_r_e_n_t-_d_i_r  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 _e_x_p_o_r_t, Pine
          retains  message  separators so that multiple mes-
          sages can accumulate in a single file  and  subse-
          quently be accessed as a folder.  On UNIX systems,
          the _e_x_p_o_r_t command pays attention to the  standard
          _u_m_a_s_k for the setting of the file permissions.



          _S_e_n_t _M_a_i_l

          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  car-
          bon  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 _d_e_f_a_u_l_t-_f_c_c="".   The  sent
          mail  folder  is  assumed  to  be  in  the default


                           - 71 -







                  - Pine Technical Notes -


          collection for saves, which is the  first  collec-
          tion named in _f_o_l_d_e_r-_c_o_l_l_e_c_t_i_o_n_s.  The name of the
          folder  can  be  chosen  by  entering  a  name  in
          _d_e_f_a_u_l_t-_f_c_c.  With PC-Pine, this can be a bit com-
          plicated.  If the default collection for saves  is
          local  (DOS),  then  the  _d_e_f_a_u_l_t-_f_c_c  needs to be
          "SENTMAIL", which is syntax for a DOS file.   How-
          ever,  if  the  default  collection  for  saves is
          remote, then the _d_e_f_a_u_l_t-_f_c_c needs  to  be  "sent-
          mail" to match the UNIX syntax.

          The  configuration  variable  _f_c_c-_n_a_m_e-_r_u_l_e   also
          plays  a role in selecting the folder to save sent
          mail in.  See the documentation on it in the  sec-
          tion on configuration variables.

          The 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  set-
          ting the configuration variable _d_e_f_a_u_l_t-_f_c_c="") or
          if the fcc folder is  a  remote/IMAP  folder  then
          there will be no pruning question.

          It is likely that Pine will be  improved  so  that
          users  can  set  the  time  increment  for pruning
          (weekly, monthly, yearly, never) but that has  not
          been implemented yet.




          _S_p_e_l_l _C_h_e_c_k_e_r

          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.

9

9                           - 72 -







                  - Pine Technical Notes -


          The default spell checker is UNIX _s_p_e_l_l.  You  can
          replace this at compile time for the whole system.
          Pine also respects the environment variable _S_P_E_L_L.
          If  it  is set, Pine will use that as the spelling
          checker.  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 alphabeti-
               cal  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
               /_u_s_r/_d_i_c_t/_h_l_i_s_t_a.  I named my  word  file
               ._b_o_b_w_o_r_d_s  and my dictionary ._b_o_b_s_p_e_l_l so
               I don't have to see them when I do  a  _l_s
               command (_l_s doesn't list "dot" files).  I
               also put the above command into my ._a_l_i_a_s
               file as the command _m_a_k_e_d_i_c_t so I can add
               a word to my word  file  and  easily  re-
               create  my  dictionary.   NOTE:   the new
               dictionary  is  in  something  called   a
               "hashed"  format,  and can't be read nor-
               mally.

          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 anoth-
               er 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 _S_P_E_L_L to
               access  your  dictionary.   Go  into your
               ._l_o_g_i_n or ._c_s_h_r_c file in your home direc-
               tory  (it  doesn't seem to make a differ-


                           - 73 -







                  - Pine Technical Notes -


               ence which one you use) and add the line

                                   setenv SPELL "spell -d [new dict name]"



               I also created an alias for _S_P_E_L_L  in  my
               ._a_l_i_a_s  file  so I can use the UNIX _s_p_e_l_l
               command to spell-check a file outside  of
               Pine.   (The ._a_l_i_a_s 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 ._l_o_g_i_n (or ._c_s_h_r_c)
               file.


          Here is an alternative method suggested by Zachary
          Leber:

               Create a  list  (e.g.  ._z_a_c_h_w_o_r_d_s)  with  the
               upper  case  followed  by  lower  case words,
               sorted alphabetically.

               Add this line to ._c_s_h_r_c:

                   setenv SPELL 'spell +/home/ie/rsa/.zachwords'


               The limitation here is that the path must  be
               absolute (e.g. +~/._z_a_c_h_w_o_r_d_s 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.




          _T_e_r_m_i_n_a_l _E_m_u_l_a_t_i_o_n _a_n_d _K_e_y _M_a_p_p_i_n_g

          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 ter-
          minals 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


                           - 74 -







                  - Pine Technical Notes -


          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 "pro-
          tected 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 _t_e_r_m_c_a_p or _t_e_r_-
          _m_i_n_f_o 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 _d_e_l_e_t_e key, so  the  _b_a_c_k_s_p_a_c_e  or
          _d_e_l_e_t_e  keys always works regardless of any confi-
          guration.  In an upcoming version, there  will  be
          an  option  to  have the _d_e_l_e_t_e key behave like ^D
          rather than ^H.

          Sometimes a communications program  or  communica-
          tions 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, _E_S_C _E_S_C _T  is  equivalent
          to ^_T.

          When a function key is pressed and Pine is in reg-
          ular  (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 unex-
          pected 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


                           - 75 -







                  - Pine Technical Notes -


              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 _t_e_r_m_c_a_p  to
          discover  them.   This is because _t_e_r_m_c_a_p is some-
          times incorrect, and because many users have  PC's
          running  terminal  emulators  that  don't  conform
          exactly to what they claim to emulate. Some  arrow
          keys  on old terminals send single control charac-
          ters 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 ._X_d_e_f_a_u_l_t_s file, include the  follow-
               ing "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\




9

9                           - 76 -







                  - Pine Technical Notes -


          2.   Start up Pine from an _x_t_e_r_m,  and  specify  a
               "resource  name".   This  resource  name will
               allow the user to specify resources for  Pine
               (that  deviate from the defaults).  For exam-
               ple, _x_t_e_r_m -_n_a_m_e _P_i_n_e -_e _p_i_n_e & (the resource
               name  _P_i_n_e  corresponds  to  the translations
               just added in the ._X_d_e_f_a_u_l_t_s file).













































9

9                           - 77 -







                  - Pine Technical Notes -


               _S_e_c_t_i_o_n _7-_N_o_t_e_s _f_o_r _P_o_r_t_i_n_g _a_n_d _M_o_d_i_f_i_c_a_t_i_o_n



          _P_o_r_t_i_n_g _P_i_n_e _t_o _O_t_h_e_r _P_l_a_t_f_o_r_m_s

          Substantial effort has gone into making  Pine/Pico
          portable.  There are still, of course, a number of
          machine  dependencies.   Some  of  the  ports  are
          well-tested and some are untested.  In particular,
          the most heavily used ports are the Ultrix,  NeXT,
          DOS, and PTX ports.

          Each platform is given a three  letter  name  (see
          the  file  _d_o_c/_p_i_n_e-_p_o_r_t_s).  Make up a new one for
          your new  port.   We've  attempted  to  bring  all
          potential  platform dependencies into three files:
          _o_s-_x_x_x._h, _o_s-_x_x_x._c, and _m_a_k_e_f_i_l_e._x_x_x where _x_x_x  is
          the  three  letter name of the port.  Thus any new
          port will hopefully just result in new versions of
          these  files  and  some  notes  for the _p_i_n_e-_p_o_r_t_s
          file.  There are actually nine new  files  needed,
          because  there  is  a set of these files in the c-
          client, Pico, and Pine  source  directories.   (As
          you  can tell by reading this technical note, Pine
          originated on Unix systems. There are still  prob-
          ably  many  Unix  dependencies built in, but these
          should be diminishing now that there are _D_O_S, _W_i_n_-
          _d_o_w_s, and _V_M_S ports.  Regrettably, the source code
          is full of instances  of  "ifdef  DOS".   Most  of
          these  are  due to memory limit problems on _D_O_S as
          opposed to actual system dependencies.

          The makefiles are kept  as  simple  and  straight-
          forward   as   possible,   because  many  previous
          attempts at automatically figuring out what to  do
          seem  to  have  become  complex and ineffective in
          what they set out to do:  which is to make compil-
          ing and installing the program easy.  Each port is
          for a specific  hardware/software  platform,  also
          because past attempts to generalize on versions of
          Unix or some CPU architecture don't seem  to  have
          gained  much.   Thus, there is a separate makefile
          for each platform that calls the appropriate  com-
          piler and linker with the appropriate flags.  Most
          of  these  makefiles  are  pretty  similar.    The
          makefile  also specifies which of the _o_s-_x_x_x._c and
          _o_s-_x_x_x._h files to use.  It is the root from  which
          all  platform  dependencies are selected.  In most
          cases the makefile also  defines  a  symbol  named
          after the platform on which there can be dependen-
          cies in the source code,  though  we've  tried  to
          minimize  relying on this where reasonable.  Pine,


                           - 78 -







                  - Pine Technical Notes -


          Pico, and the C-client don't quite  do  everything
          the  same  (there  are  at  least  three  separate
          authors involved).  Basically, to build the source
          in   one   of   the   directories,   run  _m_a_k_e  -_f
          _m_a_k_e_f_i_l_e._x_x_x where _x_x_x is the three-letter name of
          the  platform.   That's all the _b_u_i_l_d script does.
          When starting a new port in  the  _p_i_n_e  directory,
          there  is  a  generic makefile called _m_a_k_e_f_i_l_e._g_e_n
          which should be a good starting point.

          The file _o_s-_x_x_x._h is  used  for  general  platform
          dependent  #_i_n_c_l_u_d_e's  and  #_d_e_f_i_n_e_s.  In the _p_i_n_e
          directory these ._h files are located in the  _o_s_d_e_p
          subdirectory.   All  the  include  files that have
          been found to vary from one  platform  to  another
          are  also  included  here.   In  the case of Pico,
          there is only one _o_s-_x_x_x._h  file  called  _o_s-_u_n_x._h
          for most of the supported Unix ports and inside it
          are #_i_f_d_e_f_s based on the platform specific  symbol
          defined  in the makefile.  On the other hand, Pine
          now has a separate _o_s-_x_x_x._h file  for  each  plat-
          form.   There  are  a number of Pine configuration
          settings that are defined here, as well,  such  as
          the place it looks for certain files, defaults for
          the printer and folder names, the  maximum  screen
          size,  and  so  on.   For  the Pine portion of the
          port, start by looking  at  the  generic  _o_s-_g_e_n._h
          file  and comparing it to some of the specific _o_s-
          _x_x_x._h files in _o_s_d_e_p.

          The _o_s-_x_x_x._c  file  contains  functions  that  are
          potentially  platform  dependent.  Again, the idea
          is to gather all the dependencies  in  one  place.
          Pico  uses  the same strategy here as it uses with
          _o_s-_u_n_x._h.  That is, there  is  a  single  _o_s-_u_n_x._c
          file for most of the Unix ports.  Pine uses a com-
          plicated looking method to  produce  the  _o_s-_x_x_x._c
          file  from a set of included files.  Each included
          file usually contains a single function and  we've
          found  that  there  are usually only a couple dif-
          ferent implementations of  each  function  in  the
          ports  we've  done  so  far.  Hopefully, coming up
          with an _o_s-_x_x_x._c for a new port will usually be  a
          matter of including the right set of these already
          written functions.  This is done by writing a  new
          _o_s-_x_x_x._i_c  file  in the _o_s_d_e_p subdirectory.  Start
          with the generic _o_s-_g_e_n._i_c, as you  did  with  the
          _o_s-_g_e_n._h file above.

          We strongly encourage that no changes be  made  to
          the  general  source  when  porting  and  that all
          changes be  contained  in  the  three/nine  system
          dependent  files  if  possible.   The object is to


                           - 79 -







                  - Pine Technical Notes -


          maintain  source  code  integrity  and  assimilate
          ports  to new platforms rapidly.  The more conven-
          tional way to do this is with a  large  collection
          of  #_i_f_d_e_f_s.  The problem with this is that adding
          a port for a new  platform  implies  changing  the
          source  code  for  all  the  other  platforms  and
          thereby risks breaking them.   (We  readily  admit
          that  there are still too many _i_f_d_e_f_s in the code,
          but we haven't had time to devote to fully  clean-
          ing that up.)

          If you do port Pine to a new platform we hope that
          you  will  send us the changes required so that we
          may attempt to include  it  in  a  later  release.
          Thanks!



          _T_e_s_t _C_h_e_c_k_l_i_s_t

          The following is a checklist  of  some  things  to
          check when testing a new port:


          ___  Sending mail, check that headers are correct
          ___  Sending mail with attachments
          ___  Sending mail with SMTP server
          ___  Sending mail without SMTP server
          ___  Sending mail with list of two  SMTP  servers,
               first one doesn't answer
          ___  Replying to and forwarding a message
          ___  Postponing messages under composition
          ___  Composer operations
          ___  Alternate  editor,   enable-alternate-editor-
               implicitly
          ___  Make sure local user names are expanded
          ___  Test spelling checker
          ___  Catching of SIGHUP  while  message  is  being
               composed
          ___  Setting of variables in ._p_i_n_e_r_c
          ___  New mail notification.   Should  happen  with
               Pine idle to check timeouts
          ___  Reading mail (attachments,  MIME,  MIME  with
               mailcap viewers)
          ___  Deleting, undeleting, expunging, sorting
          ___  Expunge to empty folder
          ___  Make sure that ~ expansion  works  in  config
               files
          ___  Make sure that $VAR expansion works in config
               files
          ___  Save message to folder,  check  error  condi-
               tions such as permission denied
9

9                           - 80 -







                  - Pine Technical Notes -


          ___  Export message with FullHeaderMode on and off
          ___  Checkpointing (see the section on checkpoint-
               ing)
          ___  Open IMAP and RIMAP folders
          ___  Default-fcc on remote IMAP server
          ___  Fcc-name-rule, fcc in addrbook (while compos-
               ing)
          ___  Test opening bogus folders:  invalid  format,
               no permission
          ___  Open a USENET news  group,  list  in  folder-
               lister, read news, post news
          ___  Command line arguments
          ___  Change password
          ___  Lock keyboard
          ___  Address book operations (edit,  delete,  add,
               lists, whereis, composeto)
          ___  ReadOnly address book
          ___  Look at addrbook,  change  addrbook-sort-rule
               in Config, go back to addrbook screen
          ___  No permission to write in same  directory  as
               addrbook, should create addrbook.lu in a temp
               directory
          ___  Multiple address books
          ___  Address  book  loops  from  one  addrbook  to
               another and back
          ___  TakeAddr command with one address, with  mul-
               tiple addresses
          ___  TakeAddr command with ReadOnly address books
          ___  TakeAddr command  with  one  of  two  address
               books ReadOnly
          ___  Send mail with empty address book
          ___  Config  Screen  operation,  does  pinerc  get
               written?
          ___  Make sure SIGTSTP, ^Z works
          ___  Pinef
          ___  Sent-mail pruning (set back  _l_a_s_t-_t_i_m_e-_p_r_u_n_e-
               _q_u_e_s_t_i_o_n_e_d variable)
          ___  Printing using all three  printer  configura-
               tions, various screens
          ___  View help text and news
          ___  Folder  list  operations   (rename,   create,
               delete...)
          ___  Saved-msg-name-rule
          ___  Screen redrawing in various screens (^L)
          ___  Window resizing in various screens
          ___  Error messages for incorrect  terminal  types
               (try "foo" and "vt52")
          ___  Reading of /_u_s_r/_l_o_c_a_l/_l_i_b/_p_i_n_e._c_o_n_f
          ___  Fixing    variables    and    features     in
               /_u_s_r/_l_o_c_a_l/_l_i_b/_p_i_n_e._c_o_n_f._f_i_x_e_d
          ___  Flag command (check message status changed in
               mail folder)
9

9                           - 81 -







                  - Pine Technical Notes -


          ___  Initial-keystroke-list
          ___  Aggregate operations (save,  delete,  export,
               takeaddr, ...)
          ___  Build xxx from scratch, build clean
















































9

9                           - 82 -






























































9

9










                        - Pine Technical Notes -

                         Version 3.90, August 1994

               _S_e_c_t_i_o_n _1 - _I_n_t_r_o_d_u_c_t_i_o_n ...............    1
               History and Design Goals ...............    1
               Pine Components ........................    4
               _S_e_c_t_i_o_n _2 - _B_a_c_k_g_r_o_u_n_d _D_e_t_a_i_l_s .........    6
               Domain Names ...........................    6
               RFC 822 Compliance .....................    7
               SMTP and Sendmail ......................    8
               Internet  Message   Access   Protocol
                    (IMAP) ............................    9
               Multipurpose Internet Mail Extensions
                    (MIME) ............................   10
               Folder Collections .....................   12
               _S_e_c_t_i_o_n _3 - _B_u_i_l_d_i_n_g _a_n_d _I_n_s_t_a_l_l_a_t_i_o_n
                    ...................................   13
               UNIX Pine Compile-time Options .........   13
               Pico Compile-time Options ..............   15
               IMAPd Compile-time Options .............   15
               Buiding the Pine Programs ..............   15
               Installing  Pine  and  Pico  on  UNIX
                    Platforms .........................   16
               Installing PC-Pine .....................   17
               Installing IMAPd .......................   19
               Support Files and  Environment  Vari-
                    ables:  UNIX Pine .................   20
               Support Files and  Environment  Vari-
                    ables:  PC-Pine ...................   21
               _S_e_c_t_i_o_n _4 - _C_o_m_m_a_n_d _L_i_n_e _A_r_g_u_m_e_n_t_s .....   24
               _S_e_c_t_i_o_n _5 - _C_o_n_f_i_g_u_r_a_t_i_o_n _a_n_d _P_r_e_f_e_r-
                    _e_n_c_e_s .............................   28
               Pine Configuration .....................   28
               General Configuration Variables ........   30
               Retired Variables ......................   38
               Pine in Function Key Mode ..............   39
               Domain Settings ........................   40
               Syntax for Collections .................   41
               Syntax for Remote Folders ..............   43
               Sorting a Folder .......................   44
               Alternate Editor .......................   45
               Signatures and Signature Placement .....   46
               Feature List Variable ..................   47
               Additional Notes on PC-Pine ............   48
               _S_e_c_t_i_o_n _6-_B_e_h_i_n_d _t_h_e _S_c_e_n_e_s ............   50
               Address Books ..........................   50
               Checkpointing ..........................   54
               Debug Files ............................   54
               Filters ................................   55
               Folder Formats and Name Extensions .....   55
               Folder Locking .........................   59
               INBOX and Special Folders ..............   61













               Internal Help Files ....................   61
               International Character Sets ...........   62
               Interrupted and Postponed Messages .....   64
               Message Status .........................   65
               MIME-Reading a Message .................   65
               MIME-Sending a Message .................   67
               New Mail Notification ..................   68
               NFS ....................................   69
               Printers and Printing ..................   70
               Save and Export ........................   71
               Sent Mail ..............................   71
               Spell Checker ..........................   72
               Terminal Emulation and Key Mapping .....   74
               _S_e_c_t_i_o_n  _7-_N_o_t_e_s  _f_o_r   _P_o_r_t_i_n_g   _a_n_d
                    _M_o_d_i_f_i_c_a_t_i_o_n ......................   78
               Porting Pine to Other Platforms ........   78
               Test Checklist .........................   80



































9

9



