Merge branch 'master' of ssh://git.ucw.cz/home/mj/GIT/osdd

[osdd.git] / README

diff --git a/README b/README
new file mode 100644 (file)
index 0000000..c9b974d
--- /dev/null
+++ b/README
@@ -0,0 +1,71 @@
+================================================================================
+
+                           On-Screen Display Daemon
+
+                      (c) 2010 Martin Mares <mj@ucw.cz>
+
+       You can use and distribute this program under the terms of GPLv2.
+
+================================================================================
+
+
+OSDD is a simple daemon whose purpose is to wait for messages sent by other
+programs and display them on the screen using libxosd. Unlike other such
+daemons, it handles message attributes (like colors), keeps its eye on
+message timing and uses X properties to pass messages, so it works over SSH
+connections with X forwarding.
+
+I have developed osdd on Linux, but it should work on any recent POSIX-compliant
+system equipped with libX11 and libxosd.
+
+Please send all bug reports and suggestions to the author.
+
+Usage
+~~~~~
+When you run `osdd' without any parameters, it forks and waits in the background
+to serve the messages. It is convenient to invoke it from ~/.xsession, so that
+it is started with your X session. It should exit properly when the session
+terminates.
+
+The simplest way of sending messages to the daemon is using the `osdc' client,
+e.g., `osdc "Hello world!"'. Use multiple parameters to create a multi-line
+message (however, the maximum number of lines is fixed and it can be changed
+only by the `--lines' switch on daemon startup).
+
+You can also add attributes to the message (written as command-line options):
+
+  --color=c            Set foreground color of the message. Colors are specified
+                       either as #RGB, or #RRGGBB, or color names from X11 rgb.txt,
+                       or any other method documented in XParseColor(3).
+
+  --outline-color=c    Set color of character outlines.
+
+  --duration=ms                Show the message for a given number of miliseconds.
+
+  --min-duration=ms    When another message arrives while this one is displayed,
+                       the duration of this message can be shortened, but not
+                       below this parameter.
+
+  --percent=p          Draw a line with a percentage bar (p=0..100)
+
+  --slider=p           Draw a line with a slider (p=0..100)
+
+The default values of most of these attributes can be given by command-line
+options of the daemon, use `osdd --help' to get the full list.
+
+Any value can be replaced by "-", meaning "read from standard input".
+
+
+Example clients
+~~~~~~~~~~~~~~~
+
+osd-clock              Display current date and time (a shell script piping
+                       its output to osdc).
+
+osd-mpc-volume         Adjust volume of the MPD music player daemon and show
+                       a slider with the new value.
+
+osd-batt               A slightly more complex client written in C, showing
+                       the current status of laptop batteries. It can be asked
+                       to show status immediately or to run in background and
+                       croak whenever the battery is low.