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

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

commit 01cee43c685c8140f46127c7fd64ba4da3f75f1e
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                            |   25 +---------
 docs/reference/Makefile.am      |    4 +-
 docs/reference/api-breaks.xml   |   94 +++++++++++++++++++++++++++++++++++++++
 docs/reference/devhelp-docs.xml |    2 +
 4 files changed, 102 insertions(+), 23 deletions(-)
---
diff --git a/NEWS b/NEWS
index 84e97fc..96b419f 100644
--- a/NEWS
+++ b/NEWS
@@ -12,28 +12,9 @@ Version 3.25.x (not yet released)
        - Check for gsettings-desktop-schemas with pkg-config.
 
 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().
+- There has been some API breaks documented in the reference manual, but both
+  Anjuta and gnome-builder should still compile and work fine.
+- Deprecate dh_link_get_page_name().
 
 
 ==============
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..c132d8a
--- /dev/null
+++ b/docs/reference/api-breaks.xml
@@ -0,0 +1,94 @@
+<?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>
+
+  <para>
+    Devhelp is a quite old piece of software (created in 2001), and as every
+    software, the code evolves during its lifetime. So there are sometimes API
+    breaks. We try to not break applications depending on the Devhelp API. But
+    if we see that a certain API is used nowhere else than the Devhelp
+    application itself (or is dead code), we don't hesitate to break the API to
+    improve the code.
+  </para>
+
+  <para>
+    Currently we try to not break
+    <ulink url="https://wiki.gnome.org/Apps/Anjuta";>Anjuta</ulink>
+    and <ulink url="https://wiki.gnome.org/Apps/Builder";>gnome-builder</ulink>.
+    If your application is not listed and depends on the Devhelp API and is Free
+    Software, please speak up.
+  </para>
+
+  <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"/>