Import my usual \dash macro into all these man pages, and use it for

[sgt/utils] / nntpid / nntpid.but

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

\define{dash} \u2013{-}

\title Man page for \cw{nntpid}

\U NAME

\cw{nntpid} \dash 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 are a couple of alternative mode of operation. In one, enabled
by the \cw{-a} option, \cw{nntpid} retrieves \e{all} available
articles in the group and writes them to standard output in \cw{mbox}
format. In the other, enabled with \cw{-b}, \cw{nntpid} simply prints
the lowest and highest article numbers currently available in that
group from the news server.

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).

\dt \cw{-b}

\dd Print the current bounds on that group's article numbers. The
output is one line consisting of a minimum and maximum article number.
(Not every article in that range will necessarily actually exist: a
cancelled article will still use up a space in the numbering range.)

\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$