NetNews Usenet Archive 1992 #20/NN_1992_20.iso/spool/comp/os/coherent/4523

Text File | 1992-09-14 | 49.5 KB | 1,452 lines

Newsgroups: comp.os.coherent
Path: sparky!uunet!haven.umd.edu!darwin.sura.net!Sirius.dfn.de!Urmel.Informatik.RWTH-Aachen.DE!gandalf!michael
From: [e-mail] (Michael Haardt)
Subject: [documentation] wnews.1 -- wnews overwiew manual
Message-ID: <[e-mail]>
Keywords: wnews
Lines: 1437
Sender: [e-mail] (Newsfiles Owner)
Nntp-Posting-Host: messua
Reply-To: [e-mail] (Michael Haardt)
Organization: An old and gray machine, somewhere in Moria.
Date: Mon, 14 Sep 92 23:07:18 +0100
Lines: 1437

Ok ok ok before I get flooded with requests and questions, I will post
the general WNEWS 3.00 manual.  I really wonder why you don't have it
already, but the questions I got seem to indicate that it is indeed
missing, and the number of people who asked questions about wnews
seems to justify the posting.  Note that the manual is not formattable
with real nroff, only with that weird MINIX nroff thing, so better
having the sources than a screwed up formatted copy.  A try can't hurt,
because I don't know Coherent's nroff.

If you want to write an obsolete flame about wasting bandwidth ... don't
post.  It would be a waste of bandwidth too, and people will not even
archive your flame!

Michael

PS: Do I need to say that you can get the complete MINIX wnews version
    from the well known MINIX archives?  I think that is obvious.
-------------------------snip,snap -- FvKs good stuff-------------------------
.\"
.\"      MicroWalt Corporation/MINIX User Group Holland (NLMUG)
.\"
.\"                 W-NEWS NEWS Processing Package
.\"
.\"                      Fred N. van Kempen
.\"
.\"                  Version 3.00 - 03/30/91
.\"
.\"
.\"     Format this document with the command "nroff -man name"
.\"
.\" Document-specific macros

.\" Indent a line.
.de IN
.ti +5
.nf
\fB\$1\fP
.fi
.br
..

.\" Define a chapter.
.de CD
.bp
.sp 7
.nr A +1
.nr B 0 0
.ce
.nf
\fB\nA.   $1\fP
.fi
.sp 3
..

.\" Define a section.
.de HD
.ne 5
.sp 2
.nr B +1
.nf
\fB\nA.\nB  $1\fP
.fi
.sp 1
..

.\" Document global settings
.ll 72
.in 8
.nr A 0 0
.nr B 0 0

.\" Title page
.bp
.sp 15
.ce 5
.B "MicroWalt Corporation/MINIX User Group Holland (NLMUG)"
.sp 2
.B "W-NEWS NEWS Processing Package"
.sp 2
.B "Fred N. van Kempen"
.sp 2
.B "Version 3.00 - 03/30/91"
.sp 2
.B "R E F E R E N C E    M A N U A L"
.sp 2
.sp 10
.B ABSTRACT
.br
W-NEWS is a NEWS processing package which resembles the
.B B-News
package found on many UNIX systems. It was written especially for
use with the MINIX operating system, but it will work on most other
UNIX-like systems as well, since virtually no system-dependent code
is used by the programs.
.bp 1
.\" Header and footer lines.
.he "MicroWalt W-NEWS""Reference Manual
.fo "Version 3.00(Beta)""Page %

.CD "I N T R O D U C T I O N"
.B W-NEWS
is a set of programs that can be used to process news articles,
both incoming and outgoing.  This Reference Manual describes its
bugs, shortcomings, workings and history.

.HD "THE OLD DAYS"
I have been running
.B UUCP
on MINIX for some years now, and with success, as is known by
many people. I wrote some application programs such as
.B W-MAIL
and
.B U-MAIL
that let me communicate with the rest of the world in a fairly
convienient manner, and I am very pleased with it all.
.sp 1
However,
.B NEWS
access has always been a bother. My UUCP host did not have a news
feed itself, and I got somewhat tired of dialing in on my former
school to read news there. Finally, my account expired, and I was
left with no news access at all...
.sp 1
Luckily, about half a year ago someone offered to send me articles
from
.B comp.os.minix
by e-mail (note, that I did have a more-or-less reliable mail link),
which I gratefully accepted. It worked fine, but it took me lots of
time to process all incoming articles. Also, a newsreader was not
present...
.sp 1
So, to ease the reading of those articles, I ported the
.B vn
newsreader (posted by Tony Andrews) to MINIX, with only little
effort. This cured only part of the problem, since I still had to
insert the incoming articles into the NEWS spool directory...
.sp 1
About three months later, I got a "normal" UUCP link, and the system
manager of that host offered to send me comp.os.minix as
.B "batches"
of articles. I didn't have a clue as to what those things were, but
I told the guy to send 'em anyway...
.sp 1
While experimenting with the incoming data, I gradually found out
what a news batch was, and how it was constructed. I wrote two
little programs (
.B rnews
and
.B newsrun
) that allowed me to automatically process incoming articles.
.sp 1
The first stripped off this funny-looking
.sp 1
.IN "#! cunbatch"
.sp 1
header, fed the remainder through compress(1) and stored the result
in a spool directory for later processing by
.B newsrun
, which was started daily by cron(1). Newsrun unpacked the decompressed
batches, and stuffed all articles into the
.B /usr/spool/news/comp/os/minix
directory, just like vn wanted it. It also maintained an
.B active
file, because vn wanted it to exist. This worked well enough to keep
me satisfied until I set up the
.B MUGNET
network.

