Initial move of some wiki contents into main documentation.

This moves some information from the wiki into the main generated doxygen
documenation. It is fairly rought but includes examples for inline and
stand-alone diagrams, linking to external HTML pages, etc.

Among other things, it allows for better cross-referencing into the
main doxygen contents and thus for overall shorter documentation.

Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com>
Reviewed-by: Peter Hutterer <peter.hutterer@who-t.net>
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

configure.ac

@@ -76,6 +76,15 @@ else
 fi
 AM_CONDITIONAL([HAVE_DOXYGEN], [test "x$have_doxygen" = "xyes"])
 
+AC_PATH_PROG(DOT, dot)
+if test "x$DOT" = "x"; then
+	AC_MSG_WARN([Graphviz's dot not found - required for documentation])
+	have_dot="no"
+else
+	have_dot="yes"
+fi
+AM_CONDITIONAL([HAVE_DOT], [test "x$have_dot" = "xyes"])
+
 AC_ARG_ENABLE(event-gui,
 	      AS_HELP_STRING([--enable-event-gui], [Build the GUI event viewer (default=auto)]),
 	      [build_eventgui="$enableval"],

doc/Makefile.am

@@ -6,10 +6,20 @@ noinst_DATA = html/index.html
 
 header_files = \
 	$(top_srcdir)/src/libinput.h \
-	$(top_srcdir)/README.txt
+	$(top_srcdir)/README.txt \
+	$(srcdir)/absolute-axes.dox \
+	$(srcdir)/clickpad-softbuttons.dox \
+	$(srcdir)/seats.dox \
+	$(srcdir)/t440-support.dox
 
-html/index.html: libinput.doxygen $(header_files)
-	$(AM_V_GEN)$(DOXYGEN) $<
+diagram_files = \
+	$(srcdir)/dot/seats-sketch.gv
+
+html/index.html: libinput.doxygen $(header_files) $(diagram_files)
+	$(AM_V_GEN)(cat $<; \
+          echo "INPUT = $(header_files)"; \
+          echo "DOTFILE_DIRS = $(srcdir)/dot"; \
+          ) | $(DOXYGEN) -
 
 clean-local:
 	$(AM_V_at)rm -rf html

doc/absolute-axes.dox

@@ -0,0 +1,64 @@
+/**
+@page absolute_axes Absolute Axes in libinput
+
+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.
+Compare this to relative devices (e.g. a mouse) that can only detect
+directional data, not positional data.
+
+libinput supports three types of devices with absolute axes:
+
+ - multi-touch screens
+ - single-touch screens
+ - graphics tablets (currently WIP)
+
+Touchpads are technically absolute devices, but the axis values are converted
+to directional motion and posted 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"
+
+@section absolute_axes_nonorm Why x/y coordinates are not normalized
+
+x/y are not given in @ref motion_normalization "normalized coordinates"
+([0..1]) for one simple reason: the aspect ratio of virtually all current
+devices is something other than 1:1. A normalized axes thus is only useful to
+determine that the stylus is e.g. at 78% from the left, 34% from the top of
+the device. Without knowing the per-axis resolution, these numbers are
+meaningless. Worse, calculation based on previous coordinates is simply wrong:
+a movement from 0/0 to 50%/50% is not a 45% degree line.
+
+This could be alleviated by providing resolution and information about the
+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

@@ -0,0 +1,67 @@
+/**
+@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
+touchpad with the above feature as Clickpad, regardless of the manufacturer.
+
+A clickpad is always marked with the INPUT_PROP_BUTTONPAD property. Note that
+there is a type of clickpads that have the top section marked as software
+buttons as well. See @ref t440_support "Lenovo *40 series touchpad support"
+for details on the top software button.
+
+To perform a right-click on a Clickpad, two methods are available in libinput:
+
+- on Apple touchpads, a right click is performed by two fingers on the
+  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
+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.
+
+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 {
+  clickpad [
+      shape = "record";
+    label = "{\nMain\nArea\n\n|{LEFT|RIGHT}}";
+  ]
+}
+@enddot
+
+The size of the buttons is hardware dependent.
+
+- if fingers are only down in the main area, a left click is generated
+- if a finger is in the right area when the physical click happens, a right
+  click is generated
+- if fingers are in both the left and right area, a middle click is generated
+- fingers in the main area are not considered for right or middle click
+  generation
+- if a finger starts in the main 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
+  moves out of the button area it will control the pointer (if it's the first
+  finger to do so)
+- once a finger has moved out of the button area, it cannot move back in and
+  trigger a right/middle button click
+- a release event releases the buttons logically down, regardless of the
+  current finger position
+
+*/

doc/dot/seats-sketch.gv

@@ -0,0 +1,41 @@
+digraph seats
+{
+  rankdir="BT";
+  node [
+    shape="box";
+  ]
+
+  kernel [label="Kernel"];
+
+  event0 [URL="\ref libinput_event"];
+  event1 [URL="\ref libinput_event"];
+  event2 [URL="\ref libinput_event"];
+  event3 [URL="\ref libinput_event"];
+
+  pseat0 [label="phys seat0"; URL="\ref libinput_seat_get_physical_name"];
+  pseat1 [label="phys seat1"; URL="\ref libinput_seat_get_physical_name"];
+
+  lseatA [label="log seat A"; URL="\ref libinput_seat_get_logical_name"];
+  lseatB [label="log seat B"; URL="\ref libinput_seat_get_logical_name"];
+  lseatC [label="log seat C"; URL="\ref libinput_seat_get_logical_name"];
+
+  ctx1 [label="libinput context 1"; URL="\ref libinput"];
+  ctx2 [label="libinput context 2"; URL="\ref libinput"];
+
+  kernel -> event0
+  kernel -> event1
+  kernel -> event2
+  kernel -> event3
+
+  event0 -> pseat0
+  event1 -> pseat0
+  event2 -> pseat0
+  event3 -> pseat1
+
+  pseat0 -> ctx1
+  pseat1 -> ctx2
+
+  ctx1 -> lseatA
+  ctx1 -> lseatB
+  ctx2 -> lseatC
+}

doc/seats.dox

@@ -0,0 +1,10 @@
+/**
+@page seats Seats
+
+@section seats_overview Overview
+
+@dotfile seats-sketch.gv
+
+Details pending.
+
+*/

doc/t440-support.dox

@@ -0,0 +1,66 @@
+/**
+@page t440_support Lenovo *40 series touchpad support
+
+@section t440_support_overview Overview
+
+The Lenovo *40 series introduced a new type of touchpad. Previously, all
+laptops had a separate set of physical buttons for the
+<a href="http://en.wikipedia.org/wiki/Pointing_stick">trackstick</a>. This
+series removed these buttons, relying on a software emulation of the top
+section of the touchpad. This is visually marked on the trackpad itself,
+approximately like this:
+
+@dot
+digraph G {
+  subgraph cluster_0 {
+    margin="0";
+
+    clickpad [
+      shape = "record";
+      color = "none";
+    label = "{{LLLLLLLLLL|MMMMM|RRRRRRRRR}|\n\n\n\n\n\n\n\n|{LLLLLLLL|          |RRRRRRRR}}";
+    ]
+  }
+}
+@enddot
+
+The below is a list of what is needed for support of these devices. This page
+only covers the top software buttons, the bottom button behavior is covered in
+@ref clickpad_softbuttons "Clickpad software buttons".
+
+@section t440_support_btn_size Size of the buttons
+
+The approximate size of the top software buttons is 8% of the touchpad's
+announced range, starting from the top. Note that a
+<a href="https://lkml.org/lkml/2014/3/7/722">kernel patch</a> is required to
+get the right ranges.
+
+The size of the left and right buttons is approximately 42%, 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
+buttons are not replacement buttons for the bottom area but have their own
+behaviour. They do not work for click-and-drag.
+
+If the finger starts inside the top area and moves outside the button area
+without the physical button being down, movement may start.
+
+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
+(e.g. by a disable-while-typing feature).
+
+@section t440_support_identification Identification
+
+The touchpads can be identified by the PNPID, or by a DMI match
+
+- Helix: PnPID: <b>LEN0033</b>, DMI substring match <em>"Helix"</em>
+- 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>
+
+*/