Improve the documentation

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

doc/absolute-axes.dox

@@ -1,5 +1,5 @@
 /**
-@page absolute_axes Absolute Axes in libinput
+@page absolute_axes Absolute axes
 
 Devices with absolute axes are those that send positioning data for an axis in
 a device-specific coordinate range, defined by a minimum and a maximum value.
@@ -12,13 +12,37 @@ libinput supports three types of devices with absolute axes:
  - single-touch screens
  - graphics tablets (currently WIP)
 
-Touchpads are technically absolute devices, but the axis values are converted
+Touchpads are technically absolute devices but libinput converts the axis values
-to directional motion and posted as relative events. Touchpads do not count
+to directional motion and posts events as relative events. Touchpads do not count
 as absolute devices in libinput.
 
 For all absolute devices in libinput, the default unit for x/y coordinates is
 in mm off the top left corner on the device, or more specifically off the
-device's sensor, see @ref index "the API doc"
+device's sensor.
+
+@section absolute_axes_handling Handling of absolute coordinates
+
+In most use-cases, absolute input devices are mapped to a single screen. For
+direct input devices such as touchscreens the aspect ratio of the screen and
+the device match. Mapping the input device position to the output position is
+thus a simple mapping between two coordinates. libinput provides the API for
+this with
+
+- libinput_event_pointer_get_absolute_x_transformed() for pointer events
+- libinput_event_touch_get_x_transformed() for touch events
+
+libinput's API only provides the call to map into a single coordinate range.
+If the coordinate range has an offset, the compositor is responsible for
+applying that offset after the mapping. For example, if the device is mapped
+to the right of two outputs, add the output offset to the transformed
+coordinate.
+
+@section absolute_axes_nores Devices without x/y resolution
+
+An absolute device that does not provide a valid resolution is considered
+buggy and must be fixed in the kernel. Some touchpad devices that do not
+provide resolution, those devices are correctly handled within libinput
+(touchpads are not absolute devices, as mentioned above).
 
 @section absolute_axes_nonorm Why x/y coordinates are not normalized
 
@@ -35,30 +59,4 @@ aspect ratio to the caller. Which shifts processing and likely errors into the
 caller for little benefit. Providing the x/y axes in mm from the outset
 removes these errors.
 
-@section absolute_axes_handling Handling of absolute coordinates
-
-In most use-cases, absolute input devices are mapped to a single screen. For
-direct input devices such as touchscreens the aspect ratio of the screen and
-the device match. Mapping the input device position to the output position is
-thus a simple mapping between two coordinates. libinput provides the API for
-this with
-
-- libinput_event_pointer_get_absolute_x_transformed() for pointer events
-- libinput_event_touch_get_x_transformed() for touch events
-
-See @ref index "the API doc" for more details.
-
-libinput's API only provides the call to map into a single coordinate range.
-If the coordinate range has an offset, the compositor is responsible for
-applying that offset after the mapping. For example, if the device is mapped
-to the right of two outputs, add the output offset to the transformed
-coordinate.
-
-@section absolute_axes_nores Devices without x/y resolution
-
-An absolute device that does not provide a valid resolution is considered
-buggy and must be fixed in the kernel. Some touchpad devices that do not
-provide resolution, those devices are correctly handled within libinput
-(touchpads are not absolute devices, as mentioned above).
-
 */

doc/clickpad-softbuttons.dox

