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 2024-05-23 20:04:29 +01:00
parent bd49d2f690
commit 8ffd75e8d1
4 changed files with 186 additions and 85 deletions

View File

@ -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 \

View File

@ -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
View 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

View File

@ -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.