			  Trn Kit, Version 2.x

		    Copyright (c) 1991, Wayne Davison

			Based on rn, Version 4.4

		     Copyright (c) 1985, Larry Wall
                     Copyright (c) 1991, Stan Barber

You may copy the trn kit in whole or in part as long as you don't try to
make money off it, or pretend that you wrote it.
--------------------------------------------------------------------------

Please read all the directions in this file (following the brief description
of trn) before you proceed with the installation.  Failure to do so may void
your warranty. :-)

If you're upgrading from trn 1.x, read the ** LOOK ** section in the file NEW.

After you have unpacked your kit, you should have all the files listed
in MANIFEST.


What is trn?
------------
Trn is "Threaded RN" -- a newsreader that uses an article's "References:"
to order the discussions in a very natural, reply-ordered sequence called
"threads."  Having the replies associated with their parent articles not
only makes following the discussion easier, but also makes it easy to back-
track and (re-)read a specific discussion from the beginning.  Trn also
has a visual representation of the current thread in the upper right corner
of the header, which will give you a feel for how the discussion is going
and how the current article is related to the last one you read.

In addition, a thread browser/selector is available to make life in the big
newsgroups a much nicer place.  You can also choose to use it to browse
through already-read articles and select the one(s) you wish to read again.
Other nice features include the extract commands for the source and binary
groups (that recently migrated into the mainstream rn code from trn), thread-
oriented kill directives, a better newgroup finding strategy, and the abandon
command.

To use all the threaded features of trn requires the maintainence of a special
"thread" file for each group.  If you have about 5% of your newsspool size
in free space somewhere on your system, you'll probably want to maintain a
full database of thread files by running mthreads at regular intervals.  If
space is limited, some or all groups can be left unthreaded by mthreads, and
trn will either read the group unthreaded or create a temporary thread file
for the group when it is being read.  This runtime threading will cause an
delay when starting up a medium or large group, so chose this only if you
can't spare the space.

Trn can be optionally compiled as trrn -- a NNTP-compatible newsreader that
lets you access news from a remote news server.  Each client machine must
have access to a thread database.  This can either be maintained locally
via an NNTP version of mthreads, shared via NFS, or accessed remotely via
the XTHREAD extension to NNTP.  See the file nntp/xthread.patch for details
about modifying NNTP 1.5.11 into an XTHREAD-compatible version.

Trn is based on the source to rn 4.4, and the threaded extensions are fully
conditionalized.  Thus, it is possible to use this source to compile both trn
and rn.  In fact, it is possible to install trn as both rn and trn (linked
together) to maintain only one newsreader on a system where people wish to
continue to use rn.



Installation
------------

1)  Decide where you want to put the thread files.  The recommended spot
    for people with over 5% of your /usr/spool/news size free is to place
    a ".thread" file in each spool directory.  The other alternative is
    to create a directory for them (possibly on another drive) and enter
    this path at the appropriate Configure question.  Remember that you are
    not required to create thread files for all groups.  Some sites choose
    to only thread high-volume discussion groups (see the mthreads manpage),
    which will lower the amount of space required for thread files.  All
    other groups can be threaded on the fly when trn is running, if the
    user desires to do so.  If you are making an NNTP XTHREAD version of
    trn, then you must read the file nntp/xthread.patch and follow its
    directions first.

2)  If you are trying to make the NNTP version of trn, be sure you have 
    installed the NNTP inews.  Trrn expects that the NNTP is at least
    version 1.5.  You will need the source to nntp (at least the stuff
    in the common directory) to respond to Configure's question about
    where the root of the nntp source tree resides.

    The thread database created by mthreads must be accessable on each
    machine, which means that NNTP machines will need to maintain a local
    copy (usually by running the NNTP version of mthreads), or share a
    common copy (via either NFS or XTHREADS).

3)  Run Configure.  This will figure out various things about your system.
    Some things Configure will figure out for itself, other things it will
    ask you about.  It will then proceed to make config.h, config.sh, the
    Makefile, and a bunch of shell scripts.  It will also do a make depend
    for you, or let you start one in the background.  You might possibly
    have to trim # comments from the front of Configure if your sh doesn't
    handle them, but all other # comments will be taken care of.

4)  Glance through config.h and common.h to make sure system dependencies
    are correct.  Most of them should have been taken care of by running
    the Configure script.

    If you have any additional changes to make to the C definitions, they
    can be done in the Makefile, in config.h, or in common.h.  If you have
    strange mailboxes on your system you should modify mbox.saver to correctly
    append an article to a mailbox or folder.

    If you are on a machine with limited address space, you may have to
    remove some of the special functions of trn to make it fit.  This is
    easily done by undefining symbols in the System Dependencies section
    of common.h.  You should run "make depend" again to be safe.

5)  make

    This will attempt to make trn, tmpthread, and (usually) mthreads in the
    current directory.

6)  make install

    This will put trn, tmpthreads, newsetup, newsgroups, Pnews, and Rnmail
    into a public directory (normally /usr/local/bin), and put a number of
    files -- including mthreads (the database manager executable) -- into
    the private trn library (e.g. /usr/local/lib/trn).  It will also try to
    put the trn man page in a reasonable place.

7)  Read the manual entry before running trn, or at least read the file
    NEW if you are already familiar with trn.  Those that are brand new
    to trn can get a quick idea of what's different from rn by reading
    the WHAT'S NEW section of the man page.  Also check out the HINTS
    file for some ways to get the most out of using trn.

8)  Try trn, and play with some of the switches.  Use the -a option with -x
    to read each group threaded without having to create thread files (yet).
    Also try the -X option.  Any options you find that you want to make the
    default for everyone can be placed into the INIT file in the trn library.
    Personal defaults can be put in a file and the environment variable TRNINIT
    defined to point to it.

9)  Once trn is running ok, you'll probably want to create a database of
    thread files to shorten the startup time for entering a group.  If you
    like, you can start small with a command like: "mthreads rec.humor.funny"
    just to see if things are working, and then add more hierarchies with a
    command like "mthreads news".  To turn on all groups, use the command
    "mthreads all" (one time).  See the man page for details.  People
    upgrading from trn 1.x need to read the ** LOOK ** section in the file
    NEW.

10) Arrange to have the mthreads command of your choosing run on a regular
    basis.  If you run with the daemon flag, you can start it from the boot
    sequence (make sure it is su'ed appropriately), or even run it daily
    out of cron (if it's already running, the new version will exit).  If
    you run mthreads in single-pass mode, you'll want to have cron execute
    it regularly with the standard-output redirected to /dev/null.

11) IMPORTANT!  Help save the world!  Communicate any problems and suggested
    patches to Wayne Davison <davison@borland.com> so we can keep the world
    in sync.  If you have a problem, there's someone else out there who either
    has had or will have the same problem.  If the problem affects regular rn,
    code, I will pass it on to Stan Barber.

    If possible, send in patches such that the patch program will apply them.
    Unified or regular context diffs are the best, then normal diffs.  Don't
    send ed scripts--I've probably changed my copy since the version you have.

    Watch for trn patches in news.software.readers.  Patches will always be
    in the unified context diff format, for application by the patch program.
    If you don't have a patch program that handles unified context diffs,
    you'll probably want to get one (such as patch version 12u4).  Otherwise,
    you can use the (included) filter 'unipatch', which can be generated with
    the command 'make unipatch'.  To apply patches, use the command:

	unipatch <patchfile | patch -p

12) If you are going to hack on trn, please refer to rn's HACKERSGUIDE first.
