Some more words about example programs.

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

diff --git a/deal.II/doc/development/writing-documentation.html b/deal.II/doc/development/writing-documentation.html
index 592b90d062333fb3f6e4990b49c6c02d81bca6ae..3cbc26a7cd032b59211641b87954e8c05ecd0c18 100644 (file)
--- a/deal.II/doc/development/writing-documentation.html
+++ b/deal.II/doc/development/writing-documentation.html
@@ -231,9 +231,30 @@
     </p>
 
 
+
     <a name="examples">
     <h3>Writing example programs</h3>
 
+    <p>
+    At present, the tools that extract information from the example
+    programs are rather dumb. They are, to be precise, two Perl
+    scripts located in the directory of the
+    <code>deal.II/doc/tutorial</code> tree, where the HTML files are
+    generated. In principle, they extract plain text from all comments
+    in the programs that start with a double slash (C++ style
+    comment). Everything else is interpreted as program text and is
+    copied verbatim into the output.
+    </p>
+
+    <p>
+    In the future, it would certainly help if the scripts understood
+    something like a <code>title</code> or <code>section</code> tag
+    (preferably something similar to the DocBook SGML commands for
+    that) in the comments, which could help to better structure the
+    output, especially for the longer programs. One would probably
+    like to put a section break before each new function or class, or
+    something along these lines.
+    </p>
 
 
     <hr>