doc: split middle button emulation into a separate page

Easier to link to from bug reports

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

4 files changed, 43 insertions, 16 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index e033229..88877d4 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -13,6 +13,7 @@ header_files = \
 	$(srcdir)/device-configuration-via-udev.dox \
 	$(srcdir)/faqs.dox \
 	$(srcdir)/gestures.dox \
+	$(srcdir)/middle-button-emulation.dox \
 	$(srcdir)/normalization-of-relative-motion.dox \
 	$(srcdir)/palm-detection.dox \
 	$(srcdir)/page-hierarchy.dox \
diff --git a/doc/middle-button-emulation.dox b/doc/middle-button-emulation.dox
new file mode 100644
index 0000000..16ec476
--- /dev/null
+++ b/doc/middle-button-emulation.dox
@@ -0,0 +1,34 @@
+/**
+@page middle_button_emulation Middle button emulation
+
+Middle button emulation provides users with the ability to generate a middle
+click even when the device does not have a physical middle button available.
+
+When middle button emulation is enabled, a simultaneous press of the left
+and right button generates a middle mouse button event. Releasing the
+buttons generates a middle mouse button release, the left and right button
+events are discarded otherwise.
+
+The middle button release event may be generated when either button is
+released, or when both buttons have been released. The exact behavior is
+device-dependent, libinput will implement the behavior that is most
+appropriate to the physical device.
+
+The middle button emulation behavior when combined with other device
+buttons, including a physical middle button is device-dependent.
+For example, @ref clickpad_softbuttons provides a middle button area when
+middle button emulation is disabled. That middle button area disappears
+when middle button emulation is enabled - a middle click can then only be
+triggered by a simultaneous left + right click.
+
+Some devices provide middle mouse button emulation but do not allow
+enabling/disabling that emulation. Likewise, some devices may allow middle
+button emulation but have it disabled by default. This is the case for most
+mouse-like devices where a middle button is detected.
+
+libinput provides libinput_device_config_middle_emulation_set_enabled() to
+enable or disable middle button emulation. See @ref faq_configure_wayland
+and @ref faq_configure_xorg for info on how to enable or disable middle
+button emulation in the Wayland compositor or the X stack.
+ 
+*/
diff --git a/doc/page-hierarchy.dox b/doc/page-hierarchy.dox
index 4be6109..092178e 100644
--- a/doc/page-hierarchy.dox
+++ b/doc/page-hierarchy.dox
@@ -17,6 +17,7 @@
 @page pointers Mice, Trackballs, etc.
 
 - @subpage motion_normalization
+- @subpage middle_button_emulation
 
 @page tablets Graphics Tablets
 
diff --git a/src/libinput.h b/src/libinput.h
index 83e58b6..397c6f6 100644
--- a/src/libinput.h
+++ b/src/libinput.h
@@ -4569,8 +4569,7 @@ enum libinput_config_middle_emulation_state {
  * @ingroup config
  *
  * Check if middle mouse button emulation configuration is available on this
- * device. See libinput_device_config_middle_emulation_set_enabled() for
- * details.
+ * device. See @ref middle_button_emulation for details.
  *
  * @note Some devices provide middle mouse button emulation but do not allow
  * enabling/disabling that emulation. These devices return zero in
@@ -4597,19 +4596,7 @@ libinput_device_config_middle_emulation_is_available(
  * button event. Releasing the buttons generates a middle mouse button
  * release, the left and right button events are discarded otherwise.
  *
- * The middle button release event may be generated when either button is
- * released, or when both buttons have been released. The exact behavior is
- * device-dependent.
- *
- * The middle button emulation behavior when combined with other device
- * buttons, including a physical middle button is device-dependent.
- * For example, @ref clickpad_softbuttons provides a middle button area when
- * middle button emulation is disabled. That middle button area disappears
- * when middle button emulation is enabled - a middle click can then only be
- * triggered by a simultaneous left + right click.
- *
- * @note Some devices provide middle mouse button emulation but do not allow
- * enabling/disabling that emulation.
+ * See @ref middle_button_emulation for details.
  *
  * @param device The device to configure
  * @param enable @ref LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED to
@@ -4632,6 +4619,8 @@ libinput_device_config_middle_emulation_set_enabled(
  * @ingroup config
  *
  * Check if configurable middle button emulation is enabled on this device.
+ * See @ref middle_button_emulation for details.
+ *
  * If the device does not have configurable middle button emulation, this
  * function returns @ref LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED.
  *
@@ -4656,7 +4645,9 @@ libinput_device_config_middle_emulation_get_enabled(
  * @ingroup config
  *
  * Check if configurable middle button emulation is enabled by default on
- * this device. If the device does not have configurable middle button
+ * this device. See @ref middle_button_emulation for details.
+ *
+ * If the device does not have configurable middle button
  * emulation, this function returns @ref
  * LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED.
  *