XBUFFY(1)

NAME
xbuffy - yet another biff for the X Window System

SYNOPSIS
xbuffy [X toolkit options] [-help] [-version] [-horiz] [-poll seconds] [-header seconds] [-acmd sound file] [-nofork] [-nobeep] [-names] [-orig] [-priority priority] [-command command] [-shortnames] [-mail <mailbox files...>] [-news <newsgroup names...>]

DESCRIPTION
Xbuffy keeps track of multiple mailboxes. You can either specify mailbox files on the command line, in a Xresources file, in a text configuration file, or set your MAILPATH environment variable (a colon separated list of files). It will display the number of new messages in each mail file in a box. You can clear the reverse video in a box by clicking on the box with Button 3. Another key feature of xbuffy is that it will use NNTP to watch newsgroups in the same way it watches mailboxes. You can also specify newsgroups on the command line, in Xresources, in a text configuration file (the same file can specify both mailboxes and newsboxes), or set your NEWSPATH environment variable using the same format as the MAILPATH environment variable. By specifying certain command line options and/or Xresources, xbuffy can show the From and Subject lines in each box. It can also invoke shell commands on button clicks. Each box can be configured differently by using a boxfile. In general, it is a very extensible biff. Read on for details on what it can do.

OPTIONS
The following options are recognized:

-help
    Print a brief help message and exit

-version
    Print the current version and exit

-poll secs
    How often the mailbox files are polled for new mail. If this is not specified, it will use the MAILCHECK environment variable. (default: 60)

-header secs
    This will display the From: and Subject: lines from incoming mail messages in a popup window when button 1 is pressed in the box label. The mail header will also popup automatically for the amount of time indicated in secs when new mail arrives. If secs is 0, the mail header will not pop up when new mail arrives. Clicking in the popup window when mail arrives (if the argument is non-zero) will instantly popdown the window. This feature was borrowed from xpbiff.

-fill
    Makes all the boxes the same size.

-center
    Centers the name of the box in the box. This option turns on the fill option.

-acmd sound command
    This will run a command instead of ringing the bell when new mail arrives. For example, you could "cat meow >/dev/audio". This option could also be used to automatically open a mail reader when new mail arrives.

-horiz
    This will line up the boxes horizontally (default: vertical)

-nobeep
    This will disable the beep (or sound command) when new mail arrives.

-nofork
    This will prevent xbuffy from putting itself into the background.

-boxfile filename
    The name of a file containing configuration information for the boxes. The boxfile is an alternative way of specifying what to watch. The boxfile also allows each box to have different polltime, headertime, etc.

-origMode
    This will show all messages in each mailbox. It has no effect on news groups.

-names
    Will display the full pathname of all the mailboxes it is watching.

-shortnames
    Will display the file names of all the mailboxes it is watching.

-priority priority
    Nice level at which xbuffy and its child processes will run.

-command command
    This is the default command that is to be executed when Button 2 is pressed on a box.

X Options
    Standard X windows options (e.g. -fn, -display, etc.)

ENVIRONMENT
The names and purpose of the some of the following environment variables were borrowed from Bash, the GNU Shell.

MAILCHECK
    This specifies the amount of seconds to wait in between polling for mail.

MAILPATH
    This is a colon separated list of files to check for mail.

NEWSPATH
    This is a colon separated list of newsgroups to monitor.

NNTPSERVER
    This is the name of the NNTP server to use for news boxes.

X DEFAULTS
The application class is XBuffy. Almost all the arguments above can be set in the X resource database, allowing for one-time configuration and eliminating long command lines. The environment variables described above take precedence over any X resources that are specified. Also, any command line arguments take precedence over both X resources and environment variables.

BOXFILE FORMAT
The boxfile contains configuration information for each box. Any line that begins with '#' is considered a comment and is ignored. The definition of a box begins with the keyword box followed by the filename or newsgroup for that box. All subsequent lines are then used to configure that box until either another box command or the end of file. Note that these options are NOT case sensitive. The following are settable on a per box basis by using the boxfile option (note that the boxfile may also be set in the Xresources with the resource Xbuffy.boxfile: <filename>). When using a boxfile, only the box line is required. All options that are not given in the boxfile will default to the command line (or built in) value.

box file name
    The filename or newsgroup for this box. This also marks the beginning of a box definition.

title box title
    The title that you want for this box. This will override the shortname or longname option.

mailbox
    Specify that the box is a mailbox (a file). If neither mailbox or newsbox is specified, mailbox is the default.

newsbox
    Specify that the box is a newsbox (a NNTP newsgroup).

