Debian Codegraph @

upstream/debian-unstable/man1/expect_tknewsbiff.1

raw
1 .TH TKNEWSBIFF 1 "1 January 1994"
2 .SH NAME
3 tknewsbiff \- pop up a window when news appears
4 .SH SYNOPSIS
5 .B tknewsbiff
6 [
7 .I server or config-file
8 ]
9 .br
10 .SH INTRODUCTION
11 .B tknewsbiff
12 pops up a window when there is unread news in your favorite newsgroups
13 and removes the window after you've read the news. tknewsbiff can
14 optionally play a sound, start your newsreader, etc.
15
16 .SH SELECTING NEWSGROUPS
17
18 By default, the configuration file ~/.tknewsbiff describes how
19 tknewsbiff behaves. The syntax observes the usual Tcl rules
20 - however, even if you don't know Tcl, all but the most esoteric
21 configurations will be obvious.
22
23 Each newsgroup (or set of newsgroups) to be watched is described by
24 using the "watch" command. For example:
25
26 .nf
27
28 watch dc.dining
29 watch nist.*
30 watch comp.unix.wizard -threshold 3
31 watch *.sources.* -threshold 20
32
33 .fi
34
35 For each newsgroup pattern, any newsgroup that matches it and which
36 you are subscribed to (according to your newsrc file) is eligible for
37 reporting. By default, tknewsbiff reports on the newsgroup if there
38 is at least one unread article. The "-threshold" flag changes the
39 threshold to the following number. For example, "-threshold 3" means
40 there must be at least three articles unread before tknewsbiff will
41 report the newsgroup.
42
43 If no watch commands are given (or no configuration file exists), all
44 groups which are subscribed to are watched.
45
46 To suppress newsgroups that would otherwise be reported, use the
47 "ignore" command. For example, the following matches all comp.* and
48 nist.* newgroups except for nist.posix or .d (discussion) groups:
49
50 .nf
51
52 watch comp.*
53 watch nist.*
54 ignore nist.posix.*
55 ignore *.d
56
57 .fi
58
59 The flag "-new" describes a command to be executed when the newsgroup
60 is first reported as having unread news. For example, the following
61 lines invoke the UNIX command "play" to play a sound.
62
63 .nf
64
65 watch dc.dining -new "exec play /usr/local/sounds/yumyum.au"
66 watch rec.auto* -new "exec play /usr/local/sounds/vroom.au"
67
68 .fi
69
70 You can cut down on the verbosity of actions by defining procedures.
71 For example, if you have many -new flags that all play sound files,
72 you could define a sound procedure. This would allow the -new
73 specification to be much shorter.
74
75 .nf
76
77 proc play {sound} {
78 exec play /usr/local/sounds/$sound.au
79 }
80
81 watch dc.dining -new "play yumyum"
82 watch rec.auto* -new "play vroom"
83
84 .fi
85
86 As an aside, you can put an "&" at the end of an "exec" command to get
87 commands to execute asynchronously. However, it's probably not a good
88 idea to do this when playing sound files anyway.
89
90 "newsgroup" is a read-only variable which contains the name of the
91 newsgroup that is being reported. This is useful when the action is
92 triggered by a pattern. For example, the following line could run the
93 newsgroup name through a speech synthesizer:
94
95 .nf
96
97 watch * -new {
98 exec play herald.au
99 exec speak "New news has arrived in $newsgroup."
100 }
101
102 .fi
103
104 The flag "\-display" describes a command to be executed every time the
105 newsgroup is reported as having unread news. The special command
106 "display" is the default command. It schedules $newsgroup to be
107 written to tknewsbiff's display when it is rewritten. For example, by
108 explicitly providing a -display flag that omits the display command,
109 you can disable the display of newsgroups that are already reported
110 via -new.
111
112 .nf
113
114 watch dc.dining -new {exec play yumyum.au} -display {}
115
116 .fi
117
118 If you want to execute an action repeatedly and
119 .I still
120 display the newsgroup in the default manner,
121 explicitly invoke the display command via the -display flag. For example:
122
123 .nf
124
125 watch *security* -display {
126 exec play red-alert.au
127 display
128 }
129
130 .fi
131
132 Actions associated with the -new and -display flags are executed only
133 once for each matching newsgroup. The command executed is the one
134 associated with the first pattern in the configuration file that
135 matches and observes the given threshold.
136
137 Any command that is simply listed in the configuration file is
138 executed each time before the update loop in tknewsbiff. The reserved
139 (but user-defined) procedure "user" is run immediately after the
140 newsgroups are scheduled to be written to the display and before they
141 are actually written.
142
143 For example, suppose unread articles appear in several rec.auto groups
144 and you play the same sound for each one. To prevent playing the
145 sound several times in a row, make the -new command simply set a flag.
146 In the user procedure, play the sound if the flag is set (and then
147 reset the flag).
148
149 The user procedure could also be used to start a newsreader. This
150 would avoid the possibility of starting multiple newsreaders just
151 because multiple newsgroups contained unread articles. (A check
152 should, of course, be made to make sure that a newsreader is not
153 already running.)
154
155 .SH MORE VARIABLES
156
157 The following example lines show variables that can affect the
158 behavior of tknewsbiff
159
160 .nf
161
162 set delay 120
163 set server news.nist.gov
164 set server_timeout 60
165 set newsrc ~/.newsrc
166 set width 40
167 set height 20
168 set active_file /usr/news/lib/active
169
170 .fi
171
172 tknewsbiff alternates between checking for unread news and
173 sleeping (kind of like many undergraduates). The "delay" variable
174 describes how many seconds to sleep.
175
176 The "server" variable names an NNTP news-server.
177 The default is "news". The "server" variable is
178 only used if the "active_file" variable is not set.
179
180 The "server_timeout" variable describes how how many seconds to wait
181 for a response from the server before giving up. -1 means wait
182 forever or until the server itself times out. The default is 60
183 seconds.
184
185 The "newsrc" variable describes the name of your .newsrc file. By
186 default, tknewsbiff looks in your home directory for a newsrc file. A
187 server-specific newsrc is used if found. For example, if you have set
188 server to "cubit.nist.gov", then tknewsbiff looks for
189 ~/.newsrc-cubit.nist.gov. (This is the Emacs gnus convention - which
190 is very convenient when you read news from multiple servers.) If
191 there is no server-specific newsrc, tknewsbiff uses ~/.newsrc.
192
193 The "width" variable describes the width that tknewsbiff will use to
194 display information. If any newsgroup names are long enough, they
195 will be truncated so that the article counts can still be shown. You
196 can manually resize the window to see what was truncated. However, if
197 your configuration file sets the width variable, the window will be
198 restored to that size the next time that tknewsbiff checks for unread
199 news and updates its display.
200
201 The "height" variable describes the maximum height that tknewsbiff
202 will use to display information. If fewer newsgroups are reported,
203 tknewsbiff will shrink the window appropriately. You can manually
204 resize the window but if your configuration file sets the height
205 variable, the window will be restored to that size the next time that
206 tknewsbiff checks for unread news and updates its display.
207
208 The "active_file" variable describes the name of the news active file.
209 If set, the active file is read directly in preference to using NNTP
210 (even if the "server" variable is set). This is particularly useful
211 for testing out new configuration files since you can edit a fake
212 active file and then click button 2 to immediately see how tknewsbiff
213 responds (see BUTTONS below).
214
215 If the environment variable DOTDIR is set, then its value is used as a
216 directory in which to find all dotfiles instead of from the home
217 directory. In particular, this affects the tknewsbiff configuration
218 file and the .newsrc file (assuming the newsrc variable is not set
219 explicitly).
220
221 .SH WATCHING DIFFERENT NEWS SERVERS
222
223 To watch multiple servers, run tknewsbiff multiple times. (Since you
224 need different .newsrc files and the servers have different newsgroups
225 and article numbers anyway, there is no point in trying to do this in
226 a single process.)
227
228 You can point tknewsbiff at a different server with an appropriate
229 argument. The argument is tried both as a configuration file name and
230 as a suffix to the string "~/.tknewsbiff-". So if you want to watch
231 the server "kidney", store the tknewsbiff configuration information in
232 ~/.tknewsbiff-kidney". The following two commands will both use that
233 configuration file.
234
235 .nf
236
237 tknewsbiff kidney
238 tknewsbiff ~/.tknewsbiff-kidney
239
240 .fi
241
242 In both cases, the actual server to contact is set by the value of the
243 server variable in the configuration file.
244
245 If no configuration file is found, the argument is used as the server
246 to contact. This allows tknewsbiff to be run with no preparation
247 whatsoever.
248
249 If the argument is the special keyword "active" (or ends in
250 "/active"), it is used as the name of an active file. This is in turn
251 used to initialize the variable "active_file" so that tknewsbiff reads
252 from the active file directly rather than using NNTP.
253
254 Creating your own active file is a convenient way of testing your
255 configuration file. For example, after running the following command,
256 you can repeatedly edit your active file and trigger the update-now
257 command (either by pressing button 2 or setting the delay variable
258 very low) to see how tknewsbiff responds.
259
260 The active file must follow the format of a real active file. The
261 format is one newsgroup per line. After the newsgroup name is the
262 number of the highest article, the lowest article. Lastly is the
263 letter y or m. m means the newsgroup is moderated. y means posting
264 is allowed.
265
266 .SH WINDOW
267
268 When unread news is found, a window is popped up. The window lists
269 the names of the newsgroups and the number of unread articles in each
270 (unless suppressed by the -display flag). When there is no longer any
271 unread news, the window disappears (although the process continues to
272 run).
273
274 .SH BUTTONS
275
276 Button or key bindings may be assigned by bind commands. Feel free to
277 change them. The default bind commands are:
278
279 .nf
280
281 bind .list <1> help
282 bind .list <2> update-now
283 bind .list <3> unmapwindow
284
285 .fi
286
287 By default button 1 (left) is bound to "help". The help command
288 causes tknewsbiff to pop up a help window.
289
290 By default, button 2 (middle) is bound to "update-now". The update-now
291 command causes tknewsbiff to immediately check for unread news. If
292 your news server is slow or maintains a very large number of
293 newsgroups, or you have a large number of patterns in your
294 configuration file, tknewsbiff can take considerable time before
295 actually updating the window.
296
297 By default, button 3 (right) is bound to "unmapwindow". The
298 unmapwindow command causes tknewsbiff to remove the window from the
299 display until the next time it finds unread news. (The mapwindow
300 command causes tknewsbiff to restore the window.)
301
302 As an example, here is a binding to pop up an xterm and run rn when
303 you hold down the shift key and press button 1 in the listing window.
304
305 .nf
306
307 bind .list <Shift-1> {
308 exec xterm -e rn &
309 }
310
311 .fi
312
313 Here is a similar binding. However it tells rn to look only at the
314 newsgroup that is under the mouse when you pressed it. (The
315 "display_list" variable is described later in this man page.)
316
317 .nf
318
319 bind .list <Shift-1> {
320 exec xterm -e rn [lindex $display_list [.list nearest %y]] &
321 }
322
323 .fi
324
325 .SH OTHER COMMANDS AND VARIABLES
326
327 Built-in commands already mentioned are: watch, ignore, display, help,
328 update-now, unmapwindow, and mapwindow.
329
330 Any Tcl and Tk command can also be given. In particular, the list of
331 newsgroups is stored in the list widget ".list", and the scroll bar is
332 stored in the scrollbar widget ".scroll". So for example, if you want
333 to change the foreground and background colors of the newsgroup list,
334 you can say:
335
336 .nf
337
338 .list config -bg honeydew1 -fg orchid2
339
340 .fi
341
342 These can also be controlled by the X resource database as well.
343 However, the configuration file allows arbitrarily complex commands to
344 be evaluated rather than simple assignments.
345
346 Certain Tcl/Tk commands can disrupt proper function of tknewsbiff.
347 These will probably be obvious to anyone who knows enough to give
348 these commands in the first place. As a simple example, the program
349 assumes the font in the list box is of fixed width. The newsgroups
350 will likely not align if you use a variable-width font.
351
352 The following variables are accessible and can be used for esoteric
353 uses. All other variables are private. Private variables and
354 commands begin with "_" so you don't need to worry about accidental
355 collisions.
356
357 The array "db" is a database which maintains information about read
358 and unread news. db($newsgroup,hi) is the highest article that
359 exists. db($newsgroup,seen) is the highest article that you have
360 read.
361
362 A number of lists maintain interesting information. "active_list" is a
363 list of known newsgroups. "seen_list" is a list of newsgroups that
364 have been seen so far as the -new and -display flags are being
365 processed. "previous_seen_list" is "seen_list" from the previous
366 cycle. "ignore_list" is the list of newsgroup patterns to ignore.
367 "watch_list" is the list of newsgroup patterns to watch.
368 "display_list" is the list of newsgroup will be displayed at the next
369 opportunity.
370
371 .SH UPDATING YOUR FILES
372
373 tknewsbiff automatically rereads your configuration file each time it
374 wakes up to check for unread news. To force tknewsbiff to reread the
375 file immediately (such as if you are testing a new configuration or
376 have just modified your newsrc file), press button 2 in the display
377 (see BUTTONS above).
378
379 .SH CAVEATS
380
381 tknewsbiff defines the number of unread articles as the highest
382 existing article minus the highest article that you've read. So if
383 you've read the last article in the newsgroup but no others,
384 tknewsbiff thinks there are no unread articles. (It's impossible to
385 do any better by reading the active file and it would be very time
386 consuming to do this more accurately via NNTP since servers provide no
387 efficient way of reporting their own holes in the newsgroups.)
388 Fortunately, this definition is considered a feature by most people.
389 It allows you to read articles and then mark them "unread" but not
390 have tknewsbiff continue telling you that they are unread.
391
392 .SH UNWARRANTED CONCERNS
393
394 Your news administrator may wonder if many people using tknewsbiff
395 severely impact an NNTP server. In fact, the impact is negligible
396 even when the delay is very low. To gather all the information it
397 needs, tknewsbiff uses a single NNTP query - it just asks for the
398 active file. The NNTP server does no computation, formatting, etc, it
399 just sends the file. All the interesting processing happens locally
400 in the tknewsbiff program itself.
401
402 .SH BUGS
403
404 The man page is longer than the program.
405
406 .SH SEE ALSO
407 .I
408 "Exploring Expect: A Tcl-Based Toolkit for Automating Interactive Programs"
409 \fRby Don Libes,
410 O'Reilly and Associates, January 1995.
411 .SH AUTHOR
412 Don Libes, National Institute of Standards and Technology