Pine 4.21 for OS/2
(C) 1989-1999 The University of Washington.
OS/2 Port by Nicholas Sheppard (nps@zeta.org.au)


INTRODUCTION
============

This is my OS/2 port of Pine 4.21, based on David Nugent's 3.9x port. David
is no longer maintaining Pine for OS/2, so please send all correspondence
to me, as I have taken over the OS/2 port as of version 4.10 (versions 4.00-
4.05 of Pine have no OS/2 port).

I have fixed all the serious bugs discovered in the 4.10 releases (though a
couple of minor ones remain -- see below), so I am hoping that this version
is at least as stable as the old 3.9x port, and as any other port of Pine.
Nonetheless, the usual you-get-what-you-pay-for warranty applies.

The latest information about Pine for OS/2 can be found on my web site at:

	http://www.zeta.org.au/~nps/software/pine/en/index.html

General information about Pine can be found at the University of Washington's
web site at:

	http://www.washington.edu/pine

General discussion about Pine, and help for configuration problems, can be
found by reading comp.mail.pine on Usenet. There is also a general group for
OS/2 news and e-mail applications, comp.os.os2.mail-news.



INSTALLATION
============

Pine requires the EMX run-time libraries to run. You can find these on Hobbes
as emxrt.zip in the directory /os2/dev/emx/v0.9d (or whatever version is
current). I compiled Pine with EMX version 0.9d, without any fixes. Install
these before doing anything else.

Before running Pine, you need to set up some environment variables, either by
adding lines to your CONFIG.SYS or by setting them in a script that runs Pine.
You need to set the environment variable "HOME" to point to the "home directory"
of a user (think Unix). If "HOME" does not exist, the outcome is unpredictable.
If you use Unix-format mailboxes, you may also want to set the "USER" variable
to a "user name"; this is used when writing Unix-format mailboxes. If "USER" is
not set, it defaults to a value of "os2user". One of "TMP" or "TEMP" must be
set the name of a directory to which Pine can write temporary files.

For example,

	SET HOME=d:\home\sally
	SET USER=sally
	SET TMP=d:\tmp

If you aren't using Unix-format mailboxes, the "USER" variable is not used, and
there's a fair chance you can get away without it even if you do (but I am not
promising anything). The other two must be set, however, for Pine to work
properly.

