README.Command 10-Oct-92, Maker4.0 version

XMaker's keyboard interface is almost completely reconfigurable.  

This file gives details of how to customize the keyboard
interface of both X and XMaker.

**** INTRODUCTION
An assignment of a keyboard "trigger" to one or more Maker 
commands is called keyboard "mapping".  

The "Commands" files contain mappings from a representation
of X11 trigger keystrokes to FrameMaker 4.0 commands:
	trigger-keystrokes => Maker commands
The "fmMacro" files contain mappings from X11 trigger 
keystrokes to other X11 keystrokes:
	trigger-keystrokes => recorded-macro-keystrokes

The keyboard mappings are read in from "Commands" files which
are easily replaced or augmented by the system administrator
or the individual user.

Be careful.  Reconfiguring the keyboard files may confuse
other Maker users who happen to work with them.  Commands and
fmMacros files might not be transferable to non-X versions of
Maker because the keystroke representations vary and
configurability of other versions differs.

Also, some Maker triggers are documented in Maker- in the
menus and the on-line help.  Changing the keyboard interface
will NOT change this documentation.

XMaker is currently the easiest version of Maker to
configure, because it distributes the keyboard mapping into
different files, the keystrokes are easy to read, and the
command names in the Commands files have been made much more
readable.

Maker's key mappings are completely reinitialized when you use the
"Clear Current Macros" option in the "Keyboard macros..." command
available in the FILE menu (or ^r-f-t-k in the English version).
First entries from Commands files are added together, then entries
from the fminit/groupsettings/ files (if FMGROUPMENU has a value),
then entries from user defined fmCustomUI files, then entries from
fmMacros files.  Later entries will overwrite earlier ones that have
the same trigger.

Mappings in these files implement all of the Maker mappings documented
in the Maker user's manuals.  The only commands predefined in the
Maker binary are ASCII characters in the hex range 0x20 to 0xFE.

    **** NOTES
    Currently there is no no-op function.  The closest is Cancel (\x250).
    If you want to disable a macro or mapping, remap it to a keystroke
    mapped to Cancel, such as ^c.

    To use Maker, besides the usual character and numeric keys, your 
    keyboard should have a Delete OR Backspace key and space and Return 
    keys, Control and Shift modifier keys and a third modifier, which we 
    call "Meta".  Configuring the keyboard is discussed below.

    **** MISSING KEYSTROKES
    If Maker is not responding to any keystrokes, check to see if the
    wait cursor is on- Maker will not respond until it turns off.

    You'll find it helpful to understand how X and Maker use the keyboard
    before figuring out why a key is not working.  Try reading the rest
    of this document before tackling the following.

    There are 5 reasons why Maker might not respond to a keystroke:
    1.  Maker is waiting for something from your operating system or
    network.  Check to see if the wait cursor is on.  Next see if the
    menus in the menubar work, if buttons press and if Maker windows redraw.

    2.  The Maker window does not have the focus- make sure the 
    cursor is in the Maker window.  Try clicking the left mouse
    button in a Maker window (needed if your window manager is
    running in a click-to-type mode).

    3.  Your window manager might be stealing the keystroke, check your
    window-manager resource file (e.g. .mwmrc for mwm), and use the
    instructions below.

    4.  The key is a modifier key or an "altPrefix" key, see below.

    5.  If none of the above is true, call for help.

    To check further if X and Maker see a keystroke, see below, in the 
    section "Keystrokes and KeySyms".

**** COMMANDS and FMMACROS FILES

QUICK HINT: 

At start-up, Maker will automatically read ~/fminit/fmCustomUI and
~/fminit/fmMacros adding a users mappings to the predefined maker set.
You can change these names by setting the following x resources

	Maker.myCommands:  fmCustomUI
	Maker.myMacros:	   fmMacros

