move keyboard protocols into the info manual

Signed-off-by: Mattias Andrée <maandree@operamail.com>

1 files changed, 528 insertions, 3 deletions

diff --git a/doc/info/mds.texinfo b/doc/info/mds.texinfo
index 7394aac..9e26e9f 100644
--- a/doc/info/mds.texinfo
+++ b/doc/info/mds.texinfo
@@ -1721,6 +1721,7 @@ simple, reference implementation of a, status icon tray.
 @menu
 * Infrastructure protocols::        Infrastructure protocols.
 * Virtual terminal protocols::      Virtual terminal protocols.
+* Keyboard protocols::              Keyboard protocols.
 @end menu
 
 
@@ -1985,7 +1986,7 @@ VT such that they can use ioctl and similar calls on that TTY.
 Required.
 
 @item Reference implementation:
-@code{vt}
+@code{mds-vt}
 @end table
 
 
@@ -2042,7 +2043,7 @@ VT such that they can use ioctl and similar calls on that TTY.
 Required.
 
 @item Reference implementation:
-@code{vt}
+@code{mds-vt}
 @end table
 
 
@@ -2098,7 +2099,531 @@ active again.
 Required.
 
 @item Reference implementation:
-@code{vt} and @code{kkbd}
+@code{mds-vt} and @code{mds-kkbd}
+@end table
+
+
+
+@node Keyboard protocols
+@section Keyboard protocols
+
+@menu
+* key-sent::                        Announce a keyboard input event.
+* enumerate-keyboards::             List available keyboards.
+* keyboard-enumeration::            Response to @code{Command: enumerate-keyboards}.
+* set-keyboard-leds::               Activate and deactivate LED:s on a keyboard.
+* get-keyboard-leds::               List exisiting LED:s on a keyboard and their state.
+* keycode-map::                     Remap keyboard keycodes and query current mapping.
+* new-keyboard::                    Announce the existance of a new keyboard.
+* old-keyboard::                    Announce the removal of an old keyboard.
+@end menu
+
+
+
+@node key-sent
+@subsection key-sent
+
+@table @asis
+@item Identifying header:
+@command{Command: key-sent}
+
+@item Action:
+Announce a keyboard input event.
+
+@item Required header: @code{Keyboard}
+Any string that uniquely identifies the keyboard.
+@table @asis
+@item Purpose:
+Enable multi-keyboard aware programs and give at
+least on keyboard per seat in a multi-seat environment.
+@item Note:
+mds-kkbd uses @code{kernel} to indicate that it uses
+the kernel and thus lumps together all keyboards.
+@end table
+
+@item Required header: @code{Released}
+@table @code
+@item yes
+The value of the header @code{Released} will
+be @code{yes} if the key was released.
+@item no
+The value of the header @code{Released} will be
+@code{no} otherwise, that is, held down or pressed.
+@end table
+Note: pause/break is automatically released directly after
+it has been pressed. This is feature built into keyboards
+and servers should not try to circumvent this.
+
+@item Required header: @code{Keycode}
+An unsigned 14-bit integer identifying the key, may be remapped.
+
+@item Optional header: @code{Scancode}
+Either an unsigned 7-bit integer or a single blank space
+separated trio of unsigned 7-bit integers, identifying the key.
+This is the scancode sent from the keyboard and optionally
+unified by the keyboard driver, however with the typed/released
+bit zeroed out. This may not be remapped.
+
+@item Optional header: @code{Modifiers}
+Single blank space separated list of active modifiers:
+@table @code
+@item shift
+Shift (level 2)
+@item ctrl
+Control
+@item alt
+Alternative/Option
+@item altgr
+Alternative Graphic (level 3)
+@item lvl*
+@code{*} may be any @math{2^n + 1} integer with
+@math{1 < n < 20}.
+@item super
+Super
+@item hyper
+Hyper
+@item ultra
+Ultra
+@item caps
+Caps (usually a lock key)
+@item num
+Num (usually a lock key)
+@item scrl
+Scroll (usually a lock key)
+@item top
+Top (historical)
+@item front
+Front (historical)
+@item greek
+Greek (historical)
+@item compose
+Compose (rare, it is usally a dead key)
+@end table
+Any key that has been locked should be prefix with
+@code{+}, if the key has been locked by nullified
+with non-lock modifier it should be prefixed with
+a @code{-}. If no modifier is active or has been
+nullified, @code{none} should be used.
+
+@item Optional header: @code{Key}
+A textual representation of the key that has been typed or
+released, as mapped by the keyboard layout.
+@table @code
+@item esc
+Escape
+@item f*
+F@code{*} where @code{*} is any integer.
+@item sysrq
+System Request/Print Screen
+@item scrl
+Scroll (lock)
+@item break
+Break/Pause
+@item backspace
+Backspace
+@item tab
+Tab
+@item return
+Return/Enter
+@item space
+Blank Space
+@item menu
+Application Menu
+@item ins
+Insert
+@item home
+Home
+@item pgup
+Page Up
+@item del
+Delete
+@item end
+End
+@item pgdown
+Page Down
+@item up
+Up Arrow
+@item left
+Left Arrow
+@item down
+Down Arrow
+@item right
+Right Arrow
+@item shift
+Shift (level 2)
+@item begin
+Begin (keypad 5 in nagivation mode)
+@item ctrl
+Control
+@item alt
+Alternative/Option
+@item altgr
+Alternative Graphic (level 3)
+@item lvl*
+@code{*} may be any @math{2^n + 1} integer
+@math{with 1 < n < 20}.
+@item super
+Super
+@item hyper
+Hyper
+@item ultra
+Ultra
+@item caps
+Caps (usually a lock key)
+@item num
+Num (usually a lock key)
+@item scrl
+Scroll (usually a lock key)
+@item top
+Top (historical)
+@item front
+Front (historical)
+@item greek
+Greek (historical)
+@item compose
+Compose (usally a dead key)
+@item hexcompose
+Hex-Compose (usally a dead key)
+(Use to create aribitrary characters.)
+@item longhexcompose
+Long Hex-Compose (usally a dead key)
+(Variant of hexcompose for longer codepoints.)
+@item modelock
+Mode Lock
+@item letter *
+@code{*} may be any UTF-8 encoded letter.
+@end table
+Keys that lock/unlock a modifer should be suffixed with a
+blank space and a @code{lock}. If the key is a dead key
+(even the compose key) should use @code{dead} instead. A
+position, either @code{left}, @code{right}, @code{keypad}
+or an index, followed by a blank space, should prefix any
+key that occurs on multiple position on the keyboard,
+unless it only appears on the keypad once and once not on
+the keypad. Keys without any meaning should be identified
+as @code{unknown}. Modifiers and dead keys should not
+affect the value.
+
+@item Optional header: @code{Characters}
+UTF-8 encoded string that has been written.
+
+@item Purpose:
+Enable the user to use a keyboard, physical or on-screen.
+
+@item Purpose:
+Enable programs to send keys as part of a
+script or a reply of a recorded session.
+
+@item Compulsivity:
+Highly-recommended, a computer is as good
+as useless without a keyboard.
+
+@item Reference implementation:
+@command{mds-kkbd}, @command{mds-kbd} and @command{mds-keytrans}
+@end table
+
+
+
+@node enumerate-keyboards
+@subsection enumerate-keyboards
+
+@table @asis
+@item Identifying header:
+@command{Command: enumerate-keyboards}
+
+@item Action:
+List available keyboards.
+
+@item Required header: @code{Client ID}
+Your ID, provided by the @code{ID assignment} header
+in response to a @code{Command: assign-id} header.
+
+@item Instructions:
+This message must be consumed by the first server that
+receives it and implements support for it, and then send
+out a @code{Command: keyboard-enumeration} populated with
+the keyboard it provide as named in the @code{Keyboard}
+header for protocols such as @code{Command: key-sent}.
+
+@item Purpose:
+Make it possible for clients to list all available
+keyboards so that can be configured individually.
+
+@item Compulsivity:
+Optional.
+
+@item Reference implementation:
+@command{mds-kkbd} and @command{mds-kbd}
+@end table
+
+
+
+@node keyboard-enumeration
+@subsection keyboard-enumeration
+
+@table @asis
+@item Identifying header:
+@command{Command: keyboard-enumeration}
+
+@item Action:
+Response to @code{Command: enumerate-keyboards}.
+
+@item Required header: @code{To}
+The ID received under @code{Client ID} header in
+the @code{Command: enumerate-keyboards} message
+that triggered this message to be broadcasted
+
+@item Required header: @code{In response to}
+The ID received under the @code{Message ID} header
+in the @code{Command: enumerate-keyboards} message
+that triggered this message to be broadcasted.
+
+@item Required header: @code{Length}
+Length of the message.
+
+@item Message:
+New line separated list of available keyboards.
+
+@item Instructions:
+All keyboard servers should listen for this message
+and append all keyboards it implement to the message
+once recieved.
+
+@item Purpose:
+Make it possible for clients to list all available
+keyboards so that can be configured individually
+
+@item Compulsivity:
+Required if you implement @command{Command: enumerate-keyboards}.
+
+@item Reference implementation:
+@command{mds-kkbd} and @command{mds-kbd}
+@end table
+
+
+
+@node set-keyboard-leds
+@subsection set-keyboard-leds
+
+@table @asis
+@item Identifying header:
+@command{Command: set-keyboard-leds}
+
+@item Action:
+Activate and deactivate LED:s on a keyboard.
+
+@item Required header: @code{Active}
+LED:s that should be turned on. If a LED is listed here
+but not in @code{Mask} that LED should be turned on if
+it is off, and turned off if it is on.
+
+The value is a single blank space separated list of LED:s:
+@table @code
+@item num
+Num lock
+@item caps
+Caps lock
+@item scroll
+Scroll lock
+@item compose
+Compose
+@end table
+Unsupported LED:s should be silently ignored.
+
+@item Required header: @code{Mask}
+LED:s listed here that do not appear in @code{Active}
+should be turned off. The value of this header follows
+the same rules as for @code{Active}.
+
+@item Optional header: @code{Keyboard}
+A string that identifies the keyboard that should be
+affected. If omitted all keyboard are affected.
+
+@item Purpose:
+Enable keyboard layout servers to activate and deactive
+LED:s on the keyboard to indicate active locks.
+
+@item Compulsivity:
+Optional.
+
+@item Reference implementation:
+@command{mds-kkbd}, @command{mds-kbd} and @command{mds-keytrans}
+@end table
+
+
+
+@node get-keyboard-leds
+@subsection get-keyboard-leds
+
+@table @asis
+@item Identifying header:
+@command{Command: get-keyboard-leds}
+
+@item Action:
+List exisiting LED:s on a keyboard and their state.
+
+@item Required header: @code{Client ID}
+Your ID, provided by the @code{ID assignment} header
+in response to a @code{Command: assign-id} header.
+
+@item Required header: @code{Keyboard}
+A string that identifies the keyboard that
+should be affected.
+
+@item Response:
+The server implementing support for
+@code{Command: get-keyboard-leds} for the keyboard
+indicated by @code{Keyboard} should send a message
+back to the client indicated by rge @code{Client ID}
+header (using the @code{To} header) with the headers:
+@table @code
+@item Active
+List of currently turned on LED:s.
+@item Present
+List of LED:s that the server believes
+to be present on the keyboards.
+@end table
+Both of these headers followes the rules of the
+@code{Active} header under @code{Command: set-keyboard-leds}.
+
+@item Purpose:
+Enable keyboard layout servers to automatically
+set active locks when the server starts based on
+currently active LED:s
+
+@item Compulsivity:
+Recommended. Required if you implement support for
+@code{Command: set-keyboard-leds}. If you do not
+support this protocol servers and clients and stall
+when they try to get the active LED:s
+
+@item Reference implementation:
+@command{mds-kkbd}, @command{mds-kbd} and @command{mds-keytrans}
+@end table
+
+
+
+@node keycode-map
+@subsection keycode-map
+
+@table @asis
+@item Identifying header:
+@command{Command: keycode-map}
+
+@item Action:
+Remap keyboard keycodes and query current mapping.
+
+@item Required header: @code{Action}
+@table @code
+@item remap
+Remap keys if the value of the header @code{Action}
+is @code{remap}.
+@item reset
+Reset all mappings to identity mapping if the value
+of the header @code{Action} is @code{reset}.
+@item query
+Query mapping if the value of the header @code{Action}
+is @code{query}.
+@end table
+Each affected server will send a message format
+like that of @code{Action: remap} with current
+mapping that are not identity mappings.
+
+@item Optional header: @code{Keyboard}
+A string that identifies the keyboard that should be
+affected. If omitted all keyboard are affected.
+
+@item Conditionally required header: @code{Client ID}
+Your ID, provided by the @code{ID assignment} header
+in response to a @code{Command: assign-id} header.
+Required if @code{Action: query} is included in the headers.
+
+@item Conditionally optional header: @code{Length}
+The length of the message.
+Available and optional if @code{Action: remap}
+is included in the headers.
+
+@item Message:
+Each line contains contains two single space delimited numbers,
+the first number is the keycode as determined by the scancode,
+the second number is keycode that scancode should generate.
+For example, @code{1 1} resets Escape to be mapped to Escape,
+and @code{1 59} remaps Escape to F1, while
+@example
+1 59
+59 1
+@end example
+swaps Escape and F1.
+
+@item Purpose:
+Enable the user to swap or replace keys on the keyboard.
+
+@item Purpose:
+Enable the user manually correct an incorrectly mapped keyboard.
+
+@item Compulsivity:
+Optional.
+
+@item Reference implementation:
+@command{mds-kbd} and @command{mds-kkbd}
+@end table
+
+
+
+@node new-keyboard
+@subsection new-keyboard
+
+@table @asis
+@item Identifying header:
+@command{Command: new-keyboard}
+
+@item Action:
+Announce the existance of a new keyboard.
+
+@item Required header: @code{Length}
+The length of the message.
+
+@item Message:
+List of strings that identifies the keyboards
+that have been added.
+
+@item Purpose:
+Enable servers and clients to detect new keyboards.
+
+@item Compulsivity:
+Recommended.
+
+@item Reference implementation:
+@command{mds-kbd} and @command{mds-kkbd}
+@end table
+
+
+
+@node old-keyboard
+@subsection old-keyboard
+
+@table @asis
+@item Identifying header:
+@command{Command: old-keyboard}
+
+@item Action:
+Announce the removal of an old keyboard.
+
+@item Required header: @command{Length}
+The length of the message.
+
+@item Message:
+List of strings that identifies the keyboards
+that have been removed.
+
+@item Purpose:
+Enable servers and clients to detect removal of keyboards.
+
+@item Compulsivity:
+Recommended.
+
+@item Reference implementation:
+@command{mds-kbd}
 @end table