.HD "MUGNET and B NEWS"
A network backbone needs much more robust software than the little
package I wrote, and this I realized very quickly after starting up.
My package could only handle one group (it stored all incoming articles
in one directory!), and posting news was impossible (besides mailing it
to some relay system).
.sp 1
So, since we now had to handle news groups from lots of hosts, plus a
number of MUGNET groups, I had to use a package smarter than my own.
I dislike
.B "C News"
because it depends on shell scripts too much (which is
.B "very slow"
on MINIX !!!). Therefore, I finished the 'cleanup' of the MINIX-port
of the
.B "B News 2.11"
software that Peter Housel sent me, and I started using that on the
MUGNET-Europe backbone.
.sp 1
However, although my machine is large enough to run 'B', many small
MINIX systems around me (in MUGNET) cannot handle such a beast. We
just needed a simple version of the 'B' software which does not try
to do it all, since many of the special features offered by large
packages like 'B' use either special UNIX-ish tricks to get things
working, or they can be lived without (for example, the support for
old-style news articles).

.HD W-NEWS
All of this lead to me starting a major rewrite of my old NEWS package,
under the name of
.B W-NEWS
(what else? :-). Since I like the way 'B' handles things, I decided to
try and give W-NEWS as much of the 'B' look as possible. It now consists
of the following modules:
.sp 1
.IN "rnews     - handle incoming articles and batches"
.IN "unbatch   - process spooled news"
.IN "inews     - the main article relayer"
.IN "control   - implementation of control messages"
.IN "sendbatch - create batches of articles for transport"
.IN "expire    - remote old articles from the system"
.IN "pnews     - post a news article"
.IN "checknews - check if any new articles have arrived"
.sp 1
As can be seen, it is a fairly complete system. Incoming articles or
batches of articles are moved to a NEWS spool directory by the
.B rnews
program for later processing (cron!) by
.B unbatch
(also callable as
.B "rnews -U"
). Unbatch calls
.B inews
for each article to be posted locally. The latter also takes care
of the forwarding (relaying) to other systems connected to the host,
which is required for backbone operation. Inews is also called by the
.B pnews
news posting program (a derivative of the
.B W-MAIL
Message Editor) for the actual posting (both local and remote) of the
article. Posting is achieved by putting a copy (well, actually a link,
since each article is put on disk only once; all other copies in other
news groups are links) in the desired subdirectory of the NEWS spool
space. For any article forwarded to a certain remote host, a line
containing the full pathname of the article is added to a text file in
the
.B /usr/spool/batch
directory. The
.B sendbatch
program (which should be executed at least daily by cron) creates
batches (optionally compressed) from these outgoing articles, ready
for transmission with a network protocol, usually UUCP.
So, the batches end up in the UUCP spool directory for transmission
to the remote system.
.sp 1
This setup allows you to both receive (with
.B vn
) and post (with
.B pnews
) news articles, for multiple news groups the same way 'B' does it.
.sp 1
For a newsreader, I recommend the
.B vn
program, or, if you don't like using full-screen software, the
.B rna
(also called
.B readnews
)
program. These are both available from the NLMUG Archive Service. There
will be a simplified version of the vn program in the W-NEWS package in
the future.
.sp 1

.HD "OUTLINE OF THE REST"
The rest of this document will describe all the modules of the W-NEWS
system, one per section.  Following that, a description of all files
used is presented.

.CD "M O D U L E S"
This chapter describes the inner workings of the various programs
(modules) of the W-NEWS system.  It does not, however, tell you how
to invoke the programs.  See the respective manual pages for that
information.
.HD rnews
Usenet (UUCP protocol) or Internet (TCP/IP protocol).  They come
in as simple datafiles.  When these datafile are ready to be
processed by the NEWS system, the networking software calls the
.B rnews
program to take care of processing the newly received data. In
many case, however, it is at least undesirable to have the system
process the data right away, since this processing may cause the
system to be slowed down quit a bit.  Therefore, this program only
moves the datafiles to a spool directory of the NEWS system.  By
default, this is the
.B /usr/spool/news/.rnews
directory, and the filename of the datafile will be something like
.sp 1
.IN "yymmddhhmmXXXX"
.sp 1
with
.B yy
being the year (minus 1900),
.B mm
the month (01 is January),
.B dd
being the day of the month (1-based), and
.B hh
and
.B mm
being the time in hours and seconds respecively.  The last four
characters of the name are the process ID of the rnews program
in hexadecimal (to make them fit in 14 characters total).
.sp 1
This file will later be processed by the
.B unbatch
program.
.sp 1
After the file has been queued, rnews exits.  See the manual page
for
.B rnews(8)
for more details on how to invoke this program.
.HD unbatch
At regular time intervals, the system should start the
.B unbatch
program, to process the news that came in that day.
.sp 1
The first thing unbatch does is check if there is already a copy of
it running on the system.  This is indicated by the presence of the
lock file called
.B .unblock
in the news LIBDIR (usually
.B /usr/lib/news
).  If it exists, unbatch simply exits.  If the lock file does not
yet exist, unbatch creates it, to indicate that there is now a copy
of unbatch running.
.sp 1
Incoming news can be in either one of three forms:
.sp 1
.IN "1. Regular articles."
.IN "2. Batches of articles."
.IN "3. Compressed batches of articles."
.sp 1
All of these are expected to be in the "incoming" spool directory
of the NEWS system, usually this is the
.B /usr/spool/news/.rnews
directory.  When this program is invoked, it will search the directory
named above for files, which it then processes one at a time.
.sp 1
Each file is first opened.  Then, unbatch will read the first line of
text from the file (up to 128 characters in length) to determine the
type of this file.  The folllowing rules apply:
.sp 1
.B "COMPRESSED BATCHES"
are files with a line of
.sp 1
.IN "#! cunbatch"
.sp 1
as their header.
.sp 1
.B "BATCHES"
are files with the text
.sp 1
.IN "#! rnews NNNNN"
.sp 1
as their header.
.sp 1
.B "ARTICLES"
are all other files.
.sp 1
First of all, unbatch checks if the file is compressed.  If so, it
executes a command line of the form:
.sp 1
.IN "/usr/bin/compress -d"
.sp 1
with the standard input being the current input file, and with the
output being a temporary file in the
.B /tmp
directory.  After successful decompression (indicated by an exit
status of 0), unbatch closes the current file, and opens the newly
created temporary file as the current input file.
.sp 1
At this point, it can either expect to get a batch of concatenated
articles, or a plain, single article.  To see what type of file it
has currently open, it continues the check with comparing the first
9 characters of the line with the text:
.sp 1
.IN "#! rnews "
.sp 1
since this indicates the start of an article in a batch file.
.sp 1
Unbatch now goes into a loop, extracting all articles in the current
open file and posting them by calling the
.B inews
program repeatedly.  It does this by copying each article into a
temporary file, and then issue a command like:
.sp 1
.IN "/usr/lib/news/inews -h"
.sp 1
with standard input being the temporary file containing the article.
The inews program then takes care of the actual posting of the
article.
.sp 1
When a file has been completely processed, it will be removed if no
errors occurred during the unpacking.  Otherwise, it will be moved
to the parent directory, to allow the system administrator to unpack
it manually.
.sp 1
When all files in the directory have been processed in this manner
(relax; this may take some time... :-) the lock file is removed and
unbatch exits.  See the manual pages of
.B unbatch(8)
and
.B rnews(8)
for more details on how to invoke unbatch.
.HD inews
.B Inews
is the heart of the NEWS system.  It receives articles from the
unbatching program for local posting (and possibly forwarding to
other systems), and it receives articles that are generated by
news composing programs like
.B pnews
or news readers like
.B vn
when a followup is created.
.sp 1
When inews is started, it reads the article's header (as far as one
exists) into memory.  The rest of the article is copied into a
temporary file in the
.B /tmp
directory.  Now, inews checks if it has to generate a message header
(which is the case if the article was generated locally), or if it
only has to update the information in the header it just read into
memory (which is the case when unbatch calls inews with an article).
A message header usually has the following fields in it:
.sp 1
.nf
  * Path:
  * From:
  * Sender:
    Reply-To:
    Followup-To:
  * Newsgroups:
    Distribution:
    Control:
  * Subject:
    Keywords:
    Summary:
    References:
  * Message-ID:
    Organization:
    Department:
  * Date:
    Expires:
    Approved:
    Lines:
