See SETUP for minimal installation instructions.
----------------------------------------------------------------------

What is slrnpull?
==================

This version of slrn is capable of allowing a user to read offline.
This is accomplished by using slrn in conjunction with the the
slrnpull program.  Basically, slrnpull pulls a small newsfeed from an
NNTP server from which slrn will subsequently read.

There are several other ``sucking'' programs available that perform a
similar function as slrnpull.  The best known are `leafnode' and
`suck'.  All of them, with the exception of `leafnode' require the
user to run a newsserver program such as INN or CNEWS.  Like
`leafnode', slrnpull does not require a newsserver. 

In many ways `leafnode' is more ambitious than `slrnpull'.  It was
designed for many more readers and provides an nntp server to access
the news spool.  However, I felt that even it was overkill for my
purpose of pulling 10-20 newsgroups for myself.  For that reason, I
wrote slrnpull.

slrnpull is very simple to setup and use.  It requires only one
configuration file that is placed in its root news directory.  The
purpose of the file is to specify which groups to download, how many
articles should be downloaded at one time for a given newsgroup, and
how many days can go by before an article will expire.  See
slrnpull.conf file for an example and documentation for the format of
the file.

slrnpull also has the ability to score articles so that they will not
be downloaded from the server.  Unlike slrn, any article that is given
a negative score by slrnpull will be killed; that is, it will not be
retrieved from the server.


slrnpull directory structure
=============================

The directory structure assumed by slrnpull is as follows:

    SLRNPULL_ROOT/
    SLRNPULL_ROOT/data
    SLRNPULL_ROOT/news/
    SLRNPULL_ROOT/out.going/
    SLRNPULL_ROOT/out.going/rejects/

The actual news articles that are pulled from the server are placed in
directories under the SLRNPULL_ROOT/news tree.  The out.going
subdirectory is where posted articles will go until slrnpull sends
them to the server.  Any article that is rejected by the server will
be moved to the rejects subdirectory.  The files that slrnpull
generates (active, new.groups, etc.) will be placed in the data
subdirectory.

The configuration file, slrnpull.conf must be placed in the
SLRNPULL_ROOT directory.  See the sample slrnpull.conf file for an
explanation of the format of this file.  When slrnpull runs, it will
read the slrnpull.conf file.  Based on the information present in that
file, it will create the appropriate subdirectories under
SLRNPULL_ROOT/news.

If your server requires authorization information, you will need to
create a file called `authinfo' in the SLRNPULL_ROOT directory.  The
file should consist of two lines.  The first line is for the username
and the second line is for the password.

As slrnpull runs, it will append status and error messages to file
called `log' in the SLRNPULL_ROOT directory.  You are advised to check
this file after every run of slrnpull.  For example, if the server
rejects a posted article, the log file will indicate this fact.

After slrnpull has grabbed articles from the server, it will create a
file called `active' in the SLRNPULL_ROOT directory.  This `active'
file will be used by the newsreader.

The SLRNPULL_ROOT directory may be specified several ways:

   1. At compile time.  The default is /var/spool/news/slrn/.
   2. Via the SLRNPULL_ROOT environment variable.
   3. Via the -d <dir> command line option.

In the sample script, slrnpull.sh, the third method is used.

Note: the SLRNPULL_ROOT cannot be used for multiple servers.  If you
intend to use slrnpull with more than one server, you will have to set
up a different tree for each server.

slrnpull command line options
=============================

slrnpull may be controlled by several command line parameters:

   slrnpull <options>

where <options> can include any of the following:

  -d SPOOLDIR          Spool directory to use.
  -h HOSTNAME          Hostname of NNTP server to connect to.
  --debug FILE         Write dialogue with server to FILE.
  --expire             Perform expiration, but do not pull news.
  --fetch-score SCORE  Fetch article bodies with a score of at least SCORE
                       (for use in "true offline" mode)
  --help               Print this usage information.
  --kill-log FILE      Keep a log of all killed articles in FILE.
  --kill-score SCORE   Kill articles with a score below SCORE.
  --logfile FILE       Use FILE as the log file.
  --marked-bodies      Only fetch bodies that were marked for download.
  --new-groups         Get a list of new groups.
  --no-post            Do not post news.
  --post-only          Post news, but do not pull new news.
  --rebuild            Like --expire; additionally rebuilds overview files.
  --version            Show the version number.