The standard ascii codes are initialized from a table within Maker,
and then up to eight files are read in the following order
(The items with an asterisk* are optional.  
 The <filenames> in angle brackets are suggested, but are not all
 known to maker- they must be set with the appropriate resources.):

    fminit/<language>/Commands	   - main Commands file (platform-independent)
    fminit/<language>/MathCommands - math specific mappings
    fminit/<language>/XCommands    - platform-specific mappings
    fminit/<language>/display/XCommands.xxx  - keyboard specific mappings
    fminit/<language>/<product>/Menus - language & product specific menus
*   fminit/groupsettings/xxx	  - group specific settings
*   ~/fminit/fmCustomUI		  - extra user mappings
*   ~/fminit/fmMacros		  - user macros
	
To add your own mappings or macros to the default ones, see the
"QUICK HINT" above.


Maker never looks for the Commands, XCommands, or Menus files in your
~/fminit directory.  However, for other customization files, Maker
first looks in ~/fminit, and then in $FMHOME/fminit.  Thus to
substitute any of your own files, put them in an fminit directory in
your home directory.  If Maker finds a file in your $HOME/fminit
directory, it will use it and not read the corresponding $FMHOME file
(except for the Commands files).

All of these file names can be set using X11 resources or
command-line options.  The names of the options are respectively:
	commands
	mathCommands
	xCommands
	displayCommands
	menus
	myCommands
	myMacros

The directory paths are always prepended to the name 
(e.g. XCommands is always looked for in fminit/<language>) 
unless it is a full path name, one starting with "/".

For examples, look in the $FMHOME/fminit/xresources/Maker
file.  Search for "commands".

**** DEFAULT displayCommands RESOURCE AND vendorKbSuffix LIST

To find a XCommands.VENDOR file for the server's keyboard-specific
XCommands entries, Maker will use the displayCommands resource if one
has been set.  Otherwise, it will try to create a default
displayCommands name.

Maker determines the default displayCommands name by looking at the X
server's "vendor string".  Maker has a list of <string,suffix> pairs.
If one of the strings in the list is in the vendor string from the
server, the default displayCommands name is "XCommands." followed by
the corresponding suffix.  If none of the strings are found in the
vendor string, the default displayCommands name is just "XCommands".


XXX: THIS PARAGRAPH IS WRONG in 4.0

To teach Maker about a new machine's vendor string, you'll need to
reset the vendorKbSuffix string, which contains the list of
<string,suffix> pairs.  The default string in this release is:
  Maker.vendorKbSuffix : Data Gen;dg;Apollo;apollo;IBM;ibm;Siemens;
	siemens;DECWIN;dec;Hewlett;hp;MIT;mitsun;Network C;ncd;
	X11/NeWS;sun;Sony;sony;CETIA;cetia
You can set this resource in the $FMHOME/fminit/xresources/Maker
file.  Make sure your new string is all on one line in the resource file
(delete the spaces shown above for clarity) and make sure you include 
at least all machines used at your site.

**** ISOLATIN-1 (non-Ascii character) KEYSYMS

Some non-English keyboards have non-English keycaps.  If the server
produces the corresponding non-English character keysyms for these
keys, Maker will interpret them correctly.  If the server does not,
you should fix your server's keysym map with xmodmap and xev (see
below, under "Keystrokes & Keysyms") OR you must make your own
Commands file to handle these different mappings.

Effort has been made to make Maker work with some vendors' standard
way of accessing non-Ascii characters, such as Sun's Compose-key
conventions and HP's conventions.

See below, under "Alternate Characters" for more ways of using a
keyboard to produce a full multi-language character set.

**** FORMAT OF Commands/fmMacros ENTRIES

Each entry in a Commands file or fmMacros file maps a trigger to an
expansion.  In the Commands file, the "trigger" is called a
KeySequence and in the expansion is called the "Definition".  In 
the fmMacros file, the "trigger" is called a Trigger and the expansion
is called a Definition

An example Command is:

	<Command Open
	   <Label Open...>
	   <KeySequence \!fo>
	   <Definition \x301>
	   <Mode All>>