.fi
.sp 1
All fields marked with an asterisk (*) are mandatory.  The other
fields need not be present, although they frequently are.  Some
fields (From, Sender, Reply-To, Subject, Message-ID, Organization,
Date) have the same meaning as in e-mail message headers.  The rest
are special to the NEWS system.
.sp 1
As soon as inews finishes updating the article header, it creates
a complete article (comprised of the new article header plus the
article body) in a file in the NEWS main spool directory (usually
this is
.B /usr/spool/news
).  Now, a note is written to the NEWS system log file about the
arrival of this article.  If resource accounting has been enabled,
inews will also write a record about the arrival to the NEWS
accounting file, after which the temporary file in /tmp is deleted.
.sp 1
Inews will now check the system's
.B sys
file to see if the local system is interested in this article.  If
it is not, the system will try to put the article in a news group called
.B junk
, which is used to dump all unwanted articles in.  Then, it checks
to see if the directory for this news group exists, since it has to
be put somewhere.  If no directory exists, inews will change the
news group name to
.B junk
again.
.sp 1
If the
.B HISTORY
mechanism was enabled at compile time, inews will now check its
history database to see of this article has already been received
before (which is, in theory, possible if a system has more than one
news feed).  If it already got it before, it will write a message to
this effect in the log file, and stop the delivery. Otherwise, a
record for this article will be added to the history database.
.sp 1
Inews then scans through the system's
.B active
file, to see which sequence number the article will get.  If the
news group cannot be found in this file, inews will try to use
the junk group again, to prevent the article from getting lost.
.sp 1
Inews now locks the active file, and increases the number of the
next available article.  Finally, the article's temporary copy
is linked to a file with a name identical to the ASCII representation
of the sequence number for this article.  So, when using a news
group of
.B comp.os.minix
, we get a total path name of:
.sp 1
.IN "/usr/spool/news/comp/os/minix/NNNNN"
.sp 1
with
.B NNNNN
being the number of the article in that news group.  This naming
scheme allows for up to 65535 articles per news group, without the
physical need for expiration of articles.  Larger NEWS installations
use a 10-digit number instead of the usual 5-digit number.
.sp
This process of linking the temporary copy of the article to files
in the spool directories of the various news groups is repeated for
all news groups in the
.B Newsgroups:
field of the article.  Thus, only one copy of the article is on the
disks; the rest of all occurrences are links to the same article
to save disk space.
.sp 1
.B NOTE:
this requires all directories to be on the same disk!
.sp 1
Finally, inews will check the
.B sys
file to see if it has to send this article to other systems as well
(this is called
.B relaying
of news articles).  If so, it will send the article to the remote system
as described in the
.B FILES
chapter under section
.B sys
, since this can be set on a per-system basis.
.sp 1
Again, a note is written to the system log file telling to which systems
the article has been relayed.  Also, if resource accounting is enabled,
a record is written about the relaying of this article.
.sp 1
Inews now has successfully posted the incoming article to the local
system, and to any systems that were interested in the article.  It
will remove all temporary files, and exit.
.sp 1
For more information on how to invoke the inews program, see the
.B inews(8)
manual page.
.HD control
This program implements the various types of
.B "control messages"
that can be sent out using the NEWS system.  Typically, these
messages are used to add and/or remove news groups, and to
cancel previously sent articles.  Since most of these messages
share a fair amount of code, it was implemented as a single
program with a link for each of the available functions.
.sp 1
A control message is a news article with a special field in the
message header (named
.B Control:
), which can be used to tell other NEWS-running systems to perform
certain management-operations like creating or deleting a newsgroup,
or cancelling a message that was previously sent.
.sp 1
For example, the system administrator of a network may decide to
create a new newsgroup on the network.  He (or she) then posts a
control message, which looks something like:
.sp 1
.nf
 Path: minixug!mugadm
 From: [e-mail] (MUGNET Administrator)
 Newsgroups: mugnet.gov
 Distribution: world
 Control: newgroup mugnet.questions
 Subject: newgroup mugnet.questions
 Date: Thu, 28 Feb 91 17:45:00 GMT +0100
 Approved: [e-mail] (MUGNET Administrator)
 Lines: 1

 This news group is for questions from novice users on MUGNET.
