doc/user: more documentation cleanups and fixes

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

doc/user/button_debouncing.rst

@@ -32,8 +32,8 @@ immediately and most release events are delivered immediately. The
 does not enable this method unless a faulty event sequence is detected. A
 message is printed to the log when spurious deboucing was detected.
 
-Note that libinput's debouncing intended to correct hardware damage or
-substandard hardware. Debouncing is also used as an accessibility feature
+libinput's debouncing is supposed to correct hardware damage or
+substandard hardware. Debouncing also exists as an accessibility feature
 but the requirements are different. In the accessibility feature, multiple
 physical key presses, usually caused by involuntary muscle movement, must be
 filtered to only one key press. This feature must be implemented higher in
@@ -49,3 +49,8 @@ correspond to the buttons 'pressed' and 'released' states, respectively.
     :align: center
 
     Diagram illustrating button debouncing"
+
+
+Some devices send events in bursts, erroneously triggering the button
+debouncing detection. Please :ref:`file a bug <reporting_bugs>` if that
+occurs for your device.

doc/user/clickpad-softbuttons.rst

@@ -4,33 +4,39 @@
 Clickpad software button behavior
 ==============================================================================
 
-Clickpad is the name given to touchpads without physical buttons below the
-touchpad. Instead, the whole touchpad acts as a button and left or right
-button clicks are distinguished by the location and/or number of fingers on
-the touchpad.
-("ClickPad" is a trademark by Synaptics Inc.)[http://www.synaptics.com/en/clickpad.php]
+"Clickpads" are touchpads without separate physical buttons. Instead, the
+whole touchpad acts as a button and left or right button clicks are
+distinguished by :ref:`the location of the fingers <software_buttons>` or
+the :ref:`number of fingers on the touchpad <clickfinger>`.
+"ClickPad" is a trademark by `Synaptics Inc. <http://www.synaptics.com/en/clickpad.php>`_
 but for simplicity we refer to any touchpad with the above feature as Clickpad,
 regardless of the manufacturer.
 
-A clickpad is always marked with the
+The kernel marks clickpads with the
 `INPUT_PROP_BUTTONPAD <https://www.kernel.org/doc/Documentation/input/event-codes.txt>`_
-property. To perform a right-click on a Clickpad, libinput provides
-:ref:`software_buttons` and @ref clickfinger.
+property. Without this property, libinput would not know whether a touchpad
+is a clickpad or not. To perform a right-click on a Clickpad, libinput
+provides :ref:`software_buttons` and :ref:`clickfinger`.
 
-In the page below, the term "click" shall refer to a physical button press
-and/or release of the touchpad, the term "button event" refers to the events
-generated by libinput and passed to the caller in response to a click.
+.. note:: The term "click" refers refer to a physical button press
+	  and/or release of the touchpad, the term "button event" refers to
+	  the events generated by libinput in response to a click.
 
 .. _software_buttons:
 
 ------------------------------------------------------------------------------
 Software button areas
 ------------------------------------------------------------------------------
 
-On most clickpads, this is the default behavior. The bottom of the touchpad
-is split into three distinct areas generate left, middle or right button
-events on click. The height of the button area depends on the hardware but
-is usually around 10mm.
+The bottom of the touchpad is split into three distinct areas generate left,
+middle or right button events on click. The height of the button area
+depends on the hardware but is usually around 10mm.
+
+.. figure :: software-buttons-visualized.svg
+     :align: center
+
+     The locations of the virtual button areas.
+
 
 Left, right and middle button events can be triggered as follows:
 
@@ -39,34 +45,49 @@ Left, right and middle button events can be triggered as follows:
 - if a finger is in the right area, a click generates right button events.
 - if a finger is in the middle area, a click generates middle button events.
 
-The middle button is always centered on the touchpad and smaller in size
-than the left or right button. The actual size is device-dependent though as
-many touchpads do not have visible markings for the middle button the exact
-location of the button is not visibly obvious.
-
 .. figure:: software-buttons.svg
     :align: center
 
-    Left, right and middle-button click with software button areas"
+    Left, right and middle-button click with software button areas
+
+The middle button is always centered on the touchpad and smaller in size
+than the left or right button. The actual size is device-dependent. Many
+touchpads do not have visible markings so the exact location of the button
+is unfortunately not visibly obvious.
 
-.. note:: If middle button emulation is enabled on a clickpad, only left and right
-	button areas are available. For more details, see
-	**libinput_device_config_middle_emulation_set_enabled()**.
+.. note:: If :ref:`middle button emulation <middle_button_emulation>` is
+	  enabled on a clickpad, only left and right button areas are
+	  available.
 
 If fingers are down in the main area in addition to fingers in the
 left or right button area, those fingers are are ignored.
 A release event always releases the buttons logically down, regardless of
 the current finger position
 
+.. figure:: software-buttons-thumbpress.svg
+    :align: center
+
+    Only the location of the thumb determines whether it is a left, right or
+    middle click.
+
 The movement of a finger can alter the button area behavior:
 
 - if a finger starts in the main area and moves into the software button
   area, the software buttons do not apply to that finger
-- a finger in the software button area does not move the pointer
-- if a finger moves out out of the button area it will control the pointer
-  if it's the first finger in the main area
 - once a finger has moved out of the button area, it cannot move back in and
   trigger a right or middle button event
+- a finger moving within the software button area does not move the pointer
+- once a finger moves out out of the button area it will control the
+  pointer (this only applies if there is no other finger down on the
+  touchpad)
+
+.. figure:: software-buttons-conditions.svg
+    :align: center
+
+    **Left:** moving a finger into the right button area does not trigger a
+    right-button click.
+    **Right:** moving within the button areas does not generate pointer
+    motion.
 
 On some touchpads, notably the 2015 Lenovo X1 Carbon 3rd series, the very
 bottom end of the touchpad is outside of the sensor range but it is possible
@@ -90,7 +111,7 @@ software-defined button areas.
 .. figure:: clickfinger.svg
     :align: center
 
-    One, two and three-finger click with Clickfinger behavior"
+    One, two and three-finger click with Clickfinger behavior
 
 On some touchpads, libinput imposes a limit on how the fingers may be placed
 on the touchpad. In the most common use-case this allows for a user to
@@ -100,18 +121,12 @@ the touchpad.
 .. figure:: clickfinger-distance.svg
     :align: center
 
-    Illustration of the distance detection algorithm"
+    Illustration of the distance detection algorithm
 
 In the illustration above the red area marks the proximity area around the
 first finger. Since the thumb is outside of that area libinput considers the
 click a single-finger click rather than a two-finger click.
 
-Clickfinger configuration can be enabled through the
-**libinput_device_config_click_set_method()** call. If clickfingers are
-enabled on a touchpad with top software buttons, the top area will keep
-acting as softbuttons for use with the trackpoint. Clickfingers will be used
-everywhere else on the touchpad.
-
 .. _special_clickpads:
 
 ------------------------------------------------------------------------------

doc/user/features.rst

@@ -6,7 +6,7 @@ libinput Features
 
 Below is a list of features supported by libinput. The availability of
 features usually depends on the device type and a device's capabilties.
-Not all features are user-configurable, some rely on @see device-quirks
+Not all features are user-configurable, some rely on :ref:`device-quirks`
 to be useful.
 
 

doc/user/gestures.rst

@@ -4,42 +4,25 @@
 Gestures
 ==============================================================================
 
-libinput supports basic gestures on touchpads and other indirect input
-devices. Two types of gestures are supported: :ref:`gestures_pinch` and
-@ref gestures_swipe. Support for gestures depends on the hardware device, most
-touchpads support both gestures and any device that may send gesture events
-has the **LIBINPUT_DEVICE_CAP_GESTURE** capability set.
-
-Note that libinput **does not** support gestures on touchscreens, see
-:ref:`gestures_touchscreens`.
+libinput supports :ref:`gestures_pinch` and :ref:`gestures_swipe` on most
+modern touchpads and other indirect touch devices. Note that libinput **does
+not** support gestures on touchscreens, see :ref:`gestures_touchscreens`.
 
 .. _gestures_lifetime:
 
-------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 Lifetime of a gesture
-------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
+
+A gesture starts when the finger position and/or finger motion is
+unambiguous as to what gesture to trigger and continues until the first
+finger belonging to this gesture is lifted.
 
-A gesture's lifetime has three distinct stages: begin, update and end, each
-with their own event types. Begin is sent when the fingers are first set
-down or libinput decides that the gesture begins. For :ref:`gestures_pinch`
-this sets the initial scale. Any events changing properties of the gesture
-are sent as update events. On termination of the gesture, an end event is
-sent.
-
-A gesture includes the finger count (see
-**libinput_event_gesture_get_finger_count()**) and that finger count remains the
-same for the lifetime of a gesture. Thus, if a user puts down a fourth
-finger during a three-finger swipe gesture, libinput will end
-the three-finger gesture and, if applicable, start a four-finger swipe
-gesture. A caller may decide that those gestures are semantically identical
-and continue the two gestures as one single gesture.
-
-**LIBINPUT_EVENT_GESTURE_PINCH_BEGIN**
-**LIBINPUT_EVENT_GESTURE_PINCH_UPDATE**
-**LIBINPUT_EVENT_GESTURE_PINCH_END**
-**LIBINPUT_EVENT_GESTURE_PINCH_BEGIN**
-**LIBINPUT_EVENT_GESTURE_SWIPE_UPDATE**
-**LIBINPUT_EVENT_GESTURE_SWIPE_END**
+A single gesture cannot change the finger count. For example, if a user
+puts down a fourth finger during a three-finger swipe gesture, libinput will
+end the three-finger gesture and, if applicable, start a four-finger swipe
+gesture. A caller may however decide that those gestures are semantically
+identical Tand continue the two gestures as one single gesture.
 
 .. _gestures_pinch:
 
@@ -59,7 +42,7 @@ to the initial finger position.
 .. figure:: pinch-gestures.svg
     :align: center
 
-    The pinch and rotate gestures"
+    The pinch and rotate gestures
 
 The illustration above shows a basic pinch in the left image and a rotate in
 the right angle. Not shown is a movement of the logical center if the
@@ -85,7 +68,7 @@ gesture into an action or limit a gesture to specific directions only.
 .. figure:: swipe-gestures.svg
     :align: center
 
-    The swipe gestures"
+    The swipe gestures
 
 The illustration above shows a vertical three-finger swipe. The coordinates
 provided during the gesture are the movements of the logical center.
@@ -107,14 +90,13 @@ screen as well as the context of those virtual objects:
 .. figure:: touchscreen-gestures.svg
     :align: center
 
-    Context-sensitivity of touchscreen gestures"
+    Context-sensitivity of touchscreen gestures
 
-In this example, the finger movements are identical but in the left case
-both fingers are located within the same window, thus suggesting an attempt
-to zoom. In the right case  both fingers are located on a window border,
-thus suggesting a window movement. libinput only has knowledge of the finger
-coordinates (and even then only in device coordinates, not in screen
-coordinates) and thus cannot differentiate the two.
+In the above example, the finger movements are identical but in the left
+case both fingers are located within the same window, thus suggesting an
+attempt to zoom. In the right case  both fingers are located on a window
+border, thus suggesting a window movement. libinput has no knowledge of the
+window coordinates and thus cannot differentiate the two.
 
 .. _gestures_softbuttons:
 
@@ -124,14 +106,14 @@ Gestures with enabled software buttons
 
 If the touchpad device is a :ref:`Clickpad <touchpads_buttons_clickpads>`, it
 is recommended that a caller switches to :ref:`clickfinger`.
-Usually fingers placed in a :ref:`software button area <software_buttons>` is not
-considered for gestures, resulting in some gestures to be interpreted as
-pointer motion or two-finger scroll events.
+Usually fingers placed in a :ref:`software button area <software_buttons>`
+are not considered for gestures, resulting in some gestures to be
+interpreted as pointer motion or two-finger scroll events.
 
 .. figure:: pinch-gestures-softbuttons.svg
     :align: center
 
-    Interference of software buttons and pinch gestures"
+    Interference of software buttons and pinch gestures
 
 In the example above, the software button area is highlighted in red. The
 user executes a three-finger pinch gesture, with the thumb remaining in the
@@ -161,7 +143,7 @@ determined.
 .. figure:: gesture-2fg-ambiguity.svg
     :align: center
 
-    Ambiguity of three-finger gestures on two-finger touchpads"
+    Ambiguity of three-finger gestures on two-finger touchpads
 
 The image above illustrates this ambiguity. The index and middle finger are
 set down first, the data stream from both finger positions looks identical.

doc/user/meson.build

@@ -37,6 +37,9 @@ src_extra = [
 	'svg/ptraccel-touchpad.svg',
 	'svg/ptraccel-trackpoint.svg',
 	'svg/software-buttons.svg',
+	'svg/software-buttons-conditions.svg',
+	'svg/software-buttons-thumbpress.svg',
+	'svg/software-buttons-visualized.svg',
 	'svg/swipe-gestures.svg',
 	'svg/tablet-axes.svg',
 	'svg/tablet-cintiq24hd-modes.svg',