Update manpages for new mapping files

A new manpage describing the new file format for the keyboard mapping
files is added.

docs/man/Makefile.am

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

docs/man/xrdp-genkeymap.8.in

@@ -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
+.I @sysconfdir@/xrdp/km-XXXXXXXX.toml
-Files containing the keyboard mapping for language \fIXXXXXXXX\fP, which is a 8 digit hexadecimal number identifying the country and language code.
+Files containing the keyboard mapping for country and language \fIXXXXXXXX\fP.
-.RS 8
+\fIXXXXXXXX\fP is a 8 digit hexadecimal number, representing the \fIinput
-.TP
+locale identifier\fP.
-.B 00000405
+
-cs Czech
+The input locale identifier is passed from the RDP client when it connects.
-.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
 .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

docs/man/xrdp-km.toml.5.in

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

genkeymap/readme.txt

@@ -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],
+See also xrdp-genkeymap(8) which describes the utility used to
-[capslockaltgr], [shiftcapslock], [shiftcapslockaltgr], [numlock]
+generate these files.
-
-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.
 
 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
+   for the X server.
-   that xrdp and the X server agree on the low-level X11 keycodes to
-   be used for the keys.
 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
+4) Copy the generated file to /etc/xrdp/
-/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.
 
 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
+Getting a file added to xrdp
-files for the xrdp distribution. Consider adding your keyboard into this
+----------------------------
-list.
+
+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.