phpMan > man > tknewsbiff(1)

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 syn‐
       tax observes the usual Tcl rules - however, even if you don't know Tcl, all but the most eso‐
       teric configurations will be obvious.

       Each  newsgroup  (or  set of newsgroups) to be watched is described by using the "watch" com‐
       mand.  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  sub‐
       scribed to are watched.

       To suppress newsgroups that would otherwise be reported, use the "ignore" command.  For exam‐
       ple, the following matches all comp.* and nist.* newgroups except for nist.posix or .d  (dis‐
       cussion) 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  fol‐
       lowing 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 ex‐
       plicitly providing a -display flag that omits the display command, you can disable  the  dis‐
       play 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 configu‐
       ration 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 immedi‐
       ately after the newsgroups are scheduled to be written to the display and before they are ac‐
       tually 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  com‐
       mand  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  possibil‐
       ity  of starting multiple newsreaders just because multiple newsgroups contained unread arti‐
       cles.  (A check should, of course, be made to make sure that a newsreader is not already run‐
       ning.)


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 under‐
       graduates).  The "delay" variable describes how many seconds to sleep.

       The "server" variable names an NNTP news-server.  The default is "news".  The "server"  vari‐
       able 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 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-cu‐
       bit.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 infor‐
       mation.   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  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 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 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 al‐
       lows 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 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 al‐
       lowed.


WINDOW
       When unread news is found, a window is popped up.  The window lists the names  of  the  news‐
       groups  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  contin‐
       ues to run).


BUTTONS
       Button  or key bindings may be assigned by bind commands.  Feel free to change them.  The de‐
       fault 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 "display_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, unmapwin‐
       dow, 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 vari‐
       ables 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 ar‐
       ticle that you have read.

       A  number  of  lists maintain interesting information. "active_list" is a list of known news‐
       groups.  "seen_list" is a list of newsgroups that have been seen so far as the -new and -dis‐
       play 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 news‐
       group  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)