If the `-d' option is not specifed, slrnpull will attempt to determine
the SLRNPULL_ROOT directory by the SLRNPULL_ROOT environment variable.
If that fails, it will default to the compiled-in value.

The `-h' option controls the name of the NNTP server that will be used
for pulling the news feed.  If it is not specified, slrnpull will look
for the NNTPSERVER variable.  By default, slrnpull tries to connect on
port 119. If you need to change this, you can code the port into the
hostname (like in 'server.name:XXX', where XXX is an integer that
represents the port number).

The `--debug' option allows you to write the dialog with the NNTP server to
the specified file. This can be used for debugging purposes.

The `--expire' option is used to run slrnpull in expire mode.  If this
option is specifed, no attempt will be made to access the server.  It is
recommended that slrnpull be run in expire mode once every day.  Please note
that on large spools, this operation may take a few minutes to run.

The `--fetch-score' option can be used in "true offline mode"; please refer
to README.offline for details.

The `--help' option gives a short listing of available options (see above
for an example).

The `--kill-log' option allows you to keep a log of all articles killed by
slrnpull's scorefile, so you can check whether articles you really wanted to
read accidentally got deleted.

Using `--kill-score', you can change the threshold for killing articles via
the score file - all articles with a score below the SCORE value get killed.
The default is to delete all articles with negative scores.

`--logfile' is used to specifiy a log file instead of the default ("log" in
the slrnpull directory).

`--marked-bodies' is a special option when using true offline reading;
again, please refer to README.offline.

Normally slrnpull does not query the server for new groups.  The
--new-groups option forces slrnpull to query the server.  If the
server indicates any new groups, slrnpull will append the new group
names to the file SLRNPULL_ROOT/data/new.groups and update the time
stamp in the SLRNPULL_ROOT/data/new.groups-time file.

`--no-post' is used to indicate that slrnpull should not post any
outgoing messages.

The `--post-only' flag may be used to tell slrnpull to post any out-going
articles but do not attempt pull any articles from the server. Normally this
option is not required, because slrnpull will always post any articles in
the out.going directory immediately before pulling new articles.

The `--rebuild' option works like `--expire', but additionally rebuild the
overview files completely. Note that this may take quite some time. This
option also rebuilds the .headers files used for true offline reading (see
README.offline), so you may also want to use it when articles without body
are not flagged appropriately.

The `--version' option causes slrnpull to write the version number to
stdout.

Scoring with slrnpull
=====================

If slrnpull finds a file called `score' in the SLRNPULL_ROOT
directory, it will read it as an slrn score file.  This file may be
used to kill articles before they are pulled from the server.  The
syntax of this file is identical to an ordinary slrn score file;
however, any article which scores less than 0 will be killed.
See the main slrn documentation for information about scoring.  A
sample score file is present in this directory.


Setting up a minimal .slrnrc file.  
==================================

Assume that the SLRNPULL_ROOT refers to the directory
/var/spool/slrnpull.  Then the following .slrnrc lines should be
sufficient to tell slrn how to deal with the news provided by
slrnpull:

    set spool_inn_root		"/var/spool/slrnpull"
    set spool_root		"/var/spool/slrnpull/news"
    set spool_nov_root		"/var/spool/slrnpull/news"
    set read_active		1
    set use_slrnpull		1

The 'use_slrnpull' variable must be set to 1 to tell slrn to post the
file to the out.going directory.  Also note that 'spool_root' and
'spool_nov_root' must be set to the same value.

In addition, it is a good idea to include the `hostname' and
`username' lines, e.g.,

    hostname			"your.host.name"
    username			"your.user.name"


Some Limitations
=============================================================================

Slrnpull tries to be efficient by only downloading one copy of an
article that has been crossposted.  For example, if an article has
been crossposted to both sci.physics and sci.astro, then if slrnpull
already downloaded the article for sci.physics, it will not download
the article for sci.astro.  Ideally, it should create a copy of the
downloaded article in sci.astro.  This may be corrected in a future
version.