[devhelp] Book: rename "book name" to "book ID"

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

commit f7d3e67191e68a4cb007a131398dcb6c6482fc5d
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Fri Dec 8 18:46:19 2017 +0100

    Book: rename "book name" to "book ID"
    
    "book name" is confusing, one can think that it's the book title. "book
    ID" has no ambiguity.

 docs/reference/api-breaks.xml       |   12 ++++++++++++
 docs/reference/devhelp-sections.txt |    4 ++--
 src/dh-book-manager.c               |   19 ++++++++++---------
 src/dh-book.c                       |   30 +++++++++++++++++-------------
 src/dh-book.h                       |    4 ++--
 src/dh-keyword-model.c              |    4 ++--
 src/dh-window.c                     |    2 +-
 7 files changed, 46 insertions(+), 29 deletions(-)
---
diff --git a/docs/reference/api-breaks.xml b/docs/reference/api-breaks.xml
index 35db9ff..8e86230 100644
--- a/docs/reference/api-breaks.xml
+++ b/docs/reference/api-breaks.xml
@@ -162,6 +162,18 @@
           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>
     </itemizedlist>
   </refsect1>
 </part>
diff --git a/docs/reference/devhelp-sections.txt b/docs/reference/devhelp-sections.txt
index d17b828..0d0f29c 100644
--- a/docs/reference/devhelp-sections.txt
+++ b/docs/reference/devhelp-sections.txt
@@ -31,14 +31,14 @@ dh_book_new
 dh_book_get_keywords
 dh_book_get_completions
 dh_book_get_tree
-dh_book_get_name
+dh_book_get_id
 dh_book_get_title
 dh_book_get_language
 dh_book_get_index_file
 dh_book_get_enabled
 dh_book_set_enabled
 dh_book_cmp_by_path
-dh_book_cmp_by_name
+dh_book_cmp_by_id
 dh_book_cmp_by_title
 <SUBSECTION Standard>
 DhBookClass
