move deallog discussion from step4 to step3

Enable it in step3 and move the discussion there to match the output
printed in the results section.

diff --git a/examples/step-3/step-3.cc b/examples/step-3/step-3.cc
index 3ee58856738790becaa8c631ea0339ab339705db..177d05f5a5ad2787d5bb4d76cb9b8b1881ed346f 100644 (file)
--- a/examples/step-3/step-3.cc
+++ b/examples/step-3/step-3.cc
@@ -626,9 +626,31 @@ void Step3::run ()
 // This is the main function of the program. Since the concept of a main
 // function is mostly a remnant from the pre-object era in C/C++ programming,
 // it often does not much more than creating an object of the top-level class
-// and calling its principle function. This is what is done here as well:
+// and calling its principle function.
+//
+// Finally, the first line of the function is used to enable output of the
+// deal.II logstream to the screen. Functions like iterative solvers will
+// generate diagnostics (starting residual, number of solver steps, final
+// residual), but the display of the logstream to the screen is disabled by
+// default.
+//
+// The output of deallog can be redirected to the console, to a file, or
+// both. The output is nested in a way so that each function can use a prefix
+// string (separated by colons) for each line of output; if it calls another
+// function, that may also use its prefix which is then printed after the one
+// of the calling function. By running this example (or looking at the
+// "Results" section), you will see the solver statistics prefixed with
+// "DEAL:CG", which is two prefixes.  Since output from functions which are
+// nested deep below is usually not as important as top-level output, you can
+// give the deallog variable a maximal depth of nested output for output to
+// console and file. A depth of 0 (the default) will disable output to the
+// screen, while a value of 2 or higher will cause the solver info to be
+// printed. Imagine that different solvers can be nested, which we will see in
+// step-22 for example, and you might not want to see all this information.
 int main ()
 {
+  deallog.depth_console (2);
+
   Step3 laplace_problem;
   laplace_problem.run ();
 

diff --git a/examples/step-4/step-4.cc b/examples/step-4/step-4.cc
index d00befcba3742b4e9f40fcfb51b0e01b900bf393..4554a346de650ea913088ba7dea20ac1d018770d 100644 (file)
--- a/examples/step-4/step-4.cc
+++ b/examples/step-4/step-4.cc
@@ -523,24 +523,6 @@ void Step4<dim>::run ()
 // variable would only be destroyed at the end of the function, i.e. after
 // running the 3d problem, and would needlessly hog memory while the 3d run
 // could actually use it.
-//
-// Finally, the first line of the function is used to suppress some output.
-// Remember that in the previous example, we had the output from the linear
-// solvers about the starting residual and the number of the iteration where
-// convergence was detected. This can be suppressed through the
-// <code>deallog.depth_console(0)</code> call.
-//
-// The rationale here is the following: the deallog (i.e. deal-log, not
-// de-allog) variable represents a stream to which some parts of the library
-// write output. It redirects this output to the console and if required to a
-// file. The output is nested in a way so that each function can use a prefix
-// string (separated by colons) for each line of output; if it calls another
-// function, that may also use its prefix which is then printed after the one
-// of the calling function. Since output from functions which are nested deep
-// below is usually not as important as top-level output, you can give the
-// deallog variable a maximal depth of nested output for output to console and
-// file. The depth zero which we gave here means that no output is written. By
-// changing it you can get more information about the innards of the library.
 int main ()
 {
   deallog.depth_console (0);

diff --git a/include/deal.II/base/logstream.h b/include/deal.II/base/logstream.h
index 5703f1bca318bee41c6a7c2c58881b24e748e4ae..648bbab996a72569964130022a7184c685d1164c 100644 (file)
--- a/include/deal.II/base/logstream.h
+++ b/include/deal.II/base/logstream.h
@@ -252,7 +252,7 @@ public:
    * allows one to restrict console output to the highest levels of
    * iterations. Only output with less than <tt>n</tt> prefixes is
    * printed. By calling this function with <tt>n=0</tt>, no console output
-   * will be written.
+   * will be written. See step-3 for an example usage of this method.
    *
    * The previous value of this parameter is returned.
    */