.fi
.sp 1
The meaning of this article is clear.  A new newsgroup is to be
created, named
.B mugnet.questions
, with its description being the first line of the message body.
The message will go to all systems receiving the news group called
.B mugnet.gov
(which is the "official announcements" group on MUGNET, received
by all hosts on it), and the message will have a geographical
distribution of
.B world
(it is possible to only create such a group in a limited distribution,
by specifying the desired distribution).
.sp 1
This message causes the named news group to be created on all systems
receiving the message.  This includes the addition of a line to the
system's
.B active
and
.B newsgroups
files, and the creation of an empty spool directory for the news group.
.sp 1
On receipt of an article with the "Control" field present, inews assumes
that it is a control message.  It then takes the first word of the
field, and uses that as name of a program to run (in our example, it
would try to run the command
.B newgroup
in the system's LIBDIR (
.B /usr/lib/news
) directory).  The program gets the article as its standard input,
since certain control messages use the text in the message body as
well.
.sp 1
The result of the control message will be mailed to the NEWS system
administrator, together with the contents of the message.  Alternatively,
it is possible to mail the entire control message to the administrator
without executing it, if it is not desired that control messages are
executed automatically.  The administrator can then execute message if
he or she desires to.
.sp 1
For more details on how to create and execute control messages, see the
.B control(8)
manual page.
.HD sendbatch
The news batches are generated by scanning the
.B /usr/spool/batch
directory for files that are kept for all systems connected to
this host, one file per host (usually with the same name as the
host). These files contain the names of any articles that need
to be sent to that system. All these articles are then concatenated
together, prefixing them with the
.sp 1
.IN "#! rnews NNNN"
.sp 1
header line. In this header,
.B NNNN
is the number of bytes (characters) in the article. Articles are
added to the current batch as long as they still fit in it (which
can be set either manually at the time of batching or by default
at compile-time). As soon as a batch is complete, it is closed and
sent to the UUCP system, possibly via the
.B compress(1)
program. This compression of the batch is indicated by the extra
.sp 1
.IN "#! cunbatch"
.sp 1
header line.  The batch is sent to the UUCP system by issuing a
command like:
.sp 1
.IN "/usr/bin/uux -r -gd - system_name!rnews < batch_file_name"
.sp 1
which means, that the
.B uxx(1C)
program is run, with the newly generated batch file as its input.
The
.B -r
flag specifies that the job should be queued rather than to call
the system
.B system_name
at once.
.sp 1
After having sent the batch file, a new file is created, and the
process of batching all articles continues.
.sp 1
When no more articles are remaining, the current batch is closed,
and sent to UUCP if it has at least ore article in it, to prevent
UUCP from creating empty jobs. After having sent the last batch file,
it removes the lock file and exits.
.sp 1
See the manual page of the
.B unbatch(8)
program for more details on how to invoke this program.
.HD expire
Systems that receive articles via the NEWS system often find that
this can mean a substantial load on the disks, both in terms of
required space and use.  Especially the amount of disk space
required to store incoming and outgoing articles is something of
a problem to system administrators, since many news packages (
W-NEWS included) have no way of controlling the amount of space
used by the NEWS system.  The software just uses disk space until
the disks are full...
.sp 1
On the other hand, it is a waste of disk space to keep articles
online forever, since most of them will not be of lasting importance.
It is said that most articles have a certain
.B "expiration date"
, much like certain news bulletins.  This means, that articles can
be removed from the system's disks after this date, either to an
archiving subsystem (for later retrieval of the articles) or to
the Great Bit Bucket.
.sp 1
The
.B expire
program is taking care of expiring these old articles from the system
disks.  It has numerous command line options to tell it what to do
with old articles, and it can be told how to determine the age of an
article.
.sp 1
The basic strategy of this program is to simply walk through all news
spool directories, and have a look at the articles in those directories.
For each article, it will determine its age (in days), and it will then
decide if the article should be expired.  If it has to be, it can do
one out of three things:
.sp 1
.IN "1. Remove the article from the system"
.IN "2. Move the article to a different disk"
.IN "3. Archive the article and then remove it"
.sp 1
If the system's NEWS host already archives news articles, it is the
easiest to either remove the article, or to move it into another part
of the system's file system (often in the directory called
.B /usr/spool/oldnews
).
.sp 1
However, it may also be useful to archive the articles in certain
news groups (for example, source postings and such).  Expire can do
this as well, it can be told which archiving program to use in that
case.
.sp 1
After the entire tree of spool directories has been processed, expire
locks the system's
.B active
file and updates it.  This means, that the second set of digits in the
file contain the number of the first article in that news group that
has not yet been expired.  The news readers can use this number to
see which is the first article actually available in the news group.
After the updating is done, the lock is removed and expire exits.
.sp 1
Since expiring articles is a fair load on the system, it is advised
to only expire at times when the system is not doing much other work.
It also prevents the clashing of users ready news while expire is
removing articles from the system.
.sp 1
A note about the removal of an article is written to the NEWS system's
log file, to allow the system administrator to trace the entire life
of an article, from the moment it came in until and including its
expiration.
.sp 1
For more details on how to use this program, see the manual page for
the
.B expire(8)
program.
.HD pnews
Posting news is done by presenting the contents of the news article
as input to the
.B inews
program.  However, it requires a fair deal of knowledge about the
inews program (and of the NEWS system as a whole) to be able to post
news articles this way.  Therefore, any news system usually provides
one or more programs that can generate, read and often reply to news
articles.  These programs usually are (more or less :-) user-friendly,
and the users are often allowed to invoke their favourite text editor
to create the actual article text.
.sp 1
.B Pnews
is such a user-friendly news-creating program.  It uses a message
composing editor similar to the one found in the
.B W-MAIL
mailer program, which, in turn,  is very similar to the UNIX-standard
.B mailx
program.  Thus, users who are at some level familiar with the use
of one of the programs named above will have little difficulty in
posting news articles with this program.
.sp 1
See the manual page for
.B pnews(1)
for more details on how to use this program.
.HD checknews
The
.B NEWS
system maintains a file in which the actual number of articles per
news group are stored: the
.B active
file.  Most news-reading programs also maintain a file called
.B .newsrc
for each user, which holds the numbers of the articles that have been
read by the user, to prevent the user from having to read through ALL
news each time.
.sp 1
This program simply compares the system's active file with  the
contents of the .newsrc file of the calling user.  If it detects that
new articles have arrived since the last time the user's .newsrc file
was modified, it will print a message to this effect.  Alternatively,
it may be told to only say something when there is NO news waiting to
be read.  With use of some command-line arguments, the user can also
select a set of news groups to be checked.
.sp 1
See the manual page of the
.B checknews(1)
program for more details on how to invoke this program.

