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