From 6a9564c18ce70d081f2ec2fd7673ef17d75f971d Mon Sep 17 00:00:00 2001
From: Jens Peters <jp7677@gmail.com>
Date: Wed, 24 Apr 2024 20:36:51 +0200
Subject: [PATCH] docs: add mouse emulation section

Also clarify tablet button mapping restrictions.
---
 docs/labwc-config.5.scd | 28 +++++++++++++++++++++-------
 docs/rc.xml.all         | 15 +++++++++++----
 2 files changed, 32 insertions(+), 11 deletions(-)

diff --git a/docs/labwc-config.5.scd b/docs/labwc-config.5.scd
index ded6f390..26cefdb2 100644
--- a/docs/labwc-config.5.scd
+++ b/docs/labwc-config.5.scd
@@ -617,7 +617,7 @@ extending outward from the snapped edge.
 ## TABLET
 
 ```
-<tablet mapToOutput="" rotate="0">
+<tablet mapToOutput="" rotate="0" mouseEmulation="no">
   <area top="0.0" left="0.0" width="0.0" height="0.0" />
   <map button="Tip" to="Left" />
   <map button="Stylus" to="Right" />
@@ -657,21 +657,35 @@ extending outward from the snapped edge.
 	additionally setting top to "12.5", the active area is centered
 	vertically on the tablet surface.
 
+*<tablet mouseEmulation="" />* [yes|no]
+	The tablet can be forced to always use mouse emulation. This prevents
+	tablet specific restrictions, e.g. no support for drag-and-drop, but
+	also omits tablet specific features like reporting pen pressure.
+
 *<tablet><map button="" to="" />*
-	Tablet buttons emulate regular mouse buttons. If not specified
-	otherwise, the tip (Tip) is mapped to left mouse click, the first pen
-	button (Stylus) is mapped to right mouse button click and the second pen
-	button (Stylus2) emulates a middle mouse button click.
+	Pen buttons emulate regular mouse buttons. If not specified
+	otherwise, the first pen button (Stylus) is mapped to right mouse
+	button click and the second pen button (Stylus2) emulates a middle
+	mouse button click. For mouse emulation, the tip (Tip) is mapped to
+	left mouse click.
 
 	Supported map *buttons* are:
-	- Tip
+	- Tip (mouse emulation only)
 	- Stylus
 	- Stylus2
 	- Stylus3
 	- Pad
 	- Pad2..Pad9
 
-	See mouse section above for all supported *to* mouse buttons.
+	The stylus buttons (Stylus, Stylus2 and Stylus3) can be mapped *to*:
+	- Right
+	- Middle
+	- Side
+
+	The tablet pad buttons can be mapped to all available mouse buttons.
+	When using mouse emulation only, the tip and stylus buttons can also be
+	mapped to all available mouse buttons.
+	See mouse section above for all supported mouse buttons.
 
 ## LIBINPUT
 
diff --git a/docs/rc.xml.all b/docs/rc.xml.all
index 2cccecd6..a8f9f3a0 100644
--- a/docs/rc.xml.all
+++ b/docs/rc.xml.all
@@ -497,11 +497,18 @@
     height are omitted or default (0.0), width/height will be set to
     the remaining width/height seen from top/left.
 
-    Tablet buttons emulate regular mouse buttons. The tablet *button* can
-    be set to any of [Tip|Stylus|Stylus2|Stylus3|Pad|Pad2|Pad3|..|Pad9].
-    Valid *to* mouse buttons are [Left|Right|Middle].
+    The tablet can be forced to always use mouse emulation. This prevents
+    tablet specific restrictions, e.g. no support for drag&drop, but also
+    omits tablet specific features like reporting pen pressure.
+
+    Pen buttons emulate regular mouse buttons. The pen *button* can be any
+    of [Stylus|Stylus2|Stylus3] and can be mapped to mouse buttons
+    [Right|Middle|Side]. Tablet pad buttons [Pad|Pad2|Pad3|..|Pad9] also
+    emulate regular mouse buttons and can be mapped to any mouse button.
+    When using mouse emulation, the pen tip [tip] and the stylus buttons
+    can be set to any available mouse button [Left|Right|Middle|..|Task].
   -->
-  <tablet mapToOutput="" rotate="0">
+  <tablet mapToOutput="" rotate="0" mouseEmulation="no">
     <!-- Active area dimensions are in mm -->
     <area top="0.0" left="0.0" width="0.0" height="0.0" />
     <map button="Tip" to="Left" />