.CD "F I L E S"
This chapter describes the format and use of the various files used
by the NEWS system.  Most of these files are either compatible with
their counterparts on UNIX systems (sys, active), or they are unique
to W-NEWS (i.e. the accouting files).

.HD "active"
The system's
.B /usr/lin/news/active
file holds the status of each news group that is active on the system.
It is an ASCII text file with each line describing exactly one news
group.  The line format is:
.sp 1
.IN "NAME<SPACE>XXXXX<SPACE>YYYYY<SPACE>MODE"
.sp 1
with
.B NAME
being the name of the news group,
.B XXXXX
being the 5-digit, zero-prefixed ASCII representation of the number of
the article most recently received,
.B YYYYY
the number of the first article that has not yet been expired, and,
finally,
.B MODE
is a single character describing the status of the news group.  It can
be either one of:
.sp 1
.IN "y - users may post to this news group"
.sp 1
.IN "n - users cannot post to this group"
.sp 1
.IN "m - this is a moderated news group"
.sp 1
The first two modes are self-explanatory.  However, the third mode (the
.B moderated
news group mode) deserves an explanation.
.sp 1
In some news groups (like official network management bulletins) it is
often undesirable to have the network users post articles to that news
group.  However, it is also a hassle to keep changing the status from
.B n
to
.B y
each time an official announcement is posted.  So, the original implementors
of the NEWS system thought of the
.B moderator-concept
, which means, that there is only one person that can acually post articles
to the news group (this person is called the
.B moderator
of this group). To the moderator, it looks like any other non-moderated
news group.
.sp 1
However, when "ordinairy" people post an article to this news group, the
NEWS system ultimately finds out that it is a moderated group, and it then
uses a trick to get it posted...
.sp 1
The trick is, that the article is sent to the moderator of the news group
by
.B e-mail
, thus allowing the moderator to first have a look at the article before he
or she actually posts it.  To get this done, all major network backbones in
the world maintain a list of
.B aliases
, which describe the moderators for the moderated news groups.
.sp 1
For example, suppose there is a moderated group called
.B net.security
, with the moderator being
.B "Jack Safe <[e-mail]>"
(which is his e-mail address at work).  The major network backbones know
this, since their e-mail alias database lists the following entry:
.sp 1
.IN "net-security  [e-mail] (Jack Safe)"
.sp 1
or something to that effect.  So, to post an article on this news group,
a NEWS system only has to send the article as e-mail to the address:
.sp 1
.IN "net-security@my_nearest_backbone"
.sp 1
and the article gets delivered.  By now, it should be clear that the
alias of the moderator is identical to the name of the news group, with
all dots changed to dashes.
.sp 1
.B
Note
: this feature has
.B not
yet been implemented in W-NEWS!
.sp 1
To make the updaing of the active file as fast as possible (it is usually
quite large, containing most if not all of the news groups available
world-wide!), the file's contents are updated
.B "in place"
, which means that the file is not rewritten each time, but the programs
simply modify some bytes in it.  This is why the numbers have a fixed size
of 5 digits (also 10 digits in larger NEWS installations), with the numbers
being zero-prefixed.  See the comments in the NEWS software sources for
more comments on this.  You may have to tweak the system to be able to
get this updating to work properly!
.sp 1
A sample active file might look like this:
.sp 1
.nf
 mugnet.gov 00034 00030 y
 mugnet.maps 00006 00005 y
 mugnet.newgroups 00003 00003 y
 mugnet.sources 00048 00000 y
 mugnet.sources.d 00026 00019 y
 mugnet.talk 00124 00089 y
 mugnet.test 00158 00146 y
.fi
.sp 1
Again, note that this file usually is
.B "a lot"
larger than the example!
.sp 1
Also, in the example, the
.B mugnet.gov
news group (for MUGNET Network Announcements, see below) is an
example of a news group that
.B should
be moderated.  However, since the W-NEWS package does not yet
know about moderated groups, it is set to "postable" for now...

