man pages section 1: User Commands

Exit Print View

Updated: July 2014

tknewsbiff (1)


tknewsbiff - pop up a window when news appears


tknewsbiff [ server or config-file ]


User Commands                                       TKNEWSBIFF(1)

     tknewsbiff - pop up a window when news appears

     tknewsbiff [ server or config-file ]

     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.

     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

SunOS 5.11         Last change: 1 January 1994                  1

User Commands                                       TKNEWSBIFF(1)

     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/"
     watch* -new "exec play /usr/local/sounds/"

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

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

     As an aside, you can put an "&" at the end of an "exec" com-
     mand  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

     watch * -new {
          exec play
          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 sched-
     ules $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

SunOS 5.11         Last change: 1 January 1994                  2

User Commands                                       TKNEWSBIFF(1)

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

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

     watch *security* -display {
          exec play

     Actions associated with the -new and -display flags are exe-
     cuted  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

     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  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  news-
     readers  just  because  multiple newsgroups contained unread
     articles.  (A check should, of course, be made to make  sure
     that a newsreader is not already running.)

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

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

SunOS 5.11         Last change: 1 January 1994                  3

User Commands                                       TKNEWSBIFF(1)

     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 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
     "",   then  tknewsbiff  looks  for  ~/.newsrc-  (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 win-
     dow  to see what was truncated.  However, if your configura-
     tion 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 news-
     groups 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 con-
     figuration 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

SunOS 5.11         Last change: 1 January 1994                  4

User Commands                                       TKNEWSBIFF(1)

     the newsrc variable is not set explicitly).

     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  con-
     figuration   file  name  and  as  a  suffix  to  the  string
     "~/.tknewsbiff-".  So if you want to watch the server  "kid-
     ney",  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 but-
     ton 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 allowed.

     When  unread news is found, a window is popped up.  The win-
     dow lists the names of the  newsgroups  and  the  number  of

SunOS 5.11         Last change: 1 January 1994                  5

User Commands                                       TKNEWSBIFF(1)

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

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

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

SunOS 5.11         Last change: 1 January 1994                  6

User Commands                                       TKNEWSBIFF(1)

     Built-in commands already mentioned are: watch, ignore, dis-
     play, 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 fore-
     ground and background colors of the newsgroup list, you  can

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

     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 high-
     est 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.    "previ-
     ous_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.

     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

SunOS 5.11         Last change: 1 January 1994                  7

User Commands                                       TKNEWSBIFF(1)

     are testing a new configuration or have just  modified  your
     newsrc  file),  press  button  2 in the display (see BUTTONS

     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 read-
     ing  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 news-
     groups.)  Fortunately, this definition is considered a  fea-
     ture  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.

     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  sin-
     gle 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.

     The man page is longer than the program.

     See  attributes(5)  for  descriptions   of   the   following

     |Availability   | shell/expect     |
     |Stability      | Uncommitted      |
     "Exploring Expect: A Tcl-Based Toolkit for Automating Inter-
     active Programs" by Don Libes, O'Reilly and Associates, Jan-
     uary 1995.

SunOS 5.11         Last change: 1 January 1994                  8

User Commands                                       TKNEWSBIFF(1)

     Don Libes, National Institute of Standards and Technology

     This   software   was   built   from   source  available  at   The   original
     community   source   was   downloaded  from   http://source-

     Further  information about this software can be found on the
     open source community website at

SunOS 5.11         Last change: 1 January 1994                  9