From bcd9b4d3ca7646dd4c13144b3e8ae4e2d8963ef4 Mon Sep 17 00:00:00 2001
From: Peter Hutterer <peter.hutterer@who-t.net>
Date: Tue, 15 May 2018 14:18:46 +1000
Subject: [PATCH] Update the README and the graphs showing libinput in the
 stack

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
---
 README.md                         | 37 ++++++++++++++++---------------
 doc/dot/libinput-stack-wayland.gv | 22 ++++++++++++------
 doc/dot/libinput-stack-xorg.gv    | 24 ++++++++++++++------
 3 files changed, 51 insertions(+), 32 deletions(-)

diff --git a/README.md b/README.md
index dd670ce6..e9259fc6 100644
--- a/README.md
+++ b/README.md
@@ -1,39 +1,40 @@
 libinput
 ========
 
-libinput is a library that handles input devices for display servers and other
-applications that need to directly deal with input devices.
+libinput is a library that provides a full input stack for display servers
+and other applications that need to handle input devices provided by the
+kernel.
 
-It provides device detection, device handling, input device event processing
-and abstraction so minimize the amount of custom input code the user of
-libinput need to provide the common set of functionality that users expect.
-Input event processing includes scaling touch coordinates, generating
-pointer events from touchpads, pointer acceleration, etc.
-
-libinput originates from
-[weston](http://cgit.freedesktop.org/wayland/weston/), the Wayland reference
-compositor.
+libinput provides device detection, event handling and abstraction so
+minimize the amount of custom input code the user of libinput need to
+provide the common set of functionality that users expect. Input event
+processing includes scaling touch coordinates, generating
+relative pointer events from touchpads, pointer acceleration, etc.
 
 Architecture
 ------------
 
-libinput is not used directly by applications, rather it is used by the
-xf86-input-libinput X.Org driver or wayland compositors. The typical
-software stack for a system running Wayland is:
+libinput is not used directly by applications. Think of it more as a device
+driver than an application library. It is used by the xf86-input-libinput
+X.Org driver or Wayland compositors. The typical software stack for a system
+running Wayland is:
 
 @dotfile libinput-stack-wayland.gv
 
-Where the Wayland compositor may be Weston, mutter, KWin, etc. Note that
+The Wayland compositor may be Weston, mutter, KWin, etc. Note that
 Wayland encourages the use of toolkits, so the Wayland client (your
 application) does not usually talk directly to the compositor but rather
-employs a toolkit (e.g. GTK) to do so.
+employs a toolkit (e.g. GTK) to do so. The Wayland client does not know
+whether libinput is in use.
 
 The simplified software stack for a system running X.Org is:
 
 @dotfile libinput-stack-xorg.gv
 
-Again, on a modern system the application does not usually talk directly to
-the X server using Xlib but rather employs a toolkit to do so.
+libinput is not employed directly by the X server but by the
+xf86-input-libinput driver instead. That driver is loaded by the server
+on demand, depending on the xorg.conf.d configuration snippets. The X client
+does not know whether libinput is in use.
 
 Source code
 -----------
diff --git a/doc/dot/libinput-stack-wayland.gv b/doc/dot/libinput-stack-wayland.gv
index 20b334ea..7ef67466 100644
--- a/doc/dot/libinput-stack-wayland.gv
+++ b/doc/dot/libinput-stack-wayland.gv
@@ -1,17 +1,25 @@
 digraph stack
 {
+  compound=true;
   rankdir="LR";
   node [
     shape="box";
   ]
 
-  kernel [label="Kernel"];
+  subgraph cluster_2 {
+	  label="Kernel";
+	  event0 [label="/dev/input/event0"]
+	  event1 [label="/dev/input/event1"]
+  }
 
-  libinput;
-  compositor [label="Wayland Compositor"];
-  client [label="Wayland Client"];
+  subgraph cluster_0 {
+	  label="Compositor process";
+	  libinput;
+  }
 
-  kernel -> libinput
-  libinput -> compositor
-  compositor -> client
+  client [label="Wayland client"];
+
+  event0 -> libinput;
+  event1 -> libinput;
+  libinput -> client [ltail=cluster_0 label="Wayland protocol"];
 }
diff --git a/doc/dot/libinput-stack-xorg.gv b/doc/dot/libinput-stack-xorg.gv
index e50f2418..faa94481 100644
--- a/doc/dot/libinput-stack-xorg.gv
+++ b/doc/dot/libinput-stack-xorg.gv
@@ -1,19 +1,29 @@
 digraph stack
 {
+  compound=true;
   rankdir="LR";
   node [
     shape="box";
   ]
 
-  kernel [label="Kernel"];
+  subgraph cluster_2 {
+	  label="Kernel";
+	  event0 [label="/dev/input/event0"]
+	  event1 [label="/dev/input/event1"]
+  }
+
+  subgraph cluster_0 {
+	  label="X server process";
+	  subgraph cluster_1 {
+		  label="xf86-input-libinput"
+		  libinput;
+	  }
+  }
 
   libinput;
-  xf86libinput [label="xf86-input-libinput"];
-  xserver [label="X Server"];
   client [label="X11 client"];
 
-  kernel -> libinput
-  libinput -> xf86libinput
-  xf86libinput -> xserver
-  xserver -> client
+  event0 -> libinput;
+  event1 -> libinput;
+  libinput -> client [ltail=cluster_0 label="X protocol"];
 }