sparsity patterns of matrices. This is documentation at an
intermediate level: they give you an overview of what's there in a
particular area. For example when you wonder what finite element
- classes exist, you would take a look at the @ref fe module.
+ classes exist, you would take a look at the @ref fe module. The
+ modules are, of course, also cross-linked to the manual (and, at
+ times, to the tutorial); if you click on a class name, say on
+ Triangulation, would will also at the very top right under the class
+ name get a link to the modules this class is a member of if you want
+ to learn more about its context.
+Let's come back to the tutorial, since this is the first step of
+it. Each tutorial program is subdivided into the following sections:
+<ol>
+ <li> <b>Introduction:</b> This is a discussion of what the program
+ does, including the mathematical model, and
+ what programming techniques are new compared to previous
+ tutorial programs.
+ <li> <b>The commented program:</b> An extensively documented listing of the
+ source code. Here, we often document individual lines, or
+ blocks of code, and discuss what they do, how they do it, and
+ why. The comments frequently reference the introduction,
+ i.e. you have to understand <i>what</i> the program wants to achieve
+ (a goal discussed in the introduction) before you can
+ understand <i>how</i> it intends to get there.
+ <li> <b>Results:</b> The output of the program, with comments and
+ interpretation. This section also frequently has a subsection
+ that gives suggestions on how to extend the program in various
+ direction; in the earlier programs, this is intended to give
+ you directions for little experiments designed to make your
+ familiar with deal.II, while in later programs it is more about
+ how to use more advanced numerical techniques.
+ <li> <b>The plain program:</b> The source code stripped of
+ all comments. This is useful if you want to see the "big
+ picture" of the code, since the commented version of the
+ program has so much text in between that it is often difficult
+ to see the entire code of a single function on the screen at
+ once.
+</ol>
+The tutorials are not only meant to be static documentation, but you
+should play with them. To this end, go to the
+<code>examples/step-1</code> directory (or whatever the number of the
+tutorial is that you're interested in) and type
+@code
+ make
+ make run
+@endcode
+The first command compiles the sources into an executable, while the
+second executes it (strictly speaking, <code>make run</code> will also
+compile the code if the executable doesn't exist yet, so you could
+have skipped the first command if you wanted). This is all that's
+needed to run the code and produce the output that is discussed in the
+"Results" section of the tutorial programs.
+When learning the library, you need to play with it and see what
+happens. To this end, open the <code>examples/step-1/step-1.cc</code>
+source file with your favorite editor and modify it in some way (see,
+for example, the suggestions at the end of the results section of this
+program), save it and run it as above.
+
+
+<h3> What this program does </h3>
+
+Let's come back to step-1, the current program.
In this first example, we don't actually do very much, but show two
techniques: what is the syntax to generate triangulation objects, and
some elements of simple loops over all cells. We create two grids, one
which is a regularly refined square (not very exciting, but a common
starting grid for some problems), and one more geometric attempt: a
-ring-shaped domain, which is refined towards the inner edge. The
-latter is certainly not very useful and is probably only rarely used
-in numerical analysis for PDEs (although, to everyone's surprise, it
-has actually found its way into the literature, see the paper by M. Mu
-titled "PDE.MART: A network-based problem-solving environment", ACM
-Trans. Math. Software, vol. 31, pp. 508-531, 2005 :-), but looks nice
-and illustrates how loops over cells are written and some of the
-things you can do with cells.
+ring-shaped domain, which is refined towards the inner edge. Through
+this, you will get to know three things every finite element program
+will have to have somewhere: An object of type Triangulation for the
+mesh; a call to the GridGenerator functions to generate a mesh; and
+loops over all cells that involve iterators (iterators are a
+generalization of pointers and are frequently used in the C++ standard
+library; in the context of deal.II, the @ref Iterators module talks
+about them).
+
+The program is otherwise small enough that it doesn't need a whole lot
+of introduction. Let us just continue with its commented source.