From 9621af8176fb06440b5202933b8ffc0a3b140f92 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Tue, 17 Aug 2010 19:58:34 +0000 Subject: [PATCH] Cross-link. git-svn-id: https://svn.dealii.org/trunk@21676 0785d39b-7218-0410-832d-ea1e28bc413d --- .../development/writing-documentation.html | 53 ++++++++++++------- 1 file changed, 34 insertions(+), 19 deletions(-) diff --git a/deal.II/doc/development/writing-documentation.html b/deal.II/doc/development/writing-documentation.html index b64b11c37b..47a43477cc 100644 --- a/deal.II/doc/development/writing-documentation.html +++ b/deal.II/doc/development/writing-documentation.html @@ -301,23 +301,37 @@

More important is what goes into the introduction. Typically, this would first be a statement of the problem that we want to - solve. Take a look, for example, at the step-22 or step-31 - tutorial programs. Then come a few sections in which we would - discuss in mathematical terms the algorithms that we want to - use; this could, for example, include the time stepping, - discretization, or solver approaches. step-22 and step-31 are - again good, if lengthy, examples for this. + solve. Take a look, for example, at + the step-22 + or step-31 tutorial programs. Then come a few + sections in which we would discuss in mathematical terms the + algorithms that we want to use; this could, for example, include + the time stepping, discretization, or solver + approaches. step-22 + and step-31 are again good, if lengthy, examples + for this.

On the other hand, if a program is an extension of a previous program, these things need not be repeated: you would just - reference the previous program. For example, step-16 does not - talk about adaptive meshes any more — it extends step-6 - and simply refers there for details. Likewise, step-32 simply - refers to step-31 for the problem statement and basic algorithm - and simply focuses on those parts that are new compared to - step-31. + reference the previous program. For + example, step-16 does not talk about adaptive meshes + any more — it + extends step-6 and simply refers there for + details. Likewise, step-32 simply refers + to step-31 for the problem statement and basic + algorithm and simply focuses on those parts that are new + compared to + step-31.

@@ -334,13 +348,14 @@

If it helps the understanding, the introduction can refer to particular pieces of code (but doesn't have to). For example, - the introduction to step-20 has pretty lengthy code snippets - that explain how to implement a general interface of operators - that may or may not be matrices. This would be awkward to do - within the code since in the code the view is somewhat smaller - (you have to have complete parameter lists, follow the syntax of - the programming language, etc, all of which obscures the things - one wants to discuss when giving a broad overview related to + the introduction to step-20 has pretty lengthy code snippets that + explain how to implement a general interface of operators that + may or may not be matrices. This would be awkward to do within + the code since in the code the view is somewhat smaller (you + have to have complete parameter lists, follow the syntax of the + programming language, etc, all of which obscures the things one + wants to discuss when giving a broad overview related to particular C++ constructs). On the other hand, showing code snippets in the introduction risks duplicating code in two places, which will eventually get out of synch. Consequently, -- 2.39.5