

News Peruser Copyright (c) 1996, 1997 James Bailie
==================================================================

News Peruser is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.

News Peruser is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.

Although News Peruser is licensed under the Free Software Foundation's
GNU General Public License, Peruser is not produced by, nor is it
endorsed by the Free Software Foundation. The Free Software Foundation
is not responsible for developing, distributing, or supporting Peruser
in any way. Anyone may place software they own the copyright to, under
the GNU General Public License.

The GNU General Public License is included in the News Peruser
distribution archive in a file called COPYING. If you do not have a
copy of the license, you can download one from ftp://prep.ai.mit.edu,
or you can write to the Free Software Foundation, 675 Mass Ave,
Cambridge, MA 02139, USA.



News Peruser Overview
=========================================================================

The News Peruser package consists of an X-based offline newsreader,
peruser, and five command line utilities, that can also be launched
from within the newsreader: hearer, which downloads articles from an
NNTP server, teller, which posts articles to an NNTP server, fetcher,
which fetcheres waiting mail from a POP3 mailbox, sender, which
senders outgoing mail messages via SMTP, and packer, which packs
(removes "read" articles from) peruser's database of news articles.

The mail capability of peruser is very limited, and is included for
convenience. Peruser is not intended to be a replacement for more
sophisticated programs.

News Peruser is distributed in source and binary form. Before you can
run Peruser, you need to download and install some libraries for your
system.

*********************************************************************

Be aware that your POP3 password, as well as your NNTP password (if
you have an authenticating news server), are kept unencrypted in the
hidden file .peruser_config, in your home directory. The file has
permissions: -rw-------, that is to say, only the creator of the file
has permission to read or write to it.

*********************************************************************



XForms Installation
====================================================================

News Peruser was written using version 0.86 of the XForms library. It
will not compile with earlier versions.

Although News Peruser is freeware, the XForms library isn't. The Forms
Library is copyright (c) 1994, by T.C. Zhao and Mark Overmars. The
Forms Library is freely usable in non-commercial projects. Commercial
distribution of software that uses the Forms Library requires separate
licensing from the authors.

The xforms library can be retrieved from:

ftp://einstein.phys.uwm.edu/pub/xforms/elf/bxform-086.tgz

For more information on the XForms library, see:

http://bragg.phys.uwm.edu/xforms

Unzip and untar the archive somewhere appropriate like /usr/local/src,
and follow the instructions in the archive to install the XForms
library on your system. All you'll probably have to do is type "make
install".



LibXpm Installation
=======================================================================

If libXpm is not on your system, you can retrieve it from:

ftp://sunsite.unc.edu/pub/Linux/libs/X/libXpm-4.7.tar.gz.

Most Linux distributions include libXpm. It's not necessary for you to
have the most up-to-date version. 4.3 will do.



************************************************************************

If you have a binary distribution of News Peruser, you do not need any
of the following libraries, and can skip ahead to the section entitled
Peruser Installation.

************************************************************************



GNU Regular Expression Library Installation
=====================================================================

The GNU regular expression library can be found at:

ftp://prep.ai.mit.edu/pub/gnu/regex-0.12.tar.gz

unzip and untar the archive somewhere appropriate like /usr/local/src,
and compile the library. All you need to do is type "configure" and
when the configure script has finished, type "make install", and
you're done. This will put regex.h into /usr/include, but since the
regex library is not yet a true shared library but a linkable object
file, you need to edit the first line of the "Makefile" in your
peruser source directory so the link editor knows where to find it.
The first line of peruser's Makefile looks like this:

REGEXPATH=/usr/local/src/regex-0.12

If you untarred the regex library archive from /usr/local/src, then
you don't need to change anything, you can move on and follow the
instructions to compile peruser, otherwise edit the path after the
equal sign to reflect the location of the regex library source
directory on your system.



UUDeview Installation
======================================================================

Peruser uses Frank Pilhofer's uulib decoding library to decoded UU,
XX, Base64, and BinHex encoded binaries, and saves the decoded binary
files in your home directory.

The UUDeview distribution comes with some useful programs: uudeview
and uuenview allow the user to decode and encode binaries from the
command line, and XDeview is a Tcl/Tk based front end to uulib. To
compile and use XDeview you need to have Tcl 7.5 and Tk 4.1 installed
on your system. You do not need XDeview to use peruser, so don't worry
about ftp-ing and installing Tcl/Tk if you don't want to be bothered.

