The Xlogmaster Tutorial:
=========================

Alright - since I hate writing documentation, I will try to keep this
one as short as possible while giving you all the information you
need. The Xlogmaster has been around since middle of 1996, but back
then it was written with the xview toolkit and the configurability was
compile-time only, so I never bothered to release it to anyone but
good friends...  the version you have on your harddisk now is
fortunately a complete rewrite. ;-)


**********************************************************************************
**** Important information for all those who are too impatient to read the full
documentation (as I usually am): :-)
	RIGHT MOUSE BUTTON IN TEXT WINDOW BRINGS UP MENU  !! ********
	MIDDLE MOUSE BUTTON HIDES/SHOWS BUTTONS !!!         ************
**********************************************************************************


SOME NOTES FOR THE BEGINNERS:
---------------------------
Although the GTK+ feels a little clumsy sometimes (for instance you will notice
that you have to click on a button and then move the mouse a little in order to 
be able to select it) and has it's little flaws it is already VERY nice and
has a good chance of becoming one of the main toolkits, I'd say.
Apart from how nice it is to write the menus and things like that let me just
say this much: You should have a look at the "gtkrc" files... they basically allow
you to freely modify the look of the xlogmaster to fit your needs / your desktop
during runtime - if that isn't cool I don't know what is.



USING XLOGMASTER:
----------------
The xlogmaster has basically 2 modes - both named after the UNIX program that
performs a similar duty. The standard mode is obviously the:

TAIL-Mode: This mode behaves like "tail -f", so it displays logfiles continuously
(refreshing every "interval" seconds - default is 0.3, so you won't notice much of
a delay there...). You can scroll back with the slider to have a look back in
time.

By the way: The scrollbar will always keep it's relative position towards the end,
so if you set it 10 lines above the end it will stay there - I think this is the best
way of handling it... but enough of this, let's continue with the

CAT-Mode: This mode basically does a "cat" of the given file every "interval"
seconds. At first this might seem weird, but it allows you to keep track of all
those files & devices that put out stuff anew on every cat. You can for instance
keep track of the /proc/ devices that are of interest for you, or anything else
that works with the same principle. Extremely nice for us control freaks...



* About the Filters: *
----------------
You can set a practically unlimited number of filters separately for every
entry. Maintaining them is done via the menu (or config file - see below) 
and should be easy enough so I don't have to say too much about it. There
is just a few things about the matching algorithms I'd like to say:
The matching is done PER LINE, so no multi-line matches !! The
Xlogmaster uses the real REGEX routines since version 1.4.2 - this
means you can build incredibly powerful patterns (see GNU REGEX guide
for help).

The extended functionality since version 1.3.0 made it neccessay to
divide the filters into two classes:


CLASS0 - Filters:
-------------- 
Class 0 filters are filters that are being applied during
display-time. The CLASS0 Filters are excluding each other, only one
can be chosen. There are three Class 0 filters: 
RAISE, LOWER & HIDE.

RAISE: shows the matching line in a brighter color (see gtkrc).
LOWER: shows the matchine line in a darker color (see gtkrc).
HIDE: hides the matching line.

If multiple filters match on one line the one with the highest
priority is applied. The priorities (highest to lowest) are: HIDE,
RAISE, LOWER.


CLASS1 - Filters:
--------------
Class 0 filters are applied during read-time and very often in the
background. While Class 0 filters are (of course) only active if you
view the logfile they have been defined for, Class 1 Filters are
ALWAYS active and they are NOT excluding each other, you can define
all of them on a single match if you want, the logfiles are being read
in the background. There are four Class 1 filters:
ALERT, NOTICE, UNICONIFY & EXECUTE.

ALERT: Lets the button of the logfile that triggered the alert flash
in a bright color (see commandline options) and then the button slowly
fades back to normal (time and smoothness also controllable via
commandline). This is for immediate points of interest, stuff that
gets less interesting if you don't view it immediately. The fadeout
not only gives you an idea of how old the alert was but it also
prevents the buttons from being all read just because you've been away
for a few hours.

NOTICE: Pops up a little window at the current mouse position that
displays when there has been an alert and which logfile had it. if you
click on the entries you can see the line that triggered it.
This is thought for extremely important things and stuff that you need
to know even if you've been away for a week, so the notice box will
stay there until you dismiss it.

UNICONIFY: If you have limited space or just one desktop this is your
option... whenever a matching line shows up in the logfile this filter
has been defined for, the Xlogmaster deiconifies itself
automatically. This means you can keep it iconified without having to
fear you might miss anything.

