| 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 |