resync with documentation on lumiera website

doc/devel/rfc/CCodingStyleGuide.txt

@@ -65,16 +65,11 @@ For each `struct namespace_foo_struct` we have following typedefs:
 
 [source,C]
 ----
-typedef struct namespace_foo_struct namespace_foo;          // canonical
-typename
-typedef const namespace_foo * const_NamespaceFoo;           // pointer to const
-object
-typedef namespace_foo* link:NamespaceFoo[];                 // canonical
-pointer/handle
-typedef namespace_foo ** link:NamespaceFoo[]_ref;           // when intend to
-mutate the handle itself
-typedef const namespace_foo ** const_NamespaceFoo_ref;      // for const object
-handle
+typedef struct namespace_foo_struct namespace_foo;   // basic struct name
+typedef namespace_foo* NamespaceFoo;                 // canonical object pointer/handle
+typedef const namespace_foo * const_NamespaceFoo;    // pointer to const object
+typedef namespace_foo ** NamespaceFoo_ref;           // when intend to mutate the handle itself
+typedef const namespace_foo ** const_NamespaceFoo_ref;  // same for const object handle
 ----
 
 Examples:

doc/index.txt

@@ -16,6 +16,16 @@ Informations about the structure of Lumiera, they give an overview on the main c
 Programming-oriented details about the functional layers of Lumiera as well as a Doxygen documentation :
 
  * link:technical/index.html[Technical Documents]
+ * link:technical/code/codingGuidelines.html[Style and Coding Guidelines]
+
+=== the TiddlyWiki ===
+Currently, Lumiera is still in the design- and evolution phase.
+There is an embedded JavaScript wiki (TiddlyWiki) within the source tree, mostly
+used as design notebook, featuring day-to-day design sketches, notes but also
+quite some more persistent planning. Finished documentation text is constantly
+moved over to the documentation section(s) of the Lumiera website.
+
+-> access the Proy-Layer link:http://lumiera.org/wiki/renderengine.html[TiddlyWiki online here]
 
 
 == Media and Presentations ==

doc/technical/code/codingGuidelines.txt

@@ -0,0 +1,117 @@
+Coding Guidelines
+=================
+:Date: Autumn 2011
+
+
+_this page summarises some style and coding guidelines for the Lumiera code base_
+
+Style Guide
+-----------
+The Lumiera project uses GNU indentation style with slight adaptations.
+
+- *no tabs* please. The typical ``semi indent'' of GNU style thus becomes 2 spaces.
+- maximum line length is rather around *110 characters*.
+- originally, GNU style focussed on plain-C code. +
+  We thus apply some relaxations and clarifications ...
+  
+  * the braces for a class scope are indented by 2 spaces
+  * the access modifiers start at this brace level, while all declarations and definitions
+    within the class are again indented by 2 spaces
+  * the line breaking rules are relaxed. Definitions and statements may be written as single line,
+    provided that the length remains below 110 chars and the result _remains legible_. Otherwise,
+    we'll fall back to the default and wrap the lines. More specifically
+  
+    ** function declarations may be written in one line
+    ** same for definitions with just a single statement in the body
+    ** same for simple if-statements without else-branch.
+  
+  * the space between function name and opening parenthesis of the argument list is not
+    enforced when this doesn't make sense, esp. for argument-less functions, chained calls
+    or constructor syntax. But in all other cases, we really value this additional space,
+    it improves legibility.
+  * template argument declarations are _always_ written on a separate line, above the
+    return type declaration. This rule holds even if the rest of a definition can be
+    written within a single line.
+  * the opening brace of namespaces is placed on the same line. Optionally, the namespace
+    body may be indented, as long as this helps underpinning the nesting structure. But
+    there is no need to use 3 indents on a 3 level nested namespace. One level is enough
+    to underpin the presence of a nesting.
+
+Naming conventions
+~~~~~~~~~~~~~~~~~~
+Naming conventions are used to underpin the kind of element at hand and give a visual
+clue to the reader. We use our own conventions -- there is no point in arguing that this
+and that library or language uses other conventions.
+
+- type names start with an uppercase letter
+- variable and function names start with lowercase.
+- fields within a class, especially the private ones are decorated with a trailing underscore
+- a leading underscore may be used to emphasize the strictly internal or technical nature of a type,
+  variable or function
+- namespaces are all-lowercase
+- macros and constants are preferably all-caps (at least where this makes sense)
+
+There is a preference for *CamelCase* -- yet underscores are acceptable, especially when the
+name is more like a sentence than just a compound term.
+
+plain-C names
+^^^^^^^^^^^^^
+Since C has no namespaces, we strictly require a +lumiera_+ prefix on all non-local names and definitions.
+Generally, names should be formed according to the following pattern:
+
+ namespace[_object][_verb[_subjects]][_version]
+
+In case a definition actually denotes an object, there should be
+
+- a basic struct name: `typedef struct namespace_foo_struct namespace_foo;`
+- plus an object pointer/handle: `typedef namespace_foo* NamespaceFoo;`
+
+The object pointer/handle should be passed as 1^st^ argument with the name +self+
+
+
+General Code Arrangement and Layout
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+- Headers and translation units are named `*.hpp` and `*.cpp` rsp. `*.h` and `*.c` +
+  Multilingual headers are called `*.h`
+- Each header should be named according to the primary facility it exposes. For the filesystem name,
+  the +CamelCaseWords+ of this type are translated into +camel-case-words.hpp+
+- Each file should start with the GNU licence preamble. The headline should give a one-line summary.
+  The primary author(s) and the year of the initial copyright claim should be mentioned.
+- Each header should be focussed on a specific purpose. Preferably it starts with a file-level
+  doxygen comment explaining the intention and anything not obvious from reading the code.
+- when arranging headers and compilation units, please take care of the compilation times and the
+  code size. Avoid unnecessary includes. Use forward declarations where applicable.
+  Yet still, _all really required includes should be mentioned_ (even if already included by another
+  dependency)
+- The include block starts with our own dependencies, followed by a second block with the library
+  dependencies. After that, optionally some symbols may be brought into scope (through +using+ clauses).
+  Avoid cluttering top-level namespaces. Never import full namespaces (no +using namespace boost;+ please!)
+- the includes for our own dependencies shall be given relative to source-root (or test root). Don't use
+  relative includes for headers located in the same directory, or -- worse still -- in the parent directory.
+- sometimes, the actual translation units will combine several facilities for technical reasons, e.g.
+  when sharing an implementation-level class or even singleton instance.
+  Anonymous namespaces should be used liberally to avoid unnecessary exports.
+- template code mostly needs to reside in headers. (same for metaprogramming code).
+  We employ the simple inclusion model (``Borland model'') for template instantiation.
+- But in some specific situations it is preferable to drive explicit instantiations from within
+  a +*.cpp+ file. Most notably this is the case when defining some core class hierarchies.
+  Such explicit instantiations should be limited to just a view obvious places. They should be
+  written into a block at the end of some central implementation file. See +assetmanager.cpp+
+  for an example.
+- deliberately there is _no single top-level namespace._ The +namespace lumiera+ is the root of
+  our _exported interfaces_ -- intended for use by external scripts and libraries. Everything
+  implementation related is arranged in per-subsystem trees of namespaces. The APIs of the
+  subsystems are exported explicitly into the +lumiera+ namespace.
+
+
+Design Guidelines and Values
+----------------------------
+Code is written for *being read by humans*; code shall convey its meaning even to the casual reader.
+On the long run, this language nature of code is more important than any performance tweaks. Recall,
+every idiot can figure out how to make a computer perform something. Yet the real challenge is to
+write legible code. Code that operates exactly the way you'd guess just from reading it.
+Black magic and all kinds of surprise trickery and cleverness are nothing to be proud off.
+
+-> please have a look at the link:/project/background/CleanCodeDevelopment.html[Clean Code] page
+for a coherent system of design principles
+

