Show subsections of introduction and results section also in the table of contents...

git-svn-id: https://svn.dealii.org/trunk@14904 0785d39b-7218-0410-832d-ea1e28bc413d

diff --git a/deal.II/doc/doxygen/tutorial/Makefile b/deal.II/doc/doxygen/tutorial/Makefile
index 3bae0311855154d37c5e9005db3630a557f569c4..4e06291fe4083161ed2b97fd201bfb4d0f76441e 100644 (file)
--- a/deal.II/doc/doxygen/tutorial/Makefile
+++ b/deal.II/doc/doxygen/tutorial/Makefile
@@ -16,6 +16,8 @@ gen-example-names = $(addprefix generated/, $(example-names))
 # and commented and plain versions of the program as well as a combined one
 example-toc-prog   = $(addsuffix _toc.prog,$(gen-example-names))
 example-toc-plain  = $(addsuffix _toc.plain,$(gen-example-names))
+example-toc-intro  = $(addsuffix _toc.intro,$(gen-example-names))
+example-toc-results= $(addsuffix _toc.results,$(gen-example-names))
 example-toc        = $(addsuffix _toc.combined,$(gen-example-names))
 
 # same for intermediate files for doxygen output
@@ -52,14 +54,32 @@ $(example-toc-plain):
          > $@
 
 
+$(example-toc-intro):
+       @echo ================== Making $@
+       @cat $D/examples/$(call get_basename, $@)/doc/intro.dox \
+         | egrep -i "<h[3456]>.*</h[3456]>" \
+         | $(PERL) ./intro2toc \
+         > $@
+
+
+$(example-toc-results):
+       @echo ================== Making $@
+       @cat $D/examples/$(call get_basename, $@)/doc/results.dox \
+         | egrep -i "<h[3456]>.*</h[3456]>" \
+         | $(PERL) ./intro2toc \
+         > $@
+
+
 $(example-toc):
        @echo ================== Making $@
        @echo "<table class=\"tutorial\">  <tr>    <td>" > $@
        @echo "<ol>" >> $@
        @echo "  <li> <a href=\"#Intro\" class=bold>Introduction</a>" >> $@
+       @cat generated/$(call get_basename, $@)_toc.intro >> $@
        @echo "  <li> <a href=\"#CommProg\" class=bold>The commented program</a>" >> $@
        @cat generated/$(call get_basename, $@)_toc.prog >> $@
        @echo "  <li> <a href=\"#Results\" class=bold>Results</a>" >> $@
+       @cat generated/$(call get_basename, $@)_toc.results >> $@
        @echo "  <li> <a href=\"#PlainProg\" class=bold>The plain program</a>" >> $@
        @cat generated/$(call get_basename, $@)_toc.plain >> $@
        @echo "</ol> </td> </tr> </table>" >> $@
@@ -96,9 +116,11 @@ $(example-doxygen):
        @echo "@htmlonly" >> $@
        @cat generated/$(call get_basename, $@)_toc.combined >> $@
        @echo "@endhtmlonly" >> $@
-       @cat $D/examples/$(call get_basename, $@)/doc/intro.dox >> $@
+       @cat $D/examples/$(call get_basename, $@)/doc/intro.dox \
+               | $(PERL) create_anchors >> $@
        @cat generated/$(call get_basename, $@)_prog.dox >> $@
-       @cat $D/examples/$(call get_basename, $@)/doc/results.dox >> $@
+       @cat $D/examples/$(call get_basename, $@)/doc/results.dox \
+               | $(PERL) create_anchors >> $@
        @cat generated/$(call get_basename, $@)_plain.dox >> $@
        @echo " */" >> $@
 
@@ -111,7 +133,8 @@ validate-xrefs:
 
 clean:
        -rm -f $(example-toc) \
-               $(example-toc-prog)  $(example-toc-plain) \
+               $(example-toc-prog) $(example-toc-plain) \
+               $(example-toc-intro) $(example-toc-results) \
                $(example-dox-prog) $(example-dox-plain) $(example-doxygen)
        -rm -f Makefile.dep
 
