doc/user: add a graph of how different contexts work

Part-of: <https://gitlab.freedesktop.org/libinput/libinput/-/merge_requests/1376>

doc/user/dot/libinput-contexts.gv

@@ -0,0 +1,36 @@
+digraph stack
+{
+  compound=true;
+  splines=line;
+  rankdir="LR";
+  node [
+    shape="box";
+  ]
+
+  subgraph cluster_2 {
+	  label="Kernel";
+	  event0 [label="/dev/input/event0"];
+	  event1 [label="/dev/input/event1"];
+  }
+
+  subgraph cluster_0 {
+	  label="Compositor process";
+	  libinput [label="libinput context 1"];
+  }
+
+  subgraph cluster_1 {
+	  label="libinput debug-events";
+	  libinput2 [label="libinput context 2"];
+  }
+
+  stdout;
+
+  client [label="Wayland client"];
+
+  event0:e -> libinput:w;
+  event1:e -> libinput:w;
+  event0:e -> libinput2:w;
+  event1:e -> libinput2:w;
+  libinput -> client [ltail=cluster_0 label="Wayland protocol"];
+  libinput2 -> stdout [ltail=cluster_1];
+}

doc/user/faqs.rst

@@ -348,10 +348,14 @@ compositor. This indicates a misunderstanding of how libinput works:
 libinput is a library that converts kernel events into libinput events, much
 like ``sed`` reads data in, modifies it, and provides it to stdout.
 
-If ``sed`` is used by a shell-script, that script has full control over how
+.. graphviz:: libinput-contexts.gv
-``sed`` processes data. In this analogy, ``sed`` is libinput and the
+
-shell script is the compositor. It is not possible to write a program
+A libinput context is private to the process and cannot be modified from the
-to modify the behavior of the ``sed`` instance used inside that shell script
+outside. To use the ``sed`` analogy again: if ``sed`` is used by a
+shell-script, that script has full control over how ``sed`` processes data. In
+this analogy, ``sed`` is libinput and the shell script is the compositor. It is
+not possible to write a program to modify the behavior of the ``sed`` instance
+used inside that shell script.
 
 Writing a program that uses libinput is akin to writing a new script that
 invoke ``sed``. It will not have any effect on the original ``sed`` instance.
@@ -360,6 +364,14 @@ The only way to modify libinput's behavior is to use the configuration options
 exposed by the respective compositor. Those affect the libinput context inside
 the compositor and thus have an effect on the input device behavior.
 
+.. _faq_debug_events_not_showing_configuration:
+
+------------------------------------------------------------------------------
+Why doesn't libinput debug-events show my configuration
+------------------------------------------------------------------------------
+
+See :ref:`faq_separate_contexts`.
+
 ------------------------------------------------------------------------------
 Can I configure scroll speed?
 ------------------------------------------------------------------------------

doc/user/meson.build

@@ -95,6 +95,7 @@ src_rst = files(
 	# dot drawings
 	'dot/seats-sketch.gv',
 	'dot/seats-sketch-libinput.gv',
+	'dot/libinput-contexts.gv',
 	'dot/libinput-stack-wayland.gv',
 	'dot/libinput-stack-xorg.gv',
 	'dot/libinput-stack-gnome.gv',