From 81aea920a57eea329d051596f2fe84b6873693cc Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Sun, 29 May 2016 17:10:56 -0500 Subject: [PATCH] Transform the script in a way that allows processing multiple line substitutions. --- doc/doxygen/scripts/filter | 218 ++++++++++++++++++++----------------- 1 file changed, 121 insertions(+), 97 deletions(-) diff --git a/doc/doxygen/scripts/filter b/doc/doxygen/scripts/filter index 7780f549ff..65fbcaf5ec 100755 --- a/doc/doxygen/scripts/filter +++ b/doc/doxygen/scripts/filter @@ -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. ## @@ -14,109 +14,133 @@ ## ## --------------------------------------------------------------------- -# 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/(?)/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 . "video lecture $2"; - - 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/(?)/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 . ", video lecture $lecture"; - } + $substext = $1; + + $text = "\@note The material presented here is also discussed in "; + + # add links to the individual lectures + $text = $text . "video lecture $2"; + + 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 . ", video lecture $lecture"; + } + } + + $text = $text . ". (All video lectures are also available here.)"; + s/(\@dealiiVideoLecture\{([0-9\.]+)((, *[0-9\.]+ *)*)\})/$text/; } - $text = $text . ". (All video lectures are also available here.)"; - 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 . "video lecture $2"; + + if (length($3) > 0) + { + $x = $3; + $x =~ s/^, *//g; + @otherlectures = split (',', "$x"); + + foreach $lecture (@otherlectures) + { + $text = $text . ", video lecture $lecture"; + } + } + + $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 . "video lecture $2"; - - if (length($3) > 0) - { - $x = $3; - $x =~ s/^, *//g; - @otherlectures = split (',', "$x"); - - foreach $lecture (@otherlectures) - { - $text = $text . ", video lecture $lecture"; - } - } + ######################################################## + # 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; } -- 2.39.5