From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Sat, 11 May 2024 13:50:10 +0000 (-0600)
Subject: Add some commentary about tests/examples.
X-Git-Tag: v9.6.0-rc1~290^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=378a0c54d4347c642eda7ef14fe9f85f50161936;p=dealii.git

Add some commentary about tests/examples.
---

diff --git a/tests/examples/README.md b/tests/examples/README.md
index fe6d2080a4..3bf10b3bef 100644
--- a/tests/examples/README.md
+++ b/tests/examples/README.md
@@ -4,7 +4,10 @@ This folder, that is part of the deal.II testsuite, contains the logic
 to run the deal.II examples (located under ./examples/ in the
 repository) as automated tests using CTest. Instead of storing copies
 of the source code of these example, we only store a fairly small
-textual diff for each example. This is motivated by the lesson, that
+textual diff for each example that, for example, limit the number of
+time steps or number of mesh refinement steps. Wanting to test the
+current form of the tutorial programs, perhaps up to these small
+modifications, is motivated by the lesson that
 copies of examples very quickly become out of date and we repeatedly
 fail to detect if an example program breaks due to a change in the
 library.
@@ -22,4 +25,5 @@ For development of new examples, we suggest first creating an empty
 
 To modify the source code, go into ``build/tests/examples/source/``
 and edit the .cc file there. Afterwards, you can update the .diff
-files by running the ``update_diffs`` target in that folder.
+files by running the ``update_diffs`` target in that folder that calls
+the ``update_diffs.sh`` script in the current directory.
diff --git a/tests/examples/update_diffs.sh b/tests/examples/update_diffs.sh
index 67b42e77a4..9278df98ac 100755
--- a/tests/examples/update_diffs.sh
+++ b/tests/examples/update_diffs.sh
@@ -1,4 +1,14 @@
 #!/bin/bash
+#
+# A script that can be used to create/update the .diff files in the
+# current directory based on the original tutorial code and a modified
+# version stored in a separate directory (typically in
+# $BUILD/tests/examples/source). Call this script as in
+#   ./update_diffs.sh /path/to/deal.II /path/to/deal.II/tests/examples
+# This script is automatically executed when you say
+#   make update_diffs
+# in the build directory after setting up the tests.
+#
 set -u
 
 DEAL_II_SOURCE_DIR="${1}"