doc/technical/index.txt

@@ -31,6 +31,7 @@ components.
 .Development
 * link:http://www.lumiera.org/doxy/[*Doxygen generated documentation*] : API documentation of the Lumiera code.
 * organisation of the link:code/index.html[Code Base] in general
+* link:code/codingGuidelines.html[Coding Style] and further guidelines
 
 .Building
 * link:build/index.html[*Buildsystem*] : Installation & compilation tools, dependencies and packaging.

doc/technical/overview.txt

@@ -48,20 +48,28 @@ The extra components are:
 Coding Style
 ~~~~~~~~~~~~
 
-The Lumiera team agreed on using GNU coding style with some exceptions (no
-tabs, line wrap must not always be enforced). Otherwise we are a bit pedantic
-to be consistent to make the codebase uniform. Function naming conventions
-and other details are described in several RFCs.
+The Lumiera team agreed on using GNU coding style with slight adaptations.
+Generally speaking, we strive to keep the code base consistent and stick to
+widely accepted guidelines and best practices. See our separate
+link:{ldoc}/technical/code/codingGuidelines.html[Coding Guidelines] page.
+Function naming conventions and other details are also described in several RFCs.
+
 
 Documentation
 ~~~~~~~~~~~~~
+The central location for all design and technical documentation is the Lumiera
+website you're reading right now. Besides that, a summary and introduction
+for various components can be found in the file-level doxygen comments, while
+details are usualy explained in the class and function level comments.
 
-Every public function should be documented with doxygen comments. The overall
-design is outlined in this text and documented in the various detail pages and
-accompanying RFCs. Bootstrapping the Lumiera design used several other places,
-in several TiddlyWikis, an UML model and cehteh's private wiki, most of this
-information is asciidoced meanwhile and in progress to be integrated in the
-central documentation hierarchy.
+==== the TiddlyWiki
+Currently, Lumiera is still in the design- and evolution phase. Documentation
+is written as an ongoing effort.
+There is an embedded JavaScript wiki (TiddlyWiki) within the source tree, mostly
+used as design notebook, featuring day-to-day design sketches and notes, but also
+quite some more persistent planning. Finished documentation text is constantly
+moved over to the documentation section(s) of the Lumiera website. +
+-> access the Proy-Layer link:http://lumiera.org/wiki/renderengine.html[TiddlyWiki online here]
 
 
 Test Driven Development
@@ -73,7 +81,7 @@ implemented until they pass their tests. While increasing the initial
 development effort significantly, this approach is known to lead to
 clearly defined components and overall increases code quality.
 In practice, this approach might not be suitable at times,
-nevertheless we try to sick to it as far as possible
+nevertheless we try to stick to it as far as possible
 and maintain fairly complete test coverage.
 
 

doc/user/intro/intro.txt

@@ -1,7 +1,6 @@
 Lumiera (as seen) from Outer Space
 ==================================
-:Author: Christian Thäter ct@pipapo.org
-:Author: Hermann Voßeler Ichthyostega@web.de
+:Author: Lumiera_Core_Developers
 :Date: Summer 2010