]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Style updated to the use of doxygen
authorGuido Kanschat <dr.guido.kanschat@gmail.com>
Mon, 7 Mar 2005 16:13:56 +0000 (16:13 +0000)
committerGuido Kanschat <dr.guido.kanschat@gmail.com>
Mon, 7 Mar 2005 16:13:56 +0000 (16:13 +0000)
git-svn-id: https://svn.dealii.org/trunk@10033 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/doc/development/writing-documentation.html

index 4c399c38262eb6472db486ed2ebd2f4a6e07fbf1..4fe93f3107db3eb2120dab47ddf3ef69ae91f75c 100644 (file)
         </p>
 
     <li> <em>Typewriter font:</em>
+
          <p>
-        One would often like to use a typewriter font for variable,
-        function, or class names. For this, the <code>@p
-        one_word_without_spaces</code> tag is used, which generates
-        output in which the single word after the tag is set in
-        typewriter font. If you want to put multiple words into
-        typewriter font, then enclosing them in the HTML
-        <code>&lt;tt&gt;</code> is the way to go.
+        In order to use typewriter font for instance for function
+        arguments or variables, use the <code>&lt;tt&gt;</code> HTML
+        tag. For a single word, you can also use the form <code>@p
+        one_word_without_spaces</code>.
         </p>
 
         <p>
-        As a convention, we always write variable and function
-        names as <code>@p name</code> in order to give them a visible
-        distinction.
+        If you refer to member variables and member functions
+        <acronym>doxygen</acronym> has better options than this: use
+        <tt>function_name()</tt> to reference member functions and
+        <tt>#variable_name</tt> for member variables to create links
+        automatically. Refer to the documentation of <a
+        href="http:www.doxygen.org"><acronym>doxygen</acronym></a> to
+        get even more options for global variables.
         </p>
 
     <li> <em>Emphasis:</em>
          <p>
         To generate output in italics, use the <code>@em
-        one_word_without_spaces</code> tag.
+        one_word_without_spaces</code> tag or the <tt>&lt;em&gt;</tt>
+        HTML tag. To generate boldface, use <tt>&lt;b&gt;</tt>
+        </p>
+
+    <li> <em>Formul&aelig;:</em>
+         <p>
+        For simple and short formul&aelig; use the <tt>&lt;i&gt;</tt>
+        HTML tag. Remark that you can use <tt>&lt;sub&gt;</tt> and
+        <tt>&lt;sup&gt;</tt> to get subscripts an superscripts,
+        resp. Only for longer formul&aelig; use
+        <tt>$formula$</tt> to generate an LaTeX formula which will be
+        included as a graphical image.
         </p>
 
     <li> <em>Sections:</em>
          <p>
-        Sections can be generated using <code>@section TAG Section_name,
-        tag. Here, <code>TAG</code> is a symbolic name for the
-        section, which can be used for cross references.
+        Sections in class and function documentations can be
+        generated using the <tt>&lt;hN&gt;</tt> HTML headline
+        tags. Headlines inside class documentation should start at
+        level 3 (<tt>&lt;h3&gt;</tt>) to stay consistent with the
+        structure of the <acronym>doxygen</acronym> output.
+        </p>
+        
+        <p>
+        Sections cannot be referenced, unless you add a <tt>&lt;A
+        NAME="..."&gt;</tt> name anchor to them. If you really have
+        to do this, please make sure the name does not interfere with
+        <acronym>doxygen</acronym> generated anchors.
         </p>
     </ul>
     </p>
     <a name="examples">
     <h3>Writing example programs</h3>
 
+    <h4>The Tutorial</h4>
     <p>
     At present, the tools that extract information from the example
     programs are rather dumb. They are, to be precise, two Perl
     something along these lines.
     </p>
 
-
+    <h4>Code examples for the usage of single classes</h4>
+    <p>
+    Writing example files for classes is supported by
+    <acronym>doxygen</acronym>. These example files go into
+    <tt>deal.II/examples/doxygen</tt>. If they are short,
+    documentation should be inside and they are included into the
+    documentation with <code>@include filename</code>.
+    </p>
+    
+    <p>
+    Larger example files should be documented using the
+    <acronym>doxygen</acronym> command <code>@dotinclude</code> and
+    related commands.
+    </p>
     <hr>
     
     <address>

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.