Docs: Restructure the Embedded Linux article to improve readability

* Split out the Inputs chapter into its own page
* Cleanup the Inputs page to improve readability
* Remove outdated bits of info from the Embedded Linux article itself

Task-number: QTBUG-75725
Change-Id: Ia1031da92c302d78903d22199f7f13cde3a512bc
Reviewed-by: Andy Shaw <andy.shaw@qt.io>
Reviewed-by: Laszlo Agocs <laszlo.agocs@qt.io>

4 files changed, 289 insertions, 237 deletions

diff --git a/doc/src/external-resources.qdoc b/doc/src/external-resources.qdoc
index 51a5bc1b8..9ca177d3b 100644
--- a/doc/src/external-resources.qdoc
+++ b/doc/src/external-resources.qdoc
@@ -375,3 +375,23 @@
     \externalpage https://webassembly.org
     \title WebAssembly Resource site
 */
+
+/*!
+    \externalpage https://www.freedesktop.org/wiki/Software/libinput
+    \title libinput
+*/
+
+/*!
+    \externalpage https://www.yoctoproject.org
+    \title Yocto Project
+*/
+
+/*!
+    \externalpage http://lct.sourceforge.net/
+    \title Linux Console Tools (LCT)
+*/
+
+/*!
+    \externalpage https://www.x.org/
+    \title X.org
+*/
diff --git a/doc/src/platforms/configure-linux-device.qdoc b/doc/src/platforms/configure-linux-device.qdoc
index 201e22ac5..06955f882 100644
--- a/doc/src/platforms/configure-linux-device.qdoc
+++ b/doc/src/platforms/configure-linux-device.qdoc
@@ -28,7 +28,7 @@
 /*!
     \page configure-linux-device.html
     \title Configure an Embedded Linux Device
-    \brief Provides information about how to configure an embedded Linux device in Qt.
+    \brief Provides information about how to configure an Embedded Linux device in Qt.
 
     Building Qt for a given device requires a toolchain and a \c sysroot. Additionally, some
     devices require vendor-specific adaptation code for EGL and OpenGL ES 2.0 support. This is
diff --git a/doc/src/platforms/emb-linux.qdoc b/doc/src/platforms/emb-linux.qdoc
index 19816f85c..586079f05 100644
--- a/doc/src/platforms/emb-linux.qdoc
+++ b/doc/src/platforms/emb-linux.qdoc
@@ -318,238 +318,6 @@
   set the \c{QT_QPA_FB_FORCE_FULLSCREEN} environment variable to \c 0 to
   restore the behavior from earlier Qt versions.
 
-  \section1 Input
-
-  When no windowing system is present, the mouse, keyboard, and touch input are
-  read directly via \c evdev or using helper libraries such as \c libinput or
-  \c tslib.  Note that this requires that device nodes \c {/dev/input/event*} are
-  readable by the user. \c eglfs and \c linuxfb have all the input handling code
-  compiled-in.
-
-  \section2 Using libinput
-
-  \l{http://www.freedesktop.org/wiki/Software/libinput}{libinput} is a library
-  to handle input devices. It offers an alternative to the Qt's own \c evdev
-  input support. To enable using \c libinput, make sure the development files
-  for \c libudev and \c libinput are available when configuring and building
-  Qt. \c xkbcommon is also necessary if keyboard support is desired. With
-  \c eglfs and \c linuxfb no further actions are necessary as these plugins use
-  \c libinput by default. If \c libinput support is not available or the
-  environment variable \c QT_QPA_EGLFS_NO_LIBINPUT is set, Qt's own evdev
-  handlers come in to play.
-
-  \section2 Input on eglfs and linuxfb without libinput
-
-  Parameters like the device node name can be set in the environment variables
-  \c QT_QPA_EVDEV_MOUSE_PARAMETERS, \c QT_QPA_EVDEV_KEYBOARD_PARAMETERS and
-  \c QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS. Separate the entries with colons.  These
-  parameters act as an alternative to passing the settings in the \c{-plugin}
-  command-line argument, and with some backends they are essential: eglfs and
-  linuxfb use built-in input handlers so there is no separate \c {-plugin}
-  argument in use.
-
-  Additionally, the built-in input handlers can be disabled by setting
-  \c QT_QPA_EGLFS_DISABLE_INPUT or \c QT_QPA_FB_DISABLE_INPUT to \c 1.
-
-  \section2 Mouse
-
-  The mouse cursor shows up whenever \c QT_QPA_EGLFS_HIDECURSOR (for eglfs)
-  or \c QT_QPA_FB_HIDECURSOR (for linuxfb) is not set and Qt's libudev-based
-  device discovery reports that at least one mouse is available. When \c libudev
-  support is not present, the mouse cursor always show up unless explicitly
-  disabled via the environment variable.
-
-  Hot plugging is supported, but only if Qt was configured with \c libudev support
-  (that is, if the \e libudev development headers are present in the sysroot at
-  configure time). This allows connecting or disconnecting an input device while
-  the application is running.
-
-  The \e evdev mouse handler supports the following extra parameters:
-
-  \list
-
-  \li \c {/dev/input/...} - Specifies the name of the input device. When not
-  given, Qt looks for a suitable device either via \e libudev or by walking
-  through the available nodes.
-
-  \li \c nocompress - By default, input events that do not lead to changing the
-  position compared to the last Qt mouse event are compressed; a new Qt mouse
-  event is sent only after a change in the position or button state.  This can
-  be disabled by setting the \c nocompress parameter.
-
-  \li \c dejitter - Specifies a jitter limit. By default dejittering is disabled.
-
-  \li \c grab - When 1, Qt will grab the device for exclusive use.
-
-  \li \c abs - Some touchscreens report absolute coordinates and cannot be
-  differentiated from touchpads.  In this special situation pass \c abs to
-  indicate that the device is using absolute events.
-
-  \endlist
-
-  \section2 Keyboard
-
-  The \e evdev keyboard handler supports the following extra parameters:
-
-  \list
-
-  \li \c {/dev/input/...} - Specifies the name of the input device. When not
-  given, Qt looks for a suitable device either via \e libudev or by walking
-  through the available nodes.
-  \li \c {grab} - Enables grabbing the input device.
-  \li \c {keymap} - Specifies the name of a custom keyboard map file.
-  \li \c {enable-compose} - Enables compositing.
-  \li \c {repeat-delay} - Sets a custom key repeat delay.
-  \li \c {repeat-rate} - Sets a custom key repeat rate.
-  \endlist
-
-  On Embedded Linux systems that do not have their terminal sessions disabled,
-  the behavior on a key press can be confusing as input event is processed by
-  the Qt application and the tty. To overcome this, the following options are
-  available:
-
-  \list
-
-  \li \e EGLFS and \e LinuxFB attempt to disable the terminal keyboard on
-  application startup by setting the tty's keyboard mode to \c K_OFF. This
-  prevents keystrokes from going to the terminal. If the standard behavior needs
-  to be restored for some reason, set the environment variable
-  \c QT_QPA_ENABLE_TERMINAL_KEYBOARD to \c 1. Note that this works only when the
-  application is launched from a remote console (for example, via \c ssh) and
-  the terminal keyboard input remains enabled.
-
-  \li An alternative approach is to use the \e evdev keyboard handler's \c grab
-  parameter by passing \e{grab=1} in \c QT_QPA_EVDEV_KEYBOARD_PARAMETERS. This
-  results in trying to get a grab on the input device. If the \c grab is
-  successful, no other components in the system receive events from it as long as
-  the Qt application is running. This approach is more suitable for applications
-  started remotely as it does not need access to the tty device.
-
-  \li Finally, for many specialized Embedded Linux images it does not make sense
-  to have the standard terminal sessions enabled in the first place. Refer to
-  your build environment's documentation on how to disable them. For example,
-  when generating images using the \l {http://www.yoctoproject.org}{Yocto
-  Project}, unsetting \c SYSVINIT_ENABLED_GETTYS results in having no
-  \c getty process running, and thus no input, on any of the virtual terminals.
-
-  \endlist
-
-  If the default built-in keymap is not sufficient, a different one can be
-  specified either via the \c keymap parameter or by using the eglfs-specific
-  \l{QEglFSFunctions::loadKeymap()}{loadKeymap()} function. The latter allows
-  switching the keymap at runtime. Note however that this requires using eglfs'
-  built-in keyboard handler; it is not supported when the keyboard handler is
-  loaded via the \c -plugin command-line parameter.
-
-  \note Special system key combinations, such as console switching
-  (\e{Ctrl+Alt+Fx}) or zap (\e{Ctrl+Alt+Backspace}) are not currently supported
-  and are ignored.
-
-  To generate a custom keymap, the \e kmap2qmap utility can be used. This can be
-  found in the \e qttools module. The source files have to be in standard Linux
-  \c kmap format, which is understood by the kernel's \c loadkeys command.
-  This means one can use the following sources to generate \c qmap files:
-
-  \list
-  \li The \l {http://lct.sourceforge.net/}{Linux Console Tools (LCT)} project.
-  \li \l {http://www.x.org/}{Xorg} X11 keymaps can be converted to the
-  \c kmap format with the \c ckbcomp utility.
-  \li As \c kmap files are plain-text files, they can also be hand crafted.
-  \endlist
-
-  \c kmap2qmap is a command line program, that needs at least 2 files as
-  parameters.  The last one is the generated \c .qmap file, while all the
-  others are parsed as input \c .kmap files.  For example:
-
-  \badcode
-  kmap2qmap i386/qwertz/de-latin1-nodeadkeys.kmap include/compose.latin1.inc de-latin1-nodeadkeys.qmap
-  \endcode
-
-  \note \c kmap2qmap does not support all the (pseudo) symbols that the Linux
-  kernel supports.  When converting a standard keymap, a number of warnings will
-  be shown regarding \c Show_Registers, \c Hex_A, and so on; these messages can
-  safely be ignored.
-
-  \section2 Touch
-
-  For some resistive, single-touch touch screens it may be necessary to fall
-  back to using \c tslib instead of relying on the Linux multi-touch protocol and
-  the event devices. For modern touch screens this is not necessary. \c tslib
-  support can be enabled by setting the environment variable
-  \c QT_QPA_EGLFS_TSLIB or \c QT_QPA_FB_TSLIB to 1. To change the device, set the
-  environment variable \c TSLIB_TSDEVICE or pass the device name on the
-  command-line. Note that the \c tslib input handler generates mouse events and
-  supports single touch only, as opposed to \c evdevtouch which generates true
-  multi-touch QTouchEvent events too.
-
-  The \e evdev touch handler supports the following extra parameters:
-
-  \list
-
-  \li \c {/dev/input/...} - Specifies the name of the input device. When not
-  given, Qt looks for a suitable device either via \e libudev or by walking
-  through the available nodes.
-
-  \li \c rotate - On some touch screens the coordinates must be rotated, which
-  is done by setting \c rotate to 90, 180, or 270.
-
-  \li \c invertx and \c inverty - To invert the X or Y coordinates in the input
-  events, pass \c invertx or \c inverty.
-
-  \endlist
-
-  For example, doing \c{export
-  QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS=/dev/input/event5:rotate=180} before
-  launching applications results in an explicitly specified touch device and
-  flipping the coordinates - useful when the orientation of the actual
-  screen and the touch screen do not match.
-
-  \section2 Pen-based tablets
-
-  The \c evdevtablet plugin provides basic support for Wacom and similar,
-  pen-based tablets. It generates QTabletEvent events only. To enable it,
-  pass \c {QT_QPA_GENERIC_PLUGINS=evdevtablet} in the environment or,
-  alternatively, pass \c {-plugin evdevtablet} argument on the command-line.
-  The plugin can take a device node parameter, for example
-  \c{QT_QPA_GENERIC_PLUGINS=evdevtablet:/dev/event1}, in case the Qt's automatic
-  device discovery (based either on \e libudev or a walkthrough of
-  \c{/dev/input/event*}) is not functional or misbehaving.
-
-  \section2 Debugging Input Devices
-
-  It is possible to print some information to the debug output by enabling
-  the \c qt.qpa.input logging rule, for example by setting the \c QT_LOGGING_RULES
-  environment variable to \c{qt.qpa.input=true}. This is useful for detecting
-  which device is being used, or to troubleshoot device discovery issues.
-
-  \section2 Using Custom Mouse Cursor Images
-
-  \c eglfs comes with its own set of 32x32 sized mouse cursor images. If these are
-  not sufficient, a custom cursor atlas can be provided by setting the \c
-  QT_QPA_EGLFS_CURSOR environment variable to the name of a JSON file. The file
-  can also be embedded into the application via Qt's resource system.
-
-  For example, an embedded cursor atlas with 8 cursor images per row can be
-  specified like the following:
-
-  \badcode
-    {
-      "image": ":/cursor-atlas.png",
-      "cursorsPerRow": 8,
-      "hotSpots": [
-          [7, 2],
-          [12, 3],
-          [12, 12],
-          ...
-      ]
-    }
-  \endcode
-
-  Note that the images are expected to be tightly packed in the atlas: the
-  width and height of the cursors are decided based on the total image size and
-  the \c cursorsPerRow setting. Atlases have to provide an image for all the
-  supported cursors.
-
   \section1 Display Output
 
   When having multiple displays connected, the level of support for targeting
@@ -1050,15 +818,12 @@
 
   For more details, see \l{Wayland and Qt}.
 
-  \note You may experience issues with touch screen input while using the
-  \l{http://wayland.freedesktop.org/}{Weston} reference compositor. For more
-  information, see \l{https://wiki.qt.io/WestonTouchScreenIssues}.
-
   \section1 Related Topics
 
   \list
    \li \l{Qt for Device Creation}
    \li \l{Configure an Embedded Linux Device}
+   \li \l{Inputs on an Embedded Linux Device}
    \li \l Emulator
    \li \l{Qt Virtual Keyboard}
    \li \l{Qt Quick WebGL}
diff --git a/doc/src/platforms/inputs-linux-device.qdoc b/doc/src/platforms/inputs-linux-device.qdoc
new file mode 100644
index 000000000..9cb85dcee
--- /dev/null
+++ b/doc/src/platforms/inputs-linux-device.qdoc
@@ -0,0 +1,267 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+  \page inputs-linux-device.html
+  \title Inputs on an Embedded Linux Device
+  \brief Provides information about working with inputs on an Embedded Linux device in Qt.
+
+  On your Embedded Linux device, when there's no windowing system present, the mouse, keyboard,
+  and touch input are read directly via \c evdev or using helper libraries such as \c libinput or
+  \c tslib. However, this behavior requires that device nodes \c {/dev/input/event*} are readable
+  by the user. \c eglfs and \c linuxfb have all the input handling code compiled-in.
+
+  \section2 Use libinput
+
+  \l{libinput} is a library to handle input devices that offers an alternative to the Qt's own
+  \c evdev input support. To enable using \c libinput, when you configure and build Qt, make sure
+  that the development files for \c libudev and \c libinput are available. If you require keyboard
+  support, then \c xkbcommon is also necessary. With \c eglfs and \c linuxfb, no further actions
+  are necessary as these plugins use \c libinput by default. If \c libinput support is not
+  available or the \c QT_QPA_EGLFS_NO_LIBINPUT environment variable is set, then Qt's own \c evdev
+  handlers are used instead.
+
+  \section2 Input on eglfs and linuxfb without libinput
+
+  Parameters like the device node name can be set in the \c QT_QPA_EVDEV_MOUSE_PARAMETERS,
+  \c QT_QPA_EVDEV_KEYBOARD_PARAMETERS and \c QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS environment
+  variables; separate your entries with colons. These parameters are an alternative to passing
+  the settings in the \c{-plugin} command-line argument, and with some backends they are essential.
+  But \c eglfs and \c linuxfb use built-in input handlers so there's no separate \c {-plugin}
+  argument in use.
+
+  Additionally, the built-in input handlers can be disabled by setting
+  \c QT_QPA_EGLFS_DISABLE_INPUT (for \c eglfs) or \c QT_QPA_FB_DISABLE_INPUT (for \c linuxfb) to
+  \c 1.
+
+  \section2 Mouse
+
+  The mouse cursor shows up whenever \c QT_QPA_EGLFS_HIDECURSOR (for \c eglfs) or
+  \c QT_QPA_FB_HIDECURSOR (for \c linuxfb) isn't set and Qt's libudev-based device discovery
+  reports that at least one mouse is available. When \c libudev support is not present, the mouse
+  cursor is always displayed; unless it's explicitly disabled via the environment variable.
+
+  If Qt was configured with \c libudev support, connecting or disconnecting an input device while
+  the application is running (hot plugging) is supported. Then \c libudev development headers
+  are present in the sysroot at configure time.
+
+  The \c evdev mouse handler supports the following extra parameters:
+
+  \table
+    \header
+      \li Parameter
+      \li Description
+    \row
+      \li \c {/dev/input/...}
+      \li Specifies the name of the input device. If unspecified, Qt looks for a suitable device
+          either via \c libudev or by traversing the available nodes.
+    \row
+      \li \c nocompress
+      \li By default, input events that don't lead to changing the position compared to the last
+          Qt mouse event are compressed. A new Qt mouse event is sent only after a change in the
+          position or button state. To disable this behavior, set the \c nocompress parameter.
+    \row
+      \li \c dejitter
+      \li Specifies a jitter limit; disabled by default.
+    \row
+      \li \c grab
+      \li When set to \c 1, Qt grabs the device for exclusive use.
+    \row
+      \li \c abs
+      \li Some touchscreens report absolute coordinates and can't be differentiated from touchpads.
+          In this case, pass \c abs to indicate that the device is using absolute events.
+  \endtable
+
+  \section2 Keyboard
+
+  The \c evdev keyboard handler supports the following extra parameters:
+
+  \table
+    \header
+      \li Parameter
+      \li Description
+    \row
+      \li \c {/dev/input/...}
+      \li Specifies the name of the input device. If unspecified, Qt looks for a suitable device
+          either via \c libudev or by traversing the available nodes.
+    \row
+      \li \c {grab}
+      \li Enables grabbing the input device.
+    \row
+      \li \c {keymap}
+      \li Specifies the name of a custom keyboard map file.
+    \row
+      \li \c {enable-compose}
+      \li Enables compositing.
+    \row
+      \li \c {repeat-delay}
+      \li Sets a custom key repeat delay.
+    \row
+      \li \c {repeat-rate}
+      \li Sets a custom key repeat rate.
+  \endtable
+
+  On Embedded Linux systems that don't have their terminal sessions disabled, the behavior on a
+  key press can be confusing, as the input event is processed by the Qt application and the tty.
+  To overcome this, the following options are available:
+
+  \list
+    \li On application startup, \c EGLFS and \c LinuxFB attempt to disable the terminal keyboard
+        by setting the tty's keyboard mode to \c K_OFF. This prevents keystrokes from being sent to
+        the terminal. If the standard behavior is required, set the \c QT_QPA_ENABLE_TERMINAL_KEYBOARD
+        environment variable to \c 1. Note that this works only when the application is launched
+        from a remote console, via \c ssh for example, and the terminal keyboard input remains
+        enabled.
+    \li An alternative approach is to use the \c evdev keyboard handler's \c grab parameter by
+        passing \c{grab=1} in \c QT_QPA_EVDEV_KEYBOARD_PARAMETERS. This results in trying to get a
+        grab on the input device. If the \c grab is successful, no other components in the system
+        receive events from it, as long as the Qt application is running. This approach is more
+        suitable for applications that start remotely as it doesn't need access to the tty device.
+    \li Finally, for many specialized Embedded Linux images it doesn't make sense to have the
+        standard terminal sessions enabled in the first place. For more details on how to disable
+        these terminal sessions, refer to your build environment's Documentation. For example, when
+        generating images using the \l{Yocto Project}, unsetting \c SYSVINIT_ENABLED_GETTYS results
+        in having no \c getty process running. This means, there's no input on any of the virtual
+        terminals.
+  \endlist
+
+  If the default built-in keymap is not sufficient, you can specify a different one either via the
+  \c keymap parameter or via the eglfs-specific \l{QEglFSFunctions::loadKeymap()}{loadKeymap()}
+  function. The latter allows for switching the keymap at runtime. However, this behavior requires
+  using eglfs' built-in keyboard handler; it is not supported when the keyboard handler is
+  loaded via the \c -plugin command-line parameter.
+
+  \note Special system key combinations, such as console switching (\uicontrol{Ctrl+Alt+Fx}) or
+  zap (\uicontrol{Ctrl+Alt+Backspace}) are not currently supported and are ignored.
+
+  To generate a custom keymap, use the \c kmap2qmap utility, that can be found in the \c qttools
+  module. The source files have to be in standard Linux \c kmap format, which is understood by the
+  kernel's \c loadkeys command. \c qmap files can be generated in one of the following ways:
+
+  \list
+    \li The \l{Linux Console Tools (LCT)} project.
+    \li \l{X.org} X11 keymaps can be converted to the \c kmap format with the \c ckbcomp utility.
+    \li As \c kmap files are plain-text files, they can also be hand crafted.
+  \endlist
+
+  \c kmap2qmap is a command line program, that needs at least 2 files as parameters. The last
+  parameter is the generated \c .qmap file, while all the others are parsed as input \c .kmap
+  files. For example:
+
+  \badcode
+  kmap2qmap i386/qwertz/de-latin1-nodeadkeys.kmap include/compose.latin1.inc de-latin1-nodeadkeys.qmap
+  \endcode
+
+  \note \c kmap2qmap doesn't support all the (pseudo) symbols that the Linux kernel supports.
+  Consequently, when you convert a standard keymap, there'll be a number of warnings regarding
+  \c Show_Registers, \c Hex_A, and so on; these messages can be ignored.
+
+  \section2 Touch
+
+  While it's not necessary for modern touch screens, some resistive, single-touch touch screens may
+  require that you fallback to using \c tslib instead of relying on the Linux multi-touch protocol
+  and the event devices.
+
+  To enable \c tslib support, set the \c QT_QPA_EGLFS_TSLIB (for \c eglfs) or \c QT_QPA_FB_TSLIB
+  (for \c linuxfb) environment variable to 1. To change the device, set the \c TSLIB_TSDEVICE
+  environment variable or pass the device name on the command-line. Note that the \c tslib input
+  handler generates mouse events and supports single touch only, as opposed to \c evdevtouch which
+  generates true multi-touch QTouchEvent events too.
+
+  The \c evdev touch handler supports the following extra parameters:
+
+  \table
+    \header
+      \li Parameter
+      \li Description
+    \row
+      \li \c {/dev/input/...}
+      \li Specifies the name of the input device. If unspecified, Qt looks for a suitable device
+          either via \c libudev or by traversing the available nodes.
+    \row
+      \li \c rotate
+      \li On some touch screens the coordinates must be rotated by setting \c rotate to 90, 180,
+          or 270.
+    \row
+      \li \c invertx and \c inverty
+      \li Specifies the parameters to invert the X or Y coordinates in the input events.
+  \endtable
+
+  For example, if you pass the following values to \c QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS before
+  launching applications, you'd have an explicitly specified touch device with the coordinates
+  flipped. This is useful when the orientation of the actual screen and the touch screen don't
+  match.
+
+  \badcode
+    export QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS=/dev/input/event5:rotate=180
+  \endcode
+
+  \section2 Pen-based Tablets
+
+  The \c evdevtablet plugin provides basic support for Wacom and similar pen-based tablets. It
+  generates QTabletEvent events only. To enable it, pass \c {QT_QPA_GENERIC_PLUGINS=evdevtablet}
+  in the environment or, alternatively, pass the \c {-plugin evdevtablet} argument on the
+  command-line.
+
+  The plugin can take a device node parameter, such as \c{QT_QPA_GENERIC_PLUGINS=evdevtablet:/dev/event1},
+  if Qt's automatic device discovery (based either on \c libudev or traversing \c{/dev/input/event*})
+  isn't functional or is misbehaving.
+
+  \section2 Debug Input Devices
+
+  It's possible to print some information to the debug output by enabling the \c qt.qpa.input
+  logging rule, for example by setting the \c QT_LOGGING_RULES environment variable to
+  \c{qt.qpa.input=true}. This is useful for detecting which device is being used, or for
+  troubleshooting device discovery issues.
+
+  \section2 Use Custom Mouse Cursor Images
+
+  \c eglfs comes with its own set of 32x32-sized mouse cursor images. If these are insufficient,
+  you can provide a custom cursor atlas by setting the \c QT_QPA_EGLFS_CURSOR environment variable
+  to the name of a JSON file. This file can also be embedded into the application via
+  \l{The Qt Resource System}.
+
+  For example, an embedded cursor atlas with 8 cursor images per row can be specified as follows:
+
+  \badcode
+    {
+      "image": ":/cursor-atlas.png",
+      "cursorsPerRow": 8,
+      "hotSpots": [
+          [7, 2],
+          [12, 3],
+          [12, 12],
+          ...
+      ]
+    }
+  \endcode
+
+  Note that the images are expected to be tightly packed in the atlas; the width and height of the
+  cursors are determined based on the total image size and the \c cursorsPerRow setting. Atlases
+  must also provide an image for all of the supported cursors.
+
+*/