

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: hear, which downloads articles from an
NNTP server, tell, which posts articles to an NNTP server, fetch,
which fetches waiting mail from a POP3 mailbox, send, which sends
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 such as the University of Washington's Pine.

News Peruser is distributed in source form. You must compile the
executables yourself. But first, you need to download and install the
XForms library for your system, and the GNU regular expression
library. News Peruser uses the XForms Library to create its interface,
and the GNU regular expression library to search through its
spool_files. If you don't have libXpm on your system, you'll need to
get that as well.

Peruser uses a hidden file located in your home directory named
.peruser-newsrc to keep track of which articles you have read on your
news server. Each line of ~/.peruser-newsrc consists of the name of a
usenet newsgroup, a colon, and optionally, a range of article numbers
which indicate those articles already downloaded. To subscribe to a
newsgroup, insert a new line into .peruser-newsrc containing the name
of the newsgroup terminated by a colon. Be sure to terminate the last
line of .peruser-newsrc with a newline. To unsubscribe to a newsgroup,
delete the line containing the name of the newsgroup from
.peruser-newsrc.

Peruser keeps your configuration information in a text file in your
home directory named .peruser_config. Previous versions of Peruser did
not set the permissions of this file to prevent other users from
accessing this file, this has been changed. 

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

Be aware that your POP3 password, as well as your NNTP password (if
you have an authenticating news server), are kept unencrypted in
~/.peruser_config. 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 IS NOT! The
Forms Library is copyright (c) 1994, by T.C. Zhao and Mark Overmars.
The Forms Library is freely usable in non-commercial projects like
peruser. 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".



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. 



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.



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

Change to the directory containing the source files and type "make".
Then "make install" will copy the executables "peruser", "hear",
"tell", "packer", "sorter", and "threader" to /usr/local/bin. You can
remove the source directory after compilation if you like.

Peruser now comes with two predefined sizes of its interface. The
above instructions make the large size of the interface. To make the
small size type "make clean" then "make SIZE=SMALL install". If you
want to switch back to the large interface, remember to do a "make
clean" before you "make install".



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:

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

or

tell [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 hear and tell 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,
hear 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 hear to download all new articles on the server from the
newsgroups listed in the user's .peruser-newsrc.

For example:

hear news.wwdc.com

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

hear 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 hear 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."

hear 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 hear 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 hear and tell: group,
head, article, post, and quit, so they should work with any server out
there.



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

Hear 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 hear menu form, or from the command line. This command line
will download only the article headers of all new articles:

hear news.wwdc.com headers

while,

hear 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:

hear 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 "hear (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 hear 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 hear causes no change to the user's .peruser-newsrc.



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

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

hear news.wwdc.com list

will cause hear to send 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.



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

Tell, the program which posts the user's original news articles, is
launched by the tell button in peruser, or tell can run from the
command line. Tell 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 fetch, fetches your mail from you POP
server. Fetch 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:

fetch mail.wwdc.com jbailie (password)

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

The program send, sends your outgoing mail to your SMTP server. Send
requires only the address of the SMTP server to be passed on the
command line:

send mail.wwdc.com

Again, the simplest way to use fetch and send 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 articles references from the
requests queue.



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

Original mail messages and news articles are created with an external
editor, specified in the configure form of peruser. As well, when
running the command line utilities from within peruser, it is
convenient to watch the conversation they have with the server, which
is sent to stdout. In the configure form you can specify a terminal
emulator program, such as xterm, to launch the utilities in. By
default, peruser comes configured to use vi and xterm.

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 hear and tell 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. Older versions of peruser put .peruser_config in
~/.peruser_spool. This change was made along with others to prevent
peruser from spitting out superfluous error messages when first
installed. So, if you've been using an older version of peruser and
been wondering why you had to re-enter your configuration info, that's
why.

On the article forms the shortcuts for the arrow buttons are as
follows: 

double-left-arrow (previous newsgroup): P
double-right-arrow (next newsgroup): N
single-left-arrow (next article): n
single-right-arrow (previous article): p



Bugs
===========================================================================

Yes.



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

James Bailie. Email address: jbailie@wwdc.com. 



