Restructure a bit and provide some advice on debugging, with a link to the FAQ.

git-svn-id: https://svn.dealii.org/trunk@24041 0785d39b-7218-0410-832d-ea1e28bc413d

diff --git a/deal.II/examples/step-1/doc/results.dox b/deal.II/examples/step-1/doc/results.dox
index 7528d60d707d94fdd95bf1f6ae6177d1b04b3efc..756c67a271e6af2ccdfde4f9b558146414bce754 100644 (file)
--- a/deal.II/examples/step-1/doc/results.dox
+++ b/deal.II/examples/step-1/doc/results.dox
@@ -28,6 +28,8 @@ good for some things at least.
 
 <h3> Possible extensions </h3>
 
+<h4> Different adaptive refinement strategies </h4>
+
 This program obviously does not have a whole lot of functionality, but
 in particular the <code>second_grid</code> function has a bunch of
 places where you can play with it. For example, you could modify the
@@ -46,6 +48,31 @@ the $x$-coordinate, subscripting <code>[1]</code> the
 $y$-coordinate). By looking at the functions that TriaAccessor
 provides, you can also use more complicated criteria for refinement.
 
+<h4> Different geometries </h4>
+
 Another possibility would be to generate meshes of entirely different
-geometries altogether. For this, take a look at the GridGenerator
-namespace to see what it provides.
+geometries altogether. While for complex geometries there is no way around
+using meshes obtained from mesh generators, there is a good number of
+geometries for which deal.II can create meshes using the functions in the
+GridGenerator namespace. Take a look at what it provides and see how it could
+be used in a program like this.
+
+<h4> Comments about programming and debugging </h4>
+
+We close with a comment about modifying or writing programs with deal.II in
+general. When you start working with tutorial programs or your own
+applications, you will find that mistakes happen: your program will contain
+code that either aborts the program right away or bugs that simply lead to
+wrong results. In either case, you will find it extremely helpful to know how
+to work with a debugger: you may get by for a while by just putting debug
+output into your program, compiling it, and running it, but ultimately finding
+bugs with a debugger is much faster, much more convenient, and more reliable
+because you don't have to recompile the program all the time and because you
+can inspect the values of variables and how they change.
+
+Rather than postponing learning how to use a debugger, here's the one piece of
+advice we will provide in this program: learn how to use a debugger as soon as
+possible. It will be time well invested. The deal.II Frequently Asked
+Questions (FAQ) page linked to from the top-level <a
+href="http://www.dealii.org/">deal.II webpage</a> also provides a good number
+of hints on debugging deal.II programs.