You will need to set some of Pine's configuration options before using Pine.
You can do this either by editing the "pinerc" file in the HOME directory
(Pine will create a new one when you run it, if it doesn't exist), or by going
Setup ("S") then Config ("C") from the main menu.

The "personal-name" field should be set to the name you want to have attached
to your out-going e-mails. The "user-id" and "user-domain" fields should be
set, respectively, to the first (i.e. before the "@") and second parts of your
e-mail address. The "smtp-server" field should be set to the name of your SMTP
server -- note that OS/2 Pine cannot use sendmail to send e-mail (except, I
suppose, by specifying your own machine as an SMTP server).

It appears to be a well-kept secret that Pine can read e-mail over a TCP/IP
link using the POP3 protocol, which is the ubiquitous method for obtaining
mail. Let it be a secret no longer! If you want to get e-mail from your POP3
server, set the "inbox-path" field to something of the form

	inbox-path={mail.yourisp.net/pop3}inbox

where "mail.yourisp.net" is your POP3 server. Note the "/pop3" at the end -- if
you get a message saying "Cannot connect to mail.yourisp.net,143: Connection
refused" when you try to connect, you have left this off.

Alternatively, you can get your mail via the IMAP protocal over a TCP/IP link,
in which case you should set the "inbox-path" field to something of the form

	inbox-path={mail.yourisp.net}inbox

that is, the same as for POP3 but without the "/pop3" on the end. Finally, you
can also get your mail from a file by specifying the name of the file in the
"inbox-path" field. The file can be in any mailbox format recognised by OS/2
Pine (see below). Note that Pine assumes that all mailboxes have the extension
specified by the "folder-extension" field, which defaults to ".mtx" if nothing
is entered here, and this includes the INBOX. If your mail comes from a Unix
system, for example, you will need to set "folder-extension" to be "" (this is
NOT the same as having it unset), or organise for a link "USER.mtx" to be made,
or something.

Putting that all together, for example, we might have

	personal-name=Sally J. Pineuser
	user-id=sally
	user-domain=theisp.net.au
	smtp-server=smtp.theisp.net.au

Of course, you may want to set any number of other options while you're at it.
Pine has extensive on-line help for all of the options (press "?" on the
configuration screen when the cursor is on the appropriate field) which should
get you through this process.


USING PINE TO READ USENET
=========================

Pine can read Usenet groups by setting the "nntp-server" field to the name of
your NNTP (news) server, for example,

	nntp-server=news.theisp.net.au

You can then access your newsgroups through the Folders ("L") screen on the
main menu in much the same way mail folders are accessed.

Be warned that news access can be extremely slow over a modem link (or any
oher low-bandwidth link), especially when subscribing to new groups. It is
almost certainly worth enabling the "news-post-without-validation" option.

On my system, under both OS/2 and Linux, Pine displays a lot of deleted
messages with no body; I am not sure if this is a bug in Pine, in my ISP's
news server, or just odd behaviour. In any case, the most common statement
by those in the know about Pine's newsreader on comp.mail.pine is "Use slrn".


FOLDER FORMATS
==============

The code for reading local folders is copied directly from the NT port. I have
tested the MTX and Unix formats, and Pine, by default, uses the MTX format.
The MBX and Tenex formats, while (theoretically) supported by OS/2 Pine, have
only been tested under Windows NT and I cannot guarantee that they work properly
under OS/2.


DIFFERENCES BETWEEN OS/2 AND OTHER PORTS OF PINE
================================================

  * Colour

    To use colour with OS/2, set the colour option to "use-termdefs". OS/2 Pine
    does not really "use termdefs" (i.e. the termcap or ncurses library); this
    option actually uses the OS/2 VIO API. The result of using the force-ansi
    options is unpredictable.

  * Sendmail

    OS/2 Pine cannot send mail using a local version of sendmail (or suchlike),
    except, possibly, by using the local machine as SMTP server.

  * FAT drives

    Alas, these things are still haunting us. While FAT-compliant file names
    are used in the OS/2 port whenever Pine generates a file name, there is at
    least one place (Unix-format folders) where using long file names is
    unavoidable. I have created compile-time options (FATKLUDGE) which, if
    used, will cause OS/2 Pine to force 8.3 file names at the expense of
    compatability with Unix and NT versions of Pine. By default, this option is
    turned off.

  * Password file

    The PASSFILE compile-time option is turned on by default for OS/2 Pine.

  * Mail servers

    The imapd and ipopd daemons distributed with Unix Pine have not been ported
    to OS/2.
    


USEFUL HINTS
============

Some people are irritated by being constantly asked for passwords. You can save
passwords by creating a file "PINE.PWD" (use "touch", if you have it; otherwise
open it in an editor and save it without typing anything in) in the same
directory as "pinerc". If this file exists, Pine will ask you if you want to
save your password in this file. If you do, Pine will get the password from the
file forevermore. Though the password is encrypted (albeit not very strongly,
according to the documentation), USE OF THIS FEATURE HAS SERIOUS SECURITY
IMPLICATIONS. At best, it gives anyone with access to your machine free access
to your e-mail. At worst, it allows them to gain your password. USE IT WITH
EXTREME CAUTION.


You can use a configuration file other than "pinerc" by invoking Pine with the
-p option, e.g. if you have multiple e-mail accounts or multiple people using
the same copy of Pine, for example,

	pine -p sally\pinerc
	pine -p bruce\pinerc

if "Sally" and "Bruce" are both using Pine on the same computer to access their
e-mail accounts. Each has a configuration files in their own directories below
the main Pine directory. If you have multiple accounts for a single person, you
may prefer to use the "incoming-folders" field in pinerc for this purpose.


Note that some configuration fields, e.g. "incoming-folders", are only
available in the pinerc file and not through Pine's configuration screen. I'm
not sure what the story is with this -- it may be a bug -- but be aware of it,
and if you are a fussy configurer it is worth looking through pinerc for things
you didn't see on the configuration screen.


When specifying application names, e.g. in the "url-viewers" field, you need to
specify the full path name of the application, for example,

	url-viewers=d:\tcpip\bin\explore.exe

and not

	url-viewers=explore

as Pine does not search the path when looking for them.



OS/2-SPECIFIC CHANGES FROM PINE 4.10 BETA 3
===========================================

 * The PINEHOME and PINEUSER environment variables are no longer used
   (use HOME and USER, as Unix).

 * Support for Tenex and MBX mailbox formats have been added, but has not
   been tested. The code is copied unchanged from the NT version (where
   it *has* been tested).

 * URL-highlighting did not work if the character set was set to anything
   other than US-ASCII.

 * Display of some non-ASCII characters did not work. You may need to set
   the "pass-control-characters-as-is" option to get some non-ASCII
   characters to display (not my fault, so far as I can tell); Pine seems
   to think they are control characters.

 * Some additions and minor changes to the installation instructions.

Changes from older versions of Pine not specific to OS/2 can be found at

	http://www.washington.edu/pine/changes


BUGS
====

If you find any bugs specific to the OS/2 version, please send them to me
(nps@zeta.org.au) so that I can correct them. Please check my web site
first for known bugs (and, where known, work-arounds). Bugs not specific to
the OS/2 version can be reported to the original programmers at
pine-bugs@washington.edu.

The known OS/2 bugs in 4.21, at the time of release, are:

 * "Command "B" not defined" messages appear occasionally when Pine is left
    idle; this is harmless, so far as I know.

 * When inserting a file into the Pine composer (the ^R command), the file
   is taken from the current directory rather than the home directory. The
   similar bug in Pico seems to be common to all ports.
