doc/user: more fixes including adding a device-types section

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

11 files changed, 86 insertions, 37 deletions

diff --git a/doc/user/button_debouncing.rst b/doc/user/button_debouncing.rst
index 3630423b..47be1d2c 100644
--- a/doc/user/button_debouncing.rst
+++ b/doc/user/button_debouncing.rst
@@ -48,7 +48,7 @@ correspond to the buttons 'pressed' and 'released' states, respectively.
 .. figure:: button-debouncing-wave-diagram.svg
     :align: center
 
-    Diagram illustrating button debouncing"
+    Diagram illustrating button debouncing
 
 
 Some devices send events in bursts, erroneously triggering the button
diff --git a/doc/user/device-configuration-via-udev.rst b/doc/user/device-configuration-via-udev.rst
index f484befa..eac1c409 100644
--- a/doc/user/device-configuration-via-udev.rst
+++ b/doc/user/device-configuration-via-udev.rst
@@ -136,7 +136,8 @@ Model-specific configuration
 ------------------------------------------------------------------------------
 
 As of libinput 1.12, model-specific configuration is stored in the
-:ref:`device-quirks` and not in the hwdb anymore. Please see @ref device-quirks for
+:ref:`device-quirks` and not in the hwdb anymore. Please see
+:ref:`device-quirks` for
 details.
 
 .. _model_specific_configuration_x220fw81:
diff --git a/doc/user/palm-detection.rst b/doc/user/palm-detection.rst
index df869c8e..2c650430 100644
--- a/doc/user/palm-detection.rst
+++ b/doc/user/palm-detection.rst
@@ -108,7 +108,8 @@ tapping motion, it does not generate an emulated button event. Touch 'D'
 likewise occurs within the exclusion zone but in the bottom half. libinput
 will generate a button event for this touch.
 
-@image html palm-detection.svg
+.. figure:: palm-detection.svg
+    :align: center
 
 .. _trackpoint-disabling:
 
@@ -200,7 +201,8 @@ thumb hanging mostly off the touchpad will have a small surface area.
 libinput has a definitive thumb zone where any touch is considered a resting
 thumb.
 
-@image html thumb-detection.svg
+.. figure:: thumb-detection.svg
+    :align: center
 
 The picture above shows the two detection areas. In the larger (light red)
 area, a touch is labelled as thumb when it exceeds a device-specific
diff --git a/doc/user/pointer-acceleration.rst b/doc/user/pointer-acceleration.rst
index a25782a1..fafa4ddf 100644
--- a/doc/user/pointer-acceleration.rst
+++ b/doc/user/pointer-acceleration.rst
@@ -91,7 +91,7 @@ and after :ref:`motion_normalization` is applied.
 .. figure:: ptraccel-linear.svg
     :align: center
 
-    Linear pointer acceleration"
+    Linear pointer acceleration
 
 The image above shows the linear pointer acceleration settings at various
 speeds. The line for 0.0 is the default acceleration curve, speed settings
@@ -117,7 +117,7 @@ coordinates (see :ref:`motion_normalization`).
 .. figure:: ptraccel-low-dpi.svg
     :align: center
 
-    Pointer acceleration for low-dpi devices"
+    Pointer acceleration for low-dpi devices
 
 The image above shows the default pointer acceleration curve for a speed of
 0.0 at different DPI settings. A device with low DPI has the acceleration
@@ -138,7 +138,7 @@ deceleration factor.
 .. figure:: ptraccel-touchpad.svg
     :align: center
 
-    Pointer acceleration curve for touchpads"
+    Pointer acceleration curve for touchpads
 
 The image above shows the touchpad acceleration profile in comparison to the
 :ref:`ptraccel-linear`. The shape of the curve is identical but vertically squashed.
@@ -171,7 +171,7 @@ consistent behavior across different touchpad devices.
 .. figure:: ptraccel-trackpoint.svg
     :align: center
 
-    Pointer acceleration curves for trackpoints"
+    Pointer acceleration curves for trackpoints
 
 The image above shows the trackpoint acceleration profile for the speed in
 units/ms.
