man: expand the man page to mention libxkbcommon and the custom layout

This may save us some typing in issue reports.

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

1 files changed, 26 insertions, 2 deletions

diff --git a/man/man.xsl b/man/man.xsl
index 9ed9b7b..9e0f3bf 100644
--- a/man/man.xsl
+++ b/man/man.xsl
@@ -8,8 +8,32 @@
 xkeyboard-config \- XKB data description files
 .SH DESCRIPTION
 xkeyboard-config provides the description files for the X Keyboard
-Extension (XKB). The configuration options below are usually applied with
-setxkbmap(1).
+Extension (XKB) and for libxkbcommon. Typically it is
+the task of the desktop environment to apply the
+requested configuration. Users running an X server can also use the
+setxkbmap(1) tool to apply keyboard configuration at runtime or configure XKB
+settings in the xorg.conf(5).
+
+.SH XKB DATA FILES LOAD PATHS
+
+xkeyboard-config provides the XKB data files installed in
+@xkb_base@. User-specific data files may be elsewhere but it depends on
+the tool whether those files are loaded. For example, the libxkbcommon
+library will by default load XKB data files from the user's home directory.
+See the libxkbcommon documentation for details.
+
+.SH THE "CUSTOM" LAYOUT
+
+The "custom" layout is a layout that is listed as available to tools
+reading the data files but is not actually provided by xkeyboard-config.
+A user may save a layout specification in the @xkb_base@/symbols/custom file
+and that layout will be available to most tools interacting with the
+xkeyboard-config data files. This is primarily aimed at systems running X
+where additional lookup paths cannot easily be added.
+.PP
+Because the "custom" layout is merely listed as available but not
+provided by xkeyboard-config, the layout will not be overwritten on updates.
+
 .SH MODELS
 .TS
 left,box;