3096ed75 |
1 | \cfg{man-identity}{nntpid}{1}{2004-11-21}{Simon Tatham}{Simon Tatham} |
2 | |
92dccb8d |
3 | \define{dash} \u2013{-} |
4 | |
3096ed75 |
5 | \title Man page for \cw{nntpid} |
6 | |
7 | \U NAME |
8 | |
92dccb8d |
9 | \cw{nntpid} \dash retrieve a single article from a news server |
3096ed75 |
10 | |
11 | \U SYNOPSIS |
12 | |
67784f1f |
13 | \c nntpid [ -v ] [ -d ] article [ article... ] |
14 | \e bbbbbb bb bb iiiiiii iiiiiii |
15 | \c nntpid [ -v ] [ -d ] |
16 | \e bbbbbb bb bb |
52f9a468 |
17 | \c nntpid [ -v ] -a newsgroup-name |
18 | \e bbbbbb bb bb iiiiiiiiiiiiii |
3096ed75 |
19 | |
20 | \U DESCRIPTION |
21 | |
52f9a468 |
22 | \cw{nntpid} makes a connection to a news server, retrieves one or |
67784f1f |
23 | more articles, and displays them. |
3096ed75 |
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 | |
a5d9e758 |
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 | |
db8c4d39 |
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. |
52f9a468 |
51 | |
016b40f7 |
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 | |
3096ed75 |
56 | \U ARGUMENTS |
57 | |
67784f1f |
58 | \cw{nntpid} will attempt to interpret its argument list as specifying |
59 | a series of news articles, as follows: |
3096ed75 |
60 | |
67784f1f |
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. |
3096ed75 |
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 | |
a5d9e758 |
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 | |
52f9a468 |
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 | |
db8c4d39 |
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 | |
0f90ca06 |
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 | |
3096ed75 |
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$ |