.HD "sys"
The
.B /usr/lib/news/sys
file is one of the most important files in the NEWS system.  It
defines the names (and/or classes) of the news groups in which
the local system is interested, and it defines to which distribution
codes the system belongs.  Also, it defines the systems that are
connected to the local system, exchanging NEWS articles.
.sp 1
As most files in the NEWS system, sys is a simple ASCII text file,
with one line describing exactly one system.  The first line
.B MUST
be the line for the local system (this is not a feature, it is a
true bug- for simplicity).  The line format is defined as follows:
.sp 1
.IN "sysname:distributions,subscriptions:transport:filename"
.sp 1
In this format, there are four fields, separated from each other by
colons.  The first field contains the UUCP name of the system to be
defined.  It
.B MAY
be the text
.B ME
to indicate (in a portable manner) that this entry is for the local
system.  The third field describes how this system wants to receive
the articles, since not all systems can do it using the same protocol.
The field contains a single-character transport code, which can be one
of the following:
.sp 1
.IN "B - use B News article format"
.sp 1
.IN "F - use batches of 'B' formatted articles"
.sp 1
.IN "X - use a special program to deliver"
.sp 1
The default (i.e. no code at all- an empty field) is the same as
.B B
, since that is the most often used format of articles.  Note, that
W-NEWS does
.B NOT
support the old
.B "A News"
formatted articles.  If the 'B' format is selected, then the fourth
field is neither used nor checked.  The article is sent to the
system via the UUCP system
.B uux(1C)
command at once.  The UUCP system then decides if the call should
be made at once or not.
.sp 1
If the
.B F
code is selected, the article will be added to the list of articles
that have to be sent to that system.  The name of this list file is
expected to be in the fourth field, and defaults to:
.sp 1
.IN "/usr/spool/batch/sysname"
.sp 1
if no name is presented there.  See the chapters on the
.B sendbatch(8)
and
.B unbatch(8)
programs for more details on how a batch of articles is created.
.sp 1
Finally, the
.B X
code can be used to specify the path name of the special program to
be used for the delivery.  This is mostly useful for sending articles
to an automated archiving system, like in the example file below.
The complete path name plus the arguments to the program are expected
to be in the fourth field.
.sp 1
A sample sys file might look like this:
.sp 1
.nf
 ME:world,nl,mugnet,news,comp,!rec,!soc,!sci:F:
 minixug:world,nl,mugnet,all.all:F:
 archive:world,nl,mugnet.sources:X:/usr/ucb/archive -I
.fi
.sp 1
Now, what is this silly stuff in the second field about?  It looks
rather odd, eh?
.sp 1
Well, the second field is called the
.B "subscribtion list"
of that system.  It also contains the code of the distributions to
which that systems belongs.  All subfields in this field are separated
by commas, as can be seen above.
.sp 1
Usually, the field starts with the list of distribution code.  Then,
all news group classes (i.e. names without dots- see below), possibly
followed by a number of selected news groups.
.sp 1
The NEWS system uses a
.B wildcarding
scheme that is somewhat similar to the use of the asterisk (*) in the
standard UNIX shell.  Instead of the asterisk, the term
.B all
(or simply no term at all) is used as a wildcard.  So, the text:
.sp 1
.IN "world,comp,soc.culture.all,sci.all"
.sp 1
means: all groups below the
.B comp
class (in shell notation: comp.*), plus all groups below the
.B soc.culture
and
.B sci
level.  This scheme allows one to subscribe to a large number of news
groups without the need for enourmous subscription lists.
.sp 1
However, one has to be able to tell the system that only
.B certain
news groups are not of interest to the system.  For example, if we
 expand the above example to:
.sp 1
.IN "world,comp,soc.culture.all,!comp.os.msdos"
.sp 1
then all groups in the
.B comp
class will be received except for the
.B comp.os.msdos
news group.  So, one can start off with specifying ALL, followed by
a certain number of
.B not
subscriptions...
.sp 1
It is common practice to have the news feeding host setup a master
selection of news groups, to prevent the local system from having to
download too much articles that will be thrown away anyhow.  The local
system then refines the selection as much as is desired by the system
administrator.
.sp 1
Note, that the larger NEWS software packages have lots of other options
that can be presented in this file.  However, for the sake of simplicitly,
most of them have not been implemented in W-NEWS, and probably never will
to keep the package as small and fast as possible!

.HD "newsgroups"
The NEWS system maintains a database of news groups that are active
in the world.  This database is maintained as a simple ASCII text
file, organized as lines of text with two fields (separated by one or
more <TAB> and/or <SPACE> characters).  The first field identifies the
name of the news group, the second field provides an explanation about
the nature of this news group.  It is maintained automatically by the
NEWS system, since this is one of the files changed by the
.B newgroup
and
.B rmgroup
control messages.
.sp 1
A sample
.B /usr/lib/news/newsgroups
file might look like:
.sp 1
.nf
 mugnet.gov        Discussions about MUGNET politics.
 mugnet.maps       MUGNET UUCP Mapping Project Map postings.
 mugnet.newgroups  Announcements of/requests for new groups.
 mugnet.sources    MUGNET-wide source postings.
 mugnet.sources.d  Discussions about postings in mugnet.sources.
 mugnet.talk       Any talk.
 mugnet.test       MUGNET-wide test group.
.fi
.sp 1
Note, that this file is usually quite large, since it contains the
definitions of ALL new groups active in the world.  This is just an
example of what might be in it!
.sp 1
This file is used only by user-programs like news readers and posters,
to inform the user about which groups can be selected.  It therefore
must be readable by all users who have access to the NEWS system.