An example Macro is:

	Macros saved on Sat Oct 10 16:22:46 1992
	Type "Hello there":
	   <Macro Macro1
	       <Label Macro1>
	       <Trigger /F21 >
	       <TriggerLabel /F21>
	       <Definition Hello\sthere>
	       <Mode NonMath>>

After typing the trigger keystroke or keystroke sequence, 
it is expanded into the expansion code or sequence.

The syntax for Commands and Macros is discussed more thoroughly in the
documentation.

A Commands file maps keystroke sequences to Maker function sequences.
The KeySequence is defined in the line which looks something like

	<KeySequence \!fo>

and the function-sequence is defined in the line which looks something
like

	<Definition \x301>

An fmMacros file maps keystroke sequences to keystroke sequences.
The Trigger is defined in the line which looks something like 

	<Trigger /F21>

and the keystroke sequence is defined in the line which looks
something like

	<Definition Hello\sthere>

The trigger key-sequence can have up to 5 values.

Expansion sequences can have up to 250 values inside Maker.
Note that character keystrokes are a single value to Maker,
but most other keys (function keys, arrows, etc) are two
values and a few non-standard keystrokes are three values.
Each Maker function is a single value.

In addition, macros are fully expanded into function codes
before they are executed and the limit is 300 values.

Also, the mode may be one of Math, NonMath, or All, meaning the
trigger is for math mode, non-math-mode (really anywhere outside
equations- in documents, in dialogs, books) or (all) in both modes.
Math mode is ONLY for typing in equations.

**** KEYSTROKES and KEYSYMS

Keystrokes are represented as X11 keysyms plus modifiers.
Keysyms are defined in the /usr/include/X11/keysymdef.h file.
Each has a name (or two) and a numerical value.

Maker knows the ascii names of the standard X11 keysyms
with values in the range 0xFF00 through 0xFFFF, so these
may be written as:
	/KeySym
such as
	/Return  /F1   /Cancel   /Left
The keysyms that Maker knows, and the names and values it does not
know are listed at the end of this file.

You can discover what keysyms your keyboard produces with either
the xev program, the xmodmap program or maker.

The xev program is the best one for this.  Run it from an xterm and
it will create a window on the designated server.  Put the mouse 
in the window and press keys and it print information about the
keypresses to the xterm, including the keysym value.  Try "xev -h".
(To quit, ^C in the xterm, or close using a window-mgr function.)

The xmodmap program will print out a listing of which keysyms
and modifiers are bound to which keys and it enables you to 
change these bindings.  Try "xmodmap -h" and "xmodmap -g" for
help.  Usually, "xmodmap" tells modifier bindings and "xmodmap -pk"
prints the keysyms.

Also, you can inspect keystrokes with Maker.  Begin recording
a macro (with ^]), type a character and then end the macro 
(again with ^]) so that the RecordMacroTrigger dialog appears.

Now type the keystroke and IF Maker receives it, it will display
a representation of it in the text box.  If Maker displays nothing,
perhaps it is a modifier key (like shift and control) or an 
"altPrefix" key (discussed below).  Hold down the key and press 
the "a" key.  If a character appears before the "a", the key was
a modifier key (see next section).  If something besides the "a" 
appears, the key is an "altPrefix" key.

When you create macros with Maker, it will output a readable form of
the macros to a file, ~/fminit/fmMacroLog.  (When you clear macros or
save them to a file, the fmMacroLog file is removed.)  So you can also
record keystrokes into a macro and inspect the fmMacroLog file.

**** MODIFIERS, SHIFT, CONTROL, META

A keystroke is a keysym PLUS zero or more modifiers.  In X11 there
are 7 possible modifiers:
	Shift Control Mod1 Mod2 Mod3 Mod4 Mod5
A Meta, or Alt key is usually Mod1.  To find out which modifiers 
are mapped to which keys on your system, run "xmodmap".

Modifiers are represented in a Commands or fmMacros file as 1 or 2 characters:
	Shift Control	  Mod1  Mod2 Mod3 Mod4 Mod5
	  +	^	~ or \1  \2   \3   \4   \5

