
Configuration of jws
====================

What to configure
-----------------

You can configure jws via some environment variables:

- JFONT (default "font"): name of the font file
- JFONT_CF (default "font.cf"): name of the font scaling configuration
  file
- JWS_KEYMAP (default "keymap"): name of the keyboard map file,
  containing key redefinitions and jws commands
- JWS_KEY_FALLBACK (default "none"): "f" (full) means every undefined
  key/modifier pair is taken from xmodmap, "b" (blank) means every
  completely undefined key is taken from xmodmap
- JWS_TERM (default "jterm"): name and parameters for the terminal
  client
- JWS_LOCK (default "jlock"): name and parameters for the screen lock
  client
- JWS_REQ (default "jreq"): name and parameters for the exit
  confirmation client
- JSERVER (default $DISPLAY): host and port of jws, for
  jterm/jlock/jreq

If you're desperate, you can also configure some things directly in the
source, notably in src/strings.c and gamma and colors in
src/fontcache.c.

Format of the JWS_KEYMAP file
-----------------------------

Empty lines and lines beginning with a tab are treated as comments and
ignored.  Every other line defines the mapping of one key.

The line begins with the Keysym of the key as defined with xmodmap. 
You can specify any Keysym, no matter whether it's only reachable with
a modifier.  Alternatively you can give a Keycode directly with "=xx"
as a hex number.  The rest of the line consists of zero or more
definitions for the actions generated by the key if used with
modifiers.  Each single definition is preceded by a tab.

A definition entry consists of an optional list of modifiers, a "!"
marking the key/modifier pair as to be grabbed by jws, or another list
of modifiers preceded by a "?" marking those modifiers as to be
ignored, a "=" and an action.

Valid modifiers are "s" (shift), "l" (lock), "c" (control), "m" (meta),
"a" (alt), and "1" - "5" (mod1 - mod5).

Valid actions are "\!w01" - "\!w32" for switching to an existing
window, "\!s01" - "\!s32" for swapping the current window to a new
position, "\!lock" for starting the JWS_LOCK client, "\!x11" for
switching to the X screen, "\!restart" for restarting jws, "\!exit" for
exiting jws (after a confirmation requested by the JWS_REQ client),
"\!launch" for starting a new JWS_TERM client, "\!compose" for
introducing a key compose sequence, and one or more characters
separated by ",".

Characters can be specified by writing them verbatim (allowed for "!" -
"~" except "\"), or as "\^A" - "\^_" for control characters (lowercase
is also allowed), or as "\\" for "\", or as a two character hex number
(lowercase or uppercase) preceded by "\".

Format of the JFONT_CF file
---------------------------

Each entry consists of 10 numbers (and any non-number is interpreted as
end of file).

The first two numbers determine the original size of the font, the
second two determine the scaled down size of the font, the rest are two
pairs of three determining the scaling parameters in the x and y
directions.

The file is scanned line by line for an entry that matches the actual
original size of the font and the desired new width (that is the width
of the jws window divided by 80 and the number of windows and rounded
down).  If no entry matches, an entry of the form "old_w old_h new_w
new_h 0 new_w old_w 0 new_w old_w" with an appropriately scaled new
height is assumed.

The scaling parameter triple consists of an offset and scaling factor
enumerator and denominator.  The pixels are shifted down respectively
to the right by offset/denominator and scaled by
enumerator/denominator.

Examples
--------

- This is what could be used with a Dec LK401 keyboard:

JWS_KEYMAP=$HOME/jws/keymaps/lk401
JWS_KEY_FALLBACK=f

JFONT=$HOME/jws/fonts/tt51x93.latin1
JFONT_CF=$HOME/jws/fonts/tt51x93.cf

JWS_TERM='jterm -ls'

- Excerpts from "lk401" (note that there may be no spaces except in
  comments):

	F1 (grabbed) = switch to window 1,
	Ctrl-F1 (grabbed) = move window to position 1
F1	!=\!w01	c!=\!s01

	Delete = delete character, regardless of modifiers
Delete	?macs=\7f

	Alt-O = oe, Shift-Alt-O = Oe,
	Meta-O (grabbed) = launch a jterm
o	a=\f6	sa=\d6	m!=\!launch

	Meta-Alt-Enter (grabbed) = restart jws
KP_Enter	ma!=\!restart

	Cursor Up = Esc O A
Up	=\1b,O,A

- An example "font.cf" with the first line being the same as the
  default values and the other three modified values for those font
  sizes:

51 93    8 15   0  8 51    0  8 51

51 93    7 13   0  7 51   13 13 93
51 93    8 15   0  8 51    0 15 93
51 93   10 20   0 10 51   20 20 93

