NEWS PERUSER OVERVIEW

News Peruser is a suite of seven small programs to enable 
one to do offline reading and composition of Usenet news
articles. Peruser can compose replies-by-mail, as well, and
pass them off to a local sendmail. The toplevel applet's
filename is npcollections, but the distribution Makefile
attempts to make a symbolic link from npcollections to
peruser in /usr/local/bin, so you should be able to launch
News Peruser by typing either name at the shell prompt.


CONFIGURATION

Almost all configuration of News Peruser is accomplished
with the npconfig applet, which is launched by pressing the
configure button of npcollections, although it can be
launched from the command line. Only the first three
notebook pages are required to be completed for Peruser to
function properly, the rest of the pages specify optional
parameters. The npconfig program accepts no command-line
arguments. 


THE SERVER TREES

Newsgroups are organized into trees in the main scrolled
window widget of npcollections. The root node of each tree
is the server node, and its children are the group nodes.
Folders, if any have been configured, are represented by a
separate tree, below the news server trees in the scrolled
window. Folders are spool files where the user can store
abitrary messages indefinitely.

All news server trees have four groups appended to their
trees automatically upon creation: the FOLLOW-UPS group, the
POSTED group, the OUTBOX group, and the SENT-MAIL group.
Original news articles created by News Peruser for a
particular news server, sit in the FOLLOW-UPS group until
the next time the group is transferred, when Peruser will
attempt to post the articles to the appropriate news server.
Successfully posted articles are moved from the FOLLOW-UPS
group to the POSTED group, where they sit until explicitly
deleted.  Outgoing mail messages generated by Peruser sit in
the group's OUTBOX file until the next time the group is
transferred, when Peruser will attempt to pass the messages
off to the sendmail program. Sent mail is moved from the
OUTBOX group to the SENT-MAIL group, where it sits until
explicitly deleted by the user. 


MANUAL DATABASE MANAGEMENT

The scope of the actions which the transfer, pack, expire,
and search buttons launch, is limited by the
currently-selected node in the server tree of npcollections.
If a server node is selected, then only the newsgroups in
that server's tree will be affected. If a single newsgroup
is selected, then only that group will be affected. If no
selection exists in the server tree, all groups of all
server nodes will be affected by the transfer, pack, expire,
or search operation.

All message transfers are started by pressing the transfer
button of npcollections. The transfer operation actually
performed depends upon the type of the group which is
currently being processed. Transferring an actual newsgroup,
will cause the nptransfer program to retrieve usenet
articles or headers from their appropriate news servers into
the corresponding spool files, for FOLLOW-UPS groups
transferring the group will cause nptransfer to attempt to
post any articles in the group to the appropriate news
server, for OUTBOX groups the nptransfer program will
attempt to send any outgoing mail messages to the sendmail
program, and lastly for folders, any header-only messages
marked as requested in the folder will cause nptransfer to
try to replace them with their full article text. The
appropriate action is performed automatically.

The only means to remove messages from actual newsgroups is
by packing or expiring them. To pack a newsgroup, means to
remove all the seen articles from it. To expire a newsgroup,
means to remove all articles having a Date header describing
a time older than the configured expiry period displayed on
the first notebook page of the npconfig applet. If you wish
to keep particular messages, and remove others, you may mark
those you wish to keep as unseen, and those you wish to
remove as seen, and then pack the newsgroup, or you can copy
the messages into a folder, where they will remain until
explicitly deleted.

Folders, FOLLOW-UPS, POSTED, OUTBOX, and SENT-MAIL groups
are not affected by packing or expiring. Messages linger in
these groups until they are explicitly deleted or they are
posted/mailed.  All explicitly deleted messages are stored
on disk by Peruser and can be undeleted or purged from
storage by pressing the undelete button on the npcollections
window.


AUTOMATED DATABASE MANAGEMENT

You don't need to read this paragraph unless you want to
automate the upkeep of Peruser's database. Management of
News Peruser's spool files is accomplished by two filters,
npsepax and nptransfer. News transport functions are
performed by nptransfer, which also passes off outgoing
mail. Packing and expiring of spoolfiles is performed by the
npsepax program. Each of these programs will spit out a
usage message if you try to launch them from the shell with
no arguments. One launches these programs, setting some
options on the command line, and then feeds server and group
names to the program's standard input in this form:
server.address:group.name[newline]. The filters perform the
appropriate actions and return the number of messages
transferred/packed/expired to standard output. One may use
these programs in cron jobs or shell scripts to automate the
upkeep of the article database without launching the GUI.
The other programs in the suite are not intended to be used
independently, but are part of the GUI and are launched by
the toplevel npcollections program as necessary.


