mdw@git.distorted.org.uk Git - sgt/utils/blob - nntpid/nntpid.but

   1 \cfg{man-identity}{nntpid}{1}{2004-11-21}{Simon Tatham}{Simon Tatham}
   2
   3 \title Man page for \cw{nntpid}
   4
   5 \U NAME
   6
   7 \cw{nntpid} - retrieve a single article from a news server
   8
   9 \U SYNOPSIS
  10
  11 \c nntpid [ -v ] [ -d ] article [ article... ]
  12 \e bbbbbb   bb     bb   iiiiiii   iiiiiii
  13 \c nntpid [ -v ] [ -d ]
  14 \e bbbbbb   bb     bb
  15 \c nntpid [ -v ] -a newsgroup-name
  16 \e bbbbbb   bb   bb iiiiiiiiiiiiii
  17
  18 \U DESCRIPTION
  19
  20 \cw{nntpid} makes a connection to a news server, retrieves one or
  21 more articles, and displays them.
  22
  23 You can specify the article you want by either:
  24
  25 \b giving its Message-ID. Message-IDs are globally unique, so you
  26 don't need to know which newsgroup the article was in. Also, they do
  27 not vary between news servers.
  28
  29 \b giving a newsgroup name and an article number within that
  30 newsgroup. Article numbers are assigned internally by a particular
  31 news server, so they will be different on other servers carrying the
  32 same group.
  33
  34 By default, \cw{nntpid} will try to display the article using a
  35 pager (\cw{more}(1), unless you have specified an alternative in the
  36 environment variable \cw{PAGER}). This is partly for convenience,
  37 and partly a mild security measure: it gives you some protection
  38 against the news article potentially containing control sequences
  39 that cause unexpected behaviour in your terminal. If \cw{nntpid}
  40 detects that its standard output is not a terminal, however, it will
  41 bypass the pager and just write out the article directly.
  42
  43 There is an alternative mode of operation, enabled by the \cw{-a}
  44 option, in which \cw{nntpid} retrieves \e{all} available articles in
  45 the group and writes them to standard output in \cw{mbox} format.
  46
  47 The location of the news server is obtained by reading the
  48 environment variable \cw{NNTPSERVER}, or failing that the file
  49 \cw{/etc/nntpserver}.
  50
  51 \U ARGUMENTS
  52
  53 \cw{nntpid} will attempt to interpret its argument list as specifying
  54 a series of news articles, as follows:
  55
  56 \b An argument containing an @ sign will be parsed as a Message-ID.
  57 The angle brackets that usually delimit Message-IDs are optional;
  58 \cw{nntpid} will strip them off if it sees them, and will not complain
  59 if it does not. If the angle brackets are present, anything outside
  60 them will also be discarded.
  61
  62 \b Otherwise, an argument containing whitespace or a colon will be
  63 parsed as a group name and an article number.
  64
  65 \b Otherwise, two successive arguments will be treated as a group name
  66 and an article number.
  67
  68 For example, the following invocations should all behave identically.
  69 (Single quotes are intended to represent POSIX shell quoting, not part
  70 of the command line as it reaches \cw{nntpid}.)
  71
  72 \c $ nntpid '<foo.bar@baz.quux>' misc.test 1234
  73 \e   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
  74 \c $ nntpid 'foo.bar@baz.quux' misc.test:1234
  75 \e   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
  76 \c $ nntpid 'wibble <foo.bar@baz.quux> blah' 'misc.test 1234'
  77 \e   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
  78
  79 If \cw{nntpid} is given no arguments at all, it will read from
  80 standard input. Every line it reads will be interpreted as described
  81 above, except that whitespace will also be trimmed from the start and
  82 end of the line first.
  83
  84 If you provide the \cw{-a} option (see below), none of the above
  85 applies. Instead, \cw{nntpid} will expect exactly one command-line
  86 argument, which it will treat as a newsgroup name.
  87
  88 \U OPTIONS
  89
  90 \dt \cw{-v}
  91
  92 \dd Verbose mode. In this mode, \cw{nntpid} will log its entire
  93 conversation with the news server on standard error.
  94
  95 \dt \cw{-d}
  96
  97 \dd Direct output. In this mode, \cw{nntpid} will write the article
  98 straight to standard output without bothering to try using a pager.
  99
 100 \dt \cw{-a}
 101
 102 \dd Retrieve all articles from the given newsgroup. In this mode,
 103 \cw{nntpid} will always write straight to standard output (so the
 104 \cw{-d} option is unnecessary).
 105
 106 \U AUTHENTICATION
 107
 108 Currently, the only form of authentication supported by \cw{nntpid}
 109 is \cw{AUTHINFO GENERIC}, using the environment variable
 110 \cw{NNTPAUTH}. It will only attempt this if it receives a 480
 111 response from the news server; if your news server never sends 480
 112 then \cw{nntpid} will never even look at \cw{NNTPAUTH}.
 113
 114 \U LICENCE
 115
 116 \cw{nntpid} is free software, distributed under the MIT licence.
 117 Type \cw{nntpid --licence} to see the full licence text.
 118
 119 \versionid $Id$