diff --git a/doc/user/scrolling.rst b/doc/user/scrolling.rst
index 28b164b5..92cfdbc8 100644
--- a/doc/user/scrolling.rst
+++ b/doc/user/scrolling.rst
@@ -5,14 +5,14 @@ Scrolling
 ==============================================================================
 
 libinput supports three different types of scrolling methods:
-:ref:`twofinger_scrolling`, @ref edge_scrolling and @ref button_scrolling. Some
-devices support multiple methods, though only one can be enabled at a time.
-As a general overview:
+:ref:`twofinger_scrolling`, :ref:`edge_scrolling` and
+:ref:`button_scrolling`. Some devices support multiple methods, though only
+one can be enabled at a time. As a general overview:
 
 - touchpad devices with physical buttons below the touchpad support edge and
   two-finger scrolling
-- touchpad devices without physical buttons (:ref:`clickpad_softbuttons`
-  "clickpads") support two-finger scrolling only
+- touchpad devices without physical buttons (:ref:`ClickPads <clickpad_softbuttons>`)
+  support two-finger scrolling only
 - pointing sticks provide on-button scrolling by default
 - mice and other pointing devices support on-button scrolling but it is not
   enabled by default
@@ -50,7 +50,7 @@ vertically or horizontally.
 .. figure:: twofinger-scrolling.svg
     :align: center
 
-    Vertical and horizontal two-finger scrolling"
+    Vertical and horizontal two-finger scrolling
 
 For scrolling to trigger, a built-in distance threshold has to be met but once
 engaged any movement will scroll. In other words, to start scrolling a
@@ -79,7 +79,7 @@ scroll).
 .. figure:: edge-scrolling.svg
     :align: center
 
-    Vertical and horizontal edge scrolling"
+    Vertical and horizontal edge scrolling
 
 Due to the layout of the edges, diagonal scrolling is not possible. The
 behavior of edge scrolling using both edges at the same time is undefined.
@@ -105,7 +105,7 @@ scroll events when the trackstick's middle mouse button is held down.
 .. figure:: button-scrolling.svg
     :align: center
 
-    Button scrolling"
+    Button scrolling
 
 The button may be changed with
 **libinput_device_config_scroll_set_button()** but must be on the same device as
diff --git a/doc/user/t440-support.rst b/doc/user/t440-support.rst
index 4dc485c0..1fc6e1f7 100644
--- a/doc/user/t440-support.rst
+++ b/doc/user/t440-support.rst
@@ -24,7 +24,7 @@ the respective area:
 .. figure:: top-software-buttons.svg
     :align: center
 
-    Left, right and middle-button click with top software button areas"
+    Left, right and middle-button click with top software button areas
 
 This page only covers the top software buttons, the bottom button behavior
 is covered in :ref:`Clickpad software buttons <clickpad_softbuttons>`.
diff --git a/doc/user/tablet-support.rst b/doc/user/tablet-support.rst
index 0be0d9ff..104ea448 100644
--- a/doc/user/tablet-support.rst
+++ b/doc/user/tablet-support.rst
@@ -12,7 +12,7 @@ Apple iPad.
 .. figure:: tablet.svg
     :align: center
 
-    Illustration of a graphics tablet"
+    Illustration of a graphics tablet
 
 .. _tablet-tools:
 
@@ -36,7 +36,7 @@ across multiple kernel devices.
 .. figure:: tablet-interfaces.svg
     :align: center
 
-    Difference between Pad and Tool buttons"
+    Difference between Pad and Tool buttons
 
 Touch events on the tablet integrated into a screen itself are exposed
 through the **LIBINPUT_DEVICE_CAP_TOUCH** capability. Touch events on a
@@ -118,7 +118,7 @@ additionally provide tilt information along the x and y axis.
 .. figure:: tablet-axes.svg
     :align: center
 
-    Illustration of the distance, pressure and tilt axes"
+    Illustration of the distance, pressure and tilt axes
 
 The granularity and precision of the distance and pressure axes varies
 between tablet devices and cannot usually be mapped into a physical unit.
