TKNEWSBIFF(1)						      General Commands Manual						     TKNEWSBIFF(1)

NAME

       tknewsbiff - pop up a window when news appears

SYNOPSIS

       tknewsbiff [ server or config-file ]

INTRODUCTION

       tknewsbiff  pops  up  a	window	when  there  is unread news in your favorite newsgroups and removes the window after you've read the news.
       tknewsbiff can optionally play a sound, start your newsreader, etc.

SELECTING NEWSGROUPS

       By default, the configuration file ~/.tknewsbiff describes how tknewsbiff behaves.  The syntax observes the usual Tcl rules - however, even
       if you don't know Tcl, all but the most esoteric configurations will be obvious.

       Each newsgroup (or set of newsgroups) to be watched is described by using the "watch" command.  For example:

       watch dc.dining
       watch nist.*
       watch comp.unix.wizard  -threshold 3
       watch *.sources.*       -threshold 20

       For  each  newsgroup pattern, any newsgroup that matches it and which you are subscribed to (according to your newsrc file) is eligible for
       reporting.  By default, tknewsbiff reports on the newsgroup if there is at least one unread article.  The  "-threshold"	flag  changes  the
       threshold  to  the following number.  For example, "-threshold 3" means there must be at least three articles unread before tknewsbiff will
       report the newsgroup.

       If no watch commands are given (or no configuration file exists), all groups which are subscribed to are watched.

       To suppress newsgroups that would otherwise be reported, use the "ignore" command.  For example,  the  following  matches  all  comp.*  and
       nist.* newgroups except for nist.posix or .d (discussion) groups:

       watch comp.*
       watch nist.*
       ignore nist.posix.*
       ignore *.d

       The  flag "-new" describes a command to be executed when the newsgroup is first reported as having unread news.	For example, the following
       lines invoke the UNIX command "play" to play a sound.

       watch dc.dining -new "exec play /usr/local/sounds/yumyum.au"
       watch rec.auto* -new "exec play /usr/local/sounds/vroom.au"

       You can cut down on the verbosity of actions by defining procedures.  For example, if you have many -new flags that all play  sound  files,
       you could define a sound procedure.  This would allow the -new specification to be much shorter.

       proc play {sound} {
	    exec play /usr/local/sounds/$sound.au
       }

       watch dc.dining -new "play yumyum"
       watch rec.auto* -new "play vroom"

       As  an  aside,  you can put an "&" at the end of an "exec" command to get commands to execute asynchronously.  However, it's probably not a
       good idea to do this when playing sound files anyway.

       "newsgroup" is a read-only variable which contains the name of the newsgroup that is being reported.  This is useful  when  the	action	is
       triggered by a pattern.	For example, the following line could run the newsgroup name through a speech synthesizer:

       watch * -new {
	    exec play herald.au
	    exec speak "New news has arrived in $newsgroup."
       }

       The  flag  "-display"  describes  a command to be executed every time the newsgroup is reported as having unread news.  The special command
       "display" is the default command.  It schedules $newsgroup to be written to tknewsbiff's display when it is  rewritten.	 For  example,	by
       explicitly  providing  a  -display flag that omits the display command, you can disable the display of newsgroups that are already reported
       via -new.

       watch dc.dining -new {exec play yumyum.au} -display {}

       If you want to execute an action repeatedly and still display the newsgroup in the default manner, explicitly invoke  the  display  command
       via the -display flag.  For example:

       watch *security* -display {
	    exec play red-alert.au
	    display
       }

       Actions	associated  with  the -new and -display flags are executed only once for each matching newsgroup.  The command executed is the one
       associated with the first pattern in the configuration file that matches and observes the given threshold.

       Any command that is simply listed in the configuration file is executed each time before the update loop in tknewsbiff.	The reserved  (but
       user-defined) procedure "user" is run immediately after the newsgroups are scheduled to be written to the display and before they are actu-
       ally written.

       For example, suppose unread articles appear in several rec.auto groups and you play the same sound for each one.  To  prevent  playing  the
       sound  several times in a row, make the -new command simply set a flag.	In the user procedure, play the sound if the flag is set (and then
       reset the flag).

       The user procedure could also be used to start a newsreader.  This would avoid  the  possibility  of  starting  multiple  newsreaders  just
       because	multiple  newsgroups contained unread articles.  (A check should, of course, be made to make sure that a newsreader is not already
       running.)

