diff --git a/doc/GUIDELINES b/doc/GUIDELINES
index 8038f997de..5603ca3f65 100644
--- a/doc/GUIDELINES
+++ b/doc/GUIDELINES
@@ -109,7 +109,7 @@ eg,
     |
     |    Within the implementation, a loop over all patches is done:
     |    @code
-    |        forAll (patches, patchI)
+    |        forAll(patches, patchI)
     |        {
     |            ...  // some operation
     |        }
@@ -222,4 +222,4 @@ The doc/Doxygen/tools directory contains miscellaneous scripts for finding
 and possibly repairing documentation issues.
 
 
-Updated: 2008-03-17
+Updated: 2009-11-27
diff --git a/doc/codingStyleGuide.org b/doc/codingStyleGuide.org
index 6c5f691aa5..da50ffcd93 100644
--- a/doc/codingStyleGuide.org
+++ b/doc/codingStyleGuide.org
@@ -17,292 +17,244 @@
     + Avoid trailing whitespace.
 
     + stream output
-      << is always four characters after the start of the stream,
-      so that the << symbols align, i.e.
+      =<<= is always four characters after the start of the stream,
+      so that the =<<= symbols align, i.e.
 
-#+BEGIN_EXAMPLE
-      Info<< ...
-      os  << ...
-#+END_EXAMPLE
+    :Info<< ...
+    :os  << ...
 
       so
 
-#+BEGIN_EXAMPLE
-      WarningIn("className::functionName()")
-          << "Warning message"
-#+END_EXAMPLE
+    :WarningIn("className::functionName()")
+    :    << "Warning message"
 
       NOT
 
-#+BEGIN_EXAMPLE
-      WarningIn("className::functionName()")
-      << "Warning message"
-#+END_EXAMPLE
+    :WarningIn("className::functionName()")
+    :<< "Warning message"
+
 
     + no unnecessary class section headers, i.e. remove
 
-#+BEGIN_EXAMPLE
-      // * * * * * * * * * * * * * Private Member Functions  * * * * * * * * * * * //
-
-      // Check
-
-      // Edit
-
-      // Write
-#+END_EXAMPLE
+    :// * * * * * * * * * * * * * Private Member Functions  * * * * * * * * * * * //
+    :
+    :// Check
+    :
+    :// Edit
+    :
+    :// Write
 
       if they contain nothing, even if planned for 'future use'
 
     + class titles are centred
 
-#+BEGIN_EXAMPLE
-     /*---------------------------------------------------------------------------*\
-                             Class exampleClass Declaration
-     \*---------------------------------------------------------------------------*/
-#+END_EXAMPLE
+    :/*---------------------------------------------------------------------------*\
+    :                        Class exampleClass Declaration
+    :\*---------------------------------------------------------------------------*/
 
-    NOT
+      NOT
 
-#+BEGIN_EXAMPLE
-     /*---------------------------------------------------------------------------*\
-                    Class exampleClass Declaration
-     \*---------------------------------------------------------------------------*/
-#+END_EXAMPLE
+    :/*---------------------------------------------------------------------------*\
+    :               Class exampleClass Declaration
+    :\*---------------------------------------------------------------------------*/
 
-*** .H Files
+*** The =.H= Files
     + header file spacing
-      Leave two empty lines between sections (as per functions in the .C file etc)
+      Leave two empty lines between sections (as per functions in the =.C= file etc)
 
     + use "//- Comment" comments in header file
       + add descriptions to class data and functions
     + destructor
       If adding a comment to the destructor - use //- and code as a normal function:
 
-#+BEGIN_EXAMPLE
-      //- Destructor
-      ~className();
-#+END_EXAMPLE
+    ://- Destructor
+    :~className();
+
     + inline functions
       Use inline functions where appropriate in a separate classNameI.H file.
       Avoid cluttering the header file with function bodies.
 
-*** .C Files
-    + Do not open/close namespaces in a .C file
+*** The =.C= Files
+    + Do not open/close namespaces in a =.C= file
       Fully scope the function name, i.e.
 
-#+BEGIN_EXAMPLE
-      Foam::returnType Foam::className::functionName()
-#+END_EXAMPLE
+    :Foam::returnType Foam::className::functionName()
 
       NOT
 
-#+BEGIN_EXAMPLE
-      namespace Foam
-      {
-          ...
-
-          returnType className::functionName()
-
-          ...
-      }
-#+END_EXAMPLE
+    :namespace Foam
+    :{
+    :    ...
+    :
+    :    returnType className::functionName()
+    :
+    :    ...
+    :}
 
       EXCEPTION
 
