+++ /dev/null
-.ig
-//=============================================================================
-//
-// Manual page for `dumpkeymap'.
-//
-// Copyright (C) 1999,2000 by Eric Sunshine <sunshine@sunshineco.com>
-// All rights reserved.
-//
-// Redistribution and use in source and binary forms, with or without
-// modification, are permitted provided that the following conditions are met:
-//
-// 1. Redistributions of source code must retain the above copyright
-// notice, this list of conditions and the following disclaimer.
-// 2. Redistributions in binary form must reproduce the above copyright
-// notice, this list of conditions and the following disclaimer in the
-// documentation and/or other materials provided with the distribution.
-// 3. The name of the author may not be used to endorse or promote products
-// derived from this software without specific prior written permission.
-//
-// THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
-// WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-// MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
-// EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
-// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
-// OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
-// WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
-// OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
-// ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-//
-//=============================================================================
-//
-// $XFree86: xc/programs/Xserver/hw/darwin/utils/dumpkeymap.man,v 1.2 2000/12/05 21:18:34 dawes Exp $
-//
-..
-.ig
-//-----------------------------------------------------------------------------
-// Local identification information.
-//-----------------------------------------------------------------------------
-..
-.nr VE 4 \" Version number
-.TH DUMPKEYMAP 1 "v\n(VE \-\- 1 December 2000" "Version \n(VE"
-.de UP
-1 December 2000
-..
-.ig
-//-----------------------------------------------------------------------------
-// Annotation Macros
-// -----------------
-// Facilitate creation of annotated, non-filled blocks of text. An
-// annotated block is initiated with the `AS' macro. Each annotated,
-// non-filled line within the block must be introduced with the `AN' macro
-// which takes three arguments. The first argument is the detail text to
-// be annotated. The second is a string of spaces used to align the
-// annotations by certain (broken) roff interpreters which fail to
-// implement the proper set of roff commands (such as diversions,
-// indentation, and tab stops). It is assumed that the spaces will be
-// used with fixed-point font. The third argument is the annotation
-// itself. The block should be terminated with the `AE' macro. For all
-// roff interpreters which properly implement diversions, indentation, and
-// tab stops, all anotations within the block are automatically aligned at
-// the same horizontal position. This position is guaranteed to be just
-// to the right of the widest `AN' detail line. For broken roff
-// interpreters, such as `rman', the string of spaces from the second
-// argument are used to align the annotations. Finally, the `AZ' macro,
-// which takes a single argument, can be used to to insert a non-annotated
-// line into the block which does not play a part in the calculation of
-// the horizontal annotation alignment.
-//
-// Implementation Notes
-// --------------------
-// *1* These macros utilize a diversion (named `AD'). Since the prevailing
-// indentation is stored along with the diverted text, we must muck with
-// the indentation level in order to prevent the indentation from being
-// applied to the text a second time when `AD' is finally emitted.
-//
-// *2* Unfortunately, `.if' strips leading whitespace from following text, so
-// `AN' uses \& to preserve the whitespace.
-//
-// *3* This manual page has been tested for proper formatting with troff,
-// groff, nroff and rman (the `man' to `HTML' converter). Unfortunately,
-// rman fails to implement many useful features such as diversions,
-// indentation, and tab stops, and is also hideously buggy. Furthermore
-// it identifies itself as nroff and fails to provide any further
-// identification, so there is no way to create macros which specifically
-// work around its limitations. Following is a list of several bugs in
-// rman which the implementation of these macros must avoid:
-// o Fails with multi-line conditionals within macros.
-// o Fails on macro definition within multi-line conditionals.
-// o Fails when macro arguments are not delimited by exactly 1 space.
-// o String definition `.ds' ignores the value; uses empty "" instead.
-// As a consequence of these problems, the following macros are written
-// using a series of ugly single-line `.if' conditionals rather than the
-// more natural multi-line `.if' and `.ie' conditionals. Also, rman fails
-// to understand the common idiom of `.\"' to introduce a comment, which
-// is why all comments in this file are wrapped in ignore `.ig' blocks.
-//-----------------------------------------------------------------------------
-..
-.de AS
-.if t .nr AW 0
-.if t .nr AI \\n(.i
-.if t .in -\\n(AI
-.nf
-..
-.de AN
-.if t .if \w'\\$1'>\\n(AW .nr AW \w'\\$1'
-.if t .da AD
-.if t \\&\\$1\\t\\$3
-.if t .da
-.if n \\&\\$1 \\$2\\$3
-..
-.de AZ
-.if t .da AD
-\\$1
-.if t .da
-..
-.de AE
-.if t .in +\\n(AIu
-.if t .if \\n(AW .ta \\n(AWu+\w'\\(em'u
-.if t .AD
-.if t .DT
-.if t .rm AD
-.if t .rm AW
-.fi
-..
-.ig
-//-----------------------------------------------------------------------------
-// Bulleted list macros -- `BG' begins a bulleted list; `BU' delimits
-// bulleted entries; `BE' ends a bulleted list.
-//-----------------------------------------------------------------------------
-..
-.de BG
-.PP
-.RS
-..
-.de BU
-.HP
-\\(bu\\ \\c
-..
-.de BE
-.RE
-.PP
-..
-.ig
-//-----------------------------------------------------------------------------
-// Indented paragraph with stylized hanging tag macro. `TG' takes a single
-// argument and treats it as the hanging tag of the indented paragraph.
-// The tag is italicized in troff but not in nroff.
-//-----------------------------------------------------------------------------
-..
-.de TG
-.TP
-.ie t .I "\\$1"
-.el \\$1
-..
-.ig
-//-----------------------------------------------------------------------------
-// Manual page for `dumpkeymap'.
-//-----------------------------------------------------------------------------
-..
-.SH NAME
-dumpkeymap \- Dianostic dump of a .keymapping file
-.SH SYNOPSIS
-.B dumpkeymap
-.RI [ options "] [-] [" file "...]"
-.SH DESCRIPTION
-.I dumpkeymap
-prints a textual representation of each Apple/\c
-.SM NeXT
-.I .keymapping
-file mentioned on the command-line. If no files are mentioned and if the
-local machine is an Apple or
-.SM NeXT
-installation, then the key mapping currently in use by the WindowServer and the
-AppKit is printed instead.
-.SH OPTIONS
-.TP
-.B "\-h \-\^\-help"
-Display general program instructions and option summary.
-.TP
-.B "\-k \-\^\-help\-keymapping"
-Display a detailed description of the internal layout of a
-.I .keymapping
-file. This is the same information as that presented in the
-.I "Key Mapping Description"
-section of this document.
-.TP
-.B "\-o \-\^\-help\-output"
-Display an explanation of the output generated by
-.I dumpkeymap
-when dissecting a
-.I .keymapping
-file. This is the same information as that presented in the
-.I "Output Description"
-section of this document.
-.TP
-.B "\-f \-\^\-help\-files"
-Display a summary of the various files and directories which are related to
-key mappings. This is the same information as that presented in the
-.I "Files"
-section of this document.
-.TP
-.B "\-d \-\^\-help\-diagnostics"
-Display a list of the various diagnostic messages which may be emitted by
-.I dumpkeymap.
-This is the same information as that presented in the
-.I "Diagnostics"
-section of this document.
-.TP
-.B "\-v \-\^\-version"
-Display the
-.I dumpkeymap
-version number and warranty information.
-.TP
-.B "\- \-\^\-"
-Inhibit processing of options at this point in the argument list. An
-occurrence of `\-' or `\-\^\-' in the argument list causes all following
-arguments to be treated as file names even if an argument begins with a `\-'
-character.
-.SH "KEY MAPPING DESCRIPTION"
-The following sections describe, in complete detail, the format of a raw key
-mapping resource, as well as the format of the
-.I .keymapping
-file which encapsulates one or more raw mappings.
-.SH "Types and Data"
-The following type definitions are employed throughout this discussion:
-.PP
-.RS
-.AS
-.AZ "typedef unsigned char byte;"
-.AZ "typedef unsigned short word;"
-.AZ "typedef unsigned long dword;"
-.AE
-.RE
-.PP
-Additionally, the type definition
-.RI ` number '
-is used generically to
-indicate a numeric value. The actual size of the
-.RI ` number '
-type may be one or two bytes depending upon how the data is stored in the key
-map. Although most key maps use byte-sized numeric values, word-sized values
-are also allowed.
-.PP
-Multi-byte values in a key mapping file are stored in big-endian byte order.
-.SH "Key Mapping File and Device Mapping"
-A key mapping file begins with a magic-number and continues with a
-variable number of device-specific key mappings.
-.PP
-.RS
-.AS
-.AZ "struct KeyMappingFile {"
-.AN " char magic_number[4];" " " "// `KYM1'"
-.AN " DeviceMapping maps[...];" "" "// Variable number of maps"
-.AZ };
-.AE
-.PP
-.AS
-.AZ "struct DeviceMapping {"
-.AN " dword interface;" " " "// Interface type"
-.AN " dword handler_id;" "" "// Interface subtype"
-.AN " dword map_size;" " " "// Byte count of `map' (below)"
-.AN " KeyMapping map;"
-.AZ };
-.AE
-.RE
-.PP
-The value of `interface' represents a family of keyboard device types
-(such as Intel
-.SM "PC, ADB, NeXT,"
-Sun Type5, etc.), and is generally specified as one of the constant values
-.SM "NX_EVS_DEVICE_INTERFACE_ADB, NX_EVS_DEVICE_INTERFACE_ACE,"
-etc., which are are defined in IOHIDTypes.h on MacOS/X and Darwin, and in
-ev_types.h on MacOS/X Server, OpenStep, and NextStep.
-.PP
-The value of `handler_id' represents a specific keyboard layout within the
-much broader `interface' family. For instance, for a 101-key Intel
-.SM PC
-keyboard (of type
-.SM NX_EVS_DEVICE_INTERFACE_ACE\c
-) the `handler_id' is '0', whereas for a 102-key keyboard it is `1'.
-.PP
-Together, `interface' and `handler_id' identify the exact keyboard hardware to
-which this mapping applies. Programs which display a visual representation of
-a keyboard layout, match `interface' and `handler_id' from the
-.I .keymapping
-file against the `interface' and `handler_id' values found in each
-.I .keyboard
-file.
-.SH "Key Mapping"
-A key mapping completely defines the relationship of all scan codes with their
-associated functionality. A
-.I KeyMapping
-structure is embedded within the
-.I DeviceMapping
-structure in a
-.IR KeyMappingFile .
-The key mapping currently in use by the WindowServer and AppKit is also
-represented by a
-.I KeyMapping
-structure, and can be referred to directly by calling NXGetKeyMapping() and
-accessing the `mapping' data member of the returned
-.I NXKeyMapping
-structure.
-.PP
-.RS
-.AS
-.AZ "struct KeyMapping {"
-.AN " word number_size;" " " "// 0=1 byte, non-zero=2 bytes"
-.AN " number num_modifier_groups;" "" "// Modifier groups"
-.AZ " ModifierGroup modifier_groups[...];"
-.AN " number num_scan_codes;" " " "// Scan groups"
-.AN " ScanGroup scan_table[...];"
-.AN " number num_sequence_lists;" " " "// Sequence lists"
-.AN " Sequence sequence_lists[...];"
-.AN " number num_special_keys;" " " "// Special keys"
-.AN " SpecialKey special_key[...];"
-.AZ };
-.AE
-.RE
-.PP
-The `number_size' flag determines the size, in bytes, of all remaining numeric
-values (denoted by the type definition
-.RI ` number ')
-within the
-key mapping. If its value is zero, then numbers are represented by a single
-byte. If it is non-zero, then numbers are represented by a word (two bytes).
-.SH "Modifier Group"
-A modifier group defines all scan codes which map to a particular type of
-modifier, such as
-.IR shift ,
-.IR control ,
-etc.
-.PP
-.RS
-.AS
-.AZ "enum Modifier {"
-.AZ " ALPHALOCK = 0,"
-.AZ " SHIFT,"
-.AZ " CONTROL,"
-.AZ " ALTERNATE,"
-.AZ " COMMAND,"
-.AZ " KEYPAD,"
-.AZ " HELP"
-.AZ };
-.AE
-.PP
-.AS
-.AZ "struct ModifierGroup {"
-.AN " number modifier;" " " "// A Modifier constant"
-.AN " number num_scan_codes;"
-.AN " number scan_codes[...];" "" "// Variable number of scan codes"
-.AZ };
-.AE
-.RE
-.PP
-The scan_codes[] array contains a list of all scan codes which map to the
-specified modifier. The
-.IR shift ", " command ", and " alternate
-modifiers are frequently mapped to two different scan codes, apiece,
-since these modifiers often appear on both the left and right sides of
-the keyboard.
-.SH "Scan Group"
-There is one
-.I ScanGroup
-for each scan code generated by the given keyboard. This number is given by
-KeyMapping::num_scan_codes. The first scan group represents hardware scan
-code 0, the second represents scan code 1, etc.
-.PP
-.RS
-.AS
-.AZ "enum ModifierMask {"
-.AN " ALPHALOCK_MASK" " " "= 1 << 0,"
-.AN " SHIFT_MASK" " " "= 1 << 1,"
-.AN " CONTROL_MASK" " " "= 1 << 2,"
-.AN " ALTERNATE_MASK" " " "= 1 << 3,"
-.AN " CARRIAGE_RETURN_MASK" "" "= 1 << 4"
-.AZ };
-.AZ "#define NOT_BOUND 0xff"
-.AE
-.PP
-.AS
-.AZ "struct ScanGroup {"
-.AN " number mask;"
-.AN " Character characters[...];"
-.AZ };
-.AE
-.RE
-.PP
-For each scan code, `mask' defines which modifier combinations generate
-characters. If `mask' is
-.SM NOT_BOUND
-(0xff) then then this scan code does not generate any characters ever, and its
-characters[] array is zero length. Otherwise, the characters[] array contains
-one
-.I Character
-record for each modifier combination.
-.PP
-The number of records in characters[] is determined by computing (1 <<
-bits_set_in_mask). In other words, if mask is zero, then zero bits are set,
-so characters[] contains only one record. If `mask' is
-.SM "(SHIFT_MASK | CONTROL_MASK),"
-then two bits are set, so characters[] contains four records.
-.PP
-The first record always represents the character which is generated by that
-key when no modifiers are active. The remaining records represent characters
-generated by the various modifier combinations. Using the example with the
-.I shift
-and
-.I control
-masks set, record two would represent the character with the
-.I shift
-modifier active; record three, the
-.I control
-modifier active; and record four, both the
-.I shift
-and
-.I control
-modifiers active.
-.PP
-As a special case,
-.SM ALPHALOCK_MASK
-implies
-.SM SHIFT_MASK,
-though only
-.SM ALPHALOCK_MASK
-appears in `mask'. In this case the same character is generated for both the
-.I shift
-and
-.I alpha-lock
-modifiers, but only needs to appear once in the characters[] array.
-.PP
-.SM CARRIAGE_RETURN_MASK
-does not actually refer to a modifier key. Instead, it is used to
-distinguish the scan code which is given the special pseudo-designation of
-.I "carriage return"
-key. Typically, this mask appears solo in a
-.I ScanGroup
-record and only the two
-.I Character
-records for control-M and control-C follow. This flag may be a throwback to
-an earlier time or may be specially interpreted by the low-level keyboard
-driver, but its purpose is otherwise enigmatic.
-.SH Character
-Each
-.I Character
-record indicates the character generated when this key is pressed, as well as
-the character set which contains the character. Well known character sets are
-.SM `ASCII'
-and `Symbol'. The character set can also be one of the meta values
-.SM FUNCTION_KEY
-or
-.SM KEY_SEQUENCE.
-If it is
-.SM FUNCTION_KEY
-then `char_code' represents a generally well-known function key such as those
-enumerated by
-.I FunctionKey.
-If the character set is
-.SM KEY_SEQUENCE
-then `char_code' represents is a zero-base index into
-KeyMapping::sequence_lists[].
-.PP
-.RS
-.AS
-.AZ "enum CharacterSet {"
-.AN " ASCII" " " "= 0x00,"
-.AN " SYMBOL" " " "= 0x01,"
-.AN " ..."
-.AN " FUNCTION_KEY" "" "= 0xfe,"
-.AN " KEY_SEQUENCE" "" "= 0xff"
-.AZ };
-.AE
-.PP
-.AS
-.AZ "struct Character {"
-.AN " number set;" " " "// CharacterSet of generated character"
-.AN " number char_code;" "" "// Actual character generated"
-.AZ };
-.AE
-.PP
-.AS
-.AZ "enum FunctionKey {"
-.AZ " F1 = 0x20, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12,"
-.AZ " INSERT, DELETE, HOME, END, PAGE_UP, PAGE_DOWN, PRINT_SCREEN,"
-.AZ " SCROLL_LOCK, PAUSE, SYS_REQUEST, BREAK, RESET, STOP, MENU,"
-.AZ " USER, SYSTEM, PRINT, CLEAR_LINE, CLEAR_DISPLAY, INSERT_LINE,"
-.AZ " DELETE_LINE, INSERT_CHAR, DELETE_CHAR, PREV, NEXT, SELECT"
-.AZ };
-.AE
-.RE
-.SH Sequence
-When Character::set contains the meta value
-.SM KEY_SEQUENCE,
-the scan code is bound to a sequence of keys rather than a single character.
-A sequence is a series of modifiers and characters which are automatically
-generated when the associated key is depressed.
-.PP
-.RS
-.AS
-.AZ "#define MODIFIER_KEY 0xff"
-.AE
-.PP
-.AS
-.AZ "struct Sequence {"
-.AN " number num_chars;"
-.AN " Character characters[...];"
-.AZ };
-.AE
-.RE
-.PP
-Each generated
-.I Character
-is represented as previously described, with the exception that
-.SM MODIFIER_KEY
-may appear in place of
-.SM KEY_SEQUENCE.
-When the value of Character::set is
-.SM MODIFIER_KEY
-then Character::char_code represents a modifier key rather than an actual
-character. If the modifier represented by `char_code' is non-zero, then it
-indicates that the associated modifier key has been depressed. In this case,
-the value is one of the constants enumerated by
-.I Modifier
-(\c
-.SM "SHIFT, CONTROL, ALTERNATE,"
-etc.). If the value is zero then it means that the modifier keys have been
-released.
-.SH "Special Key"
-A special key is one which is scanned directly by the Mach kernel rather than
-by the WindowServer. In general, events are not generated for special keys.
-.PP
-.RS
-.AS
-.AZ "enum SpecialKeyType {"
-.AZ " VOLUME_UP = 0,"
-.AZ " VOLUME_DOWN,"
-.AZ " BRIGHTNESS_UP,"
-.AZ " BRIGHTNESS_DOWN,"
-.AZ " ALPHA_LOCK,"
-.AZ " HELP,"
-.AZ " POWER,"
-.AZ " SECONDARY_ARROW_UP,"
-.AZ " SECONDARY_ARROW_DOWN"
-.AZ };
-.AE
-.PP
-.AS
-.AZ "struct SpecialKey {"
-.AN " number type;" " " "// A SpecialKeyType constant"
-.AN " number scan_code;" "" "// Actual scan code"
-.AZ };
-.AE
-.RE
-.SH OUTPUT
-What follows is an explanation and description of the various pieces of
-information emitted by
-.I dumpkeymap.
-.PP
-For a more thorough discussion of any particular piece of information described
-here, refer to the detailed description of the internal layout of a key mapping
-provided by the
-.I "Key Mapping Description"
-section above.
-.SH Conventions
-Depending upon context, some numeric values are displayed in decimal
-notation, whereas others are displayed in hexadecimal notation.
-Hexadecimal numbers are denoted by a `0x' prefix (for instance, `0x7b'),
-except when explicitly noted otherwise.
-.SH "Key Mapping Source"
-The first piece of information presented about a particular key mapping is the
-source from which the data was gleaned. For a
-.I .keymapping
-file, the title
-.SM "`KEYMAP FILE'"
-is emitted along with the path and name of the file in question. For the key
-mapping currently in use by the WindowServer and AppKit, the title
-.SM "`ACTIVE KEYMAP'"
-is emitted instead.
-.SH "Device Information"
-Each
-.I .keymapping
-file may contain one or more raw key mappings. For example, a file which maps
-keys to a Dvorak-style layout might contain raw mappings for Intel
-.SM "PC, ADB, NeXT,"
-and Sun Type5 keyboards.
-.PP
-For each raw mapping, the following information is emitted:
-.BG
-.BU
-The title
-.SM `KEYMAP'
-along with the mapping's relative position in the
-.I .keymapping
-file.
-.BU
-The `interface' identifier.
-.BU
-The `handler_id' sub-identifier.
-.BU
-The size of the raw mapping resource counted in bytes.
-.BE
-The `interface' and `handler_id' values, taken together, define a specific
-keyboard device. A
-.I .keyboard
-file, which describes the visual layout of a keyboard, also contains
-`interface' and `handler_id' identifiers. The
-.I .keyboard
-file corresponding to a particular key mapping can be found by matching the
-`interface' and `handler_id' values from each resource.
-.SH Modifiers
-Each mapping may contain zero or more modifier records which associate hardware
-scan codes with modifier descriptions such as
-.I "shift, control, alternate,"
-etc. The title
-.SM `MODIFIERS'
-is printed along with the count of modifier records which follow. For each
-modifier record, the modifier's name is printed along with a list of scan
-codes, in hexadecimal format, which generate that modifier value. For example:
-.PP
-.RS
-.nf
-MODIFIERS [4]
-alternate: 0x1d 0x60
-control: 0x3a
-keypad: 0x52 0x53 ... 0x63 0x62
-shift: 0x2a 0x36
-.fi
-.RE
-.SH Characters
-Each mapping may contain zero or more character records which associate
-hardware scan codes with the actual characters generated by those scan
-codes in the presence or absence of various modifier combinations. The
-title
-.SM `CHARACTERS'
-is printed along with the count of character records which follow. Here is a
-highly abbreviated example:
-.PP
-.RS
-.nf
-CHARACTERS [9]
-scan 0x00: -AC-L "a" "A" "^A" "^A" ca c7 "^A" "^A"
-scan 0x07: -AC-L "x" "X" "^X" "^X" 01/b4 01/ce "^X" "^X"
-scan 0x0a: ---S- "<" ">"
-scan 0x13: -ACS- "2" "@" "^@" "^@" b2 b3 "^@" "^@"
-scan 0x24: R---- "^M" "^C"
-scan 0x3e: ----- [F4]
-scan 0x4a: ----- [page up]
-scan 0x60: ----- {seq#3}
-scan 0x68: not-bound
-.fi
-.RE
-.PP
-For each record, the hexadecimal value of the hardware scan code is printed,
-followed by a list of modifier flag combinations and the actual characters
-generated by this scan code with and without modifiers applied.
-.PP
-The modifier flags field is composed of a combination of single letter
-representations of the various modifier types. The letters stand for:
-.PP
-.RS
-.nf
-L \- alpha-lock
-S \- shift
-C \- control
-A \- alternate
-R \- carriage-return
-.fi
-.RE
-.PP
-As a special case, the
-.I alpha-lock
-flag also implies the
-.I shift
-flag, so these two flags never appear together in the same record.
-.PP
-The combination of modifier flags determines the meaning and number of fields
-which follow. The first field after the modifier flags always represents the
-character that will be generated if no modifier keys are depressed. The
-remaining fields represent characters generated by the various modifier
-combinations. The order of the fields follows this general pattern:
-.BG
-.BU
-The character generated by this scan code when no modifiers are in effect is
-listed first.
-.BU
-If the `L' or `S' flag is active, then the shifted character generated by this
-scan code is listed next.
-.BU
-If the `C' flag is active, then the control-character generated by this scan
-code is listed next. Furthermore, if the `L' or `S' flag is also active, then
-the shifted control-character is listed after that.
-.BU
-If the `A' flag is active, then the alternate-character generated by this scan
-code is listed next. Furthermore, if the `L' or `S' flag is active, then the
-shifted alternate-character is listed after that. If the `C' flag is also
-active, then the alternate-control-character is listed next. Finally, if the
-`C' and `L' or `C' and `S' flags are also active, then the shifted
-alternate-control-character is listed.
-.BE
-The `R' flag does not actually refer to a modifier key. Instead, it is used to
-distinguish the scan code which is given the special pseudo-designation of
-.I "carriage return"
-key. Typically, this mask appears solo and only the two fields for control-M
-and control-C follow. This flag may be a throwback to an earlier time or may
-be specially interpreted by the low-level keyboard driver, but its purpose is
-otherwise enigmatic.
-.PP
-Recalling the example from above, the following fields can be identified:
-.PP
-.RS
-.nf
-scan 0x00: -AC-L "a" "A" "^A" "^A" ca c7 "^A" "^A"
-.fi
-.RE
-.BG
-.BU
-Lower-case `a' is generated when no modifiers are active.
-.BU
-Upper-case `A' is generated when
-.IR shift " or " alpha-lock
-are active.
-.BU
-Control-A is generated when
-.I control
-is active.
-.BU
-Control-A is generated when
-.IR control " and " shift
-are active.
-.BU
-The character represented by the hexadecimal code 0xca is generated when
-.I alternate
-is active.
-.BU
-The character represented by 0xc7 is generated when
-.IR alternate " and " shift " (or " alpha-lock ") are active."
-.BU
-Control-A is generated when
-.IR alternate " and " control
-are active.
-.BU
-Control-A is generated when
-.IR "alternate, control" " and " shift " (or " alpha-lock ") are active."
-.BE
-The notation used to represent a particular generated character varies.
-.BG
-.BU
-Printable
-.SM ASCII
-characters are quoted, as in "x" or "X".
-.BU
-Control-characters are quoted and prefixed with `^', as in "^X".
-.BU
-Characters with values greater than 127 (0x7f) are displayed as hexadecimal
-values without the `0x' prefix.
-.BU
-Characters in a non-\c
-.SM ASCII
-character set (such as `Symbol') are displayed as two hexadecimal numbers
-separated by a slash, as in `01/4a'. The first number is the character set's
-identification code (such as `01' for the `Symbol' set), and the second number
-is the value of the generated character.
-.BU
-Non-printing special function characters are displayed with the function's
-common name enclosed in brackets, as in `[page up]' or `[F4]'.
-.BU
-If the binding represents a key sequence rather than a single character, then
-the sequence's identification number is enclosed in braces, as in `{seq#3}'.
-.BE
-Recalling a few examples from above, the following interpretations can be made:
-.PP
-.RS
-.nf
-scan 0x07: -AC-L "x" "X" "^X" "^X" 01/b4 01/ce "^X" "^X"
-scan 0x3e: ----- [F4]
-scan 0x4a: ----- [page up]
-scan 0x60: ----- {seq#3}
-.fi
-.RE
-.BG
-.BU
-"x" and "X" are printable
-.SM ASCII
-characters.
-.BU
-"^X" is a control-character.
-.BU
-`01/b4' and `01/ce' represent the character codes 0xb4 and 0xce in the `Symbol'
-character set.
-.BU
-Scan code 0x3e generates function-key `F4', and scan code 0x4a generates
-function-key `page up'.
-.BU
-Scan code 0x60 is bound to key sequence #3.
-.BE
-Finally, if a scan code is not bound to any characters, then it is annotated
-with the label `not-bound', as with example scan code 0x68 from above.
-.SH Sequences
-A scan code (modified and unmodified) can be bound to a key sequence rather
-than generating a single character or acting as a modifier. When it is bound
-to a key sequence, a series of character invocations and modifier actions are
-automatically generated rather than a single keystroke.
-.PP
-Each mapping may contain zero or more key sequence records. The title
-.SM `SEQUENCES'
-is printed along with the count of sequence records which follow. For example:
-.PP
-.RS
-.nf
-SEQUENCES [3]
-sequence 0: "f" "o" "o"
-sequence 1: {alternate} "b" "a" "r" {unmodify}
-sequence 2: [home] "b" "a" "z"
-.fi
-.RE
-.PP
-The notation used to represent the sequence of generated characters is
-identical to the notation already described in the
-.I Characters
-section above, with the exception that modifier actions may be interposed
-between generated characters. Such modifier actions are represented by the
-modifier's name enclosed in braces. The special name `{unmodify}' indicates
-the release of the modifier keys.
-.PP
-Thus, the sequences in the above example can be interpreted as follows:
-.BG
-.BU
-Sequence\ #0 generates `foo'.
-.BU
-Sequence\ #1 invokes the
-.I alternate
-modifier, generates `bar', and then releases
-.I alternate.
-.BU
-Sequence\ #2 invokes the
-.I home
-key and then generates `baz'. In a text editor, this would probably result in
-`baz' being prepended to the line of text on which the cursor resides.
-.BE
-.SH Special Keys
-Certain keyboards feature keys which perform some type of special purpose
-function rather than generating a character or acting as a modifier. For
-instance, Apple keyboards often contain a
-.I power
-key, and
-.SM NeXT
-keyboards have historically featured screen brightness and volume control keys.
-.PP
-Each mapping may contain zero or more special-key records which associate
-hardware scan codes with such special purpose functions. The title
-.SM `SPECIALS'
-is printed along with the count of records which follow. For each record, the
-special function's name is printed along with a list of scan codes, in
-hexadecimal format, which are bound to that function. For example:
-.PP
-.RS
-.nf
-SPECIALS [6]
-alpha-lock: 0x39
-brightness-down: 0x79
-brightness-up: 0x74
-power: 0x7f
-sound-down: 0x77
-sound-up: 0x73
-.fi
-.RE
-.SH FILES
-.IP *.keymapping
-A key mapping file which precisely defines the relationship of all
-hardware-specific keyboard scan-codes with their associated functionality.
-.IP *.keyboard
-A file describing the physical layout of keys on a particular type of
-keyboard. Each `key' token in this file defines the position and shape of the
-key on the keyboard, as well as the associated scan code which that key
-generates. A
-.I .keymapping
-file, on the other hand, defines the characters which are generated by a
-particular scan code depending upon the state of the various modifier keys
-(such as
-.I shift,
-.I control,
-etc.). The `interface' and `handler_id' values from a
-.I .keymapping
-file are matched against those in each
-.I .keyboard
-file in order to associate a particular
-.I .keyboard
-file with a key mapping. Various
-.SM GUI
-programs use the
-.I .keyboard
-file to display a visual representation of a keyboard for the user. Since
-these files are just plain text, they can be easily viewed and interpreted
-without the aid of a specialized program, thus
-.I dumpkeymap
-leaves these files alone.
-.PP
-/System/Library/Keyboards
-.br
-/Network/Library/Keyboards
-.br
-/Local/Library/Keyboards
-.br
-/Library/Keyboards
-.RS
-Repositories for
-.I .keymapping
-and
-.I .keyboard
-files for MacOS/X, Darwin, and MacOS/X Server.
-.RE
-.PP
-/NextLibrary/Keyboards
-.br
-/LocalLibrary/Keyboards
-.RS
-Repositories for
-.I .keymapping
-and
-.I .keyboard
-files for OpenStep and NextStep.
-.RE
-.IP $(HOME)/Library/Keyboards
-Repository for personal
-.I .keymapping
-and
-.I .keyboard
-files.
-.SH DIGANOSTICS
-The following diagnostic messages may be issued to the standard error stream.
-.TG "Unrecognized option."
-An unrecognized option was specified on the command-line. Invoke
-.I dumpkeymap
-with the
-.B "\-\^\-help"
-option to view a list of valid options.
-.TG "Insufficient data in keymapping data stream."
-The key mapping file or data stream is corrupt. Either the file has been
-incorrectly truncated or a field, such as those which indicates the number of
-variable records which follow, contains a corrupt value.
-.PP
-The following diagnostic messages have significance only when trying to print
-.I .keymapping
-files mentioned on the command-line.
-.TG "Bad magic number."
-The mentioned file is not a
-.I .keymapping
-file. The file's content does not start with the string `KYM1'.
-.TG "Unable to open key mapping file."
-The call to fopen() failed; probably because the specified path is invalid or
-.I dumpkeymap
-does not have permission to read the file.
-.TG "Unable to determine key mapping file size."
-The call to fstat() failed, thus memory can not be allocated for loading the
-file.
-.TG "Unable to read key mapping file."
-The call to fread() failed.
-.PP
-The following diagnostic messages have significance only when trying to print
-the currently active key mapping when no
-.I .keymapping
-files have been mentioned on the command-line.
-.TG "Unable to open event status driver."
-The call to NXOpenEventStatus() failed.
-.TG "Bad key mapping length."
-The call to NXKeyMappingLength() returned a bogus value.
-.TG "Unable to get current key mapping."
-The call to NXGetKeyMapping() failed.
-.PP
-The following diagnostic messages have significance only when using
-.I dumpkeymap
-on a non-Apple/\c
-.SM NeXT
-platform.
-.TG "Must specify at least one .keymapping file."
-No
-.I .keymapping
-files were mentioned on the command-line. On non-Apple/\c
-.SM NeXT
-platforms, there is no concept of a currently active
-.I .keymapping
-file, so at least one file must be mentioned on the command-line.
-.SH AUTHOR
-Eric Sunshine <sunshine@sunshineco.com> wrote
-.I dumpkeymap
-and this document, the
-.I "dumpkeymap user's manual."
-Both
-.I dumpkeymap
-and this document are copyright \(co1999,2000 by Eric Sunshine
-<sunshine@sunshineco.com>. All rights reserved.
-.PP
-The implementation of
-.I dumpkeymap
-is based upon information gathered on September 3, 1997 by Eric Sunshine
-<sunshine@sunshineco.com> and Paul S. McCarthy <zarnuk@zarnuk.com> during an
-effort to reverse engineer the format of the
-.SM NeXT
-.I .keymapping
-file.
-.if n .PP
-.if n Version \n(VE \-\-
-.if n .UP
projects / synfig.git / blobdiff