MORE VARIABLES

       The following example lines show variables that can affect the behavior of tknewsbiff

       set delay	  120
       set server	  news.nist.gov
       set server_timeout 60
       set newsrc	  ~/.newsrc
       set width	  40
       set height	  20
       set active_file	  /usr/news/lib/active

       tknewsbiff alternates between checking for unread news and sleeping (kind of like many undergraduates).	The "delay" variable describes how
       many seconds to sleep.

       The  "server" variable names an NNTP news-server.  The default is "news".  The "server" variable is only used if the "active_file" variable
       is not set.

       The "server_timeout" variable describes how how many seconds to wait for a response from the server before giving up.  -1 means	wait  for-
       ever or until the server itself times out.  The default is 60 seconds.

       The  "newsrc"  variable describes the name of your .newsrc file.  By default, tknewsbiff looks in your home directory for a newsrc file.  A
       server-specific newsrc is used if found.  For example, if you have set server to "cubit.nist.gov", then	tknewsbiff  looks  for	~/.newsrc-
       cubit.nist.gov.	 (This	is the Emacs gnus convention - which is very convenient when you read news from multiple servers.)  If there is no
       server-specific newsrc, tknewsbiff uses ~/.newsrc.

       The "width" variable describes the width that tknewsbiff will use to display information.  If any newsgroup names  are  long  enough,  they
       will  be  truncated so that the article counts can still be shown.  You can manually resize the window to see what was truncated.  However,
       if your configuration file sets the width variable, the window will be restored to that size the  next  time  that  tknewsbiff  checks  for
       unread news and updates its display.

       The  "height"  variable	describes  the	maximum height that tknewsbiff will use to display information.  If fewer newsgroups are reported,
       tknewsbiff will shrink the window appropriately.  You can manually resize the window but if your configuration file sets the  height  vari-
       able, the window will be restored to that size the next time that tknewsbiff checks for unread news and updates its display.

       The  "active_file"  variable  describes	the name of the news active file.  If set, the active file is read directly in preference to using
       NNTP (even if the "server" variable is set).  This is particularly useful for testing out new configuration files since you can edit a fake
       active file and then click button 2 to immediately see how tknewsbiff responds (see BUTTONS below).

       If  the	environment  variable  DOTDIR is set, then its value is used as a directory in which to find all dotfiles instead of from the home
       directory.  In particular, this affects the tknewsbiff configuration file and the .newsrc file (assuming the newsrc  variable  is  not  set
       explicitly).

WATCHING DIFFERENT NEWS SERVERS

       To  watch  multiple  servers,  run tknewsbiff multiple times.  (Since you need different .newsrc files and the servers have different news-
       groups and article numbers anyway, there is no point in trying to do this in a single process.)

       You can point tknewsbiff at a different server with an appropriate argument.  The argument is tried both as a configuration file  name  and
       as a suffix to the string "~/.tknewsbiff-".  So if you want to watch the server "kidney", store the tknewsbiff configuration information in
       ~/.tknewsbiff-kidney".  The following two commands will both use that configuration file.

	    tknewsbiff kidney
	    tknewsbiff ~/.tknewsbiff-kidney

       In both cases, the actual server to contact is set by the value of the server variable in the configuration file.

       If no configuration file is found, the argument is used as the server to contact.  This allows tknewsbiff to be	run  with  no  preparation
       whatsoever.

       If  the argument is the special keyword "active" (or ends in "/active"), it is used as the name of an active file.  This is in turn used to
       initialize the variable "active_file" so that tknewsbiff reads from the active file directly rather than using NNTP.

       Creating your own active file is a convenient way of testing your configuration file.  For example, after running  the  following  command,
       you can repeatedly edit your active file and trigger the update-now command (either by pressing button 2 or setting the delay variable very
       low) to see how tknewsbiff responds.

       The active file must follow the format of a real active file.  The format is one newsgroup per line.  After the newsgroup name is the  num-
       ber  of	the  highest  article,	the lowest article.  Lastly is the letter y or m.  m means the newsgroup is moderated.	y means posting is
       allowed.

WINDOW

       When unread news is found, a window is popped up.  The window lists the names of the newsgroups and the number of unread articles  in  each
       (unless	suppressed  by the -display flag).  When there is no longer any unread news, the window disappears (although the process continues
       to run).

