newsfish
—
batch USENET news reader with filter
capabilities
newsfish |
[ -CFVhlv ]
[-f
config ]
[-c
group ]
[-m
limit ]
[-n
maxRequests ]
[NNTP server ] |
newsfish
reads all unread articles in one or
more newsgroups. Articles are then subjected to a set of user-defined filters,
and those that pass are saved to a file in mailbox format. For speed, only
article
headers are tested.
The options are as follows:
-C
- Mark all articles in all newsgroups as
read.
-F
- Force
newsfish
to connect, even if the
precommand terminates abnormally.
-V
- Display version information and quit.
-h
- Display command line summary and quit.
-v
- Turns on the verbose flag.
-f
config
- Specify an alternate server configuration file. The default is
$HOME/.newsfish-servers.
-c
group
- Mark all articles in group as read. You
may specify multiple
-c
group options.
-m
limit
- Limits all output files to limit bytes
each. If limit ends with a ``b'', ``k''
or ``m'', then the actual byte limitation is
limit times 512, 1024, or 1048576
respectively.
-l
- Display all available newsgroups on the server and quit.
-n
maxRequests
- Set the maximum number of outstanding NNTP requests. For values greater
than 1,
newsfish
will pipeline
requests, allowing fuller utilization of your link. The recommended value
is 10, though you may want to tune it up or down depending on the speed of
your link. The default value is 1, meaning no pipelining is
performed.
- NNTP server
- The NNTP server to connect to. If this is specified, it will override the
environment variable
NNTPSERVER
described below.
The file
$HOME/.newsfishrc defines what
newsgroups to read and what filters to apply to their articles. The format of
this file is fairly simple. The file is divided into “blocks”.
Each “block” defines a set of filters for a particular newsgroup
and what file to save matching articles to. Each “block”
consists of:
- The name of the newsgroup followed by a colon. (':') The newsgroup name
may contain asterisks, in which case the conditions for the block are
applied to all blocks that match the newsgroup pattern. The wildcard
matcher is fairly simple. It only supports wildcard prefixes (comp.sys.*),
suffixes (*.hardware.misc), or both (*.hardware.*). You may also define a
global match pattern ('*'), which will apply the conditions of the block
to each and every other block.
- Zero or more lines beginning with an asterisk ('*'), a space (' '),
followed by an
egrep(1)
style regular expression. The regular expression is case-insensitive.
Leading and trailing whitespace are ignored. If more than one of these
lines are defined, then an article's header must match
all regular expressions in order for the
article to be saved. Having no regular expression lines matches
each and every article in the newsgroup. The
sense of a regular expression line can be inverted if it is prefixed with
a '!'.
- A filename relative to the directory from which
newsfish
is run. Use of absolute
filenames is OK and is encouraged to eliminate ambiguity. Alternatively,
if the first non-blank character is a pipe ('|') then the rest of the line
names a program (and its arguments) that will receive the article on its
standard input. The program is executed by ``/bin/sh -c''.
Blank lines and lines beginning with a pound-sign ('#') are ignored. All leading
and trailing whitespace on any line are also ignored.
Multiple blocks can be defined for the same newsgroup, each with a differing set
of regular expression lines (the output files need not be different). In any
case,
newsfish
is smart enough to only
process newsgroups once.
For example, to save all articles from a group called “foo.bar” on
the subject of “garply”, you would define the block:
foo.bar:
* ^Subject:.*garply
some/file
As a more complex example, to save all articles from a group called
“foo.baz” on the subject of “stuff”, ignoring
posts from anyone with the e-mail address of ⟨someone@spam.net⟩,
define the block:
foo.baz:
* !^From:.*someone@spam\.net
* ^Subject:.*stuff
another/file
If a server configuration file
(
$HOME/.newsfish-servers by default)
exists,
newsfish
will attempt to read it.
This file specifies per-server configuration details, allowing
newsfish
to easily switch between different
servers. Like
$HOME/.newsfishrc, this file
is also divided into “blocks”. Each “block”
defines a set of entries for one particular server. Each consists of:
- The name of the NNTP server enclosed in square brackets ('[', ']'). This
does not necessarily have to be the DNS name of the NNTP server. If it
isn't the DNS name of the server, you must specify a valid
“host” attribute, as explained below. When
newsfish
is run, either the environment
variable NNTPSERVER
or the command-line
argument NNTP server must match the name
of an NNTP server block. If not, the server is assumed to have the default
configuration.
- Zero or more “attributes”. Each “attribute”
consists of a keyword and an argument, separated by one or more
whitespace. See below.
As usual, all leading and trailing whitespace are ignored. Any line that begins
with a pound-sign ('#') is also ignored.
A simple example that defines a news server called “mynewsserver”:
[mynewsserver]
host news.mynewsserver.com
config .newsfishrc-mynewsserver
newsrc .newsfishrc-newsrc-mynewsserver
A complex example that defines a news server called “myisp”. The
news server requires authentication. Rather than sending our password through
the network in the clear, we set up an
ssh(1)
tunnel to a host local to the news server.
[myisp]
host localhost
port 1234
config .newsfishrc-myisp
newsrc .newsfishrc-newsrc-myisp
user myusername
password mypassword
preconnect ssh -f -x -L 1234:news:119 shell1.myisp.com sleep 30
The following server attributes are currently understood by
newsfish
:
- host NNTP-host
- The host to connect to. If unspecified, the default is the name of the
NNTP server (the name within the square brackets).
- port NNTP-port
- The port to connect to. If unspecified, the default is 119.
- config config-file
- The filter definitions file to use. If unspecified, the default is
$HOME/.newsfishrc. See the special note
below regarding where
newsfish
finds
its configuration files.
- newsrc newsrc-file
- The newsrc file to use. Defaults to
$HOME/.newsfish-newsrc if left
unspecified. Since article numbers typically differ by NNTP server, you
must specify a unique newsrc file for each
server.
- password passwd
- If the server requires authentication, this specifies the password to use.
If this is defined,
newsfish
will
attempt authentication with the server. Otherwise, no authentication will
be performed. Currently, newsfish
only
supports the “original AUTHINFO” authentication scheme.
- user username
- If the server requires authentication, this specifies the username to use.
Note that for some NNTP servers, the username is optional. In this case
this should be left unspecified.
- preconnect command
- Before connecting to the server,
newsfish
will attempt to execute
command.
command is passed verbatim to ``/bin/sh
-c''. newsfish
will wait for the
command to complete before continuing. If the command exits with a
non-zero result code (usually indicating error),
newsfish
will immediately exit. This
behavior can be controlled with the -F
option described above. Finally note that although
newsfish
strips leading and trailing
whitespace, whitespace within command are
preserved.
- postconnect command
- Similar to “preconnect”, but
command is executed after
newsfish
disconnects from the
server.
- Unless a configuration filename is absolute (i.e. it begins with
“/” or is relative to the current directory (i.e. it begins
with “./” or “../”),
newsfish
expects its configuration
files to be relative to your home directory. For example:
- Filename
- Expected Location
- .newsfishrc
- $HOME/.newsfishrc
- ./myconfig
- ./myconfig (in the current
directory)
- /tmp/someconfig
- /tmp/someconfig
- foo/bar
- $HOME/foo/bar
This mapping applies to the server configuration file, all filter definition
files, and all newsrc files. Note that this mapping does
not apply to files which
newsfish
saves articles to. Finally
note that this mapping applies to the
-f
config option!
- If the
-C
or
-c
group options are specified,
newsfish
will
not scan newsgroups as usual. Instead, it
will catch up all matching newsgroups and simply quit.
NNTPSERVER
- The NNTP server to connect to. This must be
defined if NNTP server is not given on
the command line.
- $HOME/.newsfish-servers
- Contains per-server configuration details. For an example, see
dot.newsfish-servers.sample.
- $HOME/.newsfishrc
- The file containing the filter definitions. See the file
dot.newsfishrc.sample for an example.
- $HOME/.newsfish-newsrc
- Contains the highest article number for each newsgroup already scanned by
newsfish
.
egrep(1),
sh(1)
See the file
ChangeLog.
This manual page was written by
Allan Saddi
⟨allan@saddi.com⟩.
See the file
TODO.