[devhelp] docs: better document the book management architecture change

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

commit 89b10fb299714a7e6319dbbbdd2f98026244d637
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Fri May 11 15:24:05 2018 +0200

    docs: better document the book management architecture change

 NEWS                          |   23 ++++++++++++++++++-----
 docs/reference/api-breaks.xml |    7 ++++---
 2 files changed, 22 insertions(+), 8 deletions(-)
---
diff --git a/NEWS b/NEWS
index b9309dc..0b1990d 100644
--- a/NEWS
+++ b/NEWS
@@ -1,10 +1,23 @@
 News in 3.29.2, 2018-xx-yy (not yet released)
 --------------------------
-* Decouple book selection from DhBook: remove DhBook "enabled" property,
-  introduce DhBookList base class, DhBookListSimple and DhBookListBuilder.
-* Allow custom search paths to load DhBooks: add DhBookListDirectory, remove
-  DhBookManager implementation.
-* DhProfile: add a DhBookList.
+* A new and more flexible book management architecture in the libdevhelp:
+
+ - DhBookManager is now completely empty and entirely deprecated, the minimum
+   amount of API is kept to not break Anjuta. It has been replaced by a more
+   flexible infrastructure: DhProfile, DhSettings and DhBookList. If an
+   application uses only the default libdevhelp widgets it will still work fine
+   – even if the code of the application is not adapted – because in that case
+   it will use the default DhProfile, which contains the same content as how
+   DhBookManager was implemented.
+
+ - Whether a DhBook is enabled/selected is now decoupled from DhBook:
+   dh_book_get_enabled() and dh_book_set_enabled() have been removed, as well
+   as the DhBook::enabled and DhBook::disabled signals. For a book to be
+   enabled it now needs to be part of a DhBookList, which is more flexible
+   because there can be several different DhBookLists in parallel.
+
+ - Allow custom search paths to load DhBooks, with DhBookListDirectory.
+
 * Listen to external changes to the "books-disabled" GSettings key.
 * Port other Devhelp classes to DhProfile and DhBookList.
 
diff --git a/docs/reference/api-breaks.xml b/docs/reference/api-breaks.xml
index 9dad980..718f535 100644
--- a/docs/reference/api-breaks.xml
+++ b/docs/reference/api-breaks.xml
@@ -40,14 +40,15 @@
           <link linkend="DhBookList">DhBookList</link>. If your application uses
           only the default libdevhelp widgets it will still work fine – even if
           you don't adapt the code of the application – because in that case it
-          will use the default profile, which contains the same content as how
+          will use the default <link linkend="DhProfile">DhProfile</link>, which
+          contains the same content as how
           <link linkend="DhBookManager">DhBookManager</link> was implemented.
         </para>
       </listitem>
       <listitem>
         <para>
-          Whether a <link linkend="DhBook">DhBook</link> is enabled is now
-          decoupled from <link linkend="DhBook">DhBook</link>:
+          Whether a <link linkend="DhBook">DhBook</link> is enabled/selected is
+          now decoupled from <link linkend="DhBook">DhBook</link>:
           <code>dh_book_get_enabled()</code> and
           <code>dh_book_set_enabled()</code> have been removed, as well as the
           <code>DhBook::enabled</code> and <code>DhBook::disabled</code>