The UUDeview homepage is: http://www.uni-frankfurt.de/~fp/uudeview/

Once you have built the programs and uulib, you must edit the line of
Peruser's Makefile that looks like this:

UU_DEVIEW_PATH=/usr/local/src/uudeview-0.5.13

to reflect the location of the untarred UUDeview distribution.

The "decode binaries" button on the main form of Peruser decodes all
the encoded binaries in the currently selected newsgroup, saving the
binary files in your home directory. A form pops up to show you
messages from the decoding library. If you click on any line with this
form: "Successfully decoded: <filename>," Peruser will attempt to
lookup a program to run to view the file, depending upon your having
your /etc/mime.types (and/or ~/.mime.types) and /etc/mailcap (and/or
~/.mailcap) configuration files properly setup.



Peruser Installation
========================================================================

If you have a binary distribution of News Peruser, just copy the
executable files in the archive into a directory on your path, such as
/usr/local/bin.

If you have a source distribution, change to the directory containing
the source files and type "make". Then "make install" will copy the
executables "peruser", "hearer", "teller", "packer", "sorter", and
"threader" to /usr/local/bin, and create the symbolic links that
peruser uses, "chearer", "cteller", "cpacker", "csorter", and
"cthreader". Don't run these programs with the symbolic link name, as
they check to see what name they are invoked by and will write their
output to a named pipe if invoked by the symbolic link. If you do this
from the command line, the program will hang. You can remove the
source directory after compilation if you like.



Authenticating News Servers
=======================================================================

The following examples assume you are not using an authenticating news
server. To use an authenticating news server, insert the following
three arguments right after your news server's address, and before any
other command line options, like this:

hearer [news.server.address] -a [nntp_username] [nntp_password] ...

or

teller [news.server.address] -a [nntp_username] [nntp_password]



Downloading News Articles
=======================================================================

The easiest way to transfer articles to and from your news server is
to do so from inside Peruser, however hearer and teller and packer
were written as separate command line utilities so that they could be
run from shell scripts or crontabs. When executed from the command
line, hearer requires the address of the NNTP server to be passed as
the first command line argument. An optional positive integer second
argument specifies the number of articles to be downloaded from each
newsgroup listed in the user's .peruser-newsrc. The lack of a second
argument causes hearer to download all new articles on the server from
the newsgroups listed in the user's .peruser-newsrc.

For example:

hearer news.wwdc.com

would download all new articles from the named server; while,

hearer news.wwdc.com 10

would download the last ten articles from each subscribed newsgroup,
regardless of the last-read article indicated in the user's
.peruser-newsrc. When hearer finished downloading those articles, it
would update the user's .peruser-newsrc such that the last-read
article number for each newsgroup in the .peruser-newsrc would be the
article number of the last available article on the server, that is,
the newsgroup would be marked, "fully read."

hearer news.wwdc.com 0

would update each newsgroup to be "fully read," in the user's
.peruser-newsrc, but download no articles. Negative second arguments
are ignored.

Once it has disconnected from the news server hearer will call another
command line utility, sorter, to sort the spool files. You shouldn't
need to use this utility directly, but it won't hurt anything if you
do. Only five NNTP commands are implemented by hearer and teller:
group, head, article, post, and quit, so they should work with any
server out there.



Header Retrieval
======================================================================

Hearer supports header retrieval as of News Peruser 1.6, with the
addition of two words that may be passed as arguments: "headers" and
"requests". Header retrieval may be accomplished from within peruser
from the hearer menu form, or from the command line. This command line
will download only the article headers of all new articles:

hearer news.wwdc.com headers

while,

hearer news.wwdc.com 10 headers

would download the headers of the last ten articles from every
newsgroup listed in the users .peruser-newsrc. From within peruser the
user can select article headers for full article retrieval. After
having done so, the command line:

hearer news.wwdc.com requests

will download the full article text of each selected header, replacing
the header with the full article in the newsgroup's spool file.

Be aware that if you select headers for full article retrieval, and
then pack the spool files, those headers will still be selected,
although the headers themselves have been deleted. The full article
text corresponding to those article headers will be downloaded at the
next invocation of "hearer (server address) requests". Two buttons
have been added to peruser to enable the user to clear all the
requests files, or just the requests file of the current newsgroup.

