Man Pages

tknewsbiff(1) - phpMan tknewsbiff(1) - phpMan

Command: man perldoc info search(apropos)  


TKNEWSBIFF(1)                                                    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 obvi-
       ous.

       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 tknewsb-
       iff's display when it is rewritten.  For example, by explicitly providing a -display flag that omits  the  dis-
       play 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 mul-
       tiple  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 giv-
       ing 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  dis-
       play.

       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  immedi-
       ately 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  sin-
       gle 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  run-
       ning 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 immedi-
       ately 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  but-
       ton 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 arbi-
       trarily 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.  "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.


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  con-
       suming  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 Asso-
       ciates, January 1995.

AUTHOR
       Don Libes, National Institute of Standards and Technology



                                1 January 1994                   TKNEWSBIFF(1)