Add a vital missing paragraph to the man page, and update the header

[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 ] message-id
\e bbbbbb   bb     bb   iiiiiiiiii
\c nntpid [ -v ] [ -d ] newsgroup-name article-number
\e bbbbbb   bb     bb   iiiiiiiiiiiiii iiiiiiiiiiiiii
\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 it.

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 a third 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

If you specify one argument, \cw{nntpid} assumes it is 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 you specify two arguments, \cw{nntpid} will interpret the first
as a newsgroup name, and the second as an article number.

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