#!/usr/bin/perl -p
## ---------------------------------------------------------------------
## $Id: filter 31496 2013-10-31 14:29:06Z maier $
##
## Copyright (C) 2007 - 2013 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|\@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;
