Add some commentary about tests/examples.

diff --git a/tests/examples/README.md b/tests/examples/README.md
index fe6d2080a4780482434ac7234eefc6768e374bb3..3bf10b3befc53547999e8d9dc633dc98e592c9ed 100644 (file)
--- 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 67b42e77a4bfce7f7c7be46707a0f9cb7d0a15a2..9278df98acd37a1c20eeb3f210653611c4e455f8 100755 (executable)
--- 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}"