EXECUTE: Executes the given program basically just as typing it in in
the shell would do - you also have some variables you can use:
	%F: absoute path to file/device of entry
	%H: helptext of entry
	%L: line that actually triggered the EXECUTE
	%M: mode of entry
	%N: name of the Logfile that triggered the EXECUTE
additionally all the variables are also given as environment
variables. They are called
	XLM_FILENAME	( = %F )
	XLM_HELP		( = %H )
	XLM_LINE		( = %L )
	XLM_MODE	( = %M )
	XLM_NAME	( = %N )
and can be used the usual way.

A word of warning: Since the routine will NOT check for whether a line
triggered the alert multiple times you should make sure your substring
is kinda specific - otherwise you might get so "overinformed" that it
gets very annoying ! :-)
If you think about it you could even pipe the stdout of the xlogmaster
into a logfile and create EXECUTE{echo XYZ} filters. That way you'd
have a logfile that you can control with the Xlogmaster. *GRIN*
Oh - and one last word: No piping in EXECUTE - at least not from the
Xlogmasters side. You COULD do something like this though (example is
for the bash ):
/bin/sh -c "commandlineaslongasyouwantforyourfavoriteshell"
And in there you could use piping and everything else... :-)

If there are multiple matches on a line ALL of them are being
taken. This means you could make the same string trigger all three
actions...



Audio Support:
-----------
Since version 1.3.0 the Xlogmaster got Open Sound System (OSS)
support. For every Class 1 filter category you can define a special
sound that gets played whenever this category has been triggered.

The sound files should be playably via "cat filename > /dev/dsp", so
they should be about 8KHz and in a standard format (WAVE, ULaw or
so). See manpage for commandline options concerning sound.



Commandline Options:
------------------
please see the manpage



Configuraton files:
--------------
There are basically two different format: one for the logfiles to be watched
and one for the style of the xlogmaster (the gtkrc files). I won't say anthing
about the gtkrc ones - you can go to the GTK+ docs for that and I even supplied
some examples in gtkrc-samples - some people might want to know about the 
format of the log-config files, though.  They are pure ASCII and look like this:

.
.
.
MODE{FILENAME,INTERVAL,BUTTONTEXT,HELPTEXT}
.
.

where:
- MODE is either CAT or TAIL
- FILENAME is an absolute filename
- INTERVAL is the interval between two refreshes (in seconds/10)
- BUTTONTEXT is the text on the button
- HELPTEXT is the text to pop up when the mouse stays over the
	button for a while

MODE,FILENAME, BUTTONTEXT are mandatory, INTERVAL & HELPTEXT are
optional.

You probably won't need to edit it by hand, though, because the menu
allows you to create your configuration very nicely and then you can save
it.

If you want to edit the filter settings by hand, just add the filter entrys
BELOW the logfile you want them to apply to. They are of the form
.
MODE{REGEXP}
.
where MODE is one of "RAISE", "LOWER", "HIDE", "NOTICE", "ALERT",
"UNICONIFY", "EXECUTE", "INVERT", "CASE_SENSITIVE" and REGEXP is the
string you want the filter to search for. You can also give a list of
modes separated by commas, but only one of the Class 0 filters is
allowed ! (so RAISE,NOTICE{regexp} would be o.k. whereas RAISE,LOWER
isn't)
If you specified EXECUTE there is another string appended behind the
REGEXP (also in {}) - this line is identical to the one you can enter
in the customisation menu. So an execution entry would look like:
EXECUTE{match me}{/bin/program -option dostuff}.
The "INVERT" and "CASE_SENSITIVE" flags are not filters but rather
options for matching (whether the sense should be inverted and whether
the matching should be done case sensitive) that can be used in
conjunction with any filter.

NOTE: IT IS CRUCIAL THAT THE FILTER ENTRY IS IN JUST ONE LINE,
OTHERWISE READING IT WILL FAIL !!!!

If you put a logfile configuration file to: "$(HOME)/.xlogmaster" it will
automatically be read at startup.



COPYING
-------

  The Xlogmaster
  
  a GTK+ based program to keep track of logfiles & devices
  Copyright (C) 1998 Georg C. F. Greve
  This is a GNU program
  
  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.
  
  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.
  
  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  
  Contact: 
           mailto:xlogmaster-bugs@gnu.org
           http://www.gnu.org/software/xlogmaster/
  Secondary sources:
           http://porter.desy.de/~greve/xlogmaster/
           http://www.fusebox.hanse.de/xlogmaster/

