[libhandy/unstable-api: 32/33] doc: Tell to stop acknowledging the API unstability

[Adrien Plazas <aplazas src gnome org>]

commit 017c4b4a0d444fd82d7c4f11e7187c8f7cd70019
Author: Adrien Plazas <kekun plazas laposte net>
Date:   Thu Jan 9 10:20:45 2020 +0100

    doc: Tell to stop acknowledging the API unstability
    
    Let the users know that they can stop defining HANDY_USE_UNSTABLE_API.

 doc/build-howto.xml            | 41 -----------------------------------------
 doc/hdy-migrating-0-0-to-1.xml | 18 ++++++++++++++++++
 2 files changed, 18 insertions(+), 41 deletions(-)
---
diff --git a/doc/build-howto.xml b/doc/build-howto.xml
index c7e967d6..a6f731f3 100644
--- a/doc/build-howto.xml
+++ b/doc/build-howto.xml
@@ -119,47 +119,6 @@
     </programlisting></informalexample>
   </refsect2>
 
-  <refsect2>
-    <title>Acknowledge the Instability</title>
-
-    <para>
-      Since the library is young and is still changing a lot, in order to use
-      it you are required to acknowledge that your are using an unstable API.
-      To do so, <literal>HANDY_USE_UNSTABLE_API</literal> must be defined for
-      compilation to succeed.
-    </para>
-
-    <para>
-      From C code or any compatible language, you can prefix your inclusion of
-      the &package_string; header like so:
-    </para>
-
-    <informalexample><programlisting>
-      #define HANDY_USE_UNSTABLE_API
-      #include &lt;handy.h&gt;
-    </programlisting></informalexample>
-
-    <para>
-      Including individual headers rather than <literal>handy.h</literal> is
-      not recommended.
-    </para>
-
-    <para>
-      You can also acknowledge this with the definition option of your C
-      compiler, like <literal>-DHANDY_USE_UNSTABLE_API</literal>. This is
-      required from Vala.
-    </para>
-
-    <para>
-      To use libhandy from Vala, you must define the acknowledgment in C via
-      <literal>-X -DHANDY_USE_UNSTABLE_API</literal>. If your build system uses
-      a two pass compilation and hence your Vala compiler outputs C (Meson,
-      Automake, or using the <literal>--ccode</literal> Vala compiler option to
-      trigger that) then you must add <literal>-DHANDY_USE_UNSTABLE_API
-      </literal> to your C compiler arguments instead.
-    </para>
-  </refsect2>
-
   <refsect2>
     <title>Building on macOS</title>
 
diff --git a/doc/hdy-migrating-0-0-to-1.xml b/doc/hdy-migrating-0-0-to-1.xml
index 333870d6..7c0950ba 100644
--- a/doc/hdy-migrating-0-0-to-1.xml
+++ b/doc/hdy-migrating-0-0-to-1.xml
@@ -321,6 +321,24 @@
       </para>
     </refsect3>
 
+    <refsect3>
+      <title>Stop acknowledging the Instability</title>
+      <para>
+        When the library was young and changing a lot, we required you to
+        acknowledge that your are using an unstable API. To do so, you had to
+        define <literal>HANDY_USE_UNSTABLE_API</literal> for compilation to
+        succeed.
+      </para>
+      <para>
+        The API remained stable since many versions, despite this acknowlegment
+        still being required. To reflect that proven stability, the
+        acknowlegment isn't necessary and you can stop defining
+        <literal>HANDY_USE_UNSTABLE_API</literal>, either before including the
+        &package_string; header in C-compatible languages, or with the
+        definition option of your compiler.
+      </para>
+    </refsect3>
+
   </refsect2>
 
 </refentry>