@@ -128,12 +151,21 @@ Makefile.dep: $(shell echo $D/examples/*/*.cc) Makefile
                        `echo $D/examples/$${i}/*.cc` ; \
                echo generated/$${i}_toc.plain : generated/$${i}_toc.prog ; \
                echo generated/$${i}_toc.combined : \
-                       generated/$${i}_toc.prog generated/$${i}_toc.plain ; \
+                       generated/$${i}_toc.intro \
+                       generated/$${i}_toc.results \
+                       generated/$${i}_toc.prog \
+                       generated/$${i}_toc.plain ; \
                echo doxygen/$$i.h : generated/$${i}_prog.dox generated/$${i}_plain.dox \
                                generated/$${i}_toc.combined \
                                $D/examples/$$i/doc/intro.dox \
                                $D/examples/$$i/doc/results.dox \
- ; \
+                        ; \
+               echo generated/$${i}_toc.intro : \
+                               $D/examples/$$i/doc/intro.dox \
+                        ; \
+               echo generated/$${i}_toc.results : \
+                               $D/examples/$$i/doc/results.dox \
+                        ; \
         done \
        > $@
 

diff --git a/deal.II/doc/doxygen/tutorial/create_anchors b/deal.II/doc/doxygen/tutorial/create_anchors
new file mode 100644 (file)
index 0000000..0fd0614
--- /dev/null
+++ b/deal.II/doc/doxygen/tutorial/create_anchors
@@ -0,0 +1,29 @@
+#---------------------------------------------------------------------------
+#    $Id: create_anchors 14782 2007-06-15 16:37:12Z kanschat $
+#    Version: $Name$
+#
+#    Copyright (C) 2007 by the deal.II authors
+#
+#    This file is subject to QPL and may not be  distributed
+#    without copyright and license information. Please refer
+#    to the file deal.II/doc/license.html for the  text  and
+#    further information on this license.
+#
+#---------------------------------------------------------------------------
+
+
+# If we find a a heading in a .dox file, create an HTML anchor for it.
+
+while (<>) {
+    if ( /<h.>(.*)<\/h.>\s*/ ) {
+       $reftext = $1;
+
+       # for the anchor, use the name of the section but discard
+       # everything except for letters, numbers, and underscores
+       $reftext =~ s/[^a-zA-Z0-9_]//g;
+
+       print "<a name=\"$reftext\"></a>$_\n";
+    } else {
+        print;
+    }
+}

diff --git a/deal.II/doc/doxygen/tutorial/intro2toc b/deal.II/doc/doxygen/tutorial/intro2toc
new file mode 100644 (file)
index 0000000..2330a29
--- /dev/null
+++ b/deal.II/doc/doxygen/tutorial/intro2toc
@@ -0,0 +1,61 @@
+#---------------------------------------------------------------------------
+#    $Id: intro2toc 14782 2007-06-15 16:37:12Z kanschat $
+#    Version: $Name$
+#
+#    Copyright (C) 2006, 2007 by the deal.II authors
+#
+#    This file is subject to QPL and may not be  distributed
+#    without copyright and license information. Please refer
+#    to the file deal.II/doc/license.html for the  text  and
+#    further information on this license.
+#
+#---------------------------------------------------------------------------
+
+print "    <ul>\n";
+
+$level = 3;
+while (<>) {
+    if ( /<h(.)>(.*)<\/h.>\s*/ ) {
+       $newlevel = $1;
+       $text = $2;
+       
+       # only allow header levels 3 through 6, since higher ones are
+       # reserved for top-level document headers
+       if (! ($newlevel =~ /[3456]/)) {
+           print STDERR "Only header levels 3 through 6 are allowed.\n";
+           print STDERR "You had $newlevel.\n";
+           die;
+       }
+
+       if ($newlevel > $level) {
+           for ($i=$level; $i<$newlevel; ++$i) {
+               print "      <ul>\n";
+            }
+       } elsif ($newlevel < $level) {
+           for ($i=$newlevel; $i<$level; ++$i) {
+               print "      </ul>\n";
+            }
+       }
+
+       $reftext = $text;
+
+       # for the anchor, use the name of the section but discard
+       # everything except for letters, numbers, and underscores
+       $reftext =~ s/[^a-zA-Z0-9_]//g;
+
+       # replace quotation marks by the appropriate HTML quotation marks
+       $text =~ s!``!&#8220;!g;
+       $text =~ s!''!&#8221;!g;
+
+        # replace double dashes in comments by &mdash;
+       $text =~ s!--!&mdash;!g;
+
+       print "        <li><a href=\"#$reftext\">$text</a>\n";
+
+       $level = $newlevel;
+    } 
+}
+
+for (; $level>=3; --$level) {
+    print "      </ul>\n";
+}

diff --git a/deal.II/doc/news/changes.html b/deal.II/doc/news/changes.html
index 57a95adebd437d220719fdd46ee5af2a7cc7f8ce..423144f31a980f3a207a5c86cf52c52190db3cf8 100644 (file)
--- a/deal.II/doc/news/changes.html
+++ b/deal.II/doc/news/changes.html
@@ -230,6 +230,13 @@ inconvenience this causes.
 <h3>General</h3>
 
 <ol>
+  <li> <p>
+       Improved: The table of contents of tutorial programs now also shows
+       subsections of introduction and results.
+       <br>
+       (WB 2007/08/05)
+       </p>
+
   <li> <p>
        Extended: Up to now, in 3D only 'orientable' meshes could be used in
        deal.II, i.e. all lines are in standard orientation and the faces can be