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.  tknewsb-
       iff can optionally play a sound, start your newsreader, etc.


SELECTING NEWSGROUPS
       By default, the configuration file ~/.tknewsbiff describes how tknewsb-
       iff 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 thresh-
       old  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  specifica-
       tion 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 "dis-
       play" 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  dis-
       able 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 news-
       group 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 actually
       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"  vari-
       able 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 forever
       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, tknewsb-
       iff  will shrink the window appropriately.  You can manually resize the
       window but if your configuration file sets  the  height  variable,  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 direc-
       tory.   In  particular,  this affects the tknewsbiff configuration file
       and the .newsrc file (assuming the newsrc variable is not  set  explic-
       itly).


WATCHING DIFFERENT NEWS SERVERS
       To  watch  multiple servers, run tknewsbiff multiple times.  (Since you
       need different .newsrc files and the servers have different  newsgroups
       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 what-
       soever.

       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 ini-
       tialize 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 con-
       figuration 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 for-
       mat is one newsgroup per line.  After the newsgroup name is the  number
       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  news-
       groups,  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 unmapwin-
       dow 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.   How-
       ever,  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  pro-
       cessed.   "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.  "dis-
       play_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 exist-
       ing 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 defi-
       nition 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  se-
       verely  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  Pro-
       grams" by Don Libes, O'Reilly and Associates, January 1995.

AUTHOR
       Don Libes, National Institute of Standards and Technology



                                1 January 1994                   TKNEWSBIFF(1)