@@ -258,7 +258,7 @@ the caller to ignore these events.
 .. figure:: tablet-out-of-bounds.svg
     :align: center
 
-    Illustration of the out-of-bounds area on a tablet"
+    Illustration of the out-of-bounds area on a tablet
 
 In the image above, the display area is shown in black. The red area around
 the display illustrates the sensor area that generates input events. Events
@@ -321,7 +321,7 @@ point.
 .. figure:: tablet-left-handed.svg
     :align: center
 
-    Tablet axes in right- and left-handed mode"
+    Tablet axes in right- and left-handed mode
 
 Pad buttons are not affected by left-handed mode; the number of each button
 remains the same even when the perceived physical location of the button
@@ -377,7 +377,7 @@ device.
 .. figure:: tablet-intuos-modes.svg
     :align: center
 
-    Modes on an Intuos Pro-like tablet"
+    Modes on an Intuos Pro-like tablet
 
 In the image above, the Intuos Pro-like tablet provides 4 LEDs to indicate
 the currently active modes. The button inside the touch ring cycles through
@@ -392,7 +392,7 @@ and all subsequent events.
 .. figure:: tablet-cintiq24hd-modes.svg
     :align: center
 
-    Modes on an Cintiq 24HD-like tablet"
+    Modes on an Cintiq 24HD-like tablet
 
 In the image above, the Cintiq 24HD-like tablet provides 3 LEDs on each side
 of the tablet to indicate the currently active mode for that group of
diff --git a/doc/user/tapping.rst b/doc/user/tapping.rst
index 48279f20..85fdc1a1 100644
--- a/doc/user/tapping.rst
+++ b/doc/user/tapping.rst
@@ -60,7 +60,7 @@ Note that drag lock only applies if tap-and-drag is be enabled.
 .. figure:: tap-n-drag.svg
     :align: center
 
-    Tap-and-drag process"
+    Tap-and-drag process
 
 The above diagram explains the process, a tap (a) followed by a finger held
 down (b) starts the drag process and logically holds the left mouse button
diff --git a/doc/user/touchpads.rst b/doc/user/touchpads.rst
index 5755982d..f6f44759 100644
--- a/doc/user/touchpads.rst
+++ b/doc/user/touchpads.rst
@@ -49,7 +49,7 @@ whole, i.e. a user presses down on the touch area and triggers a physical
 click. Clickpads thus only provide a single button, everything else needs to
 be software-emulated. See :ref:`clickpad_softbuttons` for more information.
 
-Clickpads are labelled by the kernel with the @c INPUT_PROP_BUTTONPAD input
+Clickpads are labelled by the kernel with the **INPUT_PROP_BUTTONPAD** input
 property.
 
 .. _touchpads_buttons_forcepads:
@@ -86,9 +86,9 @@ Single-touch touchpads
 Single-finger touchpads can track a single touchpoint. Most single-touch
 touchpads can also detect three fingers on the touchpad, but no positional
 information is provided for those. In libinput, these touches are termed
-"fake touches". The kernel sends @c BTN_TOOL_DOUBLETAP,
-@c BTN_TOOL_TRIPLETAP, @c BTN_TOOL_QUADTAP and @c BTN_TOOL_QUINTTAP events when
-multiple fingers are detected.
+"fake touches". The kernel sends **BTN_TOOL_DOUBLETAP**,
+**BTN_TOOL_TRIPLETAP**, **BTN_TOOL_QUADTAP** and **BTN_TOOL_QUINTTAP**
+events when multiple fingers are detected.
 
 .. _touchpads_touch_mt:
 
@@ -106,10 +106,10 @@ provide an ellipse and the orientation of the ellipse for each touch point.
 Other touchpads provide a pressure value for each touch point (see
 :ref:`touchpads_pressure_handling`).
 