.HD "distributions"
This ASCII text file contains the definitions of the distribution
codes that are valid on the system.  A distribution code identifies
the geographical spread of an article, which is useful for certain
types of messages.  The file contains of lines of ASCII text, with
only two fields (separated by one or more <TAB> and/or <SPACE>
characters).  The first field is the name of the distribution code,
to be used in article headers. The second field is the explanation
of the distribution.
.sp 1
A sample
.B distributions
file could be:
.sp 1
.nf
 local   local to this site
 mugnet  everywhere on MUGNET
 world   everywhere in the world
 nl      Netherlands only
 de      Germany only
 fr      France only
 uk      United Kingdom only
 usa     United States only
.fi
.sp 1
Note, that this file is only used by the
.B pnews
program to see if the user typed a valid distribution code.  It must
therefore be readable by all users who may post news!

.HD "log"
The
.B /usr/lib/news/log
file contains a written record of all NEWS system activity.  All kinds
of things can go wrong with a system that runs NEWS, so it is important
to be able to see what happened with incoming and outgoing articles.
.sp 1
By looking in the logfile, a system administrator is able to trace the
entire life time of an article; from the moment it came in via UUCP
(or Internet) or from the moment it was posted, up to and including the
moment the article got expired.  All system errors will be written to the
.B errlog
file, so the system administrator does not need to watch this file very
closely if the system is running OK.  However, this file grows very fast,
so it should be cleaned up every now and then.  That is also the right
time to have a close look at the errlog file, after which they can both
be removed.
.sp 1
All messages in the log files are from the
.B inews
program, unless the message is explicitly prefixed by the name of the
program writing the message.  Also, all messages are prefixed with a
date/time stamp, and, if possible, with the ID of the article that
caused the error.

.HD "errlog"
The
.B /usr/lib/news/errlog
file contains a record of all errors that occurred during the execution
of the various NEWS modules.  It should be watched closely!

.HD "history"
The
.B HISTORY
mechanism can be used to detect the arrival of articles that have
been received before.  This can happen if a system has more than
one news feeding host, with all these hosts sending articles.
Whenever the system receives an article, it adds a record about the
arrival to the
.B /usr/lib/news/history
file. This file contains lines of ASCII text, with the following
field definitions:
.sp 1
.IN "msgid<TAB>date<SAPCE>time<TAB>newsgroup/artseqno"
.sp 1
So, the first field uniquely identifies a message.  The second field
forms the date and time at which the article arrived.  Finally, the
third (and last) field tells us where the article was stored.  Note,
that the name of the news group is written in NEWS style, not as a
UNIX path name.  Also note, that if an article was cross-posted to
more than one news group, there will be just as many entries of the
article in the history file.
.sp 1
A sample history file might look like this:
.sp 1
.nf
 <[e-mail]>    02/28/91 19:15  comp.os.minix/731
 <[e-mail]>    02/28/91 19:15  comp.os.minix/735
 <[e-mail]> 02/28/91 19:16  comp.os.minix/750
.fi
.sp 1
The history file is also updated by the
.B cancel
control message.  The program that executes this message simply
reads through the history file, and removes all occurrences of
a certain article on the disks.  It also removes their entries
in the history file.
.sp 1
Note, that this feature is relatively expensive in terms of both
disk space usage and CPU cycle demand.  Use it only when you
really think you need it.  Usually, the news host takes care of
cancelling articles!

.HD "news.adm"
If NEWS resource accounting is enabled at compile time, this file
will contain the accounting records of the NEWS system.  A record
is a line of ASCII text, formatted as follows:
.sp 1
.IN "yy/MM/dd<SPC>hh:mm<TAB>type<TAB>dist<TAB>size<TAB>host"
.sp 1
In this definition, the first field forms the date and time the
record was created. The second field indicates the type of accounting
record.  It can either be
.B sent
or
.B recv
, meaning "I sent this article" and "I received this article" respectively.
The third field is the value of the
.B Distribution:
article header field. It is needed because it may be the case that not
all types of distributions are equally expensive.  The fourth field
is the ASCII representation of the article size in bytes.  Finally, the
last field is a list of host names.  If it is a
.B sent
record, then it this field indicates to which systems the article was
also relayed. Otherwise, it indicates from which host the article was
received.
.sp 1
A sample accounting file might look like this:
.sp 1
.nf
 91/02/01 10:00  rcvd    world   1168    nmrdc1
 91/02/01 10:00  sent    world   1168    drinkel pa3ebv uwalt
 91/02/01 23:16  rcvd    world   740     pa3ebv
 91/02/01 23:16  sent    world   740     nmrdc1 drinkel uwalt
 91/02/02 01:40  rcvd    nl      44245   uwalt
 91/02/02 01:40  sent    nl      44245   nmrdc1 drinkel pa3ebv
 91/02/02 01:40  rcvd    nl      44249   uwalt
 91/02/02 01:40  sent    nl      44249   drinkel pa3ebv
 91/02/02 01:40  rcvd    nl      37390   uwalt
 91/02/02 01:40  sent    nl      37390   drinkel pa3ebv
 91/02/03 23:55  rcvd    world   791     wiesje
 91/02/03 23:55  sent    world   791     nmrdc1 drinkel pa3ebv
 91/02/06 04:30  rcvd    nl      1644    drinkel
 91/02/06 04:30  sent    nl      1644    pa3ebv uwalt
.fi
.sp 1
Note, that this feature is relatively expensive in terms of both
disk space usage and CPU cycle demand.  Use it only when you have
to...

.HD "organization"
The file called
.B /usr/lib/news/organization
contains a line which is used as the value of the
.B Newsgroups:
field in the article header.  If the file is not present, or is
empty, the field is not generated at all.  A sample line might
be:
.sp 1
.IN "MicroWalt Corporation, for MINIX Software Development"
.sp 1
which is the organization name of my software development company.

