Update Doxyfile.in again, now using all defined doxygen tags

The process to generate the docs now uses the full Doxyfile as given
by `doxygen -u Doxyfile.in` with a specific doxygen version, in this
commit version 1.8.14.

There's only one addition: 'HTML_COLORSTYLE = TOGGLE' which has been
added to doxygen in version 1.9.5. We're using it now to give the user
the choice to select a "dark mode" or "light mode" theme if the docs
are generated with doxygen 1.9.5 or later.

Unknown doxygen tags are now filtered silently and logged in files
documentation/Doxyfile_error.log and documentation/Doxybook_error.log,
respectively.

1 files changed, 44 insertions, 0 deletions

diff --git a/documentation/convert_doxyfile b/documentation/convert_doxyfile
new file mode 100755
index 000000000..57c3c28a6
--- /dev/null
+++ b/documentation/convert_doxyfile
@@ -0,0 +1,44 @@
+#!/bin/sh
+#
+# Convert 'Doxyfile.in' to 'Doxyfile' or 'Doxybook' for doxygen docs
+#
+# Usage:
+#
+#   $ sh convert_doxyfile doxygen_path input output logfile
+#
+# where
+# - 'doxygen_path' is the full path to the doxygen executable or just
+#   'doxygen' if this is in the user's PATH. If the full path is used
+#   an arbitrary doxygen executable and thus doxygen version can be used.
+# - 'input' is the file 'Doxyfile.in' stored in Git or any other file.
+# - 'output' is the generated doxygen file, usually either 'Doxyfile'
+#   or 'Doxybook' which will be used subsequently to generate the
+#   HTML or PDF docs, respectively.
+#
+# Doxygen warnings and errors are stored in 'logfile' for review.
+#
+#=======================================================================
+# This script requires a posix shell and uses the following commands:
+#   'echo', 'date', and (obviously) doxygen.
+#=======================================================================
+
+# doxygen command, input and output file names
+
+DOXYGEN="$1"
+ INFILE="$2"
+OUTFILE="$3"
+LOGFILE="$4"
+
+# get doxygen version
+
+VERSION=$($DOXYGEN --version)
+
+# write info header to LOGFILE
+
+echo "$OUTFILE created by doxygen version $VERSION" > $LOGFILE
+echo "  at `date`" >> $LOGFILE
+echo "" >> $LOGFILE
+
+# convert doxygen file and append errors and warnings to LOGFILE
+
+${DOXYGEN} -u -s - < $INFILE > $OUTFILE 2>> $LOGFILE