From f97e727ddbf33b49eadc6120350f40fd761040d6 Mon Sep 17 00:00:00 2001
From: Wolfgang Bangerth <bangerth@math.tamu.edu>
Date: Tue, 29 Dec 2015 17:50:36 -0600
Subject: [PATCH] Also generate the legend for the tutorial connection graph
 automatically.

This allows us to show the actual symbols for each kind, rather than having to
describe them in words.
---
 doc/doxygen/scripts/steps.pl       | 78 +++++++++++++++++++++++++++---
 doc/doxygen/tutorial/tutorial.h.in | 20 ++------
 2 files changed, 77 insertions(+), 21 deletions(-)

diff --git a/doc/doxygen/scripts/steps.pl b/doc/doxygen/scripts/steps.pl
index 05dc8a78c8..41a9f593d0 100644
--- a/doc/doxygen/scripts/steps.pl
+++ b/doc/doxygen/scripts/steps.pl
@@ -19,10 +19,10 @@ my $tutorial_file = shift;
 open TUTORIAL, "<$tutorial_file";
 
 # Print the first part of tutorial.h.in up until the point where we
-# find the line with '@@MAP@@'
+# find the line with '@@TUTORIAL_MAP@@'
 while (my $line = <TUTORIAL>)
 {
-  last if($line =~ m/\@\@MAP\@\@/);
+  last if($line =~ m/\@\@TUTORIAL_MAP\@\@/);
   print $line;
 }
 
@@ -91,7 +91,7 @@ foreach $step (@ARGV)
       my $number = $step;
       $number =~ s/^.*-//;
 
-      printf "Step$number [label=\"$number\", URL=\"\\ref step_$number\", tooltip=\"$tooltip\"";
+      printf "  Step$number [label=\"$number\", URL=\"\\ref step_$number\", tooltip=\"$tooltip\"";
       print "$style{$kind}";
     }
     else
@@ -103,7 +103,7 @@ foreach $step (@ARGV)
       my $tag = $name;
       $tag =~ s/[^a-zA-Z]/_/g;
 
-      printf "code_gallery_$tag [label=\"\", URL=\"\\ref code_gallery_$tag\", tooltip=\"$tooltip\"";
+      printf "  code_gallery_$tag [label=\"\", URL=\"\\ref code_gallery_$tag\", tooltip=\"$tooltip\"";
       my $kind = "code-gallery";
       print "$style{$kind}";
     }
@@ -145,10 +145,10 @@ foreach $step (@ARGV)
     my $source;
     foreach $source (split ' ', $buildson) {
         $source =~ s/step-/Step/g;
-        print "$source -> $destination";
+        print "  $source -> $destination";
         if ($destination =~ /code_gallery/)
         {
-            print " [style=\"dashed\"]";
+            print " [style=\"dashed\", arrowhead=\"empty\"]";
         }
         print "\n";
     }
@@ -156,6 +156,72 @@ foreach $step (@ARGV)
 
 print "}\n";
 
+# Copy that part of tutorial.h.in up until the point where we
+# find the line with '@@TUTORIAL_LEGEND@@'
+while (my $line = <TUTORIAL>)
+{
+  last if($line =~ m/\@\@TUTORIAL_LEGEND\@\@/);
+  print $line;
+}
+
+# Print a preamble setting common attributes
+print << 'EOT'
+graph StepsDescription
+{
+  overlap=false;
+  edge [fontname="FreeSans",
+        fontsize="10",
+        labelfontname="FreeSans",
+        labelfontsize="10",
+        color="black",
+        style="solid"];
+  node [fontname="FreeSans",
+        fontsize="10",
+        shape="rectangle",
+        height=0.2,
+        width=0.4,
+        color="black",
+        fillcolor="white",
+        style="filled"];
+EOT
+    ;
+
+my %kind_descriptions = (
+ "basic"          => 'Basic techniques',
+ "techniques"     => 'Advanced techniques',
+ "fluids"         => 'Fluid dynamics',
+ "solids"         => 'Solid mechanics',
+ "time dependent" => 'Time dependent problems',
+ "unfinished"     => 'Unfinished codes',
+ "code-gallery"   => 'Code gallery',
+    );
+
+# for each kind, print a box in the same style as used in
+# the connections graph; also print a fake box with a
+# description of what each kind is. then connect these
+my $kind;
+foreach $kind (keys %style)
+{
+    my $escaped_kind = $kind;
+    $escaped_kind =~ s/[^a-zA-Z]/_/g;
+    printf "  $escaped_kind [label=\"\" $style{$kind}];\n";
+    printf "  fake_$escaped_kind [label=\"$kind_descriptions{$kind}\", shape=plaintext];\n";
+    printf "  $escaped_kind -- fake_$escaped_kind [style=dotted, arrowhead=odot, arrowsize=1];\n";
+}
+# now add connections to make sure they appear nicely next to each other
+# in the legend
+print "  basic -- techniques -- fluids -- solids -- time_dependent -- unfinished -- code_gallery;\n";
+
+# we need to tell 'dot' that all of these are at the same
+# rank to ensure they appear next to (as opposed to atop)
+# each other
+print "  {rank=same; basic, techniques, fluids, solids, time_dependent, unfinished, code_gallery}";
+
+# end the graph
+print "}\n";
+
+
+
 # Then print the rest of tutorial.h.in
 while (my $line = <TUTORIAL>)
 {
diff --git a/doc/doxygen/tutorial/tutorial.h.in b/doc/doxygen/tutorial/tutorial.h.in
index 1611560fa8..ad8af33fc3 100644
--- a/doc/doxygen/tutorial/tutorial.h.in
+++ b/doc/doxygen/tutorial/tutorial.h.in
@@ -1,6 +1,6 @@
 // ---------------------------------------------------------------------
 //
-// Copyright (C) 2005 - 2014 by the deal.II authors
+// Copyright (C) 2005 - 2015 by the deal.II authors
 //
 // This file is part of the deal.II library.
 //
@@ -65,23 +65,13 @@
  * your mouse pointer over a box, a brief description of the program
  * should appear.
  * @dot
-@@MAP@@
+@@TUTORIAL_MAP@@
  * @enddot
  *
  * <b>Legend:</b><br />
- * <ul>
- *
- * <li><i>Green:</i> programs that show basic techniques;
- *
- * <li><i>Orange:</i> advanced techniques;
- *
- * <li><i>Yellow:</i> applications in fluid dynamics;
- *
- * <li><i>Light blue:</i> applications in solid mechanics;
- *
- * <li><i>Dark blue:</i> time dependent problems.
- *
- * </ul>
+ * @dot
+@@TUTORIAL_LEGEND@@
+ * @enddot
  *
  * <a name="list"></a>
  * <h3>Tutorial programs listed by number</h3>
-- 
2.39.5