Any command line invocation of hearer with "headers" as an argument
will cause the user's .peruser-newsrc file to be updated to reflect
the last articles available on the news server, while passing
"requests" to hearer causes no change to the user's .peruser-newsrc.



Getting a List of Newsgroups
===========================================================================

Hearer also will accept one other command line argument, the word
"list".

hearer news.wwdc.com list

will cause hearer to sender the "list" command to the NNTP server, and
compile from the server's reply, a list of all the newsgroups
available on the server, leaving the list in ~/.peruser_spool/LIST.
If the hidden file ~/.peruser_spool/.timestamp exists, hearer will
issue the NEWGROUPS command using the timestamp as argument to the
commmand. If you wish to retrieve a full list, you must delete 
~/.peruser_spool/.timestamp. Peruser does this for you if you are
retrieving a list from the Edit ~/.peruser-newsrc form.


Posting News Articles
========================================================================

Teller, the program which posts the user's original news articles, is
launched by the teller button in peruser, or teller can run from the
command line. Teller requires only the address of the NNTP server be
passed as an argument.

Peruser will create a minimal usenet header for every outgoing
message, and will insert a blank line after the header. Remember that
properly formed messages must contain a blank line between the header
and the body of the article. If you remove this line, your posting
will be rejected by your server. This header is intended to be minimal
complete header that you can add to, or modify as you are wont, but
can be left as it is without fear of rejection by a server.

Peruser has a quoter facility to allow you to quote lines of messages
to which you wish to follow-up, and the contents of a file called
.signature, if found in the user's home directory, will be appended to
every outgoing message.



Mail
=======================================================================

As of version 2.0, peruser can now transport email via the POP3 and
SMTP protocols. the program fetcher, fetcheres your mail from you POP
server. Fetcher requires the POP server address, your POP user name,
and your POP password, respectively be passed on the command line.

For example, I would use:

fetcher mail.wwdc.com jbailie (password)

With (password) replaced with my POP password without parentheses.

The program sender, senders your outgoing mail to your SMTP server.
Sender requires only the address of the SMTP server to be passed on
the command line:

sender mail.wwdc.com

Again, the simplest way to use fetcher and sender is from within
peruser, once you have correctly filled out the configure form.



Threading By Reference
=======================================================================

Peruser now includes a module to thread the spool files by references,
after news has been downloaded and sorted. Threading is indicated by
indentation in the subject line browser of the main form. This should
be straightforward to understand.

If a subject line is indented multiple places then there are articles
in the thread missing between the current article and the last one in
the thread on file. A new button has been added to the article form,
"request references," to allow the user to request all the articles
listed in the current article's "References: ..." header line, if it
has one. In this way you can selectively download the articles
necessary to complete a thread, if your news server still has them on
file.

Articles which have their references requested, have their subject
lines displayed in italic type in the subject line browser of the main
form. If peruser does not change a subject line to italic type when
you press "request references," then either all the references of the
current article have already been requested by another article in the
thread, or all the referenced articles are already on file. Pressing
"request references" twice removes the article's references from the
requests queue for that newsgroup.



 
Configuration
========================================================================

Original mail messages and news articles are created with an external
editor, specified in the configure form of peruser.

The first time peruser is run, you must fill out the configure form
that appears. Peruser uses this information to create message headers
and passes the appropriate arguments to hearer and teller when they
are run from within the news reader.

Peruser keeps its spool files in a hidden directory, .peruser_spool,
created as a subdirectory of the user's home directory. If things go
wonky, deleting the spool files with a rm *, should put things back to
normal.

Peruser keeps your configuration file, .peruser_config, in your home
directory.

Peruser now accepts the -geometry command line option, to specify the
size and/or position of the main form, but it ignores negative
position values (eg peruser -geom 600x600+10+0).



Last XForms Version
===========================================================================

This is the last XForms-based version of Peruser. I'm moving to an
interface library that is a little more sophisticated, perhaps Tcl/Tk,
with a custom library for newsreading functions. Peruser was never
intended to be anything but a little hack to allow myself to read news
offline. It's outgrown its current incarnation. If you get some use
out of Peruser, that's great. Version 3.0 will be a total rewrite, and
I intend to support all the features you would expect from popular
Windows offline newsreaders.



Author
===========================================================================

James Bailie <jbailie@wwdc.com>

News Peruser homepage: http://www.wwdc.com/~jbailie/peruser.html


