]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Transform the script in a way that allows processing multiple line substitutions.
authorWolfgang Bangerth <bangerth@math.tamu.edu>
Sun, 29 May 2016 22:10:56 +0000 (17:10 -0500)
committerWolfgang Bangerth <bangerth@math.tamu.edu>
Tue, 31 May 2016 22:49:58 +0000 (17:49 -0500)
doc/doxygen/scripts/filter

index 7780f549ffdb7fb29f804eb8da954c007bf33181..65fbcaf5eca5e864fd4702a975a0335cb9daa4dd 100755 (executable)
@@ -1,7 +1,7 @@
-#!/usr/bin/perl -p
+#!/usr/bin/perl
 ## ---------------------------------------------------------------------
 ##
-## Copyright (C) 2007 - 2014 by the deal.II authors
+## Copyright (C) 2007 - 2014, 2016 by the deal.II authors
 ##
 ## This file is part of the deal.II library.
 ##
 ##
 ## ---------------------------------------------------------------------
 
-# make sure we can just write $...$ for formulas.
-s/\$/\@f\$/g;
-
-# however, undo that change if the dollar sign was escaped with a backslash
-s/\\\@f\$/\$/g;
-
-# We don't let doxygen put everything into a namespace
-# dealii. consequently, doxygen can't link references that contain an
-# explicit dealii:: qualification. remove it and replace it by the
-# global scope
-#
-# Now, as of doxygen 1.5, this still produces the wrong result, but
-# that's not our fault. This is reported here:
-#    http://bugzilla.gnome.org/show_bug.cgi?id=365053
-s/(::)?dealii::/::/g;
-
-# Replace all occurrences of something like step-xx by
-#    @ref step_xx "step-xx"
-# so that doxygen properly cross references them. Before we had
-# this rule, we actually had to write this sequence out in our
-# documentation. Unfortunately, as a consequence, there are vestiges
-# of this style, so we can't substitute things that look like
-# "step-xx". We therefore not substitute if step-xx is preceded or
-# followed by quotation marks, or if the text is explicitly
-# preceded by a backslash for escaping.
-#
-# There are other exceptions:
-# - the scripts in doc/doxygen/tutorial produce files that have
-#   table of contents entries. We don't want these cross-linked
-#   to itself.
-# - things like step-12.solution.png that typically appear in
-#   @image commands.
-# - things in headings
-s/(?<![\"\\\/])step-(\d+)(?!\")/\@ref step_\1 \"step-\1\"/gi
-  if !m/(\@page|\<img|\@image|<h\d>)/i;
-
-# If step-xx was explicitly escaped with a backslash, remove the
-# latter
-s/\\(step-\d+)/\1/g;
-
-# doxygen version 1.7.1 and later have the habit of thinking that
-# everything that starts with "file:" is the beginning of a link,
-# but we occasionally use this in our tutorials in the form
-# "...this functionality is declared in the following header file:",
-# where it leads to a non-functional link. We can avoid the problem
-# by replacing a "file:" at the end of a line with the text
-# "file :", which doxygen doesn't recognize:
-s#file:[ \t]*$#file :#g;
-
-
-
-# Handle commands such as @dealiiVideoLecture{20.5,33} by expanding it
-# into a note with some text
-if (m/(\@dealiiVideoLecture\{([0-9\.]+)((, *[0-9\.]+ *)*)\})/)
-{
-    $substext = $1;
 
-    $text = "\@note The material presented here is also discussed in ";
+# read all lines of input. within the loop, first do some
+# easy substitutions that are confined to a single line; later
+# do some multi-line substitutions as well
 
-    # add links to the individual lectures
-    $text = $text . "<a href=\"http://www.math.tamu.edu/~bangerth/videos.676.$2.html\">video lecture $2</a>";
-    
-    if (length($3) > 0)
+while (<>)
+{
+    ########################################################
+    # Step 1: substitutions within a single line
+    ########################################################
+
+
+    # make sure we can just write $...$ for formulas.
+    s/\$/\@f\$/g;
+
+    # however, undo that change if the dollar sign was escaped with a backslash
+    s/\\\@f\$/\$/g;
+
+    # We don't let doxygen put everything into a namespace
+    # dealii. consequently, doxygen can't link references that contain an
+    # explicit dealii:: qualification. remove it and replace it by the
+    # global scope
+    #
+    # Now, as of doxygen 1.5, this still produces the wrong result, but
+    # that's not our fault. This is reported here:
+    #    http://bugzilla.gnome.org/show_bug.cgi?id=365053
+    s/(::)?dealii::/::/g;
+
+    # Replace all occurrences of something like step-xx by
+    #    @ref step_xx "step-xx"
+    # so that doxygen properly cross references them. Before we had
+    # this rule, we actually had to write this sequence out in our
+    # documentation. Unfortunately, as a consequence, there are vestiges
+    # of this style, so we can't substitute things that look like
+    # "step-xx". We therefore not substitute if step-xx is preceded or
+    # followed by quotation marks, or if the text is explicitly
+    # preceded by a backslash for escaping.
+    #
+    # There are other exceptions:
+    # - the scripts in doc/doxygen/tutorial produce files that have
+    #   table of contents entries. We don't want these cross-linked
+    #   to itself.
+    # - things like step-12.solution.png that typically appear in
+    #   @image commands.
+    # - things in headings
+    s/(?<![\"\\\/])step-(\d+)(?!\")/\@ref step_\1 \"step-\1\"/gi
+        if !m/(\@page|\<img|\@image|<h\d>)/i;
+
+    # If step-xx was explicitly escaped with a backslash, remove the
+    # latter
+    s/\\(step-\d+)/\1/g;
+
+    # doxygen version 1.7.1 and later have the habit of thinking that
+    # everything that starts with "file:" is the beginning of a link,
+    # but we occasionally use this in our tutorials in the form
+    # "...this functionality is declared in the following header file:",
+    # where it leads to a non-functional link. We can avoid the problem
+    # by replacing a "file:" at the end of a line with the text
+    # "file :", which doxygen doesn't recognize:
+    s#file:[ \t]*$#file :#g;
+
+
+
+    # Handle commands such as @dealiiVideoLecture{20.5,33} by expanding it
+    # into a note with some text
+    if (m/(\@dealiiVideoLecture\{([0-9\.]+)((, *[0-9\.]+ *)*)\})/)
     {
-        # if it is a list of lectures, also list the others.
-       $x = $3;
-       $x =~ s/^, *//g;
-       @otherlectures = split (',', "$x");
-
-       foreach $lecture (@otherlectures)
-       {
-           $text = $text . ", <a href=\"http://www.math.tamu.edu/~bangerth/videos.676.$lecture.html\">video lecture $lecture</a>";
-       }
+        $substext = $1;
+
+        $text = "\@note The material presented here is also discussed in ";
+
+        # add links to the individual lectures
+        $text = $text . "<a href=\"http://www.math.tamu.edu/~bangerth/videos.676.$2.html\">video lecture $2</a>";
+        
+        if (length($3) > 0)
+        {
+            # if it is a list of lectures, also list the others.
+            $x = $3;
+            $x =~ s/^, *//g;
+            @otherlectures = split (',', "$x");
+
+            foreach $lecture (@otherlectures)
+            {
+                $text = $text . ", <a href=\"http://www.math.tamu.edu/~bangerth/videos.676.$lecture.html\">video lecture $lecture</a>";
+            }
+        }
+
+        $text = $text . ". (All video lectures are also available <a href=\"http://www.math.tamu.edu/~bangerth/videos.html\">here</a>.)";
+        s/(\@dealiiVideoLecture\{([0-9\.]+)((, *[0-9\.]+ *)*)\})/$text/;
     }
 
-    $text = $text . ". (All video lectures are also available <a href=\"http://www.math.tamu.edu/~bangerth/videos.html\">here</a>.)";
-    s/(\@dealiiVideoLecture\{([0-9\.]+)((, *[0-9\.]+ *)*)\})/$text/;
-}
 
+    # @dealiiVideoLectureSeeAlso works as above, but just expands into
+    # regular text, no @note
+    if (m/(\@dealiiVideoLectureSeeAlso\{([0-9\.]+)((, *[0-9\.]+ *)*)\})/)
+    {
+        $substext = $1;
+
+        $text = "See also ";
+
+        # add links to the individual lectures
+        $text = $text . "<a href=\"http://www.math.tamu.edu/~bangerth/videos.676.$2.html\">video lecture $2</a>";
+        
+        if (length($3) > 0)
+        {
+            $x = $3;
+            $x =~ s/^, *//g;
+            @otherlectures = split (',', "$x");
+
+            foreach $lecture (@otherlectures)
+            {
+                $text = $text . ", <a href=\"http://www.math.tamu.edu/~bangerth/videos.676.$lecture.html\">video lecture $lecture</a>";
+            }
+        }
+
+        $text = $text . ".";
+        s/(\@dealiiVideoLectureSeeAlso\{([0-9\.]+)((, *[0-9\.]+ *)*)\})/$text/;
+    }
 
-# @dealiiVideoLectureSeeAlso works as above, but just expands into
-# regular text, no @note
-if (m/(\@dealiiVideoLectureSeeAlso\{([0-9\.]+)((, *[0-9\.]+ *)*)\})/)
-{
-    $substext = $1;
 
-    $text = "See also ";
 
-    # add links to the individual lectures
-    $text = $text . "<a href=\"http://www.math.tamu.edu/~bangerth/videos.676.$2.html\">video lecture $2</a>";
-    
-    if (length($3) > 0)
-    {
-       $x = $3;
-       $x =~ s/^, *//g;
-       @otherlectures = split (',', "$x");
-
-       foreach $lecture (@otherlectures)
-       {
-           $text = $text . ", <a href=\"http://www.math.tamu.edu/~bangerth/videos.676.$lecture.html\">video lecture $lecture</a>";
-       }
-    }
+    ########################################################
+    # Step 2: substitutions for patterns that span
+    #         multiple lines
+    ########################################################
+
 
-    $text = $text . ".";
-    s/(\@dealiiVideoLectureSeeAlso\{([0-9\.]+)((, *[0-9\.]+ *)*)\})/$text/;
+    # Finally output the last line of what has been substituted
+    print;
 }

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.