Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
TKNEWSBIFF(1)		    General Commands Manual		 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.  tknewsb-
       iff can optionally play a sound,	start your newsreader, etc.

       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

       Each newsgroup (or set of newsgroups) to	be watched is described	by us-
       ing 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  re-
       porting.	  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  "ig-
       nore"  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/"
       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  specifica-
       tion 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"	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
	    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} -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

       Actions	associated  with the -new and -display flags are executed only
       once for	each matching newsgroup.  The command executed is the one  as-
       sociated	 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

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

       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

       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 de-
       fault, 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-cu-   (This is	the Emacs gnus convention - which is very con-
       venient 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 ac-
       tive file and then click	button 2 to immediately	see how	tknewsbiff re-
       sponds (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-

       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  ar-
       gument.	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-

       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.

       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 (un-
       less suppressed by the -display flag).  When there is no	longer any un-
       read  news,  the	 window	 disappears (although the process continues to

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

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

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

       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  re-
       porting	their own holes	in the newsgroups.)  Fortunately, this defini-
       tion is considered a feature by most people.  It	allows you to read ar-
       ticles  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  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.

       The man page is longer than the program.

       "Exploring Expect: A Tcl-Based Toolkit for Automating Interactive  Pro-
       grams" by Don Libes, O'Reilly and Associates, January 1995.

       Don Libes, National Institute of	Standards and Technology

				1 January 1994			 TKNEWSBIFF(1)


Want to link to this manual page? Use this URL:

home | help