-      When there are multiple levels of namespace, they may be used in the .C
+      When there are multiple levels of namespace, they may be used in the =.C=
       file, i.e.
 
-#+BEGIN_EXAMPLE
-      namespace Foam
-      {
-      namespace compressible
-      {
-      namespace RASModels
-      {
-
-          ...
-
-      } // End namespace RASModels
-      } // End namespace compressible
-      } // End namespace Foam
-#+END_EXAMPLE
+    :namespace Foam
+    :{
+    :namespace compressible
+    :{
+    :namespace RASModels
+    :{
+    :
+    :    ...
+    :
+    :} // End namespace RASModels
+    :} // End namespace compressible
+    :} // End namespace Foam
 
     + Use two empty lines between functions
 
-*** Coding Practise
+*** Coding Practice
     + passing data as arguments or return
       Pass bool, label and scalar as copy, anything larger by reference.
+
     + const
       Use everywhere it is applicable.
+
     + variable initialisation using "="
 
-#+BEGIN_EXAMPLE
-      const className& variableName = otherClass.data();
-#+END_EXAMPLE
+    : const className& variableName = otherClass.data();
 
       NOT
 
-#+BEGIN_EXAMPLE
-      const className& variableName(otherClass.data());
-#+END_EXAMPLE
+    : const className& variableName(otherClass.data());
 
     + virtual functions
       If a class is virtual - make all derived classes virtual.
 
 *** Conditional Statements
-#+BEGIN_EXAMPLE
-    if (condition)
-    {
-        code;
-    }
-#+END_EXAMPLE
+    :if (condition)
+    :{
+    :    code;
+    :}
 
     OR
 
-#+BEGIN_EXAMPLE
-    if
-    (
-       long condition
-    )
-    {
-        code;
-    }
-#+END_EXAMPLE
+    :if
+    :(
+    :   long condition
+    :)
+    :{
+    :    code;
+    :}
 
     NOT (no space between "if" and "(")
 
-#+BEGIN_EXAMPLE
-    if(condition)
-    {
-        code;
-    }
-#+END_EXAMPLE
+    :if(condition)
+    :{
+    :    code;
+    :}
 
-*** `for' Loops
-#+BEGIN_EXAMPLE
-    for (i = 0; i < maxI; i++)
-    {
-        code;
-    }
-#+END_EXAMPLE
+*** =for= Loops
+    :for (i = 0; i < maxI; i++)
+    :{
+    :    code;
+    :}
 
     OR
 
-#+BEGIN_EXAMPLE
-    for
-    (
-        i = 0;
-        i < maxI;
-        i++
-    )
-    {
-        code;
-    }
-#+END_EXAMPLE
+    :for
+    :(
+    :    i = 0;
+    :    i < maxI;
+    :    i++
+    :)
+    :{
+    :    code;
+    :}
 
     NOT (no space between "for" and "(")
 
-#+BEGIN_EXAMPLE
-    for(i = 0; i < maxI; i++)
-    {
-        code;
-    }
-#+END_EXAMPLE
+    :for(i = 0; i < maxI; i++)
+    :{
+    :    code;
+    :}
 
-*** `forAll' loops
-    like for loops, but
+    Note that when indexing through iterators, it is often slightly more
+    efficient to use the pre-increment form. Eg, =++iter= instead of =iter++=
 