The three common modifiers are Shift, Control and Meta.
Meta (or Alt) is usually Mod1 on a server.  For some this may
not be convenient.  So Maker allows it to be bound to another
modifier with the "meta" string resource:
	-meta x
Where x is one or more of:
	  +         ^     1    2    3    4    5
	 Shift   Control Mod1 Mod2 Mod3 Mod4 Mod4

For example
    -meta 4   -- sets meta to mean Mod4
or  -meta ^1  -- sets meta to mean both control and mod1 so
		< ~f : \x108 > would map control+mod1+f to GoToEndOfWord

Or in a resource file:
	maker.meta:		4
or	maker.meta:		^1

**** THE commandPrefix CHARACTER

There is a special "keystroke" in a Commands file denoted by the
2-character symbol "\!".  Maker thinks of this as the "commandPrefix"
keystroke.  The user may set any number of keystrokes to be translated
to the commandPrefix keystroke by setting the commandPrefix resource
when maker starts.  The value of this resource is a string of
keystroke values in the standard kbmap format for keystrokes
(described below), for example:
   -commandKeyPrefix "/Escape ^/F1"
tells Maker that whenever it gets an unmodified Escape or a control-F1
keystroke, it should translate it to the command prefix.

As a resource file entry, this would look like:
   maker.commandPrefix:		"/Escape ^/F1"
This will make these keystroke identical EVERYWHERE in Maker, 
not just as the first character in a command sequence.

**** REPRESENTATION OF KEYSTROKES, FUNCTION CODES and SEQUENCES

REPRESENTATION OF VALUES

Their are three ways to represent keysym values, as a slash followed
by the keysym name, as a single ASCII character, as a hexadecimal
value preceded by "\x", and as a character for the keysyms that
correspond to the ASCII characters in the range 0x21 through 0x7F
except for the following characters, which must be preceded by a
backslash:
	<  >	Used as mapping delimiters
	+ ^ ~	Used as modifiers
	  /	Slash is used to begin a keysym name.  It must end
		   with a non-printing character (e.g. space, tab)
		   or a mapping delimiter.
	  \	To enter Backslash in a mapping, type "\\"
		Any nonprinting characters ASCII value less than 
		   0x21 (incl space, tab, newline, linefeed)
		   and delete (value 0xff) are ignored, unless
		   preceded by a backslash.

In addition, preceding the following characters with a backslash
results in a special meaning:
     \1 \2 \3	Also used as modifers, though not in the 
	\4 \5	   standard kbmaps released by Frame.
	\!	The command prefix keystroke, as discussed above.   
	\s	The space character (\x20)
	\xHHH	A hexidecimal value HHH, as used in the ASCII
		   table below and in the keysymdef.h file.
		   It must end with a non-printing character or a
		   mapping delimiter.
	\c	All other characters, besides "12345!sx" represent
		   themselves when preceded by a backslash,
		   especially useful for "<:>+^~/\" as described above.

Examples of keystroke representations in a Commands file:

    shifts_&_KeySym___Meaning________________
		a	the plain "a"
		A	the shifted "a" key
		1	the unshifted 1 key (english keyboard)
		!	the shifted 1 key (english keyboard)
	       F1	the plain F1 key	
	      +F1	the F1 key with Shift pressed
	      ^~A	the a key with Shift, Control & Meta keys down
	     ~^F1	the F1 key with Control and Meta pressed
	   +\x4a6	the XK_kana_WO key with Shift pressed
      ~\x1000ff6f	meta and a HP's vendor-specific ClearLine key

**** MAKER FUNCTIONS

These same rules apply to Maker functions, except that you can NOT use
the /Name format in the function-sequence (i.e. the Definition) of a
Command mapping.

A list of the Maker function codes and commands names is in 
        $FMHOME/fminit/usenglish/Commands
        $FMHOME/fminit/usenglish/MathCommands
