Usenet 1994 October/usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso/unix/volume23/trn/part01/README

Text File | 1991-08-22 | 9KB | 173 lines

            Trn Kit, Version 1.0

            Copyright (c) 1985, Larry Wall
           Copyright (c) 1990, Wayne Davison

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

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 has been added to make life in the big
newsgroups much easier to live with.  It also allows you to quickly browse
through already-read articles and select the one(s) you wish to read again.
Other new features include an extract command for the source and binary groups,
thread-oriented kill directives, and additional "magic" in the header display.

To use all the new features of trn will require the maintenance of a thread
database, which is handled by the included database manager.  The amount of
space required is around 5% of your newsspool size (either in /usr/spool/news
or on another partition), but you can choose to only keep thread information
for a select portion of the newsgroups if you wish -- unthreaded groups are
read in an rn-compatible manner.

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
maintain their own database, either via the NNTP version of the database
manager, or by sharing the server's thread files through some other means.

Trn is based on the source to Larry Wall's rn (patchlevel 47), and the threaded
extensions are fully conditionalized.  Thus, it is possible to use this source
to compile both trn and (a slightly enhanced version of) 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.

Also, I'd like to publicly thank all the people who have helped me in testing
trn -- without their input, trn would have been much less compatible with all
the Unix and Xenix systems out there, and not as easy to use:

Brandon S. Allbery, Chip Rosenthal, Chip Salzenberg, David C Lawrence,
Eric Schnoebelen, George H. Martin, Guy Harris, Jason Molenda, Jaye Mathisen,
Jeff Sparkes, Jon Zeeff, Kurt Gollhardt, Linus Tolke, Mitchell F. Wyle.

Thanx guys!


Installation
------------
0)  Decide if you want to compile the newsreader as trrn (threaded remote
    rn) to read its articles using NNTP from a news server, or as regular
    trn to read the articles from the news spool directory (which could be
    mounted locally or via NFS).  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.  By choosing to create trrn (at the
    appropriate prompt in Configure), you will enable the NNTP code in both
    trn and mthreads.  Be sure you have installed your NNTP client (including
    the NNTP inews and the file that contains the name of the NNTP server)
    before running Configure.  Trrn expects at least NNTP version 1.5.

    Decide if you want to install trn as both rn and trn linked together.
    It is possible to configure trn to check the first letter of its name
    and only turn on the threaded extensions if it is a 't'.  Thus, you
    only have to maintain one newsreader package that is both a "normal"
    rn and has all the extensions of trn available for the asking.

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

    ** If you got trn in shar format, check Configure to ensure that WHITE
    and CTRLA have a Tab-Space and a Ctrl-A in them, respectively. **

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

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

3)  make

    This will attempt to make trn in the current directory.

4)  make install

    This will put trn, 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 man pages in a
    reasonable place.

5)  Once trn is compiled, you need to create some thread data to be
    able to use all the new features.  If you like, you can start small
    with a command like:  "mthreads rec.humor.funny", process a few more
    groups with the command "mthreads news", and then turn them all on
    with the command "mthreads all".  Read the mthreads manpage for
    complete details.

6)  Read the trn manual entry before running trn, or at least read the file
    NEW if you are already familiar with rn.

7)  Try trn, and play with some of the switches.  You may want to make -X
    the default on your system (you might have done this already in Configure).
    This is done by changing SELECT_INIT in config.h.  You may also want to
    modify which header lines are displayed by default and which are magic --
    This is done in head.h.

    To change default values of enviroment variables on a system-wide basis
    without recompiling trn, put the switches into the file INIT in the trn
    library.

8)  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 on a regular basis with the standard-output redirected to /dev/null.

9)  IMPORTANT!  Help save the world!  Communicate any problems and suggested
    patches to Wayne Davison ([e-mail]) so we can keep
    everyone in sync.  If you have a problem, there's someone else
    out there who either has had or will have the same problem.  Please
    don't bother either Larry Wall or Stan Barber with bugs that you
    find in trn.  If the bug is applicable to mainstream rn code, I
    will pass it along.

    If possible, send in patches such that the patch program will apply them.
    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.b or comp.sources.bugs.  Patches
    will always be in context diff format, to be applied by the patch program.

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