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 are a couple of alternative mode of operation. In one, enabled
  44 by the \cw{-a} option, \cw{nntpid} retrieves \e{all} available
  45 articles in the group and writes them to standard output in \cw{mbox}
  46 format. In the other, enabled with \cw{-b}, \cw{nntpid} simply prints
  47 the lowest and highest article numbers currently available in that
  48 group from the news server.
  49
  50 The location of the news server is obtained by reading the
  51 environment variable \cw{NNTPSERVER}, or failing that the file
  52 \cw{/etc/nntpserver}.
  53
  54 \U ARGUMENTS
  55
  56 \cw{nntpid} will attempt to interpret its argument list as specifying
  57 a series of news articles, as follows:
  58
  59 \b An argument containing an @ sign will be parsed as a Message-ID.
  60 The angle brackets that usually delimit Message-IDs are optional;
  61 \cw{nntpid} will strip them off if it sees them, and will not complain
  62 if it does not. If the angle brackets are present, anything outside
  63 them will also be discarded.
  64
  65 \b Otherwise, an argument containing whitespace or a colon will be
  66 parsed as a group name and an article number.
  67
  68 \b Otherwise, two successive arguments will be treated as a group name
  69 and an article number.
  70
  71 For example, the following invocations should all behave identically.
  72 (Single quotes are intended to represent POSIX shell quoting, not part
  73 of the command line as it reaches \cw{nntpid}.)
  74
  75 \c $ nntpid '<foo.bar@baz.quux>' misc.test 1234
  76 \e   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
  77 \c $ nntpid 'foo.bar@baz.quux' misc.test:1234
  78 \e   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
  79 \c $ nntpid 'wibble <foo.bar@baz.quux> blah' 'misc.test 1234'
  80 \e   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
  81
  82 If \cw{nntpid} is given no arguments at all, it will read from
  83 standard input. Every line it reads will be interpreted as described
  84 above, except that whitespace will also be trimmed from the start and
  85 end of the line first.
  86
  87 If you provide the \cw{-a} option (see below), none of the above
  88 applies. Instead, \cw{nntpid} will expect exactly one command-line
  89 argument, which it will treat as a newsgroup name.
  90
  91 \U OPTIONS
  92
  93 \dt \cw{-v}
  94
  95 \dd Verbose mode. In this mode, \cw{nntpid} will log its entire
  96 conversation with the news server on standard error.
  97
  98 \dt \cw{-d}
  99
 100 \dd Direct output. In this mode, \cw{nntpid} will write the article
 101 straight to standard output without bothering to try using a pager.
 102
 103 \dt \cw{-a}
 104
 105 \dd Retrieve all articles from the given newsgroup. In this mode,
 106 \cw{nntpid} will always write straight to standard output (so the
 107 \cw{-d} option is unnecessary).
 108
 109 \dt \cw{-b}
 110
 111 \dd Print the current bounds on that group's article numbers. The
 112 output is one line consisting of a minimum and maximum article number.
 113 (Not every article in that range will necessarily actually exist: a
 114 cancelled article will still use up a space in the numbering range.)
 115
 116 \U AUTHENTICATION
 117
 118 Currently, the only form of authentication supported by \cw{nntpid}
 119 is \cw{AUTHINFO GENERIC}, using the environment variable
 120 \cw{NNTPAUTH}. It will only attempt this if it receives a 480
 121 response from the news server; if your news server never sends 480
 122 then \cw{nntpid} will never even look at \cw{NNTPAUTH}.
 123
 124 \U LICENCE
 125
 126 \cw{nntpid} is free software, distributed under the MIT licence.
 127 Type \cw{nntpid --licence} to see the full licence text.
 128
 129 \versionid $Id$