
This is EEP version 1.1, an experimental .newsrc editor program.

It is intended to work with news readers such as rn and trn, that
create a .newsrc file in the $HOME directory of each user, in order
to track what messages have been read by them.  A major design
objective is that it should be easy to use, even by someone who is
not familiar with other UNIX editors.  There is however a distinct
bias towards vi in some of the commands, although this is redeemed
somewhat by use of curses, which means that up and down arrows may
be used on many systems.  Another redeeming feature is the on-line
help, activated with the ``?'' key.

Eep was written by Paul Gillingwater <paul@actrix.gen.nz>.
It was written for Actrix Information Exchange, a Public
Access UNIX BBS in Wellington, New Zealand.

This entire work is Copyrighted (C) 1991 by Paul Gillingwater, as
the sole original author (apart from where otherwise explicitly
acknowledged).  The source code provided is available for anyone to
use in any way, EXCEPT that you may not sell it or pretend that you
wrote it.  I would be happy if people wish to incorporate part or
all of this in some other product, as long as you acknowledge me as
original author of these parts.  If this code is to be incorporated 
into a commercial product, I request that you contact me with regard 
to licensing.

You may contact me care of:
	Actrix Information Exchange
	PO Box 11-410
	Wellington
	NEW ZEALAND

**** WARNING:  This program will modify your .newsrc file.  Please
ensure you have a safe copy of this file to prevent an unfortunate 
accident.

**** ADVICE: Eep will sort your .newsrc into strict alphabetical
order.  If you don't want it to do this, wait for a later version
that will be friendlier to people who like to adjust such things.

I am releasing Eep now because it may be useful to some people, and
I would welcome helpful suggestions or contributions of code to
improve this tool.  All contributions will be acknowledged.

Revision History
================
Version 1.0  ``Warts'n'All'' version released on limited (NZ only)
distribution.  Made available via anon. FTP or UUCP from Actrix.
Sent to various people to test porting to other platforms, and
implemented on Actrix BBS since it might be useful for new users.  
Released: July 20, 1991

