Ubuntu Manpage: tknewsbiff - pop up a window when news appears

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.

AUTHOR

       Don Libes, National Institute of Standards and Technology

                                                 1 January 1994                                    TKNEWSBIFF(1)