.\" $Header: /nfs/papaya/u2/rsalz/src/newsgate/RCS/mail2news.1,v 1.13 91/07/18 15:01:54 rsalz Exp Locker: rsalz $
.TH MAIL2NEWS 1 LOCAL
.SH NAME
mail2news \- feed a mail message into Usenet news
.SH SYNOPSIS
.B mail2news
[
.B \-\&.
] [
.B \-F
] [
.BI \-= program
] [
.BI \-n newsgroups
] [
.BI \-o organization
] [
.BI \-d distribution
] [
.BI \-a approval
] [
.B inewsflags
]
.SH DESCRIPTION
.I Mail2news
reads an RFC822 Mail message on standard input, writes the headers to conform
with RFC1036 (superceeding RFC850) Usenet News article.
A subject is required, unless one of the
.IR inews (8)
``\-x'' or ``\-o'' flags are specified.
.PP
If the ``\-.'' flag is specified, the modified article is sent to the
standard output, rather than feed into
.IR inews .
.PP
By default,
.I mail2news
sends its input to ``inews \-h''; this can be changed by using the ``\-=''
flag, which will send the output to the specified program.
Note that no argument parsing is done, so that only a single word may
be specified with the ``\-='' flag.
.PP
The ``\-o,'' ``\-n,'' ``\-d,'' or ``\-a'' flags may be used to specify the
Organization, Newsgroups, Distribution, or Approved header in the message.
Note that unlike the
.I inews
parallels of these flags, the ``\-n'' flag overrides any Newsgroups header
that might appear in the message, while the other flags specify defaults
if the message does not have the headers.
In addition, as a concession to
.IR sendmail (8)
alias processing the argument to the ``\-o'' flag is handled specially.
Since many
.I sendmail.cf
files do not have the ``preserve case'' flag on for the ``prog'' mailer,
a period in the argument means that the following character should be converted
to uppercase; two periods mean to output a single period.
For example, if the following line is in
.IR /etc/aliases (5):
.RS
post\-news\-admin:
    "|/usr/bin/mail2news \-o '.the .b...b...n.. .gateway' \-n news.admin"
.RE
then messages to mailed to
.I post\-news\-admin
will be posted to the ``news.admin'' newsgroup with the following header line:
.RS
Organization: The B.B.N. Gateway
.RE
.PP
If the ``\-F'' flag is given, then
.I mail2news
will try to filter out
the ``please add me to your mailing list'' messages often sent by
network neophytes.
This is done by looking for short messages which have words like
.I subscribe
in them.
.PP
.I Mail2news
can modify the newsgroups an article is sent to, based on regular expressions
found in the ``Title:'', ``Keywords:'', and ``Summary:'' headers.
The headers are scanned once for each newsgroup the article is originally
destined for, provided a mapping file exists for the newsgroup.
(The path to the mapping file depends on a compile\-time parameter.)
For example, if a mail message is to be sent to
.I talk.foo
and
.IR soc.bar ,
.I mail2news
will scan the headers twice.
If the file
.I /usr/lib/news/.admin/talk.foo
(or
.IR /var/spool/news/talk/foo/recnews.cmd )
exists, the commands in that file are interpreted.
The scan is repeated, with the appropriate file for
.IR soc.bar .
In the explanation below, the ``current newsgroup'' will be first
.I talk.foo
and then
.IR soc.bar .
.PP
Blank lines, and lines beginning with a pound sign
.RI ( # )
are ignored.
Other lines should like like this:
.RS
.IR "delim pattern delim command whitespace " "[" "arg" "]"
.RE
The
.I delim
can be any character; if it appears in the pattern, it should be
preceeded by a backslash
.RI ( \e ).
The
.I pattern
is an
.RI `` ed (1)\-style''
regular expression, as detailed in the
.IR regex (3L)
manual page.
The
.I command
is a single letter from the set
.RI [ adkmq ],
and is described below.
The
.I whitespace
is, obviously, any combination of spaces and tabs.
Finally, the optional
.I arg
should be a comma\-separated list of newsgroups to be acted on by the
command.
.PP
The valid commands are:
.RS
.nf
.ta \w'm      'u +\w'Quiet kill    'u
a	Add	All newsgroups in the arg are added
d	Delete	The current group is deleted from the article
k	Kill	The article is returned, and arg is given as a contact name
m	Move	The current group is deleted and the arg group is added
q	Quiet kill	The article is quietly ignored
.fi
.RE
.PP
For example, here is a fragment from the mapping file for a
.I local.bboard
newsgroup:
.RS
.nf
.ta \w'/apartment/m   'u
# Move seminars and talks
/seminar/m	local.seminars,region.seminars
/lecture/m	local.seminars,region.seminars
# Move housing requests
/housing/m	local.housing
/apartment/m	local.housing
# Kill flames
/flame/k	the anti-flame society
/jerk/q	@placeholder
# Copy machine downtime announcements
/downtime/a	local.config,news.config
# If you want something, it's not forsale
/want/a		local.wanted
/want/d		@placeholder
.fi
.RE
The last two lines show how one might tweak cross\-posts, if the mapping
file were for a
.I local.wanted
newsgroup.
.SH DIAGNOSTICS
Almost all return values from system calls and standard I/O library routines
are checked.
If anything goes wrong, a diagnostic message is sent to standard error, where
it will presumably be picked up by
.I sendmail
(or other mail-processing program) and returned to the originator, who will
in turn be confused because she doesn't know anything at all about this
gateway program.
.SH FILES
.ta \w'uucp\-2\-inet  'u
uucp\-2\-inet	Mapping of ``Path:'' names to Internet hostnames.
.br
inews	News delivery program.
.br
The full paths to these files are compile\-time constants; see
.I gate.h
in the source for the exact details.
.SH "SEE ALSO"
gag(1L), mkmailpost(1L), news2mail(1L).
.SH AUTHORS
Rich $alz <rsalz@bbn.com>, after
.I nrecnews
by
.br
Erik E. Fair <fair@apple.com>.
.br
Ozan Yigit <yunexus!oz> wrote the regular\-expression routines.