Xwatch 0.1.0 README

General
=======

Xwatch is a tool which monitors one or several files, optionally parsing the
output, and displaying it in an X window. Currently, Xwatch supports GTK+
only, but there are plans to support other widget libraries as well.

This is the first release, 0.1.0. Consider it beta until the necessary
--geometry option has been implemented.

Xwatch was written by Oskar Liljeblad (osk@hem.passagen.se). It is my first
released unix application. I would appreciate if all mistakes, bad programming
habits (and of course bugs too :) were reported to me.

Installation
============

Run './configure', 'make' and (optionally) 'make install' as root to install
the xwatch binary to /usr/local/bin (or wherever you set it to install
binaries). See the file 'INSTALL' for more information.

Usage & Tips
============

Xwatch monitors each file given on the command line. Xwatch can monitor
regular files, named pipes (FIFOs), sockets, devices and the standard input
(use '-'). Regular files are read from once every two seconds as default. This
delay can be changed with the --delay parameter.

It is possible to set the font, foreground and background color for the output
of each watch using the --font, --fgcolor and --bgcolor options. Colors are
specified with six hexadecimal digits. These options applies to all file
arguments after the option. (This makes the order of options important.)
For example, use
  'xwatch --fgcolor="FFFFFF" /var/log/syslog'
and not
  'xwatch /var/log/syslog --fgcolor="FFFFFF"'
To revert to the original font/color, use --no-font, --no-fgcolor, and
--no-bgcolor.

If you wish to precede each line displayed by the time it arrived, use
--timestamp. As with the file to watch, you can specify font and colors for
the timestamp only. Example:
  'xwatch --fgcolor="FFFFFF" --bgcolor="FF0000" --timestamp \
          --fgcolor="202020" --bgcolor="FFFFFF" /var/log/mylog
This would display the timestamp with red background, and the output as grey
text on white background.

It's possible (but optional) to define the timestamp string. The string is
parsed with the libc function strftime. For example, %H is hour (24h clock),
%I hour (12h clock), %p am/pm, %M minutes and %S seconds - see strftime(3)
for more information. Use --no-timestamp to disable timestamping for the
remaining files.

Xwatch also has built in support for monitoring system logs. Currently,
--syslog implies parsing and removal of dates, and computer host. This is the
Xwatch I run in .xinitrc:
  'xwatch --font="-misc-fixed-medium-r-normal-*-*-100-*-*-c-*-iso8859-1" \
   --syslog --timestamp /var/log/syslog-pipe --geometry 357x70-0-0 &'
Unfortunately, --geometry isn't implemented in 0.1.0.

The file syslog-pipe is a named pipe for more exact and efficient monitoring
of the syslog. (Instead of reading constantly every few seconds, Xwatch is
quickly notified when there is data waiting.) To enable it, add this line to
your /etc/syslog.conf (do not include the quotes):
  '*.*;auth,authpriv.none         |/var/log/syslog-pipe'

Use 'xwatch --help' for more options.

Bug Reporting
=============

Please send all bug reports, spelling mistakes, ideas and patches to
me, Oskar Liljeblad (osk@hem.passagen.se).

Known Bugs
==========

* There is a bug in the text widget in GTK+ 1.0.4, that crashes the
  application when colored text is used. (This has been verified on the GTK+
  mailing list.)
* The argument and config file parsing mechanism (--config option) is messy
  and probably a bit unstable. (I was unable to use getopt_long, because order
  of options is important.)
* If you know a better name for Xwatch, or if Xwatch is taken already, let me
  know.
* If you know a better default delay for regular files than 2 secs, let me
  know.

See TODO for more possible bugs.

Other Stuff
===========

The icon circles.xbm is from GTK+.
