Bug 653907 - Help-browser fails to sort top-level items

Sort help-browser items by a new attribute "sort", if available (to be
provided by the "gimp-help.xml" file).

plug-ins/help-browser/dialog.c

@@ -360,38 +360,57 @@ browser_dialog_make_index_foreach (const gchar    *help_id,
                                    GimpHelpItem   *item,
                                    GimpHelpLocale *locale)
 {
-#if 0
+  gchar *sort_key = item->title;
+#if DEBUG_SORT_HELP_ITEMS
   g_printerr ("%s: processing %s (parent %s)\n",
               G_STRFUNC,
               item->title  ? item->title  : "NULL",
               item->parent ? item->parent : "NULL");
 #endif
 
-  if (item->title)
+  if (item->sort &&
+      g_regex_match_simple("^[0-9]+([.][0-9]+)*$", item->sort, 0, 0))
     {
-      gchar **indices = g_strsplit (item->title, ".", -1);
+      sort_key = item->sort;
+#if DEBUG_SORT_HELP_ITEMS
+      g_printerr("%s: sort key = %s\n", G_STRFUNC, sort_key);
+#endif
+    }
+  item->index = 0;
+
+  if (sort_key)
+    {
+      const gint max_tokens = GIMP_HELP_BROWSER_INDEX_MAX_DEPTH;
+      gchar* *indices = g_strsplit (sort_key, ".", max_tokens + 1);
       gint    i;
 
-      for (i = 0; i < 5; i++)
+      for (i = 0; i < max_tokens; i++)
         {
           gunichar c;
 
           if (! indices[i])
-            break;
+            {
+              /* make sure that all item->index's are comparable */
+              item->index <<= (8 * (max_tokens - i));
+              break;
+            }
 
+          item->index <<= 8;  /* NOP if i = 0 */
           c = g_utf8_get_char (indices[i]);
-
           if (g_unichar_isdigit (c))
             {
-              item->index += atoi (indices[i]) << (8 * (5 - i));
+              item->index += atoi (indices[i]);
             }
           else if (g_utf8_strlen (indices[i], -1) == 1)
             {
-              item->index += (c & 0xFF) << (8 * (5 - i));
+              item->index += (c & 0xFF);
             }
         }
 
       g_strfreev (indices);
+#if DEBUG_SORT_HELP_ITEMS
+  g_printerr("%s: index = %lu\n", G_STRFUNC, item->index);
+#endif
     }
 
   if (item->parent && strlen (item->parent))

plug-ins/help/gimphelpitem.c

@@ -46,12 +46,14 @@
 GimpHelpItem *
 gimp_help_item_new (const gchar *ref,
                     const gchar *title,
+                    const gchar *sort,
                     const gchar *parent)
 {
   GimpHelpItem *item = g_slice_new0 (GimpHelpItem);
 
   item->ref    = g_strdup (ref);
   item->title  = g_strdup (title);
+  item->sort   = g_strdup (sort);
   item->parent = g_strdup (parent);
 
   return item;
@@ -62,6 +64,7 @@ gimp_help_item_free (GimpHelpItem *item)
 {
   g_free (item->ref);
   g_free (item->title);
+  g_free (item->sort);
   g_free (item->parent);
 
   g_list_free (item->children);

plug-ins/help/gimphelpitem.h

@@ -28,16 +28,18 @@ struct _GimpHelpItem
 {
   gchar *ref;
   gchar *title;
+  gchar *sort;   /* optional sort key provided by doc team */
   gchar *parent;
 
   /*  extra fields used by the help-browser  */
   GList *children;
-  gint   index;
+  gulong index;
 };
 
 
 GimpHelpItem * gimp_help_item_new  (const gchar   *ref,
                                     const gchar   *title,
+                                    const gchar   *sort,
                                     const gchar   *parent);
 void           gimp_help_item_free (GimpHelpItem  *item);
 

plug-ins/help/gimphelplocale.c

@@ -451,6 +451,7 @@ locale_parser_parse_item (LocaleParser  *parser,
   const gchar *id     = NULL;
   const gchar *ref    = NULL;
   const gchar *title  = NULL;
+  const gchar *sort   = NULL;  /* optional sort key provided by doc team */
   const gchar *parent = NULL;
 
   for (; *names && *values; names++, values++)
@@ -464,6 +465,9 @@ locale_parser_parse_item (LocaleParser  *parser,
       if (! strcmp (*names, "title"))
         title = *values;
 
+      if (! strcmp (*names, "sort"))
+        sort = *values;
+
       if (! strcmp (*names, "parent"))
         parent = *values;
     }
@@ -479,7 +483,7 @@ locale_parser_parse_item (LocaleParser  *parser,
 
       g_hash_table_insert (parser->locale->help_id_mapping,
                            g_strdup (id),
-                           gimp_help_item_new (ref, title, parent));
+                           gimp_help_item_new (ref, title, sort, parent));
 
 #ifdef GIMP_HELP_DEBUG
       g_printerr ("help (%s): added mapping \"%s\" -> \"%s\"\n",