Considerable redesign to incorporate UI enhancements from chiark

[sgt/utils] / nntpid / nntpid.but

\cfg{man-identity}{nntpid}{1}{2004-11-21}{Simon Tatham}{Simon Tatham}

\title Man page for \cw{nntpid}

\U NAME

\cw{nntpid} - retrieve a single article from a news server

\U SYNOPSIS

\c nntpid [ -v ] [ -d ] article [ article... ]
\e bbbbbb   bb     bb   iiiiiii   iiiiiii
\c nntpid [ -v ] [ -d ]
\e bbbbbb   bb     bb
\c nntpid [ -v ] -a newsgroup-name
\e bbbbbb   bb   bb iiiiiiiiiiiiii

\U DESCRIPTION

\cw{nntpid} makes a connection to a news server, retrieves one or
more articles, and displays them.

You can specify the article you want by either:

\b giving its Message-ID. Message-IDs are globally unique, so you
don't need to know which newsgroup the article was in. Also, they do
not vary between news servers.

\b giving a newsgroup name and an article number within that
newsgroup. Article numbers are assigned internally by a particular
news server, so they will be different on other servers carrying the
same group.

By default, \cw{nntpid} will try to display the article using a
pager (\cw{more}(1), unless you have specified an alternative in the
environment variable \cw{PAGER}). This is partly for convenience,
and partly a mild security measure: it gives you some protection
against the news article potentially containing control sequences
that cause unexpected behaviour in your terminal. If \cw{nntpid}
detects that its standard output is not a terminal, however, it will
bypass the pager and just write out the article directly.

There is an alternative mode of operation, enabled by the \cw{-a}
option, in which \cw{nntpid} retrieves \e{all} available articles in
the group and writes them to standard output in \cw{mbox} format.

The location of the news server is obtained by reading the
environment variable \cw{NNTPSERVER}, or failing that the file
\cw{/etc/nntpserver}.

\U ARGUMENTS

\cw{nntpid} will attempt to interpret its argument list as specifying
a series of news articles, as follows:

\b An argument containing an @ sign will be parsed as a Message-ID.
The angle brackets that usually delimit Message-IDs are optional;
\cw{nntpid} will strip them off if it sees them, and will not complain
if it does not. If the angle brackets are present, anything outside
them will also be discarded.

\b Otherwise, an argument containing whitespace or a colon will be
parsed as a group name and an article number.

\b Otherwise, two successive arguments will be treated as a group name
and an article number.

For example, the following invocations should all behave identically.
(Single quotes are intended to represent POSIX shell quoting, not part
of the command line as it reaches \cw{nntpid}.)

\c $ nntpid '<foo.bar@baz.quux>' misc.test 1234
\e   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
\c $ nntpid 'foo.bar@baz.quux' misc.test:1234
\e   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
\c $ nntpid 'wibble <foo.bar@baz.quux> blah' 'misc.test 1234'
\e   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb

If \cw{nntpid} is given no arguments at all, it will read from
standard input. Every line it reads will be interpreted as described
above, except that whitespace will also be trimmed from the start and
end of the line first.

If you provide the \cw{-a} option (see below), none of the above
applies. Instead, \cw{nntpid} will expect exactly one command-line
argument, which it will treat as a newsgroup name.

\U OPTIONS

\dt \cw{-v}

\dd Verbose mode. In this mode, \cw{nntpid} will log its entire
conversation with the news server on standard error.

\dt \cw{-d}

\dd Direct output. In this mode, \cw{nntpid} will write the article
straight to standard output without bothering to try using a pager.

\dt \cw{-a}

\dd Retrieve all articles from the given newsgroup. In this mode,
\cw{nntpid} will always write straight to standard output (so the
\cw{-d} option is unnecessary).

\U AUTHENTICATION

Currently, the only form of authentication supported by \cw{nntpid}
is \cw{AUTHINFO GENERIC}, using the environment variable
\cw{NNTPAUTH}. It will only attempt this if it receives a 480
response from the news server; if your news server never sends 480
then \cw{nntpid} will never even look at \cw{NNTPAUTH}.

\U LICENCE

\cw{nntpid} is free software, distributed under the MIT licence.
Type \cw{nntpid --licence} to see the full licence text.

\versionid $Id$