@@ -1,41 +1,28 @@
 /**
-@page clickpad_softbuttons Clickpad Software Button behavior
+@page clickpad_softbuttons 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. <a href="http://www.synaptics.com/en/clickpad.php">"ClickPad" is
-a term coined by Synaptics Inc.</a> but for simplicity we refer to any
+a trademark by Synaptics Inc.</a> 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 INPUT_PROP_BUTTONPAD property. Note that
+A clickpad is always marked with the <a
-there is a type of clickpads that have the top section marked as software
+href="https://www.kernel.org/doc/Documentation/input/event-codes.txt">INPUT_PROP_BUTTONPAD</a> property.
-buttons as well. See @ref t440_support "Lenovo *40 series touchpad support"
+To perform a right-click on a Clickpad, libinput provides @ref
-for details on the top software button.
+software_buttons and @ref clickfinger.
 
-To perform a right-click on a Clickpad, two methods are available in libinput:
+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.
 
-- on Apple touchpads, a right click is performed by two fingers on the
+@section software_buttons Software button areas
-  touchpad while clicking, a behavior termed "clickfinger"
-- on non-Apple touchpads, a right click is performed by a finger in a
-  software-defined right button area
 
-The button behavior depends on the hardware. Some Clickpads, notably some
+On most clickpads, this is the default behavior. The bottom of the touchpad
-Cypress ones, perform right button detection in firmware and appear to
+is split in the middle to generate left or right button events on click. The
-userspace as if the touchpad had physical buttons. While physically clickpads,
+height of the button area depends on the hardware but is usually around
-these are not handled by the software and treated like traditional touchpads.
+10mm.
-
-The clickfinger behavior is subject to some restrictions:
-
-- two fingers execute a right click, three fingers a middle click
-- The Xorg synaptics driver uses 30% of the touchpad dimensions as threshold,
-  libinput does not have this restrictions. If two fingers are on the pad
-  while clicking, that is a two-finger click.
-- clickfinger behavior is only enabled on Apple touchpads
-
-The button behavior is subject to some restrictions:
-
-The button area is usually defined like this:
 
 @dot
 digraph G {
@@ -46,22 +33,48 @@ digraph G {
 }
 @enddot
 
-The size of the buttons is hardware dependent.
+Left, right and middle button events can be triggered as follows:
+- if a finger is in the main area or the left button area, a click generates
+  left button events.
+- if a finger is in the right area, a click generates right button events.
+- if there is a finger in both the left and right button area, a click
+  generates middle button events.
 
-- if fingers are only down in the main area, a left click is generated
+If fingers are down in the main area in addition to fingers in the
-- if a finger is in the right area when the physical click happens, a right
+left or right button area, those fingers are are ignored.
-  click is generated
+A release event always releases the buttons logically down, regardless of
-- if fingers are in both the left and right area, a middle click is generated
+the current finger position
-- fingers in the main area are not considered for right or middle click
+
-  generation
+The movement of a finger can alter the button area behavior:
-- if a finger starts in the main area, the software buttons do not apply to
+- if a finger starts in the main area and moves into the software button
-  that finger
+  area, the software buttons do not apply to that finger
-- a finger in the software button area does not move the pointer, but once it
+- a finger in the software button area does not move the pointer
-  moves out of the button area it will control the pointer (if it's the first
+- if a finger moves out out of the button area it will control the pointer
-  finger to do so)
+  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/middle button click
+  trigger a right or middle button event
-- a release event releases the buttons logically down, regardless of the
+
-  current finger position
+@section clickfinger Clickfinger behavior
+
+This is the default behavior on Apple touchpads.
+Here, a left, right, middle button event is generated when one, two, or
+three fingers are held down on the touchpad when a physical click is
+generated. The location of the fingers does not matter and there are no
+software-defined button areas.
+
+The Xorg synaptics driver uses 30% of the touchpad dimensions as threshold,
+libinput does not have this restriction. If two fingers are on the pad
+while clicking, that is a two-finger click.
+
+@section special_clickpads Special Clickpads
+
+The Lenovo *40 series laptops have a clickpad that provides two software button sections, one at
+the top and one at the bottom. See @ref t440_support "Lenovo *40 series touchpad support"
+for details on the top software button.
+
+Some Clickpads, notably some Cypress ones, perform right button detection in
+firmware and appear to userspace as if the touchpad had physical buttons.
+While physically clickpads, these are not handled by the software and
+treated like traditional touchpads.
 
 */

doc/seats.dox

