The xstroke configuration file, (${HOME}/.xstrokerc), defines strokes
and actions to be performed when the stroke is entered. Currently, the
only supported action is to send a KeyPress and KeyRelease event to
the currently focused window. Future releases of xstroke will add
support for addition actions including sending strings of characters,
(macro expansion), as well as executing commands.

The current syntax for the .xstrokerc file is as follows:

Blank lines are ignored.
Lines beginning with a '#' character are ignored as comments.
All other lines should be a stroke definition of the form:

	keysym = stroke_sequence

where keysym is any X keysym, (see <X11/keysymdef.h> and ignore the
XK_ prefix).

stroke_sequence is a series of characters including the digits
'1'-'9', '?', '[' and ']'. The digits are the essential elements and
describe the stroke as a path along a 3x3 grid with each cell numbered
from 1 to 9 as shown here:

	1 2 3
	4 5 6
	7 8 9

For example, if you wanted to send an 'L' key event when you made a
stroke that looks like a capital 'L', you could use the following
stroke definition:

	L = 14789

Notice, that the path 14789 through the 3x3 grid above describes a
capital L shape. Note that xstroke never displays a grid to the
user. Instead, libstroke automatically infers the grid based on the
bounding box of the input stroke. This makes xstroke robust to many
stroke distortions including translation and independent scaling along
the X and Y axes.

The stroke definition file may contain many different strokes which
are mapped to the same keysym. In fact, every good stroke definition
file will include several different strokes for each keysym to make it
more robust when the user is sloppy with stroke input. For example,
the capital 'L' stroke might not have a sharp corner and may miss the
lower-left corner of the grid, so it could be useful to add:

	L = 1489

These two stroke defintions are sufficient for making a fairly robust
'L' shape. However, more complex strokes may require hundreds or
thousands of different strokes in order to be recognized in a robust
way. For example a clockwise circle starting at the top might be
defined as:

	0 = 214789632

This is a rather boxy shape. If the user strokes a circle, any one of
the four corners, (1, 7, 9, and 3), might be missed. We could account
for this by including 16 different strokes in the configuration
file. But this quickly becomes tedious for very complex shapes. To
save you from this tedium, the stroke_sequence can include the
characters '?', '[', and ']'.

The character '?' means that the previous digit is optional. This
means that we can specify our round circle that starts at the top
with:

	0 = 21?47?89?63?2

This stroke_sequence actually adds 16 different strokes to the
recognition database, (based on all possible combinations of optional
digits being included). If any one of the 16 strokes is entered, it
will be recognized as '0'.

The '[' and ']' characters can be used to specify alternation. Any
single digit included between the brackets can appear in the
stroke. For example:

	minus = 4[258]6

describes a stroke which goes from the left to right, (456), but may
include a bump up, (426), or a bump down, (486). All three of these
strokes will be entered into the database. (Note, that example would
not be a very useful stroke definition, it would not match things like
4256 or 4586 which might be likely input stroke).

The optional operator '?' can be combined with alteration to specify
that a class of digits is optional. For example, here is a useful
stroke sequence defining a diagonal line from the lower-left to the
upper-right:

	slash = 7[48]?5[26]?3

In one simple definition we have added 9 different strokes to the
recognition database.

If you'd like to see more elaboarate examples of the possibilities,
see the default xstrokerc file. There are a couple of things to be
aware of when designing your own strokes using '?' and '[]'. First,
there is the memory issue. If there are N occurrences of the character
'?' in a stroke, then at least 2^N strokes will be added to the
database. If you don't exercise some caution, the database could get
quite large. (As reference, the default xstrokerc file defines 134
characters using 14233 strokes! For now, xstroke is optimized for
speed not memory usage and those 14233 strokes consume at least about
400KB of memory. That's not awful, but it could get bad with a much
larger alphabet. (I am also planning on optimizing the database to
bring that size down considerably).

The second problem that can happen with liberal use of '?' and '[]' is
that you can define strokes that you never intended. For example, the
slash example above defines several strokes that look like a slash,
such as 753, 7523, and 7853. However, it also defines a couple of
strokes that might be useful for some other character in the alphabet,
such as the zigzags, 74563 and 78523. With a large alphabet it is easy
to get a lot of clashes from these accidental strokes, (xstroke will
print warnings when it finds clashes). Some care is necessary to
eliminate these clashes. I've spent a considerable amount of effort
removing all such clashes from the default xstrokerc file.

One final note: The stroke sequence may be tagged with a final '*'
character, (or "**"), to indicate that the stroke should be included
in a postscript diagram of know strokes. A single asterisk '*' will
cause a smooth, curvy stroke in the diagram. Using two asterisks,
"**", will result in a diagram with straight line segments. You will
need perl and Metapost, (included in TeX distributions), to generate
the diagrams. See the Makefile in this directory as well as
generate_diagrams.pl to see how to do this.
