Documentation
-------------

Have a look at the "XOSD Guide and Reference" at http://ldots.org/xosd-guide/.
If you really want a Debian package of it, file a RFP or wishlist bug.

Fonts and locales
-----------------

For full unicode, you need a lot of glyphs. Since many old fonts only include
glyphs for ASCII or ISO-8859-*, this is a major problem. X11 does therefor use
multiple fonts to combine them to a FontSet. Most of the time you needn't have
a full set of all unicode glyphs, but only use a small subset. This subset
depends on your locale setting, which specified which glyphs must be available
for a FontSet to be complete.

Therefor you should use wildcards in your font-specification, else X11 might
not be able to find all required glyphs and doesn't create a font at all. It's
a good idea to install additional fonts with other encodings, for example, the
xfonts-{75dpi,100dpi,base}-transcoded are a good idea.

If it still doesn't work, try to revert back to an non-UTF8 (LANG=de_DE)
encoding or use good old ASCII (LANG=C).

Even if you don't call any X11 functions directly, you're doing so indirectly
via XOSD. Therefor you HAVE TO initialize the locale in any application using
XOSD, since XOSD can't do that itself: It would overwrite any setting done by
your application. Therefor put something like the following code in you
program before calling xosd_create():
  if (setlocale(LC_ALL, "") == NULL || !XSupportsLocale())
    fprintf(stderr, "Locale not available, expect problems with fonts.\n");

Feedback
--------

Please send any commentry to: pmhahn@debian.org

BSD Notes
---------

I've heard that to compile xosd under BSD you have to include
getopt.c, getopt1.c, and getopt.h with the other files... BSD doesn't
have these in its default distro.

VERSION 2 notes
---------------

I added and removed some of the header functions. In particular, xosd_init
is now deprecated (but still works) and has been replaced by xosd_create.
For naming consistency, I also did the same for xosd_uninit. It's
deprecated and replaced by xosd_destroy.

Other new features:
  xosd_set_offset
has been replaced by
  xosd_set_horizontal_offset
  xosd_set_vertical_offset

and we can now specify alignment to be top, middle, bottom and
left,center,right.

VERSION 1 notes
---------------

There are several modules here.

xosd.c & xosd.h combine to form (VOLTRON!) libxosd.so, which is the main
unit

xmms_osd.c becomes libxmms_osd.so which is an xmms plugin to display various
things whenever they change (volume, track, paused/shuffle/repeat etc...)

testprog.c is a simple test program, not supposed to do anything useful,
but handy if you're having problems getting it going.

osd_cat.c is another simple program, it simply reads from stdin and displays
it using osd. All its options are hardcoded, its not supposed to be used for
anything too smart, I am hoping someone will code a replacement for me :)

NB: The first thing to check is that you have a proper font #define'd, use
xfontsel to find a suitable one

NBB: xosd is written in C99, which means you can't complain about my
use of C++ style comments.