@@ -1,6 +1,8 @@
 /**
 @page seats Seats
 
+Each device in libinput is associated with one physical seat and one logical seat.
+
 @section seats_overview Overview
 
 @dotfile seats-sketch.gv

doc/t440-support.dox

@@ -1,6 +1,9 @@
 /**
 @page t440_support Lenovo *40 series touchpad support
 
+The Lenovo *40 series emulates trackstick buttons on the top part of the
+touchpads.
+
 @section t440_support_overview Overview
 
 The Lenovo *40 series introduced a new type of touchpad. Previously, all
@@ -24,43 +27,48 @@ digraph G {
 }
 @enddot
 
-The below is a list of what is needed for support of these devices. This page
+This page only covers the top software buttons, the bottom button behavior
-only covers the top software buttons, the bottom button behavior is covered in
+is covered in @ref clickpad_softbuttons "Clickpad software buttons".
-@ref clickpad_softbuttons "Clickpad software buttons".
+
+Clickpads with a top button area are marked with the <a
+href="https://www.kernel.org/doc/Documentation/input/event-codes.txt">INPUT_PROP_TOPBUTTONPAD</a>
+property.
 
 @section t440_support_btn_size Size of the buttons
 
-The approximate size of the top software buttons is 8% of the touchpad's
+The line of the buttons is 5mm from the top edge of the touchpad,
-announced range, starting from the top. Note that a
+measurements of button presses showed that the size of the buttons needs to
-<a href="https://lkml.org/lkml/2014/3/7/722">kernel patch</a> is required to
+be approximately 10mm high to work reliable (especially when using the
-get the right ranges.
+thumb to press the button).
 
-The size of the left and right buttons is approximately 42%, the middle button
+The width of the left and right buttons is approximately 42% of the
-is centered and should be assigned approximately 16% of the touchpad width.
+touchpad's width, the middle button is centered and should be assigned
+approximately 16% of the touchpad width.
 
 @section t440_support_btn_behavior Button behavior
 
-Movement in the top button area must not generate pointer movement, these
+Movement in the top button area does not generate pointer movement. These
-buttons are not replacement buttons for the bottom area but have their own
+buttons are not replacement buttons for the bottom button area but have
-behaviour. They do not work for click-and-drag.
+their own behavior.
+Semantically attached to the trackstick device, libinput re-routes events
+from these buttons to appear through the trackstick device. The top button
+areas work even if the touchpad is disabled but will be disabled when the
+trackstick device is disabled.
 
 If the finger starts inside the top area and moves outside the button area
-without the physical button being down, movement may start.
+the finger is treated as dead and must be lifted to generate future buttons.
-
+Likewise, movement into the top button area does not trigger button events, a click
-Movement into the top button area should not trigger button events, a click
 has to start inside this area to take effect.
 
-The top button areas must work, even if the touchpad is otherwise disabled
+@section t440_support_identification Kernel support
-(e.g. by a disable-while-typing feature).
 
-@section t440_support_identification Identification
+The firmware on touchpads providing top software buttons is buggy and
+announces wrong ranges. <a href="https://lkml.org/lkml/2014/3/7/722">Kernel
+patches</a> are required; these fixes are available in kernels
+3.14.1, 3.15 and later but each touchpad needs a separate fix.
 
-The touchpads can be identified by the PNPID, or by a DMI match
+For a complete list of supported touchpads check <a
-
+href="http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/drivers/input/mouse/synaptics.c">the
-- Helix: PnPID: <b>LEN0033</b>, DMI substring match <em>"Helix"</em>
+kernel source</a> (search for "topbuttonpad_pnp_ids").
-- T540: PnPID: <b>LEN0034</b>, DMI substring match <em>"T540?"</em>
-- x240: PnPID: <b>LEN0035</b>, DMI substring match <em>"X240"</em>
-- T440: PnPID: <b>LEN0036</b>, DMI substring match <em>"T440?"</em>
-- Yoga: PnPID: <b>LEN0042</b>, DMI subString match <em>"S1Yoga"</em>
 
 */