.HD "/etc/uucpname"
This file (which is actually part of the NLMUG UUCP system) contains
one or two lines of ASCII text.  The first line contains the system's
UUCP name (usually with a maximum of 7 characters).  The second
line, if present, contains the name of the domain in which the
system lives.  If this line is not present, the domain name
defaults to
.B .UUCP
since this is the pseudo-domain name for UUCP systems.
.sp 1
On a typical MINIX system in MUGNET, the file might contain the
following lines:
.sp 1
.IN "uwalt"
.IN "nl.mugnet.org"
.sp 1
which means that the full name of the system is:
.sp 1
.IN "uwalt.nl.mugnet.org"
.sp 1
This file is checked automatically during NEWS installation.

.CD "N E W S    R E A D E R S"
These programs can be used to read the available news articles, in
either line-mode (like the standard
.B mail
program) or in full-screen mode. The
.B rna
program is one of the available line-oriented news readers, and the
program called
.B vn
can be used to read news in a full-screen visual mode. Below you will
find excerpts of the manuals supplied with both programs.

.HD "rna"
.B Rna
is a news reader which is a part of the NSWN News system. It is
compatible with the standard version of
.B readnews
as supplied with the
.B "B News"
system.
.sp 1
Author: Michael Rourke, University of N.S.W
.br
.nf
        (decvax!mulga!michaelr:elecvax)
.fi

.HD "vn"
.B Vn
is a news reader which uses the same .newsrc file as readnews(1),
but displays and interacts differently. It is aimed at allowing
you to rapidly scan a large number of newsgroups, looking for
something you want to read. The major premise is that you will be
interested in a small number of articles, but will be interested
in keeping tabs on a large number of newsgroups which may contain
something interesting from time to time. It also has the ability
to unpackage digests.
.sp 1
Author: Bob McQueer.
.sp 1
Significant enhancement / bugfixes / suggestions from:
.sp 1
.in +5
.nf
Lawrie Brown, John G Dobnick, Greg Earle, Rodney Goke,
Andy Marrinson, Jay Maynard, Marius Olafsson, George Pavel,
Dave Tallman, Larry Tepper, Karl Williamson, Mark Wittenberg,
Andrew Worsley and many others.
.fi
.br
.in

.HD Tass
.B Tass
is a full screen threaded newsreader:
.sp 1
.nf
    o Organizes articles by threads.  Displays a really nice
      article selection page.
    o Group selection page makes it easy to scan newsgroups,
      subscribe, unsubscribe, reorder your .newsrc
    o If you've ever used Notes, this is the program for you.
.fi
.sp 1
Tass looks a lot like Notes, but has a few improvements:
.sp 1
.nf
    o Visual group selection page, Notes didn't have one.
    o rn style unread article detection as opposed to single
      timeline uses standard /usr/spool/news article layout
.fi
.sp 1
Newsreading style under Tass tends to be different than with rn.
Instead of plowing through each group reading everything unread,
you may find yourself reading fewer articles in more groups.  It's
easier to skip about and only read interesting threads with Tass.
.sp 1
Tass keeps an index file for each group.  The first time you enter
a group, it will be a bit slow creating this file.  After that Tass
will incrementally update the index file and there should be little
delay.
.sp 1
Author: Rich Skrenta <[e-mail]>
.sp 1
Ported to MINIX by Wim van Dorst <[e-mail]>
.sp 1

.CD "V A R I I"
This chapter contains various bits 'n' pieces of information, which
are usually found in "manpage" style manuals.

.HD AUTHOR
The W-NEWS program has been written by Fred N. van Kempen. The general
outline of the various modules is similar to the outline found in the
.B "B\ News"
system (version 2.11) for UNIX systems. The
.B "Article Editor"
was derived from the
.B "W-MAIL Message Editor"
from the same author.  The news group pattern matching routines in
the
.B inews
program were taken (without permission) from the
.B "B News 2.11"
software package, which is freely redistributable.  It will be replaced
with another (home-made) routine as soon as possible.

.HD COPYRIGHT
This software is Copyright 1991 by MicroWalt Corporation.  It may be
freely used and/or distributed, as long as this notice and the headers
in the source files remain unchanged.  This software may not be used
and/or distributed for commercial purposes without prior written
consent from the Author.

.HD CHANGES
The Author will release updates to this package on a regular basis.
Please send your comments, bug reports (preferrably with their
respective fixes) and additions to the address below.

.HD ADDRESSES
Please direct all questions/suggestions/remarks to this address,
either postal or e-mail:
.sp1
.nf
.IN "MicroWalt Corporation"
.IN "Attn: W-NEWS Support Desk"
.IN "Hoefbladhof  27"
.IN "2215 DV  VOORHOUT"
.IN "The Netherlands"
.sp 1
.IN "E-mail: [e-mail] (W-NEWS Support Desk)"
.sp 1
.fi
Note, that the responding person is not necessarily the Author of
this software package!

.HD "BUGS"
Probably around, though not much. Certain things could be improved, if
only for speed or completeness. Better care should be taken with system
security in the
.B control
program, which is able to remove and create news groups.

.HD "SEE ALSO"
For more information on this topic, you might want to read one or more of
the following papers:
.sp 1
.nf
[1]  "The W-MAIL Reference Manual", Fred N. van Kempen 1990
     Available from NLMUG Archive Service

[2]  "The U-MAIL Reference Manual", Fred N. van Kempen 1990
     Available from NLMUG Archive Service

[3]  "The NLMUG UUCP Reference Manual", Fred N. van Kempen 1990
     Available from NLMUG Archive Service

[4]  "A Dial-Up Network of UNIX Systems", D. A. Nowitz 1974
     Bell Laboratories, Murray Hill, New Jersey 07974
     Also available from NLMUG Archive Service

[5]  "Uucp Implementation Description", D. A. Nowitz 1974
     Bell Laboratories, Murray Hill, New Jersey 07974
     Also available from NLMUG Archive Service

[6]  "B News version 2.11 manuals", Rick Adams et al 1987
     Available from NLMUG Archive Service
.fi

.bp