HELPERS

If you have Perl installed on your system the helpers applet
will be built at compile-time. This applet is merely a
button-bar that allows external programs to be launched with
a click of a button. The command line to be passed to the
shell, the button label text, and the button's bubble help
text are specified in the file peruser4-helpers, which by
default is installed in /usr/local/share/news-peruser,
unless you passed a different directory to the configure
script at compile-time. Peruser is distributed with a simple
module for Perl, written in Perl, to allow Perl programs to
have higher-level access to the article database.

A number of Perl programs are included in the Peruser
distribution to accomplish such tasks as the feeding of
articles to external programs to decode encoded data in MIME
messages, to display embedded encoded image files, or the
filtering of articles into folders based on the content of
header lines, using Perl regular expressions. 

You can write your own Perl programs to automate your own
tasks, and add them to the helpers button-bar, by adding an
entry in peruser4-helpers. Helpers may be written in any
language, but you can only use the included Perl module with
Perl programs, of course. The Perl module includes the
functions safe_open and safe_close, which use Peruser-style
lockfiles to mediate access to the spool files to prevent
data corruption. Peruser's lockfiles consist of the
file-to-be-locked's filename with a ':lock' suffix appended.
You will have to manage these lockfiles yourself to mediate
access to the spool files, if you write helpers in a
language other than Perl.


HEADER RETRIEVAL 

News Peruser has been designed with the concept of header
retrieval in mind. It is assumed that the user will wish to
quickly download just the headers of the unseen articles
from the newsgroups he or she is interested in, and then,
perhaps while offline, peruse those headers, marking those
messages whose full article text is of interest as requested
for future downloading.  The user can then reconnect to the
news server and transfer only the text of those particular
messages, saving considerable time if he or she reads many
newsgroups over a slow, dial-up network connection. If you
have Perl installed on your system, there will are helper
scripts you can use to automate this process.


THE THREAD TREE

Selecting a group node in the server tree will launch the
npsummary applet to display the contents of that group. In
the thread tree of the npsummary applet, the colour of the
node indicates whether the corresponding message contains a
full article, or just the header, whether or not the header
has had its full article text requested for future
downloading, and whether the message has been seen or not.
An entry in black is a full article. An entry in red is a
header-only message. An entry in green is a header-only
message that has has been requested for future downloading.
Any entry in boldface, of any colour, is considered to be
unseen.  As well, An uppercase 'D' preceding a entry
indicates it is a dummy node, inserted into the thread tree
by the program to represent a missing precursor, or to act
as a dummy root node for messages which have the same
Subject header, but which reference messages not currently
residing in the newsgroup's spool file. Dummy nodes are
displayed in blue. 

The fractions beside tree entries represent statistics for
the group or thread which they appear beside: 

   unseen-messages/total-messages :
   requested/header-only-messages.  


VIEWING TEXT

Selecting an item in npsummary's thread tree that
corresponds to a message, and not a dummy node, launches the
text viewer applet, nptext, to view the text of the message.
The nptext program attempts to use the iso-8859-1 character
set to display article text, and can recognize MIME
quoted-printable encodings of this character set in both the
headers and body of an article, and will display the text
decoded. Beyond that, the nptext program has no further
MIME-related capability. See the help text above on HELPERS
for more details on handling MIME messages containing
encoded data.


MESSAGE COMPOSITION

Peruser can generate original news articles,
replies-by-mail, and follow-up articles, by pressing the
appropriate button the the frame of the nptext applet. The
npcompose applet will create a minimal Usenet header, which
one may edit to one's liking, or leave as is. npcompose can
also launch an external editor if you prefer to use your
favourite text composition tool to create your messages. The
command to launch the external editor must be entered on the
first notebook page of the npconfig applet first.

Peruser can also generate cancel and supersede messages for
sucessfully posted articles. If a non-empty POSTED group is
selected, the Cancel and Supersede buttons appear on the
message viewer applet's frame.  Selecting a message in the
group and pressing the Cancel button will cause Peruser to
generate the header of a cancel message. A cancel message
needs no body text. When posted, the cancel message will
cause the news server to discard the successfully posted
article the cancel message refers to, and to propagate the
cancel message to other servers it exchanges news with.  A
supersedes message is a cancel message and new Usenet
article merged into one article.  If you wish to cancel a
message and post a replacement message, create a supersedes
message instead.