doc: add a page "what is libinput"

This will eventually feature the architecture diagrams, etc. But for now it's
mostly just a list of what will be and what won't be supported.

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

3 files changed, 58 insertions, 1 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index a92d791..de4f4a1 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -29,7 +29,8 @@ header_files = \
 	$(srcdir)/test-suite.dox \
 	$(srcdir)/tools.dox \
 	$(srcdir)/touchpad-jumping-cursors.dox \
-	$(srcdir)/touchpads.dox
+	$(srcdir)/touchpads.dox \
+	$(srcdir)/what-is-libinput.dox
 
 diagram_files = \
 	$(srcdir)/dot/seats-sketch.gv \
diff --git a/doc/page-hierarchy.dox b/doc/page-hierarchy.dox
index 6f1a4bc..ebfb65c 100644
--- a/doc/page-hierarchy.dox
+++ b/doc/page-hierarchy.dox
@@ -30,6 +30,7 @@
 
 @page misc Users
 
+- @subpage what_is_libinput
 - @subpage faq
 - @subpage tools
 - @subpage reporting_bugs
@@ -39,6 +40,7 @@
 Contributions to libinput are always welcome. See the links below for
 specific documentation.
 
+- @subpage what_is_libinput
 - @subpage contributing
 - @subpage building_libinput
 - @subpage test-suite
diff --git a/doc/what-is-libinput.dox b/doc/what-is-libinput.dox
new file mode 100644
index 0000000..f361f0a
--- /dev/null
+++ b/doc/what-is-libinput.dox
@@ -0,0 +1,54 @@
+/**
+
+@page what_is_libinput What is libinput?
+
+This page describes what libinput is, but more importantly it also describes
+what libinput is **not**.
+
+libinput is an input stack to be used by those applications that need full
+input device processing by commonly used input devices. That includes mice,
+keyboards, touchpads, touchscreens and graphics tablets. libinput handles
+device-specific quirks and provides an easy-to-use interface to receive
+events from devices.
+
+libinput is designed to handle all input devices available on a system. It
+is possible to limit the devices that employ libinput. For example, the use
+of xf86-input-libinput depends on xorg.conf snippets for specific
+devices. But libinput works best if it handles all input devices as this
+allows for cross-device monitoring of events and smarter handling of
+features that affect multiple devices.
+
+libinput restricts device-specific features to applicable devices only.
+Devices with specific hardware properties may expose extra features, but
+these features are not made available on other devices, even where it may be
+possible to do so. One example for this are the top software buttons on the
+touchpad in the Lenovo T440 and similar devices. While there may be
+use-cases for providing top software buttons on other devices, libinput does
+not do so.
+
+libinput is **not** a project to support experimental devices. Unless a
+device is commonly available off-the-shelf, libinput will not support this
+device. libinput can serve as a useful base for getting experimental devices
+enabled and reduce the amount of boilerplate required. But such support will
+not land in libinput master until the devices are commonly available.
+
+libinput is **not** a box of legos. It does not provide the pieces to
+assemble a selection of features. Many features can be disabled through
+configuration options, but some features are hardcoded or hardcoded on some
+devices. This usually matches the intended use of the device. There are
+plenty of use-cases to provide out-of-the-ordinary features, but libinput is
+not the place to support these.
+
+libinput is **not** a showcase for features. There are a lot of potential
+features that could be provided on input devices. But unless they have
+common usage, libinput is not the place to implement them. Every feature
+multiplies the maintenance effort, any feature that is provided but unused
+is a net drain on the already sparse developer resources libinput has
+available.
+
+libinput is boring. It does not intend to break new grounds on how devices
+are handled. Instead, it takes best practice and the common use-cases and
+provides it in an easy-to-consume package for compositors or other processes
+that need those interactions typically expected by users.
+
+*/