
# @(#)README 1.6 93/05/19

SuperXBell v2.0
---------------

Getting tired of that boring old X beep?  Jealous when your neighbor's
Macintosh howls, grunts, and winces?  This is SuperXBell, which will
make you just as noisy and annoying as the average Mac user.

SuperXbell is a tiny library that overrides the standard XBell()
routine that is found in Xlib.  When called, the new XBell() routine
will play sounds that you specify.  You can set it up so that each
application plays a different sound, so you can tell where the sound
came from.

SuperXBell runs on the client side, and does not change the server.
You can use this with any program linked with Xlib: xterm, cmdtool,
mailtool, etc. without any recompilation.

Caveats: This is a toy.  If it breaks something else, don't use it.
If you find a bug, fix it and send patches to the author.

Configurations
---------------

So far this only runs on Sun SparcStations.  It should work with MIT X,
and I've verified that it works under OpenWindows 3.x.  You will need
to have some sound files (which usually can be found in
/usr/demo/SOUND/sounds).


Setting things up
-----------------

1) Check the Makefile.  It comes ready to compile under SunOS 5.x (aka
   Solaris 2.x).  If you are building for SunOS 4.x, then you will have to
   uncomment three lines.  These lines are clearly marked.

2) Compile it.  Type:

	"make"

   This will create shared library, called "superxbell.so".  
   If you get a warning, it might be because step 1 was done incorrectly.

3) Install it somewhere permanent.  Type:

	"make install INSTALL_DIR=/installed"

   The installation step is not necessary, you can leave it in this
   directory if you wish.


4) Configure what sounds you want to have played.  Up to 10 different
   sounds can be defined using the resource database.  If more than one
   sound is specified, each sounds will be used in round-robin fashion,
   one sound per XBell().  The following is an example of what you might
   put into your .Xdefaults, it specifies the filenames for three sounds:

	SuperXBell.sounds: /usr/demo/SOUND/sounds/bark.au		\
		/usr/demo/SOUND/sounds/clink.au				\
		/home/sounds/something_interesting.au

   You can also specify sounds on the command line, for example:

	xterm -xrm 'SuperXBell.sounds: /home/sounds/my_beep.au'
	mailtool -xrm 'SuperXBell.sounds: fastbeep.au newmail.au'

   If SuperXBell cannot find the file, the default XBell sound will
   be used.


5) Finally, you have to tell the dynamic linker about this new library.
   To do this, add the following line to your .login file:

	setenv LD_PRELOAD /installed/superxbell.so

   Or you can add the following lines to your .xinitrc file:

	LD_PRELOAD=/installed/superxbell.so
	export LD_PRELOAD

  (Be sure to replace the "/installed/superxbell.so" appropriately.)
  Logging out and back in is probably the easiest way to pick up the
  changes to these environment variables.

More Caveats
------------
* This software depends on a feature (LD_PRELOAD) that is undocumented
  and unsupported for SunOS 4.x.  It is documented and supported in SunOS
  5.x, however.  (You can relink your applications with the superxbell.so
  if you want to avoid using the undocumented feature.)
* Per these instructions, superxbell.so is loaded into every application.
  SuperXBell is very tiny so space should not be a concern.  It's possible
  to work around this with a shell program if necessary.
* If you are running an application remotely, or some error occurs while
  trying to play a sound, the boring old XBell() will sound.
* SuperXBell ignores the volume parameter to XBell() and xset.  Use gaintool
  or audiotool.
* SuperXBell assumes that the sound format is 8-bit u-law 8000 Hz.
* No errors are reported.
* If you turned off your bell and can't remember how to turn it back on, try
  "xset b on".
* Setting sounds for olwm with the -xrm option to olwm does not work.


Author:
Brian Warkentine (brian.warkentine@Eng.Sun.COM)