diff --git a/src/dh-book-manager.c b/src/dh-book-manager.c
index 684e4ec..06a3866 100644
--- a/src/dh-book-manager.c
+++ b/src/dh-book-manager.c
@@ -409,15 +409,15 @@ book_manager_is_book_disabled_in_conf (DhBookManager *book_manager,
                                        DhBook        *book)
 {
         DhBookManagerPrivate *priv = dh_book_manager_get_instance_private (book_manager);
-        const gchar *name;
+        const gchar *book_id;
         GSList *l;
 
-        name = dh_book_get_name (book);
+        book_id = dh_book_get_id (book);
 
         for (l = priv->books_disabled; l != NULL; l = l->next) {
-                gchar *cur_name = l->data;
+                gchar *cur_book_id = l->data;
 
-                if (g_strcmp0 (name, cur_name) == 0)
+                if (g_strcmp0 (book_id, cur_book_id) == 0)
                         return TRUE;
         }
 
@@ -475,7 +475,7 @@ book_manager_find_book_in_disabled_list (GSList *books_disabled,
         GSList *li;
 
         for (li = books_disabled; li; li = g_slist_next (li)) {
-                if (g_strcmp0 (dh_book_get_name (book),
+                if (g_strcmp0 (dh_book_get_id (book),
                                (const gchar *)li->data) == 0) {
                         return li;
                 }
@@ -523,7 +523,7 @@ book_manager_book_disabled_cb (DhBook   *book,
          * disabled books list! */
         g_assert (li == NULL);
         priv->books_disabled = g_slist_append (priv->books_disabled,
-                                               g_strdup (dh_book_get_name (book)));
+                                               g_strdup (dh_book_get_id (book)));
         book_manager_store_books_disabled (book_manager);
 
         /* Decrement language count */
@@ -565,11 +565,12 @@ book_manager_add_from_filepath (DhBookManager *book_manager,
                 return;
         }
 
-        /* Check if book with same bookname was already loaded in the manager
-         * (we need to force unique book names) */
+        /* Check if book with same ID was already loaded in the manager (we need
+         * to force unique book IDs).
+         */
         if (g_list_find_custom (priv->books,
                                 book,
-                                (GCompareFunc)dh_book_cmp_by_name)) {
+                                (GCompareFunc)dh_book_cmp_by_id)) {
                 g_object_unref (book);
                 return;
         }
diff --git a/src/dh-book.c b/src/dh-book.c
index 14a070b..cb10226 100644
--- a/src/dh-book.c
+++ b/src/dh-book.c
@@ -58,7 +58,7 @@ typedef enum {
 
 typedef struct {
         GFile *index_file;
-        gchar *name;
+        gchar *id;
         gchar *title;
         gchar *language;
 
@@ -116,7 +116,7 @@ dh_book_finalize (GObject *object)
         g_list_free_full (priv->completions, g_free);
         g_free (priv->language);
         g_free (priv->title);
-        g_free (priv->name);
+        g_free (priv->id);
 
         G_OBJECT_CLASS (dh_book_parent_class)->finalize (object);
 }
@@ -293,7 +293,7 @@ dh_book_new (GFile *index_file)
         /* Parse file storing contents in the book struct. */
         if (!dh_parser_read_file (priv->index_file,
                                   &priv->title,
-                                  &priv->name,
+                                  &priv->id,
                                   &language,
                                   &priv->tree,
                                   &priv->keywords,
@@ -434,13 +434,17 @@ dh_book_get_tree (DhBook *book)
 }
 
 /**
- * dh_book_get_name:
+ * dh_book_get_id:
  * @book: a #DhBook.
  *
- * Returns: the book name.
+ * Gets the book ID. In the Devhelp index file format version 2, it is actually
+ * the “name”, not the ID, but “book ID” is clearer, “book name” can be confused
+ * with the title.
+ *
+ * Returns: the book ID.
  */
 const gchar *
-dh_book_get_name (DhBook *book)
+dh_book_get_id (DhBook *book)
 {
         DhBookPrivate *priv;
 
@@ -448,7 +452,7 @@ dh_book_get_name (DhBook *book)
 
         priv = dh_book_get_instance_private (book);
 
-        return priv->name;
+        return priv->id;
 }
 
 /**
@@ -584,18 +588,18 @@ dh_book_cmp_by_path (DhBook *a,
 }
 
 /**
- * dh_book_cmp_by_name:
+ * dh_book_cmp_by_id:
  * @a: a #DhBook.
  * @b: a #DhBook.
  *
- * Compares the #DhBook's by their name.
+ * Compares the #DhBook's by their IDs.
  *
  * Returns: an integer less than, equal to, or greater than zero, if @a is <, ==
  * or > than @b.
  */
 gint
-dh_book_cmp_by_name (DhBook *a,
-                     DhBook *b)
+dh_book_cmp_by_id (DhBook *a,
+                   DhBook *b)
 {
         DhBookPrivate *priv_a;
         DhBookPrivate *priv_b;
@@ -606,10 +610,10 @@ dh_book_cmp_by_name (DhBook *a,
         priv_a = dh_book_get_instance_private (a);
         priv_b = dh_book_get_instance_private (b);
 
-        if (priv_a->name == NULL || priv_b->name == NULL)
+        if (priv_a->id == NULL || priv_b->id == NULL)
                 return -1;
 
-        return g_ascii_strcasecmp (priv_a->name, priv_b->name);
+        return g_ascii_strcasecmp (priv_a->id, priv_b->id);
 }
 
 /**
diff --git a/src/dh-book.h b/src/dh-book.h
index 617eafc..4834b42 100644
--- a/src/dh-book.h
+++ b/src/dh-book.h
@@ -54,7 +54,7 @@ GList *      dh_book_get_completions (DhBook *book);
 
 GNode *      dh_book_get_tree        (DhBook *book);
 
-const gchar *dh_book_get_name        (DhBook *book);
+const gchar *dh_book_get_id          (DhBook *book);
 
 const gchar *dh_book_get_title       (DhBook *book);
 
@@ -70,7 +70,7 @@ void         dh_book_set_enabled     (DhBook   *book,
 gint         dh_book_cmp_by_path     (DhBook *a,
                                       DhBook *b);
 
-gint         dh_book_cmp_by_name     (DhBook *a,
+gint         dh_book_cmp_by_id       (DhBook *a,
                                       DhBook *b);
 
 gint         dh_book_cmp_by_title    (DhBook *a,
diff --git a/src/dh-keyword-model.c b/src/dh-keyword-model.c
index a40b1d8..f2cfa31 100644
--- a/src/dh-keyword-model.c
+++ b/src/dh-keyword-model.c
@@ -582,7 +582,7 @@ keyword_model_search_books (DhKeywordModel  *model,
 
                 /* Filtering by book? */
                 if (settings->book_id != NULL) {
-                        if (g_strcmp0 (settings->book_id, dh_book_get_name (book)) != 0) {
+                        if (g_strcmp0 (settings->book_id, dh_book_get_id (book)) != 0) {
                                 continue;
                         }
 
@@ -606,7 +606,7 @@ keyword_model_search_books (DhKeywordModel  *model,
 
                 /* Skipping a given book? */
                 if (settings->skip_book_id != NULL &&
-                    g_strcmp0 (settings->skip_book_id, dh_book_get_name (book)) == 0) {
+                    g_strcmp0 (settings->skip_book_id, dh_book_get_id (book)) == 0) {
                         continue;
                 }
 
diff --git a/src/dh-window.c b/src/dh-window.c
index 3b16913..35bff17 100644
--- a/src/dh-window.c
+++ b/src/dh-window.c
@@ -991,7 +991,7 @@ find_equivalent_local_uri (const gchar *uri)
                 GList *keywords;
                 GList *keyword_node;
 
-                if (g_strcmp0 (dh_book_get_name (cur_book), book_id) != 0)
+                if (g_strcmp0 (dh_book_get_id (cur_book), book_id) != 0)
                         continue;
 
                 keywords = dh_book_get_keywords (cur_book);