-#+BEGIN_EXAMPLE
-    forAll(
-#+END_EXAMPLE
+*** =forAll= loops
+    like =for= loops, but
+
+    :forAll(
 
     NOT
 
-#+BEGIN_EXAMPLE
-    forAll (
-#+END_EXAMPLE
+    :forAll (
 
 *** Splitting Over Multiple Lines
-   + splitting return type and function name
+
+**** Splitting return type and function name
      + split initially after the function return type and left align
 
-     + do not put "const" onto its own line - use a split to keep it with the
-       function name and arguments.
+     + do not put "const" onto its own line - use a split to keep it with
+       the function name and arguments.
 
      so:
 
-#+BEGIN_EXAMPLE
-     const Foam::longReturnTypeName&
-     Foam::longClassName::longFunctionName const
-#+END_EXAMPLE
+     :const Foam::longReturnTypeName&
+     :Foam::longClassName::longFunctionName const
 
      NOT
 
-#+BEGIN_EXAMPLE
-     const Foam::longReturnTypeName&
-         Foam::longClassName::longFunctionName const
-#+END_EXAMPLE
+     :const Foam::longReturnTypeName&
+     :    Foam::longClassName::longFunctionName const
 
      NOR
 
-#+BEGIN_EXAMPLE
-     const Foam::longReturnTypeName& Foam::longClassName::longFunctionName
-     const
-#+END_EXAMPLE
+     :const Foam::longReturnTypeName& Foam::longClassName::longFunctionName
+     :const
 
      NOR
 
-#+BEGIN_EXAMPLE
-     const Foam::longReturnTypeName& Foam::longClassName::
-     longFunctionName const
-#+END_EXAMPLE
+     :const Foam::longReturnTypeName& Foam::longClassName::
+     :longFunctionName const
 
 
-     + if need to split again, split at the function name (leaving behind the
-         preceding scoping "::"s), and again, left align, i.e.
+     + if it needs to be split again, split at the function name (leaving
+       behind the preceding scoping "::"s), and again, left align, i.e.
 
-#+BEGIN_EXAMPLE
-       const Foam::longReturnTypeName&
-       Foam::veryveryveryverylongClassName::
-       veryveryveryverylongFunctionName const
-#+END_EXAMPLE
+     For example,
 
-   + splitting long lines at an "="
+     :const Foam::longReturnTypeName&
+     :Foam::veryveryveryverylongClassName::
+     :veryveryveryverylongFunctionName const
+
+**** Splitting long lines at an "="
 
      Indent after split
 
-#+BEGIN_EXAMPLE
-     variableName =
-         longClassName.longFunctionName(longArgument);
-#+END_EXAMPLE
+     :variableName =
+     :    longClassName.longFunctionName(longArgument);
 
      OR (where necessary)
 
-#+BEGIN_EXAMPLE
-     variableName =
-         longClassName.longFunctionName
-         (
-             longArgument1,
-             longArgument2
-         );
-#+END_EXAMPLE
+     :variableName =
+     :    longClassName.longFunctionName
+     :    (
+     :        longArgument1,
+     :        longArgument2
+     :    );
 
      NOT
 
-#+BEGIN_EXAMPLE
-     variableName =
-     longClassName.longFunctionName(longArgument);
-#+END_EXAMPLE
+     :variableName =
+     :longClassName.longFunctionName(longArgument);
 
      NOR
 
-#+BEGIN_EXAMPLE
-     variableName = longClassName.longFunctionName
-     (
-         longArgument1,
-         longArgument2
-     );
-#+END_EXAMPLE
+     :variableName = longClassName.longFunctionName
+     :(
+     :    longArgument1,
+     :    longArgument2
+     :);
 
 *** Maths and Logic
     + operator spacing
@@ -318,34 +270,201 @@
       with the operator on the lower line.  Align operator so that first
       variable, function or bracket on the next line is 4 spaces indented i.e.
 
-#+BEGIN_EXAMPLE
-      variableName =
-          a * (a + b)
-        - exp(c/d)
-        * (k + t);
-#+END_EXAMPLE
+    :variableName =
+    :    a * (a + b)
+    :  - exp(c/d)
+    :  * (k + t);
 
       This is sometime more legible when surrounded by extra parentheses:
 
-#+BEGIN_EXAMPLE
-      variableName =
-      (
-          a * (a + b)
-        - exp(c/d)
-        * (k + t)
-      );
-#+END_EXAMPLE
+    :variableName =
+    :(
+    :    a * (a + b)
+    :  - exp(c/d)
+    :  * (k + t)
+    :);
 
     + splitting logical tests over several lines
 
       outdent the operator so that the next variable to test is aligned with
       the four space indentation, i.e.
 
-#+BEGIN_EXAMPLE
-      if
-      (
-          a == true
-       && b == c
-      )
-#+END_EXAMPLE
+    :if
+    :(
+    :    a == true
+    : && b == c
+    :)
+
+** Documentation
+
+*** General
+
+    + For readability in the comment blocks, certain tags are used that are
+      translated by pre-filtering the file before sending it to Doxygen.
+
+    + The tags start in column 1, the contents follow on the next lines and
+      indented by 4 spaces. The filter removes the leading 4 spaces from the
+      following lines until the next tag that starts in column 1.
+
+    + The 'Class' and 'Description' tags are the most important ones.
+
+    + The first paragraph following the 'Description' will be used for the
+      brief description, the remaining paragraphs become the detailed
+      description.
+
+      For example,
+
+    :Class
+    :    Foam::myClass
+    :
+    :Description
+    :    A class for specifying the documentation style.
+    :
+    :    The class is implemented as a set of recommendations that may
+    :    sometimes be useful.
+
+    + The class name must be qualified by its namespace, otherwise Doxygen
+      will think you are documenting some other class.
+
+    + If you don't have anything to say about the class (at the moment), use
+      the namespace-qualified class name for the description. This aids with
+      finding these under-documented classes later.
+
+
+    :Class
+    :    Foam::myUnderDocumentedClass
+    :
+    :Description
+    :    Foam::myUnderDocumentedClass
+
+
+    + Use 'Class' and 'Namespace' tags in the header files.
+      The Description block then applies to documenting the class.
+
+    + Use 'InClass' and 'InNamespace' in the source files.
+      The Description block then applies to documenting the file itself.
+
+
+    :InClass
+    :    Foam::myClass
+    :
+    :Description
+    :    Implements the read and writing of files.
+
+*** Doxygen Special Commands
+
+    Doxygen has a large number of special commands with a '\' prefix or a
+    (alternatively) an '@' prefix.
+
+    The '@' prefix form is recommended for most Doxygen specials, since it
+    has the advantage of standing out. It also happens to be what projects
+    like gcc and VTK are using.
+
+    The '\' prefix form, however, looks a bit better for the '\n' newline
+    command and when escaping single characters - eg, '\@', '\<', '\>', etc.
+
+    Since the filtering removes the leading 4 spaces within the blocks, the
+    Doxygen commmands can be inserted within the block without problems.
+
+
+    :InClass
+    :    Foam::myClass
+    :
+    :Description
+    :    Implements the read and writing of files.
+    :
+    :    An example input file:
+    :    @verbatim
+    :        patchName
+    :        {
+    :            type        myPatchType;
+    :            refValue    100;
+    :            value       uniform 1;
+    :        }
+    :    @endverbatim
+    :
+    :    Within the implementation, a loop over all patches is done:
+    :    @code
+    :        forAll(patches, patchI)
+    :        {
+    :            ...  // some operation
+    :        }
+    :    @endcode
+
+*** HTML Special Commands
+
+    Since Doxygen also handles HTML tags to a certain extent, the angle
+    brackets need quoting in the documentation blocks. Non-HTML tags cause
+    Doxygen to complain, but seem to work anyhow.
+
+    eg,
+    + The template with type <HR> is a bad example.
+
+    + The template with type \<HR\> is a better example.
+
+    + The template with type <Type> causes Doxygen to complain about an
+      unknown html type, but it seems to work okay anyhow.
+
+
+*** Documenting Namespaces
+
+    + If namespaces are explictly declared with the Namespace() macro,
+      they should be documented there.
+
+    + If the namespaces is used to hold sub-models, the namespace can be
+      documented in the same file as the class with the model selector.
+      eg,
+    :documented namespace 'Foam::functionEntries' within the
+    :class 'Foam::functionEntry'
+
+    + If nothing else helps, find some sensible header.
+      eg,
+    :namespace 'Foam' is documented in the foamVersion.H file
+
+
+*** Documenting Typedefs and classes defined via macros
+
+    ... not yet properly resolved
+
+
+*** Documenting Applications
+
+    Any number of classes might be defined by a particular application, but
+    these classes will not, however, be available to other parts of
+    OpenFOAM. At the moment, the sole purpuse for running Doxygen on the
+    applications is to extract program usage information for the '-doc'
+    option.
+
+    The documentation for a particular application is normally contained
+    within the first comment block in a =.C= source file. The solution is this
+    to invoke a special filter for the "applications/{solver,utilities}"
+    directories that only allows the initial comment block for the =.C= files
+    through.
+
+    The layout of the application documentation has not yet been finalized,
+    but foamToVTK shows an initial attempt.
+
+*** Orthography (an opinion)
+
+    Given the origins of OpenFOAM, the British spellings (eg, neighbour and
+    not neighbor) are generally favoured. For code sections that interact
+    with external libraries, it can be useful to adopt American spellings,
+    especially for names that constitute a significant part of the external
+    library - eg, 'color' within graphics sub-systems.
+
+    Both '-ize' and the '-ise' variant are found in the code comments. If
+    used as a variable or class method name, it is probably better to use
+    '-ize', which is considered the main form by the Oxford University
+    Press.
+
+    Eg,
+    :myClass.initialize()
+
+
+    The word "its" (possesive) vs. "it's" (colloquial for "it is" or "it has")
+    seems to confuse non-native (and some native) English speakers.
+    It is better to donate the extra keystrokes and write "it is" or "it has".
+    Any remaining "it's" are likely an incorrect spelling of "its".
+
+