Address comments

doc/sphinx/user/run-aspect/parameters-overview/structure.md

@@ -69,7 +69,7 @@ occurrence will overwrite the earlier occurrence(s). Thus, in the example above
 `Some parameter` and `Some other parameter`, then the final file will use the value of
 `Some parameter` from `file_b.prm`, but the value of `Some other parameter` from `file_a.prm`.
 
-Also note, that the include statement can include the file path as relative or absolute path,
+Also note, that the include statement can include the file path as a relative or absolute path,
 and you can also reference the original ASPECT source directory using the string `$ASPECT_SOURCE_DIR`.
 Thus the three include statements
 ```

source/main.cc

@@ -396,26 +396,32 @@ read_parameter_file(const std::string &parameter_file_name,
           // by making sure included files are unique, because we may have multiple
           // files including the same file in a non-circular way. So we just limit
           // the number of included files to a reasonable number.
-          Assert(n_included_files < 15,
-                 dealii::ExcMessage("Too many included files in parameter file. You likely have a circular include."));
+          AssertThrow(n_included_files < 15,
+                      dealii::ExcMessage("Too many included files in parameter file. You likely have a circular include."));
 
           // Since the line as a whole matched, the 'matches' variable needs to
           // contain two entries: [0] denotes the whole line, and [1] the
           // part that was matched by the '(.*?)' expression.
           Assert (matches.size() == 2, dealii::ExcInternalError());
 
-          // Expand ASPECT_SOURCE_DIR, but only in the included file name (to keep the formatting
-          // of all parameter files intact, which we will copy into the output directory).
-          const std::string included_filename = aspect::Utilities::expand_ASPECT_SOURCE_DIR(matches.str(1));
+          const std::string included_filename(matches.str(1));
+          const std::string prefix = "\n# Included content from " + included_filename + ":\n\n";
+
+          // Expand ASPECT_SOURCE_DIR in the included file name, but not the content of the file
+          // (to keep the formatting of all parameter files intact, which we will copy into the output directory).
+          const std::string expanded_filename = aspect::Utilities::expand_ASPECT_SOURCE_DIR(matches.str(1));
 
           // Prepend a newline character to the included file content, because if the include directive
           // is not in the first line, we will replace one newlince character
           // from the original input file in the regex_replace below.
-          const std::string included_file_content = '\n' + aspect::Utilities::read_and_distribute_file_content(included_filename, comm);
+          const std::string included_file_content = aspect::Utilities::read_and_distribute_file_content(expanded_filename, comm);
 
           // Replace the include line with the content of the included file. Note that we only replace the first
           // include line we find (there may be several, which we will replace in subsequent iterations).
-          input_as_string = std::regex_replace(input_as_string, std::regex(replace_regex), included_file_content, std::regex_constants::format_first_only);
+          input_as_string = std::regex_replace(input_as_string,
+                                               std::regex(replace_regex),
+                                               prefix + included_file_content,
+                                               std::regex_constants::format_first_only);
 
           ++n_included_files;
         }

tests/include_prm_file/original.prm

@@ -1,5 +1,7 @@
 # Test for including prm files. This is simply including the simpler_box.prm test.
 
+# Included content from $ASPECT_SOURCE_DIR/tests/simpler_box.prm:
+
 set Dimension = 2
 set CFL number                             = 1.0
 set End time                               = 0

tests/include_prm_file_recursive/original.prm

@@ -2,8 +2,12 @@
 # This is including the include_prm_file.prm test, which
 # itself is including simpler_box.prm.
 
+# Included content from $ASPECT_SOURCE_DIR/tests/include_prm_file.prm:
+
 # Test for including prm files. This is simply including the simpler_box.prm test.
 
+# Included content from $ASPECT_SOURCE_DIR/tests/simpler_box.prm:
+
 set Dimension = 2
 set CFL number                             = 1.0
 set End time                               = 0

tests/original_prm/original.prm

@@ -1,6 +1,8 @@
 # test that output/original.prm is written correctly
 
 # based on no_flow.prm:
+# Included content from $ASPECT_SOURCE_DIR/tests/no_flow.prm:
+
 # A test that deals with the problem that if there is no flow then the
 # convection time step is infinite. in that case, we need to limit the
 # time step size to something related to the conduction time step