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