Ubuntu Manpage: xlbiff - mail notification pop-up with configurable message scans

NAME

       xlbiff - mail notification pop-up with configurable message scans

SYNOPSIS

       xlbiff [ -option ... ] [ mail_file_or_imap_server ]

DESCRIPTION

       Is  “you  have  mail”  not  quite  enough detail?  Is a per-message notification too much?
       Welcome to xlbiff, the X Literate Biff.

       xlbiff presents enough information to tell you: Is this new mail worth reading right  now?
       And it stops distracting you once you decide.

       xlbiff  waits  in  the background, monitoring your mailbox file or IMAP server (or running
       your custom check-mail script).  When a new message arrives, it  invokes  the  MH  scan(1)
       command  (or  your  custom  mail-scanning  script)  and  pops  up a window with the output
       (typically the From and Subject line of each new message).  If more mail  arrives,  xlbiff
       scans again and resizes its preview window accordingly.

       Clicking  the  left mouse button anywhere in the window causes it to vanish.  It will also
       vanish if the mailbox becomes empty.  xlbiff stays out of your way when there  is  no  new
       mail and pops up only when something requests your attention.

       Features:
         • occupies no screen real estate until mail comes in
         • supports scripts for checking mail
         • has configurable screen location, color, and font
         • can notify by bell and/or keyboard LED
         • shows all new messages in one, easy-to-dismiss window
         • lets you click anywhere on it; no trying to select a tiny “x”

GETTING STARTED

       If your new mail arrives in a local mail file in the usual system directory:

           xlbiff

       If your mail file is in a different location, you will need to specify the filename:

           xlbiff ~/Mailbox

       If your mail is on an IMAP server, specify the server's name:

           xlbiff imap.example.com

       Whichever way you start xlbiff, if you have new mail, it should pop up a window displaying
       summary lines for the new messages.  (If you don't  have  new  mail,  you  won't  see  any
       window,  which is how xlbiff tries to stay out of your way.)  The window will stay visible
       until you click it away or read the new mail.

       You may need an entry in ~/.netrc to provide login credentials for your IMAP server.   The
       format of this file is described in mailbox-preview(1).

       When  you have the correct options to xlbiff figured out, you will probably want to run it
       in the background or start it at the beginning of your X session.

OPTIONS

xlbiff accepts all of the standard X Toolkit command line options along with the
additional options listed below:

-file file_or_server_name
This option specifies the name of the file or IMAP server that should be
monitored. By default, it watches file /var/mail/username, where username is your
login name.

If given the name of an IMAP server, xlbiff, assisted by its default
checkCommand/scanCommand script mailbox-preview(1), will peek at your new messages
on this server.

The -file is optional; a non-option argument will be treated the same.

-bottom This option tells xlbiff to realize/unrealize() the output window instead of using
XtPopup/down(). This has the effect of causing the window manager to reposition
the window each time it pops up, and is useful for when you specify negative Y
coordinates, i.e., at the bottom of the screen. Running xlbiff in this situation
without -bottom would cause new lines to run off the bottom edge of the screen.

+bottom Opposite of -bottom.

-rows height
This option specifies the maximum height, in lines of text, of the xlbiff window.
The default is 20.

-columns width
This option specifies the maximum width, in characters, of the xlbiff window. The
default is 80.

-resetSaver
If this option is set, xlbiff will reset the screen saver when new mail comes in.
This is useful if you're doing something near your workstation but not on it.

+resetSaver
Opposite of -resetSaver.

-update seconds
This option specifies the frequency in seconds at which xlbiff should update its
display. The default is 15 seconds.

-fade seconds
Number of seconds to wait before popping window back down. This option can be
used to monitor events of non-lasting importance, such as syslog or UUCP queues.
The default value of 0 disables the fade option.

-led ledNum
This option specifies a keyboard LED to light up when there is mail waiting in the
file. The default is zero (do not light a LED).

