Commit | Line | Data |
---|---|---|
920dae64 AT |
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 |