1TKNEWSBIFF(1)               General Commands Manual              TKNEWSBIFF(1)
2
3
4

NAME

6       tknewsbiff - pop up a window when news appears
7

SYNOPSIS

9       tknewsbiff [ server or config-file ]
10

INTRODUCTION

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
16

SELECTING NEWSGROUPS

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
23       Each newsgroup (or set of newsgroups) to be  watched  is  described  by
24       using the "watch" command.  For example:
25
26
27       watch dc.dining
28       watch nist.*
29       watch comp.unix.wizard  -threshold 3
30       watch *.sources.*       -threshold 20
31
32
33       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
41       If  no  watch commands are given (or no configuration file exists), all
42       groups which are subscribed to are watched.
43
44       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
48
49       watch comp.*
50       watch nist.*
51       ignore nist.posix.*
52       ignore *.d
53
54
55       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
59
60       watch dc.dining -new "exec play /usr/local/sounds/yumyum.au"
61       watch rec.auto* -new "exec play /usr/local/sounds/vroom.au"
62
63
64       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
69
70       proc play {sound} {
71            exec play /usr/local/sounds/$sound.au
72       }
73
74       watch dc.dining -new "play yumyum"
75       watch rec.auto* -new "play vroom"
76
77
78       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
82       "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
87
88       watch * -new {
89            exec play herald.au
90            exec speak "New news has arrived in $newsgroup."
91       }
92
93
94       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
101
102       watch dc.dining -new {exec play yumyum.au} -display {}
103
104
105       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
109
110       watch *security* -display {
111            exec play red-alert.au
112            display
113       }
114
115
116       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
121       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
127       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
133       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
139

MORE VARIABLES

141       The following example lines show variables that can affect the behavior
142       of tknewsbiff
143
144
145       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
153
154       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
158       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
162       The  "server_timeout"  variable  describes how how many seconds to wait
163       for a response from the server before giving up.  -1 means wait forever
164       or until the server itself times out.  The default is 60 seconds.
165
166       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
174       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
182       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
189       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
196       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
202

WATCHING DIFFERENT NEWS SERVERS

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
209       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
216
217            tknewsbiff kidney
218            tknewsbiff ~/.tknewsbiff-kidney
219
220
221       In  both cases, the actual server to contact is set by the value of the
222       server variable in the configuration file.
223
224       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
228       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
233       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
239       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
244

WINDOW

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
252

BUTTONS

254       Button or key bindings may be assigned by bind commands.  Feel free  to
255       change them.  The default bind commands are:
256
257
258       bind .list <1> help
259       bind .list <2> update-now
260       bind .list <3> unmapwindow
261
262
263       By default button 1 (left) is bound to "help".  The help command causes
264       tknewsbiff to pop up a help window.
265
266       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
273       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
278       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
281
282       bind .list <Shift-1> {
283            exec xterm -e rn &
284       }
285
286
287       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
291
292       bind .list <Shift-1> {
293            exec xterm -e rn [lindex $display_list [.list nearest %y]] &
294       }
295
296
297

OTHER COMMANDS AND VARIABLES

299       Built-in  commands already mentioned are: watch, ignore, display, help,
300       update-now, unmapwindow, and mapwindow.
301
302       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
308
309            .list config -bg honeydew1 -fg orchid2
310
311
312       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
316       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
322       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
326       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
330       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
339

UPDATING YOUR FILES

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
347

CAVEATS

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
360

UNWARRANTED CONCERNS

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
370

BUGS

372       The man page is longer than the program.
373
374

SEE ALSO

376       "Exploring Expect: A Tcl-Based Toolkit for Automating Interactive  Pro‐
377       grams" by Don Libes, O'Reilly and Associates, January 1995.
378

AUTHOR

380       Don Libes, National Institute of Standards and Technology
381
382
383
384                                1 January 1994                   TKNEWSBIFF(1)
Impressum