[gtk+] migrating-2to3: Add more words about GSEAL_ENABLE issues

[Jasper St. Pierre <jstpierre src gnome org>]

commit 2397521d29ed7af94a847bdcaa943f51c63fff15
Author: Jasper St. Pierre <jstpierre mecheye net>
Date:   Sun Jan 27 16:06:59 2013 -0500

    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

 docs/reference/gtk/migrating-2to3.xml |   40 +++++++++++++++++++++++++++++++++
 1 files changed, 40 insertions(+), 0 deletions(-)
---
diff --git a/docs/reference/gtk/migrating-2to3.xml b/docs/reference/gtk/migrating-2to3.xml
index 64278b1..34f4f92 100644
--- 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>