BUTTONS

       Button or key bindings may be assigned by bind commands.  Feel free to change them.  The default bind commands are:

       bind .list <1> help
       bind .list <2> update-now
       bind .list <3> unmapwindow

       By default button 1 (left) is bound to "help".  The help command causes tknewsbiff to pop up a help window.

       By default, button 2 (middle) is bound to "update-now".	The update-now command causes tknewsbiff to immediately check for unread news.	If
       your news server is slow or maintains a very large number of newsgroups, or you have a large number of patterns in your configuration file,
       tknewsbiff can take considerable time before actually updating the window.

       By default, button 3 (right) is bound to "unmapwindow".	The unmapwindow command causes tknewsbiff to remove the window	from  the  display
       until the next time it finds unread news.  (The mapwindow command causes tknewsbiff to restore the window.)

       As an example, here is a binding to pop up an xterm and run rn when you hold down the shift key and press button 1 in the listing window.

       bind .list <Shift-1> {
	    exec xterm -e rn &
       }

       Here  is  a  similar  binding.	However it tells rn to look only at the newsgroup that is under the mouse when you pressed it.	(The "dis-
       play_list" variable is described later in this man page.)

       bind .list <Shift-1> {
	    exec xterm -e rn [lindex $display_list [.list nearest %y]] &
       }

OTHER COMMANDS AND VARIABLES

       Built-in commands already mentioned are: watch, ignore, display, help, update-now, unmapwindow, and mapwindow.

       Any Tcl and Tk command can also be given.  In particular, the list of newsgroups is stored in the list widget ".list", and the  scroll  bar
       is  stored  in the scrollbar widget ".scroll".  So for example, if you want to change the foreground and background colors of the newsgroup
       list, you can say:

	    .list config -bg honeydew1 -fg orchid2

       These can also be controlled by the X resource database as well.  However, the configuration file allows arbitrarily complex commands to be
       evaluated rather than simple assignments.

       Certain Tcl/Tk commands can disrupt proper function of tknewsbiff.  These will probably be obvious to anyone who knows enough to give these
       commands in the first place.  As a simple example, the program assumes the font in the list box is of fixed  width.   The  newsgroups  will
       likely not align if you use a variable-width font.

       The following variables are accessible and can be used for esoteric uses.  All other variables are private.  Private variables and commands
       begin with "_" so you don't need to worry about accidental collisions.

       The array "db" is a database which maintains information about read and unread news.  db($newsgroup,hi) is the highest article that exists.
       db($newsgroup,seen) is the highest article that you have read.

       A  number of lists maintain interesting information. "active_list" is a list of known newsgroups.  "seen_list" is a list of newsgroups that
       have been seen so far as the -new and -display flags are being processed.  "previous_seen_list" is "seen_list"  from  the  previous  cycle.
       "ignore_list" is the list of newsgroup patterns to ignore.  "watch_list" is the list of newsgroup patterns to watch.  "display_list" is the
       list of newsgroup will be displayed at the next opportunity.

UPDATING YOUR FILES

       tknewsbiff automatically rereads your configuration file each time it wakes up to check for unread news.  To force tknewsbiff to reread the
       file  immediately  (such  as  if you are testing a new configuration or have just modified your newsrc file), press button 2 in the display
       (see BUTTONS above).

CAVEATS

       tknewsbiff defines the number of unread articles as the highest existing article minus the highest article that you've read.  So if  you've
       read the last article in the newsgroup but no others, tknewsbiff thinks there are no unread articles.  (It's impossible to do any better by
       reading the active file and it would be very time consuming to do this more accurately via NNTP since servers provide no efficient  way	of
       reporting  their own holes in the newsgroups.)  Fortunately, this definition is considered a feature by most people.  It allows you to read
       articles and then mark them "unread" but not have tknewsbiff continue telling you that they are unread.

UNWARRANTED CONCERNS

       Your news administrator may wonder if many people using tknewsbiff severely impact an NNTP server.  In fact, the impact is negligible  even
       when  the  delay  is  very  low.  To gather all the information it needs, tknewsbiff uses a single NNTP query - it just asks for the active
       file.  The NNTP server does no computation, formatting, etc, it just sends the file.  All the interesting processing happens locally in the
       tknewsbiff program itself.

BUGS

       The man page is longer than the program.

SEE ALSO

       "Exploring Expect: A Tcl-Based Toolkit for Automating Interactive Programs" by Don Libes, O'Reilly and Associates, January 1995.

AUTHOR

       Don Libes, National Institute of Standards and Technology

								  1 January 1994						     TKNEWSBIFF(1)