Man Linux: Main Page and Category List

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 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"
       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-
       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
       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 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
       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
       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, 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