"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"

[

 %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.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 DhApp, DhAssistant and

          DhWindow classes are now private. DhApp is a

          subclass of GtkApplication, and an application can have

          only one GtkApplication instance, so as-is

          DhApp didn't make sense in the library (what if two

          different libraries have both a subclass of

          GtkApplication?). Since DhAssistant and

          DhWindow depend on DhApp, they are now also

          private.

        </para>

      </listitem>

      <listitem>

        <para>

          The DhLanguage 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>

                dh_assistant_view_set_book_manager() has been

                removed.

              </para>

            </listitem>

            <listitem>

              <para>

                dh_keyword_model_set_words() has been removed.

              </para>

            </listitem>

            <listitem>

              <para>

                The DhBookTree:book-manager 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 DhSidebar:book-manager property has been

                removed.

              </para>

            </listitem>

            <listitem>

              <para>

                The book_manager parameter of

                <link linkend="dh-sidebar-new">dh_sidebar_new()</link> is now

                deprecated.

              </para>

            </listitem>

          </itemizedlist>

        </para>

      </listitem>

    </itemizedlist>

  </refsect1>

  <refsect1>

    <title>3.25.1 -> 3.25.2</title>

    <itemizedlist>

      <listitem>

        <para>

          The page parameter of <link linkend="dh-link-new">dh_link_new()</link>

          has been removed because it was broken in dh-parser.c.

          The book parameter has also been moved, to group related

          parameters together.

        </para>

      </listitem>

      <listitem>

        <para>

          The dh_link_get_page_name() function has been removed

          because it was broken and used nowhere.

        </para>

      </listitem>

      <listitem>

        <para>

          The dh_link_get_type_as_string() 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.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 dh_link_get_file_name() function has been removed.

        </para>

      </listitem>

      <listitem>

        <para>

          The dh_book_get_path() 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 GFile argument instead of a path.

        </para>

      </listitem>

      <listitem>

        <para>

          dh_book_get_name() has been renamed to

          <link linkend="dh-book-get-id">dh_book_get_id()</link>.

        </para>

      </listitem>

      <listitem>

        <para>

          dh_book_cmp_by_name() has been renamed to

          <link linkend="dh-book-cmp-by-id">dh_book_cmp_by_id()</link>.

        </para>

      </listitem>

      <listitem>

        <para>

          dh_link_get_book_name() has been renamed to

          <link linkend="dh-link-get-book-title">dh_link_get_book_title()</link>.

        </para>

      </listitem>

      <listitem>

        <para>

          dh_book_get_keywords() 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

          <link linkend="dh-book-tree-get-selected-book">dh_book_tree_get_selected_book()</link>

          and dh_sidebar_get_selected_book()

          have been changed from (transfer none) to (transfer full).

        </para>

      </listitem>

    </itemizedlist>

  </refsect1>

  <refsect1>

    <title>3.27.1 -> 3.27.2</title>

    <itemizedlist>

      <listitem>

        <para>

          dh_book_cmp_by_path() has been removed (dead code).

        </para>

      </listitem>

      <listitem>

        <para>

          The DhBookManager::language-enabled and

          DhBookManager::language-disabled 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>

          dh_sidebar_get_selected_book() has been removed (it was

          used only inside DhSidebar).

        </para>

      </listitem>

      <listitem>

        <para>

          dh_book_get_completions() has been replaced by

          <link linkend="dh-book-get-completion">dh_book_get_completion()</link>.

        </para>

      </listitem>

    </itemizedlist>

  </refsect1>

</part>