and     $FMHOME/fminit/usenglish/XCommands

Within the function-sequence, functions are individual values.  Values
below 0xFF are character values that are inserted into the document
(use hex values below 0x20 with care!).  See the Maker Reference
Manual, Appendix B, for a listing of the Maker character set.

**** HOW MAKER USES SHIFT, SHIFTLOCK, CAPSLOCK, lockTogglesShift

For greater portability and ease of use, Maker often drops the Shift
modifier from recorded keystrokes.  When a key is shifted, if a key
has different meanings when shifted and unshifted, Maker keeps the
shifted meaning and forgets that Shift was pressed.

Thus to Maker, the "1/!" key generates the "1" and "!" keystrokes,
rather than the "1" and "Shift-!" keystrokes.  This makes the French
Commands file, for example, almost identical to the English one, even
though on a French keyboard, the unshifted value of the key is "!" and
the shifted value is "1".

The Lock modifier is used by Maker to determine the keysym, but is 
not recorded as part of a keystroke.  

When Maker hears a keystroke, if the modifier(s) (besides Shift) are
the same as the modifier(s) that a lock keysym is bound to, one of 
Shift_Lock, Caps_Lock or Num_Lock, Maker processes the keystroke for 
that type of locking and clears the lock bits that are set.
If the modifier(s) don't match those of a lock keysym, all of the
modifiers belonging to Lock keys are cleared.

Caps_Lock effects keys which have lowercase and uppercase values.
Shift_Lock effects keys Caps_Lock would effect, as well as any key
where the shifted keysym (exists and) differs from the plain keysym.

If the Lock modifier gives the Shift meaning of a key, by default
pressing Shift as well has no effect.  But if you set the resource:
	Maker.lockTogglesShift : True
Then when Lock gives the uppercase meaning, Shift+Lock will give the
unshifted meaning, allowing you to type with Lock on and still easily
reach unshifted characters.

Num_Lock will effect any key that has a KP_ (keypad) keysym.

**** ALTERNATE CHARACTERS : alt

If you run "xmodmap -pk" you'll see that each key has one or two
keysym meanings, an unshifted one and optionally a shifted one.

Some servers define up to four meanings.  The third and fourth
meanings are for "alternate" characters, needed ISOLatin1 characters 
for which there is not room on the keyboard.  Commonly these are
shown as a 3rd character written onto a keyboard.  Some keyboards
have an "Alt Graph" key that generates a modifier to signal to the
application that it should use one of these alternative keysyms.

