.\" =()<.ds a @<NEWSARTS>@>()=
.ds a /usr/spool/news
.\" =()<.ds b @<NEWSBIN>@>()=
.ds b /usr/lib/newsbin
.\" =()<.ds c @<NEWSCTL>@>()=
.ds c /usr/lib/news
.\" =()<.ds m @<NEWSMASTER>@>()=
.ds m usenet
.de Is\" indentation start
.in +0.5i
..
.de Ie\" indentation end
.in -0.5i
..
.de Es\" example start
.LP
.nf
.ft B
.Is
..
.de Ee\" example end
.Ie
.ft R
.fi
.LP
..
.TH NEWS 5 "8 June 1989" "C News"
.SH NAME
news \- USENET network news articles, batches, related files
.SH DESCRIPTION
There are two formats of news articles:
.BR A " and " B.
.B A
format is obsolete,
but
looks like this:
.Es
A\fIarticle-ID
newsgroups
path
date
title
Body of article
.Ee
A
.B B
format
.I article
consists of a series of headers
and then the body.
A header
line is defined
(approximately)
as a line
at the start of the article
or immediately following a header line
with a capital letter
as the first character and
a colon immediately following the first word,
of alphanumerics and dashes,
on the line
(a specialisation of RFC 822 format).
Continued headers are as per RFC 822.
Unrecognized headers are ignored.
News is stored in the same format transmitted,
see ``Standard for the Interchange of USENET Messages''
(RFC 1036 nee 850)
for a full description.
The following headers are among those recognized:
.LP
.Is
.B From:
.IB user @ "host.domain[.domain ...]" " ("
.IB "Full Name" )
.br
.B Newsgroups:
.I "news groups"
.br
.B Message-ID:
.BI < "Unique RFC822 message-id" >
.br
.B Subject:
.I descriptive title
.br
.B Date:
.I date posted
.br
.B Expires:
.I expiration date
.br
.B Reply-To:
.I address for mail replies
.br
.B References:
.IR "Message-ID of article this is a follow-up to" .
.br
.B Control:
.I text of a control message
.Ie
.LP
Here is an example of an article:
.Es
Path: att!eagle!jerry
From: jerry@eagle.uucp (Jerry Schwarz)
Newsgroups: news.announce
Subject: Usenet Etiquette -- Please Read
Message-ID: <642@eagle.UUCP>
Date: Friday, 19 Nov 82 16:14:55 EST
Followup-To: news.misc
Expires: Saturday, 1 Jan 83 00:00:00 EST
Organization: Bell Labs, Murray Hill

