#!/usr/bin/perl -p
## ---------------------------------------------------------------------
##
## Copyright (C) 2007 - 2014 by the deal.II authors
##
## This file is part of the deal.II library.
##
## The deal.II library is free software; you can use it, redistribute
## it, and/or modify it under the terms of the GNU Lesser General
## Public License as published by the Free Software Foundation; either
## version 2.1 of the License, or (at your option) any later version.
## The full text of the license can be found in the file LICENSE at
## the top level of the deal.II distribution.
##
## ---------------------------------------------------------------------

# 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;


s#(static dealii::ExceptionBase\&)#\n//\! \@ingroup Exceptions\n \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 ";

    # 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/;
}


# @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/;
}