(try %xmodmap -e "keysym a = a A adiaeresis Adiaeresis" and then
     %xmodmap -pk
 and you'll see these two accented keysyms in your keyboard map.)

By default, Maker assumes Mod2 is your alt modifier.
If you press a Mod2 modifier key plus another key (shifted or not), 
Maker will use the alternate keysym if there is one.

This can be changed to another modifier by using the resource:
	-alt x
Where x is one or more of:
	  +         ^     1    2    3    4    5
	 Shift   Control Mod1 Mod2 Mod3 Mod4 Mod4
See the description of -meta above for more details.

(The "altPrefix" feature of previous X11 Maker versions has
 been removed.)

**** IN TEXT BOXES IN DIALOGS

In 4.0 X Maker, these all now work in text boxes in dialogs as
well as in a Maker document.

XXX: Take this out?
In addition, almost all character-expansion macros (and Commands file
entries) will work in dialog text boxes, not just ones starting with
^r, ~x and ^q, as in the previous release.

Note, however, that $FMHOME/fminit/xresources/XmText entries
will take precedence in dialog text boxes- there is no way to 
override them.

**** X11 KEYSYMS

The following keys are known by name.  They will appear in Commands
and macros preceded by a slash "/" and followed by a space.

    Alt_L      Alt_R
    Backspace  Begin       Break
    Cancel     Caps_Lock   Clear  Control_L      Control_R
    Delete     Down
    End        Escape    Execute
    F1   F2   F3   F4   F5   F6   F7  F8   F9   F10
    F11  F12  F13  F14  F15  F16  F17  F18  F19  F20
    F21  F22  F23  F24  F25  F26  F27  F28  F29  F30
    F31  F32  F33  F34  F35
    Find
    Help  Home  Hyper_L     Hyper_R
    Insert
    KP_0  KP_1  KP_2  KP_3  KP_4  KP_5  KP_6  KP_7  KP_8  KP_9
    KP_Add      KP_Decimal  KP_Divide   KP_Enter    KP_Equal
    KP_F1       KP_F2       KP_F3       KP_F4	KP_Multiply
    KP_Separator            KP_Space    KP_Subtract  KP_Tab
    Kanji
    L1  L2  L3  L4  L5  L6  L7  L8  L9  L10
    Left    Linefeed
    Menu    Meta_L  Meta_R  Mode_switch Multi_key
    Next    Num_Lock
    Pause   Print   Prior
    R1  R2  R3  R4  R5  R6  R7  R8  R9  R10
    R11 R12 R13 R14 R15
    Redo    Return  Right
    Select          script_switch
    Shift_L Shift_R Shift_Lock
    Super_L Super_R
    Tab
    Undo    Up

Note that a few of the following characters are not in the Maker
character set, though the X server might generate their keysyms.

\xa0 nobreakspace        \xd0 Eth
\xa1 exclamdown          \xd1 Ntilde
\xa2 cent                \xd2 Ograve
\xa3 sterling            \xd3 Oacute
\xa4 currency            \xd4 Ocircumflex
\xa5 yen                 \xd5 Otilde
\xa6 brokenbar           \xd6 Odiaeresis
\xa7 section             \xd7 multiply
\xa8 diaeresis           \xd8 Ooblique
\xa9 copyright           \xd9 Ugrave
\xaa ordfeminine         \xda Uacute
\xab guillemotleft       \xdb Ucircumflex
\xac notsign             \xdc Udiaeresis
\xad hyphen              \xdd Yacute
\xae registered          \xde Thorn
\xaf macron              \xdf ssharp
\xb0 degree              \xe0 agrave
\xb1 plusminus           \xe1 aacute
\xb2 twosuperior         \xe2 acircumflex
\xb3 threesuperior       \xe3 atilde
\xb4 acute               \xe4 adiaeresis
\xb5 mu                  \xe5 aring
\xb6 paragraph           \xe6 ae
\xb7 periodcentered      \xe7 ccedilla
\xb8 cedilla             \xe8 egrave
\xb9 onesuperior         \xe9 eacute
\xba masculine           \xea ecircumflex
\xbb guillemotright      \xeb ediaeresis
\xbc onequarter          \xec igrave
\xbd onehalf             \xed iacute
\xbe threequarters       \xee icircumflex
\xbf questiondown        \xef idiaeresis
\xc0 Agrave              \xf0 eth
\xc1 Aacute              \xf1 ntilde
\xc2 Acircumflex         \xf2 ograve
\xc3 Atilde              \xf3 oacute
\xc4 Adiaeresis          \xf4 ocircumflex
\xc5 Aring               \xf5 otilde
\xc6 AE                  \xf6 odiaeresis
\xc7 Ccedilla            \xf7 division
\xc8 Egrave              \xf8 oslash
\xc9 Eacute              \xf9 ugrave
\xca Ecircumflex         \xfa uacute
\xcb Ediaeresis          \xfb ucircumflex
\xcc Igrave              \xfc udiaeresis
\xcd Iacute              \xfd yacute
\xce Icircumflex         \xfe thorn
\xcf Idiaeresis          \xff ydiaeresis

In addition, Maker knows
    START_DIALOG    END_DIALOG
These appear in a macro whenever the macro opens or closes a dialog.
If when playing a macro, one of these is read from the macro when a
dialog does not open or close, or if a dialog appears or closes 
and the appropriate one is not read from the macro, maker aborts
the macro and issues an "out of sync" warning message.
