From e98eedb9657b805bf740287d2a6a87c3d734496c Mon Sep 17 00:00:00 2001
From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Mon, 29 Jan 2018 15:13:20 -0700
Subject: [PATCH] Sort entries to the code gallery by their name, not their
 directory name.

---
 doc/doxygen/scripts/code-gallery.pl | 35 +++++++++++++++++++++--------
 1 file changed, 26 insertions(+), 9 deletions(-)

diff --git a/doc/doxygen/scripts/code-gallery.pl b/doc/doxygen/scripts/code-gallery.pl
index 04a514828e..190893d4ba 100644
--- a/doc/doxygen/scripts/code-gallery.pl
+++ b/doc/doxygen/scripts/code-gallery.pl
@@ -29,10 +29,15 @@ while (my $line = <GALLERY>)
   print $line;
 }
 
-# print the list of code gallery programs as a descriptor/description
-# list
-print "<dl>\n";
-foreach my $gallery (sort @ARGV)
+# create a list of code gallery program descriptions. we will later
+# output this as a descriptor/description list, but for the moment
+# we will simply create each entry as a string, and insert it in
+# a map keyed by the entry's name so that we can later output them
+# in a way that looks sorted on the screen, rather than is sorted
+# by the directory name (which looks pretty random to the human
+# reader)
+my %descriptions;
+foreach my $gallery (@ARGV)
 {
     my $gallery_underscore = $gallery;
 
@@ -57,14 +62,26 @@ foreach my $gallery (sort @ARGV)
     $authors =~ s/,$//;
 
     $gallery_underscore    =~ s/-/_/;
-    print "  <dt><b>\@ref code_gallery_${gallery_underscore} \"$entryname\"</b> (by $authors)</dt>\n";
-    print "    <dd>\n";
+
+    my $description;
+    $description = "  <dt><b>\@ref code_gallery_${gallery_underscore} \"$entryname\"</b> (by $authors)</dt>\n";
+    $description = $description . "    <dd>\n";
     open TOOLTIP, "<$gallery_dir/$gallery/doc/tooltip";
     while (my $line = <TOOLTIP>) {
-        print "      $line";
+        $description = $description . "      $line";
     }
-    print "    </dd>\n";
-    print "\n";
+    $description = $description . "    </dd>\n";
+    $description = $description . "\n";
+
+    # now insert this description into the map mentioned above
+    $descriptions{$entryname} = $description;
+}
+
+# now print the entries generated above sorted by their keys
+print "<dl>\n";
+foreach my $key (sort keys %descriptions)
+{
+    print $descriptions{$key};
 }
 print "</dl>\n";
 
-- 
2.39.5