-Note that the kernel sends @c BTN_TOOL_DOUBLETAP,
-@c BTN_TOOL_TRIPLETAP, @c BTN_TOOL_QUADTAP and @c BTN_TOOL_QUINTTAP events for
-all touches for backwards compatibility. libinput ignores these events if
-the touchpad can track touches correctly.
+Note that the kernel sends **BTN_TOOL_DOUBLETAP**,
+**BTN_TOOL_TRIPLETAP**, **BTN_TOOL_QUADTAP** and **BTN_TOOL_QUINTTAP**
+events for all touches for backwards compatibility. libinput ignores these
+events if the touchpad can track touches correctly.
 
 .. _touchpads_touch_partial_mt:
 
@@ -125,8 +125,8 @@ five.
 
 The number of slots may limit which features are available in libinput.
 Any device with two slots can support two-finger scrolling, but
-:ref:`thumb-detection` or @ref palm_detection may be limited if only two slots are
-available.
+:ref:`thumb-detection` or :ref:`palm_detection` may be limited if only two
+slots are available.
 
 .. _touchpads_touch_semi_mt:
 
@@ -144,7 +144,7 @@ Many semi-mt touchpads also have a lower resolution for the second touch, or
 both touches. This may limit some features such as :ref:`gestures` or
 :ref:`scrolling`.
 
-Semi-mt are labelled by the kernel with the @c INPUT_PROP_SEMI_MT input
+Semi-mt are labelled by the kernel with the **INPUT_PROP_SEMI_MT** input
 property.
 
 .. _touchpads_mis:
diff --git a/doc/user/trackpoints.rst b/doc/user/trackpoints.rst
index 86aa6432..917a8ea3 100644
--- a/doc/user/trackpoints.rst
+++ b/doc/user/trackpoints.rst
@@ -12,7 +12,7 @@ the space bar.
 .. figure:: button-scrolling.svg
     :align: center
 
-    A trackpoint"
+    A trackpoint
 
 libinput always treats the buttons below the space bar as the buttons that
 belong to the trackpoint even on the few laptops where the buttons are not
diff --git a/doc/user/what-is-libinput.rst b/doc/user/what-is-libinput.rst
index ecb97d3c..123f0967 100644
--- a/doc/user/what-is-libinput.rst
+++ b/doc/user/what-is-libinput.rst
@@ -106,3 +106,49 @@ does not know whether libinput is in use.
 libinput and xf86-input-libinput are not a requirement, the driver will only
 handle those devices explicitly assigned through an xorg.conf.d snippets. It
 is possible to mix xf86-input-libinput with other X.Org drivers.
+
+------------------------------------------------------------------------------
+Device types
+------------------------------------------------------------------------------
+
+libinput handles all common devices used to interact with a desktop system.
+This includes mice, keyboards, touchscreens, touchpads and graphics tablets.
+libinput does not expose the device type to the caller, it solely provides
+capabilities and the attached features (see
+`this blog post <https://who-t.blogspot.com/2015/06/libinput-and-lack-of-device-types.html>`_).
+
+For example, a touchpad in libinput is a device that provides pointer
+events, gestures and has a number of :ref:`config_options` such as
+:ref:`tapping`. A caller may present the device as touchpad to the user, or
+simply as device with a config knob to enable or disable tapping.
+
+..............................................................................
+Handled device types
+..............................................................................
+
+- :ref:`Touchpads`
+- Touchscreens
+- Mice
+- Keyboards
+- Virtual absolute pointing devices such as those used by QEMU or VirtualBox
+- Switches (Lid Switch and Tablet Mode switch)
+- Graphics tablets
+- :ref:`Trackpoints`
+
+If a device falls into one of the above categories but does not work as
+expected, please :ref:`file a bug <reporting_bugs>`.
+
+..............................................................................
+Unhandled device types
+..............................................................................
+
+libinput does not handle some devices. The primary reason is that these
+device have no clear interaction with a desktop environment.
+
+Joysticks:
+     Joysticks have one or more axes and one or more buttons. Beyond that it is
+     difficult to find common ground between joysticks and much of the
+     interaction is application-specific, not system-specific. libinput does not
+     provide support for joysticks for that reason, any abstraction libinput
+     would provide for joysticks would be so generic that libinput would
+     merely introduce complexity and processing delays for no real benefit.