Update manpages for new mapping files
A new manpage describing the new file format for the keyboard mapping files is added.
This commit is contained in:
matt335672
parent
bd49d2f690
commit
8ffd75e8d1
@ -8,6 +8,7 @@ man_MANS = \
|
||||
xrdp-dis.1 \
|
||||
sesman.ini.5 \
|
||||
xrdp.ini.5 \
|
||||
xrdp-km.toml.5 \
|
||||
xrdp.8 \
|
||||
xrdp-chansrv.8 \
|
||||
xrdp-genkeymap.8 \
|
||||
|
||||
@ -9,48 +9,44 @@
|
||||
|
||||
.SH "SYNTAX"
|
||||
.B xrdp\-genkeymap
|
||||
.I file
|
||||
.I [ options ] file
|
||||
|
||||
.SH "DESCRIPTION"
|
||||
\fBxrdp\-genkeymap\fR extracts the key map used by the currently running X session to generated a mapping from Remote Desktop Protocol (RDP) key codes to X keysyms and Unicode code points.
|
||||
\fBxrdp\-genkeymap\fR extracts the current key map from the X server
|
||||
X session to generate a mapping from Remote Desktop Protocol (RDP)
|
||||
scan codes to X keysyms and Unicode code points.
|
||||
|
||||
Before running this utility, make sure the keymap is correct, by issuing
|
||||
the correct \fIsetxkbmap\fP command(s).
|
||||
|
||||
.SH OPTIONS
|
||||
.TP
|
||||
.I outfile
|
||||
.B -k 'keycode_set'
|
||||
Inform \fBxrdp\-genkeymap\fR of the keycode set in operation (evdev or
|
||||
base), so that the correct scan code to keycode mapping table is selected
|
||||
to generate the keymap.
|
||||
|
||||
If you omit this option, the XKB extension is asked to provide the
|
||||
name of the keycode set.
|
||||
|
||||
.TP
|
||||
.B -c 'comment'
|
||||
Adds a comment to the top of the generated file.
|
||||
|
||||
This option may be repeated more than once to add multiple comments to
|
||||
the top of the file.
|
||||
.TP
|
||||
.B outfile
|
||||
The key map information is stored in the file named \fIoutfile\fP.
|
||||
|
||||
.SH "FILES"
|
||||
.TP
|
||||
.I @sysconfdir@/xrdp/km-XXXXXXXX.ini
|
||||
Files containing the keyboard mapping for language \fIXXXXXXXX\fP, which is a 8 digit hexadecimal number identifying the country and language code.
|
||||
.RS 8
|
||||
.TP
|
||||
.B 00000405
|
||||
cs Czech
|
||||
.TP
|
||||
.B 00000407
|
||||
de German
|
||||
.TP
|
||||
.B 00000409
|
||||
en-us US English
|
||||
.TP
|
||||
.B 0000040c
|
||||
fr French
|
||||
.TP
|
||||
.B 00000410
|
||||
it Italian
|
||||
.TP
|
||||
.B 00000416
|
||||
br Portuguese (Brazil)
|
||||
.TP
|
||||
.B 00000419
|
||||
ru Russian
|
||||
.TP
|
||||
.B 0000041d
|
||||
se Swedish
|
||||
.TP
|
||||
.B 00000809
|
||||
en-uk UK English
|
||||
.I @sysconfdir@/xrdp/km-XXXXXXXX.toml
|
||||
Files containing the keyboard mapping for country and language \fIXXXXXXXX\fP.
|
||||
\fIXXXXXXXX\fP is a 8 digit hexadecimal number, representing the \fIinput
|
||||
locale identifier\fP.
|
||||
|
||||
The input locale identifier is passed from the RDP client when it connects.
|
||||
.RE
|
||||
|
||||
.SH "AUTHORS"
|
||||
@ -60,8 +56,15 @@ Simone Fedele <ilsimo@users.sourceforge.net>
|
||||
|
||||
.SH "SEE ALSO"
|
||||
.BR xrdp (8),
|
||||
.BR xrdp-km.toml (5),
|
||||
.BR setxkbmap (1),
|
||||
.BR unicode (7)
|
||||
|
||||
.PP
|
||||
Input locale identifiers on the
|
||||
.UR https://go.microsoft.com/fwlink/?LinkId=202824
|
||||
Microsoft website
|
||||
.UE
|
||||
.PP
|
||||
Description of Keyboard Input mapping on the
|
||||
.UR https://github.com/FreeRDP/FreeRDP/wiki/Keyboard
|
||||
|
||||
129
docs/man/xrdp-km.toml.5.in
Normal file
129
docs/man/xrdp-km.toml.5.in
Normal file
@ -0,0 +1,129 @@
|
||||
.\"
|
||||
.TH "xrdp-km.toml" "5" "@PACKAGE_VERSION@" "xrdp team" ""
|
||||
.SH "NAME"
|
||||
\fBxrdp-km.toml\fR \- \fBxrdp\fP key mapping file
|
||||
|
||||
.SH "DESCRIPTION"
|
||||
Key mapping files are located at \fB@sysconfdir@/xrdp/km-XXXXXXXX.toml\fP
|
||||
where \fBXXXXXXXX\fP is the input locale identifier sent by the RDP client.
|
||||
|
||||
The key mapping files are used to translate RDP scan codes into one of
|
||||
the following forms:-
|
||||
.TP
|
||||
.B X11 KeySyms
|
||||
These are used when \fBxrdp\fP connects to a VNC server.
|
||||
.TP
|
||||
.B Unicode characters
|
||||
These are used on the \fBxrdp\fP login screen.
|
||||
.RE
|
||||
.PP
|
||||
Each keymap file consists of several sections. Each section starts with
|
||||
the section name in square brackets, followed by a list of
|
||||
\fIparameter\fR=\fIvalue\fR lines.
|
||||
|
||||
.SH "SECTIONS"
|
||||
The following sections are recognized:
|
||||
.TP
|
||||
\fB[Globals]\fR
|
||||
Global configuration
|
||||
|
||||
.TP
|
||||
\fB[noshift]\fR
|
||||
Key mappings if no modifier keys (i.e. shift, alt gr, caps lock) are down.
|
||||
.TP
|
||||
\fB[shift]\fR
|
||||
Key mappings if the shift key is down.
|
||||
.TP
|
||||
\fB[altgr]\fR
|
||||
Key mappings if the alt gr key is down.
|
||||
.TP
|
||||
\fB[shiftaltgr]\fR
|
||||
Key mappings if the shift and alt gr keys are down.
|
||||
.TP
|
||||
\fB[capslock]\fR
|
||||
Key mappings if the caps lock key is down.
|
||||
.TP
|
||||
\fB[shiftcapslock]\fR
|
||||
Key mappings if the caps lock and shift keys are down.
|
||||
.TP
|
||||
\fB[shiftcapslockaltgr]\fR
|
||||
Key mappings if the shift, caps lock and alt gr keys are down.
|
||||
.TP
|
||||
\fB[numlock]\fR
|
||||
Key mappings if the numlock key is down.
|
||||
|
||||
.LP
|
||||
All parameters and values are case
|
||||
insensitive, and are described in detail below. If any parameter is
|
||||
specified more than once, the last entry will be used. Options specified
|
||||
outside their proper section will be \fIignored\fR.
|
||||
|
||||
.SH "GLOBALS Section"
|
||||
Following parameters can be used in the \fB[Globals]\fR section.
|
||||
|
||||
.TP
|
||||
\fBVersion\fR=\fInumber\fR
|
||||
Version of the file format in use.
|
||||
Can be used to check for file format mis-matches when a file is loaded.
|
||||
.RE
|
||||
|
||||
.SH "Keymap Sections"
|
||||
All other sections contain lines formatted in one of the following
|
||||
ways:-
|
||||
|
||||
.TP
|
||||
<scancode>=<KeySym>
|
||||
.TP
|
||||
<scancode>=<KeySymNum>:<unicode-char>
|
||||
.RE
|
||||
|
||||
Each line may also be followed by a comment (preceded by '#') which
|
||||
contains more information about the key, for example a KeySym string.
|
||||
|
||||
.TP
|
||||
.B scancode
|
||||
A \fBscancode\fP is an RDP scancode received from the client. These
|
||||
correspond to Windows "Scan Code Set 1" scan codes, and can be displayed
|
||||
in Windows by using an appropriate utility.
|
||||
|
||||
The \fBscancode\fP is in one of these two forms:-
|
||||
|
||||
.RS 8
|
||||
.TP
|
||||
.B <hex-digit><hex-digit>
|
||||
Standard scancodes. For example, '1C' refers to the enter key.
|
||||
These are 'key down' scancodes, and so are always between 00 and 7F.
|
||||
.TP
|
||||
.B E0_<hex-digit><hex-digit>
|
||||
Extended scancodes. For example, 'E0_1C' refers to the enter key on the numeric keypad.
|
||||
.RE
|
||||
|
||||
.TP
|
||||
.B KeySymNum
|
||||
A decimal number representing an X11 KeySym
|
||||
|
||||
.TP
|
||||
.B unicode-char
|
||||
A string of the format \fBU+XXXX\fP \fBU+XXXXX\fP,, \fBU+XXXXX\fP,
|
||||
where \fBX\fP is a hexadecimal digit.
|
||||
.RE
|
||||
|
||||
.SH "Limitations"
|
||||
This file format has the following limitations.
|
||||
.IP \(bu
|
||||
Not all combinations of shift keys are stored in the file. For example,
|
||||
at present there is no section for shift and numlock combined.
|
||||
.IP \(bu
|
||||
Modifier keys, other than the ones supported above, are not supported.
|
||||
|
||||
.SH "SEE ALSO"
|
||||
.BR xrdp-genkeymap (8)
|
||||
|
||||
.PP
|
||||
Scancode mappings for most keyboards at
|
||||
.UR https://kbdlayout.info
|
||||
.UE
|
||||
|
||||
For more info on \fBxrdp\fR see
|
||||
.UR @xrdphomeurl@
|
||||
.UE
|
||||
@ -10,47 +10,10 @@ km-xxxxxxxx.toml
|
||||
|
||||
where the xxxxxxxx is replaced by the hex number of the layout of interest.
|
||||
|
||||
The files are TOML compatible, with 10 sections;
|
||||
The contents of the files are documented in xrdp-km.toml(5)
|
||||
|
||||
[General], [noshift], [shift], [altgr], [shiftaltgr], [capslock],
|
||||
[capslockaltgr], [shiftcapslock], [shiftcapslockaltgr], [numlock]
|
||||
|
||||
The [General] section contains information about the file. All other
|
||||
sections contain key mappings corresponding to the state of the modifier
|
||||
keys when the key is pressed.
|
||||
|
||||
An example line looks like;
|
||||
|
||||
<RDP scancode>="<KeySym>[:<unicode>]" # comment
|
||||
|
||||
RDP scancode
|
||||
------------
|
||||
The RDP scancode is the code received from the RDP client for each
|
||||
key. RDP scancodes are more-or-less the same as Windows scancodes,
|
||||
or "Scan Code Set 1" key-down values.
|
||||
|
||||
Example scancodes might be '1C' for the enter key on most European
|
||||
keyboards, or 'E0 1C' for the number pad enter key.
|
||||
|
||||
A good website to consult for scancodes for a wide range of keyboards is
|
||||
https://kbdlayout.info/
|
||||
|
||||
KeySym
|
||||
------
|
||||
The KeySym is a value used by the X server as an abstraction of the
|
||||
engraving on the key being pressed. It is needed to interact with the
|
||||
VNC server.
|
||||
|
||||
Unicode
|
||||
-------
|
||||
Keys which generate a character when pressed have this value added.
|
||||
This is used by the xrdp login screen.
|
||||
|
||||
Comment
|
||||
-------
|
||||
For generated keymap files, the comment is the name of the X11 KeySym
|
||||
for the key. This makes it a lot easier to see what is going on in
|
||||
the file.
|
||||
See also xrdp-genkeymap(8) which describes the utility used to
|
||||
generate these files.
|
||||
|
||||
Creating a new file
|
||||
-------------------
|
||||
@ -58,24 +21,29 @@ Creating a new file
|
||||
To create a new file:-
|
||||
1) Start an X server
|
||||
2) Use the 'setxkbmap' command to get the keyboard configured
|
||||
for the X server. Currently this has to use the 'evdev' rules so
|
||||
that xrdp and the X server agree on the low-level X11 keycodes to
|
||||
be used for the keys.
|
||||
for the X server.
|
||||
3) Run the 'xrdp-genkeymap' command to extract the keyboard
|
||||
mappings
|
||||
|
||||
Example: ./xrdp-genkeymap /etc/xrdp/km-00000409.toml
|
||||
Example: ./xrdp-genkeymap ./km-00000409.toml
|
||||
|
||||
Note: You need to have enough rights to be able to write to the
|
||||
/etc/xrdp directory.
|
||||
|
||||
Alternatively, create the keymap file in a directory of your choice, then
|
||||
copy or move it over to /etc/xrdp using sudo/su.
|
||||
4) Copy the generated file to /etc/xrdp/
|
||||
|
||||
Using the X server of your current session may not be a good idea, as
|
||||
session and window managers can interfere with key bindings. A good option
|
||||
is to use an 'Xvfb' dummy X server to do this.
|
||||
|
||||
See also the dump_keymaps.sh script which auto-generates many keymap
|
||||
files for the xrdp distribution. Consider adding your keyboard into this
|
||||
list.
|
||||
Getting a file added to xrdp
|
||||
----------------------------
|
||||
|
||||
The file dump-keymaps.sh in this directory is used to auto-generate
|
||||
all keymap files. It runs on Linux currently, but will generate
|
||||
keymap files suitable for any xrdp platform.
|
||||
|
||||
1) Add a line towards the end of this file which causes your mapping to
|
||||
be generated. Use the other lines in this file as a guide.
|
||||
2) Run the dump-keymaps.sh script to generate a new file in
|
||||
instfiles/
|
||||
3) Add your mapping to the list in instfiless/Makefile.am
|
||||
4) Submit a pull request to the project containing the above three
|
||||
changes.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user