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