-ledPopdown
This option indicates that the LED should be turned off when xlbiff is popped
down. Ordinarily the LED stays lit to remind one of awaiting mail. This option
has no effect if the -led option is disabled.

+ledPopdown
Opposite of -ledPopdown.

-refresh seconds
This option specifies the number of seconds to wait before re-posting the mail
window after you acknowledge it, and it still contains the same mail. The default
is 0 (no refresh). A useful value for this is 1800 (30 minutes).

-mailerCommand command
Specifies the command to invoke when the mailer() action, described below, is
activated. Due to mailbox consistency considerations, the mailerCommand should
not exit before it is finished with the mailbox, i.e., it should not run its
command in the background.

Example mailerCommand values:

xterm -e alpine
emacsclient --eval '(mh-rmail)' --suppress-output

There is no default mailerCommand.

-scanCommand command
Specifies a shell command to be executed to list the contents of mailbox file.
The specified string value is used as the argument to a popen(3) call and may
therefore contain I/O redirection. The command's stdout is used to generate the
window. Internally, the command is generated as

sprintf(buf, scanCommand, file, columns, rows)

so a %s, %d and %d respectively in scanCommand will generate the values of file,
columns, and rows. The default scanCommand, specified by the XLbiff application
resources file, is

mailbox-preview %s --width %d --max-messages %d 2>&1

If a scanCommand is used to change the way the mailbox is accessed (as opposed to
change the way the content is displayed), you will need to supply a compatible
checkCommand.

-checkCommand command
Specifies a shell command to be executed to check for new mail (or some other
condition) rather than simply examining the size of the mail file. The specified
string value is used as the argument to a popen(3) call, and the output generated
is important. Like xbiff, an exit status of
• 0 indicates that a change in condition demands a new evaluation of scanCommand
and subsequent popup,
• 1 indicates no change in status, and
• 2 indicates that the condition has been cleared and the xlbiff window should
pop down.

The default, specified by the XLbiff application resources file, is

mailbox-preview %s --check %d

Similarly to scanCommand, the checkCommand is generated internally as

sprintf(buf, checkCommand, file, previous)

previous is the numeric value output by the last time checkCommand was run, or
zero the first time. This is useful for allowing the checkCommand to maintain
state.

See the EXAMPLES section, below, for different ways to use checkCommand.

-volume percentage
This option specifies how loud the bell should be rung when new mail comes in.

The following standard X Toolkit command line arguments are commonly used with xlbiff:

-display display
This option specifies the X server to contact.

-geometry +x+y
This option specifies the preferred position of the scan window.

-bg color
This option specifies the color to use for the background of the window.

-fg color
This option specifies the color to use for the foreground of the window.

-xrm resourcestring
This option specifies a resource string to be used. This is especially useful for
setting resources that do not have separate command line options.

-help This option indicates that a brief summary of the allowed options should be
printed on standard output.

RESOURCES

       The  application  class name is XLbiff.  It understands all of the core resource names and
       classes as well as:

       bottom (class Bottom)
               Same as the -bottom option.

       file (class File)
               Same as the -file option.

       mailerCommand (class MailerCommand)
               Same as the -mailerCommand option.

       scanCommand (class ScanCommand)
               Same as the -scanCommand option.

       checkCommand (class CheckCommand)
               Same as the -checkCommand option.

       resetSaver (class ResetSaver)
               Same as the -resetSaver option.

       update (class Interval)
               Same as the -update option.

       fade (class Fade)
               Same as the -fade option.

       columns (class Columns)
               Same as the -columns option.

       rows (class Rows)
               Specifies the maximum height, in lines, of the xlbiff window.  The default is 20.

       led (class Led)
               Same as the -led option.

       ledPopdown (class LedPopdown)
               Same as the -ledPopdown option.

       refresh (class Refresh)
               Same as the -refresh option.

       sound (class Sound)
               Specify a command to be run in place  of  a  bell  when  new  mail  arrives.   For
               example, on a Sun Sparc you might use:

               *sound: /usr/demo/SOUND/play -v %d /usr/demo/SOUND/sounds/doorbell.au

               The  command  is generated internally with sprintf(3), so the characters “%d” will
               be replaced with the numeric value of the volume resource.

       volume (class Volume)
               Same as the -volume option.