cclient
    Specify that the box will use the c-client library routines to deal with the mailbox. This is useful for IMAP, MMDF, MH, maildir, and other mailbox formats.

keepopen
    Keep the connection open during an IMAP session. This option only applies to a cclient box and only really makes sense if you are using IMAP.

countperiod period
    How often should a real count be performed. This option only applies to to a cclient box and only really matters if you have a headertime of 0. A full count of the mailbox will be performed every period polls of the box.

origMode
    origMode will make Xbuffy try to act like Xmultibiff and count ALL messages instead of just NEW message.

newMode
    newMode will make Xbuffy count only new messages (this is the default).

nobeep
    This will disable the beep (or sound command) when new mail arrives in the specified mailbox to be counted.

beep
    This will enable the beep (or sound) when new mail arrives in the specified mailbox to be counted.

shortname
    This will cause the specified box to be prefaced with the filename.

longname
    This will cause the specified box to be prefaced with a full path name.

audio command string
    Set to the command string to be used automatically when new mail arrives.

polltime secs
    Set to the time (in seconds) in between polling the box.

headertime secs
    Set to the time (in seconds) to display the header when new things arrive.

command command string
    Specifies a UNIX shell command to be executed by sh when the middle mouse button is pushed in a box. Take care to escape characters correctly.

The following resources are settable on a per application basis
    in the Xresources:

horiz
    Set to TRUE or FALSE. Same as the -horiz option.

mailboxes
    Set to a colon separated list of mailboxes (files). This is the same as specifying files on the command line.

newsboxes
    Set to a colon separated list of news groups. This is the same as specifying files on the command line.

C-CLIENT NOTES
If Xbuffy has been compiled to use the c-client library you can tell Xbuffy to use the routines in that library to deal with the mailbox. The advantage of this is that Xbuffy will be able to deal with all the mailbox formats that are understood by c-client. These formats include MMDF, MH, IMAP, and others. To use the c-client functions you must use a boxfile and specify the box type as cclient. The file name you give after the box option determines what type of driver cclient will use to read the mailbox. In the simplest case of just giving a filename (like Xbuffy normally uses) c-client will attempt to figure out what format the mailbox uses. There are a few special names and prefixes for certain box types.

#mhinbox
    The name #mhinbox refers to the directory inbox in the MH path.

#mh/
    The prefix #mh/ refers to the directory in the MH path.

Remote Names
    Names which start with { are remote names and are in the form
     { remote_system_name [:port] [flags] } [mailbox_name]
    where: remote_system_name Internet domain name or bracketed IP address of server.

port
    optional TCP port number, default is the default port for that service flags optional flags, one of the following (not all of these may work with Xbuffy): /service=service mailbox access service, default is "imap"

/user=user
    remote user name for login on the server

/anonymous
    remote access as anonymous user

/debug
    record protocol telemetry in application's debug log

/secure
    do not transmit a plaintext password over the network

mailbox_name
    remote mailbox name, default is INBOX

EXAMPLES
The following examples demonstrate how to configure xbuffy to do the same thing from both the command-line and X resources. Although, for maximum flexibility on a per-box basis, I suggest using a boxfile. The following example will watch 2 mailboxes in a home directory:
	% xbuffy -mail ~/box1 ~/box2
 boxfile:
	box ~/box1
	box ~/box2
The following example will watch a mailbox and a newsgroup:
	% xbuffy -mail /usr/spool/mail/you -news comp.windows.x &
 boxfile:
	box /usr/spool/mail/you
	box comp.windows.x
	newsbox
Here's a boxfile example for watching a few boxes using IMAP:
       # user fred's inbox
       box {imap.example.com/user=fred}
       title INBOX
       cclient
       polltime 180

       # user fred's box named foo
       box {imap.example.com/user=fred}foo
       title foo
       cclient
       polltime 180

GRATITUDE
Thanks to John Reardon for writing the original Xmultibiff and Xmultibiff 2.0. Xbuffy is a modified version of Xmultibiff 2.0 (although the code is looking less and less similar everyday). Thanks to Tim Culver <culver@doppke.com> for writing the original code to use with the c-client code.

BUGS
There is a bug with the NNTP stuff that isn't really Buffy's fault. Most versions of the NNTP server will not dynamically update the high message number (you must disconnect from the server and re-connect to get a new high message). If your server is running one of these versions of NNTP then you will not get told of new articles in your newsboxes.

AUTHOR
xbuffy:    Bill Pemberton, wfp5p@virginia.EDU

xmultibiff: John Reardon, Midnight Networks Inc.,
        badger@midnight.com