<?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 id="api-breaks">
  <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.29.1 -> 3.29.2</title>
    <itemizedlist>
      <listitem>
        <para>
          <link linkend="DhBookManager">DhBookManager</link> 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: <link linkend="DhProfile">DhProfile</link>,
          <link linkend="DhSettings">DhSettings</link> and
          <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 <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/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>
          signals. For a book to be enabled it now needs to be part
          of a <link linkend="DhBookList">DhBookList</link>, which is more
          flexible because there can be several different
          <link linkend="DhBookList">DhBookList</link>'s in parallel.
        </para>
      </listitem>
      <listitem>
        <para>
          The last parameter of
          <link linkend="dh-keyword-model-filter">dh_keyword_model_filter()</link>
          has been changed, it is no longer the language (a string, that
          parameter was deprecated), it is a nullable
          <link linkend="DhProfile">DhProfile</link>.
        </para>
      </listitem>
      <listitem>
        <para>
          <code>dh_book_tree_get_selected_book()</code> has been replaced by
          <link linkend="dh-book-tree-get-selected-link">dh_book_tree_get_selected_link()</link>.
        </para>
      </listitem>
    </itemizedlist>
  </refsect1>

  <refsect1>
    <title>3.28.0 -> 3.29.1</title>
    <itemizedlist>
      <listitem>
        <para>
          The <code>DhBookManager:group-by-language</code> property has been
          replaced by the
          <link linkend="DhSettings--group-books-by-language">DhSettings:group-books-by-language</link>
          property.
        </para>
      </listitem>
      <listitem>
        <para>
          <link linkend="dh-book-tree-new">dh_book_tree_new()</link> now takes a
          <link linkend="DhProfile">DhProfile</link> parameter.
        </para>
      </listitem>
    </itemizedlist>
  </refsect1>

  <refsect1>
    <title>3.27.1 -> 3.27.2</title>
    <itemizedlist>
      <listitem>
        <para>
          <code>dh_book_cmp_by_path()</code> has been removed (dead code).
        </para>
      </listitem>
      <listitem>
        <para>
          The <code>DhBookManager::language-enabled</code> and
          <code>DhBookManager::language-disabled</code> signals have been
          removed (dead code).
        </para>
      </listitem>
      <listitem>
        <para>
          <link linkend="DhSidebar">DhSidebar</link> is now a subclass of
          <link linkend="GtkGrid">GtkGrid</link>, not
          <link linkend="GtkBox">GtkBox</link>.
        </para>
      </listitem>
      <listitem>
        <para>
          <code>dh_sidebar_get_selected_book()</code> has been removed (it was
          used only inside DhSidebar).
        </para>
      </listitem>
      <listitem>
        <para>
          <code>dh_book_get_completions()</code> has been replaced by
          <link linkend="dh-book-get-completion">dh_book_get_completion()</link>.
        </para>
      </listitem>
    </itemizedlist>
  </refsect1>

  <refsect1>
    <title>3.26.0 -> 3.27.1</title>
    <itemizedlist>
      <listitem>
        <para>
          <link linkend="dh-link-new">dh_link_new()</link> has been split in
          two, with <link linkend="dh-link-new-book">dh_link_new_book()</link>
          to create a <link linkend="DhLink">DhLink</link> of type
          <link linkend="DH-LINK-TYPE-BOOK:CAPS">DH_LINK_TYPE_BOOK</link>.
        </para>
      </listitem>
      <listitem>
        <para>
          The <code>dh_link_get_file_name()</code> function has been removed.
        </para>
      </listitem>
      <listitem>
        <para>
          The <code>dh_book_get_path()</code> function has been replaced by
          <link linkend="dh-book-get-index-file">dh_book_get_index_file()</link>.
        </para>
      </listitem>
      <listitem>
        <para>
          The <link linkend="dh-book-new">dh_book_new()</link> constructor now
          takes a <code>GFile</code> argument instead of a path.
        </para>
      </listitem>
      <listitem>
        <para>
          <code>dh_book_get_name()</code> has been renamed to
          <link linkend="dh-book-get-id">dh_book_get_id()</link>.
        </para>
      </listitem>
      <listitem>
        <para>
          <code>dh_book_cmp_by_name()</code> has been renamed to
          <link linkend="dh-book-cmp-by-id">dh_book_cmp_by_id()</link>.
        </para>
      </listitem>
      <listitem>
        <para>
          <code>dh_link_get_book_name()</code> has been renamed to
          <link linkend="dh-link-get-book-title">dh_link_get_book_title()</link>.
        </para>
      </listitem>
      <listitem>
        <para>
          <code>dh_book_get_keywords()</code> has been renamed to
          <link linkend="dh-book-get-links">dh_book_get_links()</link>.
        </para>
      </listitem>
      <listitem>
        <para>
          The ownership transfer of the return values of
          <code>dh_book_tree_get_selected_book()</code>
          and <code>dh_sidebar_get_selected_book()</code>
          have been changed from (transfer none) to (transfer full).
        </para>
      </listitem>
    </itemizedlist>
  </refsect1>

  <refsect1>
    <title>3.25.1 -> 3.25.2</title>
    <itemizedlist>
      <listitem>
        <para>
          The <code>page</code> parameter of <link linkend="dh-link-new">dh_link_new()</link>
          has been removed because it was broken in <code>dh-parser.c</code>.
          The <code>book</code> parameter has also been moved, to group related
          parameters together.
        </para>
      </listitem>
      <listitem>
        <para>
          The <code>dh_link_get_page_name()</code> function has been removed
          because it was broken and used nowhere.
        </para>
      </listitem>
      <listitem>
        <para>
          The <code>dh_link_get_type_as_string()</code> function (which took a
          <link linkend="DhLink">DhLink</link> parameter) has been removed, it
          has been replaced by <link linkend="dh-link-type-to-string">dh_link_type_to_string()</link>
          which takes a <link linkend="DhLinkType">DhLinkType</link> parameter.
        </para>
      </listitem>
    </itemizedlist>
  </refsect1>

  <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>
          The <code>DhApp</code>, <code>DhAssistant</code> and
          <code>DhWindow</code> classes are now private. <code>DhApp</code> is a
          subclass of <code>GtkApplication</code>, and an application can have
          only one <code>GtkApplication</code> instance, so as-is
          <code>DhApp</code> didn't make sense in the library (what if two
          different libraries have both a subclass of
          <code>GtkApplication</code>?). Since <code>DhAssistant</code> and
          <code>DhWindow</code> depend on <code>DhApp</code>, they are now also
          private.
        </para>
      </listitem>
      <listitem>
        <para>
          The <code>DhLanguage</code> class is now private, it's currently used
          only internally by <link linkend="DhBookManager">DhBookManager</link>.
        </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_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>