ACTIONS

       xlbiff provides the following actions for use in event translations:

       popdown()
               This action causes the window to vanish.

       mailer()
               This action causes xlbiff to  pop  down  the  main  window  and  run  the  defined
               mailerCommand  (if  any),  waiting for it to exit.  Then xlbiff will check for new
               mail, and if necessary pop up again.

       exit()  This action causes xlbiff to exit.

       The default translations are

           <Button1Press>:  popdown()
           <Button2Press>:  mailer()
           <Button3Press>:  exit()

CUSTOMIZING

       You may want to tweak some values in an app-defaults file and/or  add  some  resources  to
       your  .Xdefaults  or  .Xresources  file.   See  the system app-defaults file /etc/X11/app-
       defaults/XLbiff for examples of what you can customize.

       You also probably want to tell your window manager not to  put  borders  or  titlebars  or
       whatever around the xlbiff window.

       Note that an MH format file, xlbiff.form, is included.  This form
         • omits message number, which is meaningless in this context
         • omits message size, since scan -file can't figure it out
         • puts a “*” next to the message if your name is on the To: list (to distinguish from
         mailing lists and cc's)
         • displays the date in a friendly format
         • packs as much subject and body into one line as possible.

EXAMPLES

   Bulk maildrops
       xlbiff ships  with  two  sample  scripts,  Bcheck  and  Bscan,  intended  to  be  used  in
       conjunction.   These  are for checking mail in “bulk” maildrops.  See README.bulk for more
       info.

   Laptop fan speed
       xlbiff can be used to display your laptop's temperature  sensors  only  when  the  fan  is
       running.   This example uses the sensors(1) program as a scanCommand to display the sensor
       values.  To pop up the info only when the laptop is hot, we can use a check  command  that
       extracts  from  the  sensors  output  whether the fan is running and whether its speed has
       changed.  Here is a possible check script:

           fan1_speed=$(sensors | sed -E -n '/^fan/{s/.* ([0-9]+).*/\1/p;q}')
           echo "$fan1_speed"
           [ "$fan1_speed" = 0 ] && exit 2
           [ "$fan1_speed" = "$1" ] && exit 1
           exit 0

       If the script is called xlbiff-fan-check.sh, you can use it by running xlbiff like this:

           xlbiff -checkCommand 'xlbiff-fan-check.sh %d' -scanCommand sensors

ENVIRONMENT

       DISPLAY is used to get the default host and display number.

FILES

       /var/mail/$USER
               Default mail file to check.

       /etc/X11/app-defaults/XLbiff
               System app-defaults file for X11 resources.  Override entries  here  in  your  own
               app-defaults file or your own ~/.Xdefaults or ~/.Xresources file.

       ~/.netrc
               Login info for your IMAP server.  See mailbox-preview(1).

BUGS

       Specifying dimensions in -geometry causes badness.

       The led option does not work on Suns before SunOS 4.1/X11R5.

AUTHOR

       Ed Santiago <ed@edsantiago.com>

ACKNOWLEDGMENTS

       xlbiff  took shape around the xgoodbye sample program in the O'Reilly X Toolkit Intrinsics
       Programming Manual.  A lot of code was copied from xbiff, including this man page.  Thanks
       also  to  Stephen  Gildea  (gildea@expo.lcs.mit.edu) for the many, many contributions that
       made xlbiff grow from a midnight hack to a more mature product.

       The xlbiff.form file was copied and hacked from Jerry Peek's excellent Nutshell book MH  &
       xmh: Email for Users & Programmers.

                                            2022-01-23                                  XLBIFF(1)