[devhelp/wip/misc] docs: document API breaks in the reference manual

[Sébastien Wilmet <swilmet src gnome org>]

commit 9230b7835dd4ea4bf30dacbd4f0e68111101f984
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sat May 13 13:42:33 2017 +0200

    docs: document API breaks in the reference manual

 NEWS                            |   17 ---------
 docs/reference/Makefile.am      |    4 ++-
 docs/reference/api-breaks.xml   |   77 +++++++++++++++++++++++++++++++++++++++
 docs/reference/devhelp-docs.xml |    2 +
 4 files changed, 82 insertions(+), 18 deletions(-)
---
diff --git a/NEWS b/NEWS
index 84e97fc..f3e6a50 100644
--- a/NEWS
+++ b/NEWS
@@ -16,24 +16,7 @@ API changes:
  There has been some API breaks, but both Anjuta and gnome-builder should still
  compile and work fine.
 
- - Make dh-error.h private.
  - Deprecate dh_link_get_page_name().
- - Remove the following deprecated functions:
-       - dh_book_cmp_by_path_str()
-       - dh_book_cmp_by_name_str()
-       - dh_book_manager_get_languages()
-       - dh_language_free()
-
- - Make DhBookManager a singleton.
- - Remove dh_app_peek_book_manager().
- - Remove dh_assistant_view_set_book_manager().
- - Remove dh_keyword_model_set_words().
- - DhBookTree:
-       - Remove book-manager property.
-       - API break for dh_book_tree_new().
- - DhSidebar:
-       - Remove book-manager property.
-       - Deprecate the book_manager parameter of dh_sidebar_new().
 
 
 ==============
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index 505171e..1aa6a29 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -64,7 +64,9 @@ HTML_IMAGES =
 
 # Extra files that are included by $(DOC_MAIN_SGML_FILE).
 # e.g. content_files=running.xml building.xml changes-2.0.xml
-content_files =
+content_files =                \
+       api-breaks.xml  \
+       $(NULL)
 
 # Files where gtk-doc abbrevations (#GtkWidget) are expanded
 # e.g. expand_content_files=running.xml
diff --git a/docs/reference/api-breaks.xml b/docs/reference/api-breaks.xml
new file mode 100644
index 0000000..f834c45
--- /dev/null
+++ b/docs/reference/api-breaks.xml
@@ -0,0 +1,77 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+   "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd";
+[
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+ <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
+ %gtkdocentities;
+]>
+
+<part>
+  <title>API Breaks</title>
+
+  <refsect1>
+    <title>3.24 -> 3.25.1</title>
+    <itemizedlist>
+      <listitem>
+        <para>
+          All deprecated APIs have been removed.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          dh-error.h is now private.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Due to <link linkend="DhBookManager">DhBookManager</link> being now a
+          singleton, there has been the following API changes:
+          <itemizedlist>
+            <listitem>
+              <para>
+                <code>dh_app_peek_book_manager()</code> has been removed.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <code>dh_assistant_view_set_book_manager()</code> has been
+                removed.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <code>dh_keyword_model_set_words()</code> has been removed.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                The <code>DhBookTree:book-manager</code> property has been
+                removed.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                API break for
+                <link linkend="dh-book-tree-new">dh_book_tree_new()</link>.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                The <code>DhSidebar:book-manager</code> property has been
+                removed.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                The <code>book_manager</code> parameter of
+                <link linkend="dh-sidebar-new">dh_sidebar_new()</link> is now
+                deprecated.
+              </para>
+            </listitem>
+          </itemizedlist>
+        </para>
+      </listitem>
+    </itemizedlist>
+  </refsect1>
+</part>
diff --git a/docs/reference/devhelp-docs.xml b/docs/reference/devhelp-docs.xml
index 88c5f7b..8500934 100644
--- a/docs/reference/devhelp-docs.xml
+++ b/docs/reference/devhelp-docs.xml
@@ -44,6 +44,8 @@
     </chapter>
   </part>
 
+  <xi:include href="api-breaks.xml"/>
+
   <chapter id="object-tree">
     <title>Object Hierarchy</title>
     <xi:include href="xml/tree_index.sgml"/>