[gtk/main-cleanup: 2/7] docs: Remove a reference to gtk_main_do_event

[Matthias Clasen <matthiasc src gnome org>]

commit 8f0fc24516797a1020461759a8d088ee03ef1b3d
Author: Matthias Clasen <mclasen redhat com>
Date:   Sun Feb 9 10:38:01 2020 -0500

    docs: Remove a reference to gtk_main_do_event
    
    It is not great to put a function in the public api and
    document it as "do not call this" only so we can refer
    to its docs in other places. Therefore, fold the docs
    directly into the input handling overview chapter.

 docs/reference/gtk/input-handling.xml | 50 ++++++++++++++++++++++++++++++-----
 1 file changed, 44 insertions(+), 6 deletions(-)
---
diff --git a/docs/reference/gtk/input-handling.xml b/docs/reference/gtk/input-handling.xml
index f81252dfbb..f419cd30f2 100644
--- a/docs/reference/gtk/input-handling.xml
+++ b/docs/reference/gtk/input-handling.xml
@@ -92,12 +92,50 @@
 
     <para>
       The function which initially receives input events on the GTK
-      side is gtk_main_do_event(). See its documentation
-      for details of what it does: compression of enter/leave events,
-      identification of the widget receiving the event, pushing the event onto a
-      stack for gtk_get_current_event(), and propagating the event to the
-      widget.
-    </para>
+      side is responsible for a number of tasks.
+    </para>
+    <orderedlist>
+      <listitem><para>
+        Compress enter/leave notify events. If the event passed build an
+        enter/leave pair together with the next event (peeked from GDK), both
+        events are thrown away. This is to avoid a backlog of (de-)highlighting
+        widgets crossed by the pointer.
+      </para></listitem>
+      <listitem><para>
+        Find the widget which got the event. If the widget can’t be determined
+        the event is thrown away unless it belongs to a INCR transaction.
+      </para></listitem>
+      <listitem><para>
+        Then the event is pushed onto a stack so you can query the currently
+        handled event with gtk_get_current_event().
+      </para></listitem>
+      <listitem><para>
+        The event is sent to a widget. If a grab is active all events for widgets
+        that are not in the contained in the grab widget are sent to the latter
+        with a few exceptions:
+        <itemizedlist>
+          <listitem><para>
+            Deletion and destruction events are still sent to the event widget for
+            obvious reasons.
+          </para></listitem>
+          <listitem><para>
+            Events which directly relate to the visual representation of the event
+            widget.
+          </para></listitem>
+          <listitem><para>
+            Leave events are delivered to the event widget if there was an enter
+            event delivered to it before without the paired leave event.
+          </para></listitem>
+          <listitem><para>
+            Drag events are not redirected because it is unclear what the semantics
+            of that would be.
+          </para></listitem>
+        </itemizedlist>
+      </para></listitem>
+      <listitem><para>
+        After finishing the delivery the event is popped from the event stack.
+      </para></listitem>
+    </orderedlist>
 
     <para>
       When a GDK backend produces an input event, it is tied to a #GdkDevice and