Version 1.1  This version records the order in which newsgroups are
found in the .newsrc file, and will maintain that order for display
and output purposes.  In addition, any newsgroups which don't yet
have any entry in the newsgroups file or newslocal will be sorted so
they appear first -- this will help find new newsgroups quickly (but
it's not a full solution).  

News Descriptions
=================
A major benefit of Eep is that it is intended to provide a mechanism
for selecting news groups based on more than just their name.  By
using lists provided by Gene Spafford, a brief description of each
newsgroup is presented on screen, allowing novices to make decisions
on what to read more easily.  Although both ``rn'' and ``trn'' offer
the L command to list news groups, this is unwieldy if you want to
search for specific key words in newsgroup names or descriptions.
Furthermore, Eep eliminates the necessity to actually type in the
name of a newsgroup when subscribing to it.  Simply point and play!

Eep tries to be user friendly in moving around the .newsrc file.
Experienced UNIX users will wish to use Emacs or vi to edit their
.newsrc for themselves.  Eep is intended for novice users, and is
quite a good addition to UNIX based BBS systems.

Other features of Eep include the ability to subscribe or
unsubscribe to a newsgroup, and catch up on messages.  

Eep will read a list of newsgroups and descriptions from two files.
One of these, "/usr/lib/news/newsgroups", must be present.  The
other one, "/usr/lib/news/newslocal", may or may not be present as
desired.

The NEWSGROUPS file contains one line per news group.  The first
``word'' (in the UNIX sense) on the line is the newsgroup name,
separated from its description by a space or tab.  The NEWSLOCAL
file is similar in structure, and is intended to contain groups
which are purely local to your system, as well as the top level
names of all of your hierarchies, plus other names as you desire for
descriptive purposes.  

e.g.  few articles are posted in comp.unix, but it makes a great
place to hold the description for all the directories under it.

Installation
------------

This first release assumes that all news files are stored on one
file system, and that the paths to the files may be safely hard
coded.  Please edit the eep.h file to change where those paths may
be on your system.

The /usr/lib/news/newsgroups file is created by manually editing the
messages which are posted in news.announce.newusers on a regular
basis by the net.god, Gene Spafford.  You may embed comments in the
file by starting the line with a ``#''.  The /usr/lib/news/newslocal
file contains your own local newsgroups (ones not covered by Gene's
postings), or ones specific to your country.  It is also used to
keep descriptions of top level hierarchies (which will be used in a
future version of this software).

I have provided copies of my own files for you as examples to base
yours on.

Just run ``make''.  I have tried to make the code relatively
portable.  Please send me context diffs for any changes you'd like
to suggest (or bugs, of which there are still a few).

When the code runs OK, you can use ``make install'', which will
attempt to copy eep into /usr/local/bin.

Oh, and for those who are wondering: "Why call it EEP?".  Well, may
I refer you to Sol Libes' excellent book, ``Life With UNIX''.  There
is a reference in there to an aspect of UniForum conferences in New
Zealand, and the types of jokes found there.  Then consider that one
can start a command by prefixing it with the name of the shell to
execute, e.g.:
	sh eep

<baaaah!>
-----------
The ``To Do'' list:

O command:  Order (sort) the news groups alphabetically.  Currently,
eep will maintain the order found in the .newsrc.

Although I use NNTP to fetch my news, I have not incorporated any of
the hooks for NNTP in this version.  This is definitely planned, but
not for some time.  I would welcome efforts in this direction from
others.

The Help screen is really ugly.  

The .newsrc may be kept in something other than alphabetical order
by some users (e.g. I like to have rec.humor.funny at the top to
start my day).  Eep currently rides roughshod over this desire, by
imposing its own fascist sorting on you.  Sorry.  However, a later
version will try to be more forgiving, and will also allow lines and
blocks of lines to be moved around in the file.
program 

Planned: the ``='' key will show a list of around 20 subjects (one
screenful) from the newsgroup currently selected, which will help
people to make a choice about subscribing or not.

Information on a newsgroup will include the actual number of
articles found in the directory -- only upon request.  Note that
this will impact portability, since it will have to open
directories.

A later version will allow the ``!'' key to shell out to UNIX.
Because some sites will use eep from inside a BBS, this may not be
appropriate.  For that reason, the -! flag may be used to set the
no_shell boolean.

The next version should have all files read (optionally) from
environment variables.

Design issues.
--------------

(a)  Should eep sort the news groups into alphabetical order for
reading?  The early version of eep will sort by group name when
displaying descriptions on screen.  It seems useful to track the
order in which they are read from the .newsrc, so that this order
can be restored (if desired) by the user.  Further, it would follow
from this that they should be displayed in this way, and that groups
(or multiple groups) should be able to be moved around from one
place to another.  On screen, this could be accomplished by marking
the groups with a ``['' on the left edge of the screen, and use
numbering, as well as Lotus-123 like anchoring for moving (NOT
copying) the newsgroup lines.  Of course, ESC will cancel.

(b)  If we change the ordering mechanism to use the ability to move
groups around, it may be more appropriate to change the indexing
method into a linked list.  This linked list would be based upon the
order in which the news groups were first read from the user's
.newsrc.

(c)  How should we deal with newsgroups that are not in the user's
.newsrc?  If they have trimmed down their .newsrc, then that is
their choice.  We shouldn't litter it with a whole heap of
unsubscribed news groups.  That implies that when we write out the
.newsrc, we don't output the unsubscribed ones.  But what if the
user wants to keep track of how far they had read?  Philosophical
issue, I guess, but I'm tempted to say that it's just too bad.   If
the want to subscribe later, they can always catch up.

(d)  For the first release, I have decided to force sorting of the
user's .newsrc.  This is because I need something that will be
useful immediately.  The extra code necessary to record the order in
which the records come in, plus allowing the moving of records
around, can come later.

(e) Currently, eep will delete all unsubscribed or bogus newsgroups
from your .newsrc.  I wasn't sure about doing this, but I now like
it.  I'm open to persuasion on whether this behaviour is
appropriate.   My view is that it's so easy to add new newsgroups
with Eep, and catch up, that it's no real work do add things later.

(f) NNTP hooks will be added later for those who read their news
remotely.

(g)  I don't fully understand (because I haven't tried to find out)
the mechanism by which rn and trn detect that new news groups are
present.  I suspect it is something to do with determining whether
the last modification date of the active file is subsequent to the
most recent modification date of one's .newsrc, but I don't know how
it knows which groups specifically are new.  Eep is likely to
interfere with this mechanism, because it will recreate the .newsrc,
thus making to possible to miss automatic notification of new
newsgroups.  The newsgroups will still appear in Eep's list of
course.

(h) Some hooks are present to allow the root user to modify the
active file.  This will be a later addition, along with possible
editing of the newsgroups file to add descriptions.

(i) Early user feedback indicates the sorting the .newsrc is rather
antisocial behaviour.  As a quick hack, it may be useful to record
the order of appearance from the .newsrc file, and sort the array
into this order immediately prior to displaying the opening screen.
(This has been done as of version 1.1).
There will of course be some newsgroups' descriptions NOT present 
in the .newsrc, including the distributions file, as well as new
newsgroups.  If we set the default value of the sorted filed to zero
then these will appear close to the top of the file.  This is good
if they are new newsgroups, but maybe not so good if they are top
level distribution names.  Cont'd in (j).

(j)  One addition that has been planned since the germination of eep
has been to present the newsgroups in a hierarchical structure.
Currently there are close to 2,000 newsgroups (in New Zealand) and
this is growing fast.  Having one long list, however you scroll
through it, is not good enough for newer users.  Eventually, eep
will show an opening menu of just the top-level groups (i.e. ones
with not "." in their name).  Users will then "drill-down" to the
next level, and thus will see the hierarchy as an inverted tree.  As
a prelude to this, and taking (i) into account, it seems appropriate
to add code to take the top-level names separately, and not show
them in the main list.  

(k) Most of the top-level names may be found in the
/usr/lib/news/distributions file, however not all.  For example,
there are some news groups which have a single name, e.g. control,
junk.  Should these be shown at all?  I think so -- but it's not
appropriate to treat them as top levels.  Perhaps these specials
could be kept in newslocal file.