The body of the article comes here, after a blank line.
.Ee
A
.I "news batch"
consists of zero or more articles,
each preceded by a line of the form
.Es
.BI "#! rnews" " byte-count"
.Ee
where
.I byte-count
is the number of bytes in the following article,
where each newline is counted as a single byte,
even if it is stored as a CR-LF or
some other representation.
Spaces are significant:
one before and one after
.BR rnews .
News batches are usually transmitted
.IR compress ed.
.LP
Various peculiar optional encapsulations of news batches exist
which consist of doing something to the
(probably compressed)
batch,
then prepending a
.BI #! " goo"
line to the output,
where
.I goo
reflects the form of encapsulation;
known values of
.I goo
include
.B cunbatch
(the null encapsulation),
and
.B c7unbatch
(encode the batch using only seven bits per character).
.LP
The
.I sys
file line has four fields,
each separated by colons:
.LP
.IB system-name / exclusion1 ,\c
.IB exclusion2... : subscriptions /\c
.IB distributions :\c
.IB flags : "transmission command"
.PP
A
.B #
as the first character in a line denotes a comment.
Blank lines are ignored.
A logical line may be continued to the next physical line by
putting a
.B \e
at the end of the line.
.PP
Of the \fIsys\fR fields,
only the
.I system-name
need be present.
If a field and all the fields after it are omitted,
the colon immediately before that field and all the colons
after it may be omitted too.
The optional subfields
(\c
.IR exclusion s
and
.IR distributions )
and their leading slashes
may be omitted.
.PP
The
.I system name
is the name of the system being sent to,
and
is checked against site names in
.B Path:
headers to avoid sending an article back
to a site that has seen it.
The special name
.B ME
stands for the name of the machine news is running on,
as determined by some operating-system dependent means
such as
.IR hostname (2)
or
.IR uname (2).
The
.IR exclusion s
are also checked against the
.B Path:
header and articles are not sent to
.I system name
if they have visited any of the
.IR exclusions .
.PP
The
.I subscriptions
is the list of newsgroups to be transmitted to the
.IR system
(or received if
.I system
is the current site);
they are matched against the
.B Newsgroups:
header of each article
and any matching articles are transmitted:
.B all
matches any single word,
stopping at periods and commas;
.B comp
also implies
.BR comp.all ,
recursively;
.B !talk
.I mismatches
all the
.B talk
groups;
order is unimportant;
.B comp,comp.sys.sun,!comp.sys
matches all the
.B comp
groups,
.I except
the
.B comp.sys
groups
.I "but including"
.BR comp.sys.sun .
The
.I distributions
are matched similarly with the
.B Distribution:
header,
but only when sending articles;
.I distributions
do not affect receipt of articles.
If no
.I distributions
are supplied,
the
.I subscriptions
will be matched against
.B Distribution:
instead.
.PP
The
.I flags
are a set of letters describing how the article should be transmitted.
Valid flags include
.B f
(interpret
.I "transmission command"
as a file name and write the name and size in bytes of each
article on the end of it),
.B F
(like
.B f
but omit the size),
.B I
(like
.B F
but write Message-ID:s instead of filenames),
.B n
(like
.B F
but write a Message-ID: after each filename),
.BI L n
(only send articles
generated within
.I n
hops of here;
0 is the default value for
.IR n ),
.B m
(transmit only moderated groups),
.B u
(transmit only unmoderated groups).
There are other obsolete ones.
.LP
The
.I transmission command
is executed by the shell with the article
to be transmitted as the standard input.
The default is
.RI "`uux \- \-z \-r " sysname !rnews'
for a command;
the PATH searched includes \*b/relay,
so that the commands described in \fInewsmail\fR(8)
are available as alternatives to \fIuux\fR.
If one of the \fIflags\fR has caused
this field to be taken as a filename,
the default is
.RI \*a/out.going/ sysname /togo;
if a filename is given but it does not start with `/', it is assumed
to be relative to the
\*a/out.going
directory.
.LP
Some examples:
.Es
# line indicating what we are willing to receive; note local groups on end
ME:comp,news,sci,rec,misc,soc,talk,to,can,ont,tor,ut

# sample insignificant feed not using batching
huey:news.config,to.huey/all::uux - -r -gd huey!rnews

# sample major batched feed, including (unnecessary) explicit file name
dewey:comp,news,sci,rec,misc,soc,talk,to.dewey,can,ont,tor,ut/all:f:dewey/togo

# sample long-haul feed; note no local groups
donald:comp,news,sci,rec,misc,soc,talk,to.donald/all:f:

# sample local-postings-only feed direct to major site (gets them out fast)
scrooge:comp,news,sci,rec,misc,soc,talk,to.scrooge/all:Lf:

# sample ihave/sendme link
# Send ihave telling louie what we have -- batcher turns the batch into a
# giant control message and posts it to "to.louie".  (#1)
louie:rec.music.synth/all,!sendme,!ihave:I:louie.ihave/togo
# Send sendme in response to ihave from louie -- again, turned by batcher
# into giant control message posted to "to.louie".  (#3)
louie-send-ids:to.louie/ihave:I:louie.sendme/togo
# Transmit said giant control messages by normal batching.  (#2,#4)
louie-ctl:to.louie/all,!sendme,!ihave:f:louie/togo
# Send articles in response to sendme messages from louie. (#5)
louie-real:to.louie/sendme:f:louie/togo
# Actually the last two could be combined.
.Ee
(The ``to.\fIsysname\fR'' groups are normal newsgroups used for testing
individual news feeds.)
.PP
Somewhere in the
.I sys
file,
there must be a line for the host system.
This line has no
.IR flags " or " commands .
.LP
The
.I active
file contains one line per
locally-valid news group.
Each line consists of four blank-separated fields:
newsgroup name,
highest local article number assigned,
lowest local article number in use (approximately),
and
a flag.
Both article-number fields are at least five digits wide.
(Some older news software may expect exactly five digits.)
The current flag values are
.B y
(a normal unmoderated group),
.B n
(like
.B y
but local postings disallowed),
.B m
(a normal moderated group),
.B x
(a locally-disabled group,
no articles will be filed here),
and
.B =
(followed by the real group
under which to file articles in this group;
articles are treated exactly as if their
.B Newsgroups:
header specified the real group instead of the original one;
highest and lowest fields are ignored).
An example:
.Es
comp.org.usrgroup 0000000006 00004 y
talk.bizarre 0000296123 292136 n
comp.sys.sun 0000000175 00173 m
list.sun-spots 0000000076 00076 =comp.sys.sun
comp.os.vms 0000000000 00000 x
.Ee
The
.I history
file contains one line for each article received.
Each line consists of three tab-separated fields:
a
.IR Message-ID: ,
the arrival time as seconds since midnight,
Jan 1, 1970
and
the
.B Expires:
value
(a dash indicates there was none)
separated by a tilde,
and
the list of links to this article.
If an article has been expired or cancelled without being seen first,
the list of links and the tab before it are omitted.
An example:
.Es
<3451@hcr.UUCP>	581905588~-	comp.text/1317 comp.sources.wanted/4200
<9383@alice.UUCP>	611934511~-
.Ee
.SH SEE ALSO
.IR checknews (1),
.IR compress (1),
.IR inews (1),
.IR postnews (1),
.IR readnews (1),
.IR rn (1),
.IR vnews (1),
.IR getdate (3),
.IR expire (8),
.IR newsbatch (8),
.IR newsmail (8),
.IR relaynews (8),
.IR recnews (8),
.IR rnews (8),
.IR sendnews (8),
.IR uurec (8),
.IR newsinvaders (9.1)
.br
ARPA Internet RFCs 1036 and 850
.SH BUGS
B format articles must not start with
.BR A ,
to distinguish them from
.B A
format,
which is only a problem if moderators put
.B Approved:
first.
.br
.B Control:
and
.B Newsgroups:
are not required to be the first headers,
if present.
.br
People insist on making their whacko local encapsulation schemes
.RB ( cunbatch ,
etc.)
.IR rnews 's
problem.
.br
One could argue that RFC 822
is less than an ideal base for article format.