migrating-2to3: Add more words about GSEAL_ENABLE issues

As requested by Linus Torvalds, the wording here is a bit terse.
Explain more about how to fix the errors one encounters when using
GSEAL_ENABLE.

https://bugzilla.gnome.org/show_bug.cgi?id=692659

diff --git a/docs/reference/gtk/migrating-2to3.xml b/docs/reference/gtk/migrating-2to3.xml
index 64278b1fa0bc98410e55cfe494438a03b7c9bc80..34f4f92c32d349d63b17687cad39c9c431dcb8d4 100644 (file)
--- a/docs/reference/gtk/migrating-2to3.xml
+++ b/docs/reference/gtk/migrating-2to3.xml
@@ -119,6 +119,46 @@
     make CFLAGS+="-DGSEAL_ENABLE"
     </programlisting>
   </para>
+  <para>
+    While it may be painful to convert, this helps us keep API and ABI
+    compatibility when we change internal interfaces. As a quick example,
+    when adding GSEAL_ENABLE, if you see an error like:
+    <programlisting>
+    error: 'GtkToggleButton' has no member named 'active'
+    </programlisting>
+    this means that you are accessing the public structure of
+    GtkToggleButton directly, perhaps with some code like:
+    <informalexample><programlisting>
+      static void
+      on_toggled (GtkToggleButton *button)
+      {
+        if (button->active)
+          frob_active ();
+        else
+          frob_inactive ();
+      }
+    </programlisting></informalexample>
+  </para>
+  <para>
+    In most cases, this can easily be replaced with the correct accessor
+    method. The main rule is that if you have code like the above which
+    accesses the "active" field of a "GtkToggleButton", then the accessor
+    method becomes "gtk_toggle_button_get_active":
+    <informalexample><programlisting>
+      static void
+      on_toggled (GtkToggleButton *button)
+      {
+        if (gtk_toggle_button_get_active (button))
+          frob_active ();
+        else
+          frob_inactive ();
+      }
+    </programlisting></informalexample>
+  </para>
+  <para>
+    In the case of setting field members directly, there's usually
+    a corresponding setter method.
+  </para>
   </section>
 
   <section>