[gtk/ebassi/run-dialog-run: 6/7] docs: Mention blocking functions in the migration guide

[Emmanuele Bassi <ebassi src gnome org>]

commit e8c4b8338f0f34d09050c3d4096d88498ce4172d
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Thu Apr 30 16:08:37 2020 +0100

    docs: Mention blocking functions in the migration guide
    
    Link to how to make a dialog modal, and to the response signal.

 docs/reference/gtk/migrating-3to4.xml | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
---
diff --git a/docs/reference/gtk/migrating-3to4.xml b/docs/reference/gtk/migrating-3to4.xml
index ee5bc5ecf9..32fa09d8bb 100644
--- a/docs/reference/gtk/migrating-3to4.xml
+++ b/docs/reference/gtk/migrating-3to4.xml
@@ -1254,5 +1254,24 @@
         emitted.
       </para>
     </section>
+
+    <section>
+      <title>Stop using blocking dialog functions</title>
+      <para>
+        GtkDialog, GtkNativeDialog, and GtkPrintOperation removed their
+        blocking API using nested main loops. Nested main loops present
+        re-entrancy issues and other hard to debug issues when coupled
+        with other event sources (IPC, accessibility, network operations)
+        that are not under the toolkit or the application developer's
+        control. Additionally, "stop-the-world" functions do not fit
+        the event-driven programming model of GTK.
+      </para>
+      <para>
+        You can replace calls to <function>gtk_dialog_run()</function>
+        by specifying that the #GtkDialog must be modal using
+        gtk_window_set_modal() or the %GTK_DIALOG_MODAL flag, and
+        connecting to the #GtkDialog::response signal.
+      </para>
+    </section>
   </section>
 </chapter>