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