Commits

dbacchet committed 25d176d

added very simple implementation of the IDLookupTable
first draft of the coding style for c++ (in markdown text format)

  • Participants
  • Parent commits 9126e11

Comments (0)

Files changed (8)

File docs/coding_style_cpp.html

+<p><link href="markdown.css" rel="stylesheet"></link></p>
+
+<h1>Coding Style -- C++</h1>
+
+<h2>Contents</h2>
+
+<ol>
+<li>Introduction
+<ul>
+<li>A common style is good</li>
+<li>Some choices are arbitrary</li>
+<li>Some things don't matter</li>
+<li>Avoid revision wars</li>
+<li>Style exceptions are allowed</li>
+</ul></li>
+<li>Naming
+<ul>
+<li>Naming is important</li>
+<li>Names should provide all necessary information, nothing more</li>
+<li>A bigger scope warrants a more descriptive name</li>
+<li>Do not use abbreviations in names</li>
+<li>Name functions and variables <code>like_this()</code></li>
+<li>Name classes <code>LikeThis</code></li>
+<li>Name member variables <code>_like_this</code></li>
+<li>Name #defines <code>LIKE_THIS</code></li>
+<li>Name macros <code>LIKE_THIS</code></li>
+<li>Name namespaces <code>like_this</code></li>
+<li>Name enums <code>LikeThis</code>, and enum values <code>LIKE_THIS</code></li>
+<li>Name files <code>like_this.cpp</code></li>
+<li>Standard functions</li>
+<li>Use sensible names</li>
+</ul></li>
+<li>Braces
+<ul>
+<li>The bracing styles and when to use them</li>
+<li>Use braces to increase readability in nested scopes</li>
+<li>Fit matching braces on a single screen</li>
+<li>Use <code>continue</code>, <code>break</code> or even <code>goto</code> (!) to avoid deep nesting</li>
+</ul></li>
+<li>Indentation and Spacing
+<ul>
+<li>Use four spaces of indentation</li>
+<li>Think about evaluation order when placing spaces</li>
+<li>Indent #if statements</li>
+<li>Do not indent the entire file</li>
+<li>Make lines reasonably long</li>
+</ul></li>
+<li>Comments
+<ul>
+<li>Use <code>//</code> for descriptive comments <code>/*</code> for disabling code</li>
+<li>Do not leave disabled code in the source</li>
+<li>Put interface documentation in the .h file</li>
+<li>Use Doxygen syntax for interface documentation</li>
+<li>Use comments as hints to the reader</li>
+<li>Avoid boilerplate comments</li>
+<li>Don't put high level documentation in source code comments</li>
+<li>Comment a file like this</li>
+<li>Comment a class like this</li>
+<li>Comment a function like this</li>
+</ul></li>
+<li>Design and Implementation Issues
+<ul>
+<li>Optimize wisely</li>
+</ul></li>
+<li>Miscellaneous Tidbits
+<ul>
+<li>Use <code>#pragma once</code> to avoid multiple header inclusion</li>
+</ul></li>
+</ol>
+
+<h2>1. Introduction</h2>
+
+<h3>1.1 A common style is good</h3>
+
+<p>A common coding style is useful. It makes it easier to communicate, and it makes the code easier to read.</p>
+
+<h3>1.2 Some choices are arbitrary</h3>
+
+<p>Some of the style choices described in this manual are (at least according to me) very well motivated, other are just arbitrary choices. Sometimes there is no reason to pick one particular style over another, but it is still useful to mandate a specific choice to ensure a consistent style.</p>
+
+<h3>1.3 Some things don't matter</h3>
+
+<p>The purpose of this style guide is not to cover every possible situation. If something is not covered by this guide it is probably something that doesn't matter that much and you are free to use whatever style you are most accustomed to. If you think something should be in the guide, just bring it up to discussion.</p>
+
+<h3>1.4 Avoid revision wars</h3>
+
+<p>If you see something that obviously does not follow the standard in a source file you should feel free to change it. <br>
+If you see something that perhaps does not follow the standard, but you are not sure, it is better to leave it. <br>
+There is not much point in going over the entire codebase looking for style violations. Such nitpicking is not very productive. Instead, just fix the style violations in code you are working on anyway. <br>
+Avoid changing the style back and forth in the same piece of code. If you cannot agree on the style, talk about it instead of having a "cold war" in the codebase.</p>
+
+<p>If you disagree strongly with one of the rules in this style guide, you should propose a change to the rule rather than silently rebel.</p>
+
+<h3>1.5 Style exceptions are allowed</h3>
+
+<p>You can decide to break some rule, but <em>only</em> if this bring to a clearer code, depending on the context.</p>
+
+<h2>2. Naming</h2>
+
+<h3>2.1 Naming is important</h3>
+
+<p>Naming is a fundamental part of programming. The ease-of-use and "feeling" of an API depends a lot on having good names.</p>
+
+<p>Furthermore, names are harder to changes than implementations. This is especially true for names that are exported "outside" the executable itself, such as names for script functions and parameters in configuration files. For this reason, some care should be taken when selecting a name.</p>
+
+<h3>2.2 Names should provide all necessary information, nothing more</h3>
+
+<p>A name should provide all the necessary information to understand what a function or variable is doing but no more than that. I.e., it should not contain redundant information or information that is easily understood from the context (such as the class name).</p>
+
+<pre><code>// BAD: Name provides too little information
+
+char *pstoc(char *);
+float x;
+void Image::draw(float, float);
+
+// BAD: Name provides too much information
+
+char *convert_string_in_pascal_string_format_to_c_string_format(char *);
+float the_speed;
+void Image::draw_image_at(float, float);
+
+// GOOD: Just the right amount
+
+char *pascal_string_to_c(char *s);
+float speed;
+void Image::draw_at(float x, float y);
+</code></pre>
+
+<p>If you cannot come up with a good name for something -- think harder and consult your colleagues. Never use a name that you know is bad.</p>
+
+<pre><code>// BAD:
+
+// What is link2? How it is different from link?
+void link();
+void link2();
+
+// These names don't mean anything.
+Stuff the_thing;
+</code></pre>
+
+<h3>2.3 A bigger scope warrants a more descriptive name</h3>
+
+<p>The more visible a variable is (the larger scope it has) the more descriptive its name needs to be, because less information is provided by the context.</p>
+
+<p>Consider the number of players in a network game. In a small local loop, it is fine to call the variable <code>n</code> because there is not much to confuse it with, and the context immediately shows where the variable is coming from.</p>
+
+<pre><code>int n = num_players();
+for (int i=0; i&lt;n; ++i)
+   ...
+</code></pre>
+
+<p>If it is a function in the network class we need to be more verbose, because n could mean any number of things in that context.</p>
+
+<pre><code>int Network::num_players()
+</code></pre>
+
+<p>If it is a global variable, we must be even more verbose, because we no longer have a Network class context that tells us the variable has something to do with the network:</p>
+
+<pre><code>int _num_players_in_network_game;
+</code></pre>
+
+<p>Note</p>
+
+<p>Public global variables should be avoided. If you <em>really</em> need a global variable, you should hide it behind a function interface (e.g., console_server::get()). This reduces the temptation of misusing the variable.</p>
+
+<h3>2.4 Do not use abbreviations in names</h3>
+
+<p>There are two problems with abbreviations in names:</p>
+
+<p>It gets harder to understand what the name means. This is especially the case with extreme and non-sensical abbreviations like wbs2mc.</p>
+
+<p>Once you start to mix abbreviated and non-abbreviated names, it becomes hard to remember which names where abbreviated and how. It is not hard to understand that world<em>pos means world</em>position. But it can be hard to remember whether the function was called world<em>pos or world</em>position or something else. Never using abbreviation makes it much easier to guess what a function should be called.
+The general rule is "do not use any abbreviations at all". </p>
+
+<p>The only allowed exception is <code>num_</code> which means number of, e.g. <code>num_players()</code> instead of <code>number_of_players()</code>.</p>
+
+<p>Note that the rule against abbreviations <strong>only applies to exported symbols</strong>. A local variable can very well be called pos or p.</p>
+
+<h3>2.5 Name functions and variables <code>like_this()</code></h3>
+
+<p>Use lower case characters and underscores where you would put spaces in a normal sentence.</p>
+
+<p>This style is preferred for functions and variables, because it is the most readable one (most similar to ordinary language) and functions and variables are the things we have most of.</p>
+
+<p>Do not use any kind of Hungarian notation when naming variables and functions. Hungarian notation is evil.</p>
+
+<h3>2.6 Name classes <code>LikeThis</code></h3>
+
+<p>It is good to use a different standard for classes than variables, because it means that we can give temporary variables of a class good names:</p>
+
+<pre><code>Circle circle;
+</code></pre>
+
+<p>If the class was called circle, the variable would have to be called something horrible like <code>a_circle</code> or <code>the_circle</code> or <code>tmp</code>.</p>
+
+<h3>2.7 Name member variables <code>_like_this</code></h3>
+
+<p>Being able to quickly distinguish member variables from local variables is good for readability... and it also allows us to use the most natural syntax for getter and setter methods:</p>
+
+<pre><code>Circle &amp;circle() {return _circle;}
+void set_circle(Circle &amp;circle) {_circle = circle;}
+</code></pre>
+
+<p>A single underscore is used as a prefix, because a prefix with letters in it (like <code>m_</code>) makes the code harder to read.</p>
+
+<pre><code>This _sentence can _be _easily read _even though _it _has _extra underscores.
+But m_throw in m_some letters m_and it m_is m_not so m_easy m_anymore, m_kay.
+</code></pre>
+
+<p>Also, using _ makes the member variables stand out more, since there could be other variables starting with m.</p>
+
+<h3>2.8 Name macros <code>LIKE_THIS</code></h3>
+
+<p>It is good to have <code>#define</code> macro names really standing out, since macros can be devious traps when it comes to understanding the code. (Like when Microsoft redefines GetText to GetTextA.)</p>
+
+<h3>2.9 Name namespaces <code>like_this</code></h3>
+
+<p>This is the most readable syntax, so we prefer this when we don't have any reason to do otherwise.</p>
+
+<h2>2.10 Name enums <code>LikeThis</code>, and enum values <code>LIKE_THIS</code></h2>
+
+<p>Enums are types, just as classes and structs and should follow the same naming convention.</p>
+
+<p>Enum values have big scope (either global scope or enclosing class scope). In many cases enum values are used in the same way as <code>#define</code>s of integer constants and as a user of an API you don't care if a constant is implemented with an enum or with a a macro.</p>
+
+<pre><code>#define ALIGN_LEFT = 0
+enum {ALIGN_LEFT = 0};
+</code></pre>
+
+<p>Since enum values have almost as big scope as macros and in many cases are used in the same way, we use the same naming convention as for macros:</p>
+
+<pre><code>enum Align {ALIGN_LEFT, ALIGN_RIGHT, ALIGN_CENTER};
+</code></pre>
+
+<p>Note that the prefix ALIGN_ on the enum values is needed, since the enum value scope is big. (I consider the big scope of enums a design mistake in C++.)</p>
+
+<h3>2.11 Name files <code>like_this.cpp</code></h3>
+
+<p>Again, this is the most readable format, so we choose that when we don't have a reason to do something else.</p>
+
+<p>The .h files should be put in the same directory as the .cpp files, not in some special "include" directory, for easier navigation between the files.</p>
+
+<h3>2.12 Standard functions</h3>
+
+<p>Getter and setter functions should look like this.</p>
+
+<pre><code>Circle &amp;circle() {return _circle;}
+void set_circle(Circle &amp;circle) {_circle = circle;}
+</code></pre>
+
+<p>The getter is called circle rather than get<em>circle, since the get</em> prefix is superfluous. However, we use a set_ prefix to emphasize that we are changing the state of the object.</p>
+
+<h3>2.13 Use sensible names</h3>
+
+<p>Spell your names correctly.
+Do not write the words "to" and "for" as "2" and "4".
+All names and comments should be in American English.</p>
+
+<h2>3. Braces</h2>
+
+<h3>3.1 The three bracing styles and when to use them</h3>
+
+<p>There are three bracing styles used:</p>
+
+<pre><code>// Single line
+int f() {return 3;}
+
+// Opened on same line
+while (true) {
+    do(stuff);
+    more(stuff);
+}
+
+// New line
+int X::f()
+{
+    return 3;
+}
+</code></pre>
+
+<p>The first style is typically used for getter and setter functions in the header file to make the header more compact.</p>
+
+<p>The second style should never be used.</p>
+
+<p>This third is the preferred for class declarations, function declarations and loops in the cpp file.</p>
+
+<h3>3.2 Use braces to increase readability in nested scopes</h3>
+
+<p>Instead of</p>
+
+<pre><code>// BAD
+while (a)
+    if (b)
+        c;
+</code></pre>
+
+<p>Write</p>
+
+<pre><code>while (a) 
+{
+   if (b)
+       c;
+}
+</code></pre>
+
+<p>Only the innermost scope is allowed to omit its braces.</p>
+
+<h3>3.3 Try to fit matching braces on a single screen</h3>
+
+<p>The opening and closing of a brace should preferably fit on the same screen of code to increase readability.</p>
+
+<p>Class and namespace definitions can of course cover more than one screen.</p>
+
+<p>Function definitions can sometimes cover more than one screen -- if they are clearly structured.</p>
+
+<h3>3.4 Use <code>continue</code>, <code>break</code> or even (gasp) <code>goto</code> to avoid deep nesting</h3>
+
+<p>Code that is indented four or five times can be very hard to read. Often such indentation comes from a combination of loops and if-statements:</p>
+
+<pre><code>// BAD
+for (i=0; i&lt;parent-&gt;num_children(); ++i) 
+{
+    Child child = parent-&gt;child(i);
+    if (child-&gt;is_cat_owner()) 
+    {
+        for (j=0; j&lt;child-&gt;num_cats(); ++j) 
+        {
+            Cat cat = child-&gt;cat(j);
+            if (cat-&gt;is_grey()) 
+            {
+                ...
+</code></pre>
+
+<p>Using continue to rewrite gives a clearer structure:</p>
+
+<pre><code>for (i=0; i&lt;parent-&gt;num_children(); ++i) 
+{
+    Child child = parent-&gt;child(i);
+    if (!child-&gt;is_cat_owner())
+        continue;
+
+    for (j=0; j&lt;child-&gt;num_cats(); ++j) 
+    {
+        Cat cat = child-&gt;cat(j);
+        if (!cat-&gt;is_grey())
+            continue;
+
+        ...
+</code></pre>
+
+<p>Excessive indentation can also come from error checking:</p>
+
+<pre><code>// BAD
+File f = open_file();
+if (f.valid()) 
+{
+    std::string name;
+    if (f.read(&amp;name)) 
+    {
+        int age;
+        if (f.read(&amp;age)) 
+        {
+            ...
+        }
+    }
+}
+</code></pre>
+
+<p>This is one of the few cases where goto can be validly used:</p>
+
+<pre><code>File f = open_file();
+if (!f.valid())
+    goto err;
+
+std::string name;
+if (!f.read(&amp;name))
+    goto err;
+
+int age;
+if (!f.read(&amp;age))
+    goto err;
+
+err:
+    ...
+</code></pre>
+
+<h2>4. Indentation and Spacing</h2>
+
+<h3>4.1 Use four spaces of indentation</h3>
+
+<p>This is the default in Visual Studio and a good compromise between readability and succinctness.</p>
+
+<h3>4.2 Think about evaluation order when placing spaces</h3>
+
+<p>For statements, put a space between keywords and paranthesis, put a space before braces on the same line. Do not put any space before a semicolon.</p>
+
+<pre><code>while (x == true) {
+    do_stuff();
+}
+</code></pre>
+
+<p>Placement of spaces in expressions is not that important. I generally tend to put a space around every binary operator, but not around unary operators (such as array access, function calls, etc).</p>
+
+<pre><code>z = x * y(7) * (3 + p[3]) - 8;
+</code></pre>
+
+<p>You can use a more terse or a more loose style if you want to... but make sure that the placement of spaces reflects the evaluation order of the expression. I.e. begin by removing spaces around operators that have a higher order of precedence. This is OK:</p>
+
+<pre><code>z = x*y(7)*(3 + p[3]) - 8;
+</code></pre>
+
+<p>Because * has higher precedence than - and =. This is confusing and not OK:</p>
+
+<pre><code>// BAD
+z=x * y(7) * (3+p [3])-8;
+</code></pre>
+
+<h3>4.3 Indent <code>#if</code> statements</h3>
+
+<p>By default, the visual studio editor left flushes all preprocessing macros. This is idiotic and makes the code really hard to read, especially when the macros are nested:</p>
+
+<pre><code>// BAD
+void f()
+{
+#ifdef _WIN32
+#define RUNNINGS_WINDOWS
+#ifdef PRODUCTION
+    bool print_error_messages = true
+#else
+    bool print_error_messages = false
+#endif
+#else
+    bool win32 = false
+#endif
+</code></pre>
+
+<p>Instead, indent your macros just as you would normal C code:</p>
+
+<pre><code>void f()
+{
+    #ifdef _WIN32
+        #define RUNNINGS_WINDOWS
+        #ifdef PRODUCTION
+            bool print_error_messages = true
+        #else
+            bool print_error_messages = false
+        #endif
+    #else
+        bool win32 = false
+    #endif
+</code></pre>
+
+<h3>4.4 Do not indent the entire file</h3>
+
+<p>When the entire file is inside one (or several) namespaces, you should not indent the entire file. Indenting an entire file does not increase readability, it just means you will fit less code on the screen.</p>
+
+<p>Instead, put a comment on the closing brace.</p>
+
+<pre><code>namespace skinny
+{
+
+void x();
+...
+
+} // namespace skinny
+</code></pre>
+
+<p>When the namespace declaration does not cover the entire file, but only a screenfull or so, then it can be a good idea to indent it.</p>
+
+<h3>4.5 Make lines reasonably long</h3>
+
+<p>A lot of style guides say that lines should never be more than 80 characters long. This is overly restrictive. We all have displays that can show more than 80 characters per line.</p>
+
+<p>Never write code like this:</p>
+
+<pre><code>// BAD
+int x = the + code +
+    is + indented +
+    and + I + dont +
+    want + to + create
+    + long + lines;
+</code></pre>
+
+<p>Either use less indentation or write longer lines.</p>
+
+<p>Don't go crazy with line lengths, scrolling to see the end of the line is annnoying. Also, make sure not to put very important stuff far to the right where it might be clipped from view.</p>
+
+<h2>5. Comments</h2>
+
+<h3>5.1 Use <code>//</code> for descriptive comments <code>/*</code> for disabling code</h3>
+
+<p><code>//</code> comments are better for comments that you want to leave in the code, because they don't have any nesting problems, it is easy to see what is commented, etc.</p>
+
+<p><code>/*</code> is useful when you want to quickly disable a piece of code.</p>
+
+<h3>5.2 Do not leave disabled code in the source</h3>
+
+<p>Commenting out old bad code with <code>/*</code> ... <code>*/</code> is useful and necessary.</p>
+
+<p>It can be useful to leave the old commented out code in the source file for a while, while you check that the new code does not have any bugs, performance problems, etc. But once you are sure of that you should remove the commented out code from the file.</p>
+
+<p>Having a lot of old, unused, commented out code in the source files makes them harder to read, because you constantly ask yourself why was this commented out, maybe the solution to my problem lies in this commented out code, etc. Source control already keeps a version history, we don't need to keep old code in comments.</p>
+
+<h3>5.3 Put interface documentation in the .h file</h3>
+
+<p>Put interface (function and class documentation) in the .h file. This makes it easier to find all the relevant interface documentation for someone browsing the .h files.</p>
+
+<p>A drawback of this is that the .h files will become bigger and harder to grasp, but that is a price we are willing to pay.</p>
+
+<h3>5.4 Use Doxygen syntax for interface documentation</h3>
+
+<p>Doxygen is a well established standard for interface documentation.</p>
+
+<p>We use the Javadoc-syntax for documentation (///) rather than the QT syntax (//!), because it is easier to type. Use @name to name groups of methods/members.</p>
+
+<pre><code>/// @name Time functions
+
+/// Elapsed seconds since the start of the program
+float time();
+</code></pre>
+
+<p>Most public methods of classes in external interfaces should be documented. Private methods and private variables can be documented when that increases the understanding of the class.</p>
+
+<h3>5.5 Use comments as hints to the reader</h3>
+
+<p>The main source of information about what the code does should be the code itself. The code is always up-to-date, it doesn't lie and no extra effort is required to maintain it. You should not need to add comments that explain what the code does:</p>
+
+<pre><code>// BAD
+
+/// Returns the speed of the vehicle
+float sp() {return _sp;}
+
+// Computes speed from distance and time
+s = d / t;
+
+// Check for end of file
+if (c == -1)
+</code></pre>
+
+<p>Instead, write code that is self-explanatory.</p>
+
+<pre><code>float speed() {return _speed;}
+
+speed = distance / time;
+
+if (c == END_OF_FILE_MARKER)
+</code></pre>
+
+<p>Source code comments should be used as hints to the reader who tries to understand the code. They should point out when the code does something which is a little bit clever or tricky, something that may not be immediately obvious from reading just the code. In complicated algorithms that consist of several steps, they are also useful for identifying the separate steps and giving the user a sense of context.</p>
+
+<pre><code>// Use Duff's device for loop unrolling
+// See for example: http://en.wikipedia.org/wiki/Duff's_device
+switch (count % 8)
+{
+  case 0:        do {  *to = *from++;
+  case 7:              *to = *from++;
+  case 6:              *to = *from++;
+  case 5:              *to = *from++;
+  case 4:              *to = *from++;
+  case 3:              *to = *from++;
+  case 2:              *to = *from++;
+  case 1:              *to = *from++;
+                    } while ((count -= 8) &gt; 0);
+}
+</code></pre>
+
+<h3>5.6 Avoid boilerplate comments</h3>
+
+<p>The purpose of comments is to convey information. Avoid big cut-and-paste boilerplate comments in front of classes and functions. Make the comments succint and to the point. There is no point in repeating information in the comment that is already in the function header, like this:</p>
+
+<pre><code>// BAD
+
+/// @param p1  a point
+/// @param p2  another point
+/// @return The distance between p1 and p2
+float distance(const Vector3 &amp;p1, const Vector3 &amp;p2);
+</code></pre>
+
+<h3>5.7 Don't put high level documentation in source code comments</h3>
+
+<p>Source code comments are not and should not be the only kind of documentation. Source code comments are good for documenting details that are directly related to the code, such as reference documentation for an API.</p>
+
+<p>Aside from detail documentation, systems also need high level documentation. The high level documentation should provide an overview of the system and an entry point for programmers who are new to the system. It should explain the different concepts that are used in the system and how they relate to each other, the goals of system and the different design choices that have been made.</p>
+
+<p>High level documentation should not be put in source code comments. That makes it fragmented and hard to read. Instead, it should be created as an HTML document, where the user can read it as a single continuous text with nice fonts, illustrations, examples, etc.</p>
+
+<h3>5.8 Comment a file like this</h3>
+
+<pre><code>/// @file
+///
+/// This file contains classes for parsing and generating
+/// XML files.
+</code></pre>
+
+<p>There is no need for putting dates, author names, etc in the file comment. You can read that from the subversion repository.</p>
+
+<p>If the file contains only a single class, you typically do not need a file comment, just a comment for the main class.</p>
+
+<h3>5.9 Comment a class like this</h3>
+
+<pre><code>/// Contains the result of a raycast.
+///
+/// @ingroup Physics
+class RaycastResult
+</code></pre>
+
+<p>Every class should have a @ingroup definition since that makes them easier to browse in Doxygen.</p>
+
+<p>If a file contains a lot of classes or other logically separate parts, you can add a divider line between them to increase readability:</p>
+
+<pre><code>// ----------------------------------------------------------------------
+</code></pre>
+
+<h3>5.10 Comment a function like this</h3>
+
+<pre><code>/// Cost in going from @a p1 to @a p2.
+/// @note Cost of going in z is 2 times as expensive.
+static inline float cost(const Vector3 &amp;p1, const Vector3 &amp;p2)
+</code></pre>
+
+<p>You don't have to comment every single function in the interface. If the function's meaning is clear from its name, then adding a comment conveys no extra information. I.e... this is pointless:</p>
+
+<pre><code>// BAD
+
+/// Returns the speed.
+float speed();
+</code></pre>
+
+<p>Do not add a super heavy boilerplate comments to functions with parameters, return values, etc. Such comments tend to contain mostly fluff anyway. They convey no more information than a simple comment and they make it much harder to get an overview of the code.</p>
+
+<p>I.e. avoid fluff pieces like this:</p>
+
+<pre><code>// BAD
+
+/************************************************************
+ * Name: cost
+ *
+ * Description: Returns the cost of going from point p1 to p2.
+ * Note: Cost of going in z direction is 2 times as expensive.
+ *
+ * Parameters:
+ *     p1 - The one point
+ *     p2 - The other point
+ * Return value:
+ *     The cost of going from p1 to p2.
+ *************************************************************/
+ static inline float cost(const Vector3 &amp;p1, const Vector3 &amp;p2)
+</code></pre>
+
+<h2>6. Design and Implementation Issues</h2>
+
+<h3>6.1 Optimize wisely</h3>
+
+<p>All the code in the engine does not have to be super optimized. Code that only runs once-per-frame has very little impact on a game's performance. Do not spend effort on optimizing that code. Consider what are the heavy-duty number-crunching parts of the code and focus your efforts on them. Use the profiler as a guide to finding the parts of the code that matter.</p>
+
+<p>Be very wary of sacrificing simplicity for code efficiency. Your code will most likely live for a long time and go through several rounds of optimization and debugging. Every time you add complexity you make future optimizations more difficult. Thus, an optimization that makes the code faster today may actually make it slower in the long run by preventing future optimizations. Always strive for the simplest possible code. Only add complexity when it is absolutely necessary.</p>
+
+<p>Be aware that the rules of optimization have changed. Cycle counts matter less. Memory access patterns and parallelization matter more. Write your optimizations so that they touch as little memory as possible and as linearly as possible. Write the code so that it can be parallelized and moved to SPUs. Focus on data layouts and data transforms. Read up on data oriented design.</p>
+
+<h2>7. Miscellaneous Tidbits</h2>
+
+<h3>7.1 Use <code>#pragma once</code> to avoid multiple header inclusion</h3>
+
+<p>All current compilers understand the #pragma once directive. And it is a lot easier to read than the standard #ifndef syntax:</p>
+
+<pre><code>// BAD
+#ifndef _MY_UNIQUE_HEADER_NAME_H_
+#define _MY_UNIQUE_HEADER_NAME_H_
+   ...
+#endif
+
+// GOOD
+#pragma once
+</code></pre>
+
+<p>On MSVC is also much faster (it doesn't process the file multiple times).</p>

File docs/coding_style_cpp.markdown

+<link href="markdown.css" rel="stylesheet"></link>
+
+Coding Style -- C++
+===================
+
+Contents
+--------
+
+1. Introduction
+    - A common style is good
+    - Some choices are arbitrary
+    - Some things don't matter
+    - Avoid revision wars
+    - Style exceptions are allowed
+2. Naming
+    - Naming is important
+    - Names should provide all necessary information, nothing more
+    - A bigger scope warrants a more descriptive name
+    - Do not use abbreviations in names
+    - Name functions and variables `like_this()`
+    - Name classes `LikeThis`
+    - Name member variables `_like_this`
+    - Name #defines `LIKE_THIS`
+    - Name macros `LIKE_THIS`
+    - Name namespaces `like_this`
+    - Name enums `LikeThis`, and enum values `LIKE_THIS`
+    - Name files `like_this.cpp`
+    - Standard functions
+    - Use sensible names
+3. Braces
+    - The bracing styles and when to use them
+    - Use braces to increase readability in nested scopes
+    - Fit matching braces on a single screen
+    - Use `continue`, `break` or even `goto` (!) to avoid deep nesting
+4. Indentation and Spacing
+    - Use four spaces of indentation
+    - Think about evaluation order when placing spaces
+    - Indent #if statements
+    - Do not indent the entire file
+    - Make lines reasonably long
+5. Comments
+    - Use `//` for descriptive comments `/*` for disabling code
+    - Do not leave disabled code in the source
+    - Put interface documentation in the .h file
+    - Use Doxygen syntax for interface documentation
+    - Use comments as hints to the reader
+    - Avoid boilerplate comments
+    - Don't put high level documentation in source code comments
+    - Comment a file like this
+    - Comment a class like this
+    - Comment a function like this
+6. Design and Implementation Issues
+    - Optimize wisely
+7. Miscellaneous Tidbits
+    - Use `#pragma once` to avoid multiple header inclusion
+
+
+
+1. Introduction
+---------------
+
+### 1.1 A common style is good
+
+A common coding style is useful. It makes it easier to communicate, and it makes the code easier to read.
+
+
+### 1.2 Some choices are arbitrary
+
+Some of the style choices described in this manual are (at least according to me) very well motivated, other are just arbitrary choices. Sometimes there is no reason to pick one particular style over another, but it is still useful to mandate a specific choice to ensure a consistent style.
+
+
+### 1.3 Some things don't matter
+
+The purpose of this style guide is not to cover every possible situation. If something is not covered by this guide it is probably something that doesn't matter that much and you are free to use whatever style you are most accustomed to. If you think something should be in the guide, just bring it up to discussion.
+
+
+### 1.4 Avoid revision wars
+
+If you see something that obviously does not follow the standard in a source file you should feel free to change it.  
+If you see something that perhaps does not follow the standard, but you are not sure, it is better to leave it.  
+There is not much point in going over the entire codebase looking for style violations. Such nitpicking is not very productive. Instead, just fix the style violations in code you are working on anyway.  
+Avoid changing the style back and forth in the same piece of code. If you cannot agree on the style, talk about it instead of having a "cold war" in the codebase.
+
+If you disagree strongly with one of the rules in this style guide, you should propose a change to the rule rather than silently rebel.
+
+### 1.5 Style exceptions are allowed
+
+You can decide to break some rule, but *only* if this bring to a clearer code, depending on the context.
+
+
+
+2. Naming
+---------
+
+### 2.1 Naming is important
+
+Naming is a fundamental part of programming. The ease-of-use and "feeling" of an API depends a lot on having good names.
+
+Furthermore, names are harder to changes than implementations. This is especially true for names that are exported "outside" the executable itself, such as names for script functions and parameters in configuration files. For this reason, some care should be taken when selecting a name.
+
+
+### 2.2 Names should provide all necessary information, nothing more
+
+A name should provide all the necessary information to understand what a function or variable is doing but no more than that. I.e., it should not contain redundant information or information that is easily understood from the context (such as the class name).
+
+    // BAD: Name provides too little information
+    
+    char *pstoc(char *);
+    float x;
+    void Image::draw(float, float);
+    
+    // BAD: Name provides too much information
+    
+    char *convert_string_in_pascal_string_format_to_c_string_format(char *);
+    float the_speed;
+    void Image::draw_image_at(float, float);
+        
+    // GOOD: Just the right amount
+    
+    char *pascal_string_to_c(char *s);
+    float speed;
+    void Image::draw_at(float x, float y);
+
+If you cannot come up with a good name for something -- think harder and consult your colleagues. Never use a name that you know is bad.
+
+    // BAD:
+    
+    // What is link2? How it is different from link?
+    void link();
+    void link2();
+    
+    // These names don't mean anything.
+    Stuff the_thing;
+
+
+### 2.3 A bigger scope warrants a more descriptive name
+
+The more visible a variable is (the larger scope it has) the more descriptive its name needs to be, because less information is provided by the context.
+
+Consider the number of players in a network game. In a small local loop, it is fine to call the variable `n` because there is not much to confuse it with, and the context immediately shows where the variable is coming from.
+
+    int n = num_players();
+    for (int i=0; i<n; ++i)
+       ...
+
+If it is a function in the network class we need to be more verbose, because n could mean any number of things in that context.
+
+    int Network::num_players()
+
+If it is a global variable, we must be even more verbose, because we no longer have a Network class context that tells us the variable has something to do with the network:
+
+    int _num_players_in_network_game;
+
+Note
+
+Public global variables should be avoided. If you *really* need a global variable, you should hide it behind a function interface (e.g., console_server::get()). This reduces the temptation of misusing the variable.
+
+
+### 2.4 Do not use abbreviations in names
+
+There are two problems with abbreviations in names:
+
+It gets harder to understand what the name means. This is especially the case with extreme and non-sensical abbreviations like wbs2mc.
+
+Once you start to mix abbreviated and non-abbreviated names, it becomes hard to remember which names where abbreviated and how. It is not hard to understand that world_pos means world_position. But it can be hard to remember whether the function was called world_pos or world_position or something else. Never using abbreviation makes it much easier to guess what a function should be called.
+The general rule is "do not use any abbreviations at all". 
+
+The only allowed exception is `num_` which means number of, e.g. `num_players()` instead of `number_of_players()`.
+
+Note that the rule against abbreviations **only applies to exported symbols**. A local variable can very well be called pos or p.
+
+
+### 2.5 Name functions and variables `like_this()`
+
+Use lower case characters and underscores where you would put spaces in a normal sentence.
+
+This style is preferred for functions and variables, because it is the most readable one (most similar to ordinary language) and functions and variables are the things we have most of.
+
+Do not use any kind of Hungarian notation when naming variables and functions. Hungarian notation is evil.
+
+
+### 2.6 Name classes `LikeThis`
+
+It is good to use a different standard for classes than variables, because it means that we can give temporary variables of a class good names:
+
+    Circle circle;
+
+If the class was called circle, the variable would have to be called something horrible like `a_circle` or `the_circle` or `tmp`.
+
+### 2.7 Name member variables `_like_this`
+
+Being able to quickly distinguish member variables from local variables is good for readability... and it also allows us to use the most natural syntax for getter and setter methods:
+
+    Circle &circle() {return _circle;}
+    void set_circle(Circle &circle) {_circle = circle;}
+
+A single underscore is used as a prefix, because a prefix with letters in it (like `m_`) makes the code harder to read.
+
+    This _sentence can _be _easily read _even though _it _has _extra underscores.
+    But m_throw in m_some letters m_and it m_is m_not so m_easy m_anymore, m_kay.
+
+Also, using _ makes the member variables stand out more, since there could be other variables starting with m.
+
+
+### 2.8 Name macros `LIKE_THIS`
+
+It is good to have `#define` macro names really standing out, since macros can be devious traps when it comes to understanding the code. (Like when Microsoft redefines GetText to GetTextA.)
+
+
+### 2.9 Name namespaces `like_this`
+
+This is the most readable syntax, so we prefer this when we don't have any reason to do otherwise.
+
+
+## 2.10 Name enums `LikeThis`, and enum values `LIKE_THIS`
+
+Enums are types, just as classes and structs and should follow the same naming convention.
+
+Enum values have big scope (either global scope or enclosing class scope). In many cases enum values are used in the same way as `#define`s of integer constants and as a user of an API you don't care if a constant is implemented with an enum or with a a macro.
+
+    #define ALIGN_LEFT = 0
+    enum {ALIGN_LEFT = 0};
+
+Since enum values have almost as big scope as macros and in many cases are used in the same way, we use the same naming convention as for macros:
+
+    enum Align {ALIGN_LEFT, ALIGN_RIGHT, ALIGN_CENTER};
+
+Note that the prefix ALIGN_ on the enum values is needed, since the enum value scope is big. (I consider the big scope of enums a design mistake in C++.)
+
+
+### 2.11 Name files `like_this.cpp`
+
+Again, this is the most readable format, so we choose that when we don't have a reason to do something else.
+
+The .h files should be put in the same directory as the .cpp files, not in some special "include" directory, for easier navigation between the files.
+
+
+### 2.12 Standard functions
+
+Getter and setter functions should look like this.
+
+    Circle &circle() {return _circle;}
+    void set_circle(Circle &circle) {_circle = circle;}
+
+The getter is called circle rather than get_circle, since the get_ prefix is superfluous. However, we use a set_ prefix to emphasize that we are changing the state of the object.
+
+
+### 2.13 Use sensible names
+
+Spell your names correctly.
+Do not write the words "to" and "for" as "2" and "4".
+All names and comments should be in American English.
+
+
+
+3. Braces
+---------
+
+### 3.1 The three bracing styles and when to use them
+
+There are three bracing styles used:
+
+    // Single line
+    int f() {return 3;}
+    
+    // Opened on same line
+    while (true) {
+        do(stuff);
+        more(stuff);
+    }
+    
+    // New line
+    int X::f()
+    {
+        return 3;
+    }
+
+The first style is typically used for getter and setter functions in the header file to make the header more compact.
+
+The second style should never be used.
+
+This third is the preferred for class declarations, function declarations and loops in the cpp file.
+
+
+### 3.2 Use braces to increase readability in nested scopes
+
+Instead of
+
+    // BAD
+    while (a)
+        if (b)
+            c;
+Write
+
+    while (a) 
+    {
+       if (b)
+           c;
+    }
+
+Only the innermost scope is allowed to omit its braces.
+
+
+### 3.3 Try to fit matching braces on a single screen
+
+The opening and closing of a brace should preferably fit on the same screen of code to increase readability.
+
+Class and namespace definitions can of course cover more than one screen.
+
+Function definitions can sometimes cover more than one screen -- if they are clearly structured.
+
+
+### 3.4 Use `continue`, `break` or even (gasp) `goto` to avoid deep nesting
+
+Code that is indented four or five times can be very hard to read. Often such indentation comes from a combination of loops and if-statements:
+
+    // BAD
+    for (i=0; i<parent->num_children(); ++i) 
+    {
+        Child child = parent->child(i);
+        if (child->is_cat_owner()) 
+        {
+            for (j=0; j<child->num_cats(); ++j) 
+            {
+                Cat cat = child->cat(j);
+                if (cat->is_grey()) 
+                {
+                    ...
+Using continue to rewrite gives a clearer structure:
+
+    for (i=0; i<parent->num_children(); ++i) 
+    {
+        Child child = parent->child(i);
+        if (!child->is_cat_owner())
+            continue;
+            
+        for (j=0; j<child->num_cats(); ++j) 
+        {
+            Cat cat = child->cat(j);
+            if (!cat->is_grey())
+                continue;
+                
+            ...
+Excessive indentation can also come from error checking:
+
+    // BAD
+    File f = open_file();
+    if (f.valid()) 
+    {
+        std::string name;
+        if (f.read(&name)) 
+        {
+            int age;
+            if (f.read(&age)) 
+            {
+                ...
+            }
+        }
+    }
+This is one of the few cases where goto can be validly used:
+
+    File f = open_file();
+    if (!f.valid())
+        goto err;
+        
+    std::string name;
+    if (!f.read(&name))
+        goto err;
+        
+    int age;
+    if (!f.read(&age))
+        goto err;
+        
+    err:
+        ...
+
+
+
+4. Indentation and Spacing
+--------------------------
+
+
+### 4.1 Use four spaces of indentation
+
+This is the default in Visual Studio and a good compromise between readability and succinctness.
+
+
+### 4.2 Think about evaluation order when placing spaces
+
+For statements, put a space between keywords and paranthesis, put a space before braces on the same line. Do not put any space before a semicolon.
+
+    while (x == true) {
+        do_stuff();
+    }
+Placement of spaces in expressions is not that important. I generally tend to put a space around every binary operator, but not around unary operators (such as array access, function calls, etc).
+
+    z = x * y(7) * (3 + p[3]) - 8;
+You can use a more terse or a more loose style if you want to... but make sure that the placement of spaces reflects the evaluation order of the expression. I.e. begin by removing spaces around operators that have a higher order of precedence. This is OK:
+
+    z = x*y(7)*(3 + p[3]) - 8;
+Because * has higher precedence than - and =. This is confusing and not OK:
+
+    // BAD
+    z=x * y(7) * (3+p [3])-8;
+
+
+### 4.3 Indent `#if` statements
+
+By default, the visual studio editor left flushes all preprocessing macros. This is idiotic and makes the code really hard to read, especially when the macros are nested:
+
+    // BAD
+    void f()
+    {
+    #ifdef _WIN32
+    #define RUNNINGS_WINDOWS
+    #ifdef PRODUCTION
+        bool print_error_messages = true
+    #else
+        bool print_error_messages = false
+    #endif
+    #else
+        bool win32 = false
+    #endif
+Instead, indent your macros just as you would normal C code:
+
+    void f()
+    {
+        #ifdef _WIN32
+            #define RUNNINGS_WINDOWS
+            #ifdef PRODUCTION
+                bool print_error_messages = true
+            #else
+                bool print_error_messages = false
+            #endif
+        #else
+            bool win32 = false
+        #endif
+
+
+### 4.4 Do not indent the entire file
+
+When the entire file is inside one (or several) namespaces, you should not indent the entire file. Indenting an entire file does not increase readability, it just means you will fit less code on the screen.
+
+Instead, put a comment on the closing brace.
+
+    namespace skinny
+    {
+    
+    void x();
+    ...
+    
+    } // namespace skinny
+
+When the namespace declaration does not cover the entire file, but only a screenfull or so, then it can be a good idea to indent it.
+
+
+### 4.5 Make lines reasonably long
+
+A lot of style guides say that lines should never be more than 80 characters long. This is overly restrictive. We all have displays that can show more than 80 characters per line.
+
+Never write code like this:
+
+    // BAD
+    int x = the + code +
+        is + indented +
+        and + I + dont +
+        want + to + create
+        + long + lines;
+Either use less indentation or write longer lines.
+
+Don't go crazy with line lengths, scrolling to see the end of the line is annnoying. Also, make sure not to put very important stuff far to the right where it might be clipped from view.
+
+
+
+5. Comments
+-----------
+
+
+### 5.1 Use `//` for descriptive comments `/*` for disabling code
+
+`//` comments are better for comments that you want to leave in the code, because they don't have any nesting problems, it is easy to see what is commented, etc.
+
+`/*` is useful when you want to quickly disable a piece of code.
+
+
+### 5.2 Do not leave disabled code in the source
+
+Commenting out old bad code with `/*` ... `*/` is useful and necessary.
+
+It can be useful to leave the old commented out code in the source file for a while, while you check that the new code does not have any bugs, performance problems, etc. But once you are sure of that you should remove the commented out code from the file.
+
+Having a lot of old, unused, commented out code in the source files makes them harder to read, because you constantly ask yourself why was this commented out, maybe the solution to my problem lies in this commented out code, etc. Source control already keeps a version history, we don't need to keep old code in comments.
+
+
+### 5.3 Put interface documentation in the .h file
+
+Put interface (function and class documentation) in the .h file. This makes it easier to find all the relevant interface documentation for someone browsing the .h files.
+
+A drawback of this is that the .h files will become bigger and harder to grasp, but that is a price we are willing to pay.
+
+
+### 5.4 Use Doxygen syntax for interface documentation
+
+Doxygen is a well established standard for interface documentation.
+
+We use the Javadoc-syntax for documentation (///) rather than the QT syntax (//!), because it is easier to type. Use @name to name groups of methods/members.
+
+    /// @name Time functions
+    
+    /// Elapsed seconds since the start of the program
+    float time();
+
+Most public methods of classes in external interfaces should be documented. Private methods and private variables can be documented when that increases the understanding of the class.
+
+
+### 5.5 Use comments as hints to the reader
+
+The main source of information about what the code does should be the code itself. The code is always up-to-date, it doesn't lie and no extra effort is required to maintain it. You should not need to add comments that explain what the code does:
+
+    // BAD
+    
+    /// Returns the speed of the vehicle
+    float sp() {return _sp;}
+    
+    // Computes speed from distance and time
+    s = d / t;
+    
+    // Check for end of file
+    if (c == -1)
+
+Instead, write code that is self-explanatory.
+
+    float speed() {return _speed;}
+    
+    speed = distance / time;
+    
+    if (c == END_OF_FILE_MARKER)
+
+Source code comments should be used as hints to the reader who tries to understand the code. They should point out when the code does something which is a little bit clever or tricky, something that may not be immediately obvious from reading just the code. In complicated algorithms that consist of several steps, they are also useful for identifying the separate steps and giving the user a sense of context.
+
+    // Use Duff's device for loop unrolling
+    // See for example: http://en.wikipedia.org/wiki/Duff's_device
+    switch (count % 8)
+    {
+      case 0:        do {  *to = *from++;
+      case 7:              *to = *from++;
+      case 6:              *to = *from++;
+      case 5:              *to = *from++;
+      case 4:              *to = *from++;
+      case 3:              *to = *from++;
+      case 2:              *to = *from++;
+      case 1:              *to = *from++;
+                        } while ((count -= 8) > 0);
+    }
+
+
+### 5.6 Avoid boilerplate comments
+
+The purpose of comments is to convey information. Avoid big cut-and-paste boilerplate comments in front of classes and functions. Make the comments succint and to the point. There is no point in repeating information in the comment that is already in the function header, like this:
+
+    // BAD
+    
+    /// @param p1  a point
+    /// @param p2  another point
+    /// @return The distance between p1 and p2
+    float distance(const Vector3 &p1, const Vector3 &p2);
+
+
+### 5.7 Don't put high level documentation in source code comments
+
+Source code comments are not and should not be the only kind of documentation. Source code comments are good for documenting details that are directly related to the code, such as reference documentation for an API.
+
+Aside from detail documentation, systems also need high level documentation. The high level documentation should provide an overview of the system and an entry point for programmers who are new to the system. It should explain the different concepts that are used in the system and how they relate to each other, the goals of system and the different design choices that have been made.
+
+High level documentation should not be put in source code comments. That makes it fragmented and hard to read. Instead, it should be created as an HTML document, where the user can read it as a single continuous text with nice fonts, illustrations, examples, etc.
+
+
+### 5.8 Comment a file like this
+
+    /// @file
+    ///
+    /// This file contains classes for parsing and generating
+    /// XML files.
+
+There is no need for putting dates, author names, etc in the file comment. You can read that from the subversion repository.
+
+If the file contains only a single class, you typically do not need a file comment, just a comment for the main class.
+
+
+### 5.9 Comment a class like this
+
+    /// Contains the result of a raycast.
+    ///
+    /// @ingroup Physics
+    class RaycastResult
+
+Every class should have a @ingroup definition since that makes them easier to browse in Doxygen.
+
+If a file contains a lot of classes or other logically separate parts, you can add a divider line between them to increase readability:
+
+    // ----------------------------------------------------------------------
+
+
+### 5.10 Comment a function like this
+
+    /// Cost in going from @a p1 to @a p2.
+    /// @note Cost of going in z is 2 times as expensive.
+    static inline float cost(const Vector3 &p1, const Vector3 &p2)
+
+You don't have to comment every single function in the interface. If the function's meaning is clear from its name, then adding a comment conveys no extra information. I.e... this is pointless:
+
+    // BAD
+    
+    /// Returns the speed.
+    float speed();
+
+Do not add a super heavy boilerplate comments to functions with parameters, return values, etc. Such comments tend to contain mostly fluff anyway. They convey no more information than a simple comment and they make it much harder to get an overview of the code.
+
+I.e. avoid fluff pieces like this:
+
+    // BAD
+    
+    /************************************************************
+     * Name: cost
+     *
+     * Description: Returns the cost of going from point p1 to p2.
+     * Note: Cost of going in z direction is 2 times as expensive.
+     *
+     * Parameters:
+     *     p1 - The one point
+     *     p2 - The other point
+     * Return value:
+     *     The cost of going from p1 to p2.
+     *************************************************************/
+     static inline float cost(const Vector3 &p1, const Vector3 &p2)
+
+
+
+6. Design and Implementation Issues
+-----------------------------------
+
+
+### 6.1 Optimize wisely
+
+All the code in the engine does not have to be super optimized. Code that only runs once-per-frame has very little impact on a game's performance. Do not spend effort on optimizing that code. Consider what are the heavy-duty number-crunching parts of the code and focus your efforts on them. Use the profiler as a guide to finding the parts of the code that matter.
+
+Be very wary of sacrificing simplicity for code efficiency. Your code will most likely live for a long time and go through several rounds of optimization and debugging. Every time you add complexity you make future optimizations more difficult. Thus, an optimization that makes the code faster today may actually make it slower in the long run by preventing future optimizations. Always strive for the simplest possible code. Only add complexity when it is absolutely necessary.
+
+Be aware that the rules of optimization have changed. Cycle counts matter less. Memory access patterns and parallelization matter more. Write your optimizations so that they touch as little memory as possible and as linearly as possible. Write the code so that it can be parallelized and moved to SPUs. Focus on data layouts and data transforms. Read up on data oriented design.
+
+
+
+7. Miscellaneous Tidbits
+------------------------
+
+
+### 7.1 Use `#pragma once` to avoid multiple header inclusion
+
+All current compilers understand the #pragma once directive. And it is a lot easier to read than the standard #ifndef syntax:
+
+    // BAD
+    #ifndef _MY_UNIQUE_HEADER_NAME_H_
+    #define _MY_UNIQUE_HEADER_NAME_H_
+       ...
+    #endif
+	
+    // GOOD
+    #pragma once
+
+On MSVC is also much faster (it doesn't process the file multiple times).

File docs/markdown.css

+@charset "utf-8";
+
+/**
+ * markdown.css
+ *
+ * This program is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU Lesser General Public License as published by the Free
+ * Software Foundation, either version 3 of the License, or (at your option) any
+ * later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program. If not, see http://gnu.org/licenses/lgpl.txt.
+ *
+ * @project      Weblog and Open Source Projects of Florian Wolters
+ * @version      GIT: $Id$
+ * @package      xhtml-css
+ * @author       Florian Wolters <florian.wolters.85@googlemail.com>
+ * @copyright    2012 Florian Wolters
+ * @cssdoc       version 1.0-pre
+ * @license      http://gnu.org/licenses/lgpl.txt GNU Lesser General Public License
+ * @link         http://github.com/FlorianWolters/jekyll-bootstrap-theme
+ * @media        all
+ * @valid        true
+ */
+
+body {
+    font-family: Helvetica, Arial, Freesans, clean, sans-serif;
+padding:1em;
+margin:auto;
+max-width:62em;
+background:#fefefe;
+}
+
+h1, h2, h3, h4, h5, h6 {
+    font-weight: bold;
+}
+
+h1 {
+    color: #000000;
+    font-size: 28px;
+}
+
+h2 {
+    border-bottom: 1px solid #CCCCCC;
+    color: #000000;
+    font-size: 24px;
+}
+
+h3 {
+    font-size: 18px;
+}
+
+h4 {
+    font-size: 16px;
+}
+
+h5 {
+    font-size: 14px;
+}
+
+h6 {
+    color: #777777;
+    background-color: inherit;
+    font-size: 14px;
+}
+
+hr {
+    height: 0.2em;
+    border: 0;
+    color: #CCCCCC;
+    background-color: #CCCCCC;
+}
+
+p, blockquote, ul, ol, dl, li, table, pre {
+    margin: 15px 0;
+}
+
+code, pre {
+    border-radius: 3px;
+    background-color: #F8F8F8;
+    color: inherit;
+}
+
+code {
+    border: 1px solid #EAEAEA;
+    margin: 0 2px;
+    padding: 0 5px;
+}
+
+pre {
+    border: 1px solid #CCCCCC;
+    line-height: 1.25em;
+    overflow: auto;
+    padding: 6px 10px;
+}
+
+pre > code {
+    border: 0;
+    margin: 0;
+    padding: 0;
+}
+
+a, a:visited {
+    color: #4183C4;
+    background-color: inherit;
+    text-decoration: none;
+}

File sources/utils/containers/idlookuptable.h

+#ifndef __IDLOOKUP_TABLE_H__
+#define __IDLOOKUP_TABLE_H__
+
+#include <map>
+
+typedef unsigned int ID;
+
+template <typename Object>
+class IDLookupTable
+{
+public:
+	ID _next_id;
+	std::map<ID, Object *> _objects;
+
+	IDLookupTable()
+	:_next_id(0)
+	{}
+
+	inline bool has(ID id) 
+	{
+		return _objects.count(id) > 0;
+	}
+	
+	inline Object &lookup(ID id) 
+	{
+		return *_objects[id];
+	}
+	
+	inline ID add() 
+	{
+		ID id = _next_id++;
+		Object *o = new Object();
+		o->id = id;
+		_objects[id] = o;
+		return id;
+	}
+	
+	inline void remove(ID id) 
+	{
+		Object &o = lookup(id);
+		_objects.erase(id);
+		delete &o;
+	}
+};
+
+
+#endif

File testing/utils/containers_test_idlkt.cpp

+#include <iostream>
+#include <cstdio>
+#include <string>
+
+#include "UnitTest++.h"
+using namespace UnitTest;
+
+#include "containers/idlookuptable.h"
+
+namespace 
+{
+
+    struct MYObject
+    {
+        ID id;
+
+        int uno;
+        int due;
+        double tre;
+    };
+
+  
+    
+
+    
+    TEST (TestIDLookupTableAdd)
+    {
+        IDLookupTable<MYObject> lkt;
+
+        ID id1 = lkt.add();
+
+        CHECK (true==lkt.has(id1));
+
+        MYObject &obj1 = lkt.lookup(id1);
+          obj1.uno=1;
+          obj1.due=2;
+          obj1.tre=3.03;
+        MYObject &obj2 = lkt.lookup(id1);
+        CHECK_EQUAL (obj2.uno,obj1.uno);
+        CHECK_EQUAL (obj2.due,obj1.due);
+        CHECK_CLOSE (obj2.tre,obj1.tre,1e-6);
+    }
+
+    TEST (TestIDLookupTableRemove)
+    {
+        IDLookupTable<MYObject> lkt;
+
+        const unsigned int no = 100;
+        ID ids[no];
+
+        for (unsigned int i=0; i<100; i++)
+        {
+            ids[i] = lkt.add();
+            MYObject &obj1 = lkt.lookup(ids[i]);
+            obj1.uno=i;
+        }
+
+        MYObject &obj20 = lkt.lookup(ids[20]);
+        CHECK_EQUAL( obj20.uno,20 );
+
+        CHECK_EQUAL( lkt.has(ids[9]), true);
+        CHECK_EQUAL( lkt.has(ids[10]),true);
+        CHECK_EQUAL( lkt.has(ids[12]),true);
+        CHECK_EQUAL( lkt.has(ids[15]),true);
+        // Remove elements
+        lkt.remove(ids[10]);
+        lkt.remove(ids[11]);
+        lkt.remove(ids[12]);
+        lkt.remove(ids[13]);
+        lkt.remove(ids[14]);
+        CHECK_EQUAL( lkt.has(ids[9]), true);
+        CHECK_EQUAL( lkt.has(ids[10]),false);
+        CHECK_EQUAL( lkt.has(ids[12]),false);
+        CHECK_EQUAL( lkt.has(ids[15]),true);
+    }
+	
+
+}

File var/markdown/License.text

+Copyright (c) 2004, John Gruber  
+<http://daringfireball.net/>  
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+
+* Neither the name "Markdown" nor the names of its contributors may
+  be used to endorse or promote products derived from this software
+  without specific prior written permission.
+
+This software is provided by the copyright holders and contributors "as
+is" and any express or implied warranties, including, but not limited
+to, the implied warranties of merchantability and fitness for a
+particular purpose are disclaimed. In no event shall the copyright owner
+or contributors be liable for any direct, indirect, incidental, special,
+exemplary, or consequential damages (including, but not limited to,
+procurement of substitute goods or services; loss of use, data, or
+profits; or business interruption) however caused and on any theory of
+liability, whether in contract, strict liability, or tort (including
+negligence or otherwise) arising in any way out of the use of this
+software, even if advised of the possibility of such damage.

File var/markdown/Markdown Readme.text

+Markdown
+========
+
+Version 1.0.1 - Tue 14 Dec 2004
+
+by John Gruber  
+<http://daringfireball.net/>
+
+
+Introduction
+------------
+
+Markdown is a text-to-HTML conversion tool for web writers. Markdown
+allows you to write using an easy-to-read, easy-to-write plain text
+format, then convert it to structurally valid XHTML (or HTML).
+
+Thus, "Markdown" is two things: a plain text markup syntax, and a
+software tool, written in Perl, that converts the plain text markup 
+to HTML.
+
+Markdown works both as a Movable Type plug-in and as a standalone Perl
+script -- which means it can also be used as a text filter in BBEdit
+(or any other application that supporst filters written in Perl).
+
+Full documentation of Markdown's syntax and configuration options is
+available on the web: <http://daringfireball.net/projects/markdown/>.
+(Note: this readme file is formatted in Markdown.)
+
+
+
+Installation and Requirements
+-----------------------------
+
+Markdown requires Perl 5.6.0 or later. Welcome to the 21st Century.
+Markdown also requires the standard Perl library module `Digest::MD5`. 
+
+
+### Movable Type ###
+
+Markdown works with Movable Type version 2.6 or later (including 
+MT 3.0 or later).
+
+1.  Copy the "Markdown.pl" file into your Movable Type "plugins"
+    directory. The "plugins" directory should be in the same directory
+    as "mt.cgi"; if the "plugins" directory doesn't already exist, use
+    your FTP program to create it. Your installation should look like
+    this:
+
+        (mt home)/plugins/Markdown.pl
+
+2.  Once installed, Markdown will appear as an option in Movable Type's
+    Text Formatting pop-up menu. This is selectable on a per-post basis.
+    Markdown translates your posts to HTML when you publish; the posts
+    themselves are stored in your MT database in Markdown format.
+
+3.  If you also install SmartyPants 1.5 (or later), Markdown will offer
+    a second text formatting option: "Markdown with SmartyPants". This
+    option is the same as the regular "Markdown" formatter, except that
+    automatically uses SmartyPants to create typographically correct
+    curly quotes, em-dashes, and ellipses. See the SmartyPants web page
+    for more information: <http://daringfireball.net/projects/smartypants/>
+
+4.  To make Markdown (or "Markdown with SmartyPants") your default
+    text formatting option for new posts, go to Weblog Config ->
+    Preferences.
+
+Note that by default, Markdown produces XHTML output. To configure
+Markdown to produce HTML 4 output, see "Configuration", below.
+
+
+### Blosxom ###
+
+Markdown works with Blosxom version 2.x.
+
+1.  Rename the "Markdown.pl" plug-in to "Markdown" (case is
+    important). Movable Type requires plug-ins to have a ".pl"
+    extension; Blosxom forbids it.
+
+2.  Copy the "Markdown" plug-in file to your Blosxom plug-ins folder.
+    If you're not sure where your Blosxom plug-ins folder is, see the
+    Blosxom documentation for information.
+
+3.  That's it. The entries in your weblog will now automatically be
+    processed by Markdown.
+
+4.  If you'd like to apply Markdown formatting only to certain posts,
+    rather than all of them, see Jason Clark's instructions for using
+    Markdown in conjunction with Blosxom's Meta plugin:
+    
+    <http://jclark.org/weblog/WebDev/Blosxom/Markdown.html>
+
+
+### BBEdit ###
+
+Markdown works with BBEdit 6.1 or later on Mac OS X. (It also works
+with BBEdit 5.1 or later and MacPerl 5.6.1 on Mac OS 8.6 or later.)
+
+1.  Copy the "Markdown.pl" file to appropriate filters folder in your
+    "BBEdit Support" folder. On Mac OS X, this should be:
+
+        BBEdit Support/Unix Support/Unix Filters/
+
+    See the BBEdit documentation for more details on the location of
+    these folders.
+
+    You can rename "Markdown.pl" to whatever you wish.
+
+2.  That's it. To use Markdown, select some text in a BBEdit document,
+    then choose Markdown from the Filters sub-menu in the "#!" menu, or
+    the Filters floating palette
+
+
+
+Configuration
+-------------
+
+By default, Markdown produces XHTML output for tags with empty elements.
+E.g.:
+
+    <br />
+
+Markdown can be configured to produce HTML-style tags; e.g.:
+
+    <br>
+
+
+### Movable Type ###
+
+You need to use a special `MTMarkdownOptions` container tag in each
+Movable Type template where you want HTML 4-style output:
+
+    <MTMarkdownOptions output='html4'>
+        ... put your entry content here ...
+    </MTMarkdownOptions>
+
+The easiest way to use MTMarkdownOptions is probably to put the
+opening tag right after your `<body>` tag, and the closing tag right
+before `</body>`.
+
+To suppress Markdown processing in a particular template, i.e. to
+publish the raw Markdown-formatted text without translation into
+(X)HTML, set the `output` attribute to 'raw':
+
+    <MTMarkdownOptions output='raw'>
+        ... put your entry content here ...
+    </MTMarkdownOptions>
+
+
+### Command-Line ###
+
+Use the `--html4tags` command-line switch to produce HTML output from a
+Unix-style command line. E.g.:
+
+    % perl Markdown.pl --html4tags foo.text
+
+Type `perldoc Markdown.pl`, or read the POD documentation within the
+Markdown.pl source code for more information.
+
+
+
+Bugs
+----
+
+To file bug reports or feature requests please send email to:
+<markdown@daringfireball.net>.
+
+
+
+Version History
+---------------
+
+1.0.1 (14 Dec 2004):
+
++	Changed the syntax rules for code blocks and spans. Previously,
+	backslash escapes for special Markdown characters were processed
+	everywhere other than within inline HTML tags. Now, the contents
+	of code blocks and spans are no longer processed for backslash
+	escapes. This means that code blocks and spans are now treated
+	literally, with no special rules to worry about regarding
+	backslashes.
+
+	**NOTE**: This changes the syntax from all previous versions of
+	Markdown. Code blocks and spans involving backslash characters
+	will now generate different output than before.
+
++	Tweaked the rules for link definitions so that they must occur
+	within three spaces of the left margin. Thus if you indent a link
+	definition by four spaces or a tab, it will now be a code block.
+	
+		   [a]: /url/  "Indented 3 spaces, this is a link def"
+
+		    [b]: /url/  "Indented 4 spaces, this is a code block"
+	
+	**IMPORTANT**: This may affect existing Markdown content if it
+	contains link definitions indented by 4 or more spaces.
+
++	Added `>`, `+`, and `-` to the list of backslash-escapable
+	characters. These should have been done when these characters
+	were added as unordered list item markers.
+
++	Trailing spaces and tabs following HTML comments and `<hr/>` tags
+	are now ignored.
+
++	Inline links using `<` and `>` URL delimiters weren't working:
+
+		like [this](<http://example.com/>)
+
++	Added a bit of tolerance for trailing spaces and tabs after
+	Markdown hr's.
+
++	Fixed bug where auto-links were being processed within code spans:
+
+		like this: `<http://example.com/>`
+
++	Sort-of fixed a bug where lines in the middle of hard-wrapped
+	paragraphs, which lines look like the start of a list item,
+	would accidentally trigger the creation of a list. E.g. a
+	paragraph that looked like this:
+
+		I recommend upgrading to version
+		8. Oops, now this line is treated
+		as a sub-list.
+
+	This is fixed for top-level lists, but it can still happen for
+	sub-lists. E.g., the following list item will not be parsed
+	properly:
+
+		+	I recommend upgrading to version
+			8. Oops, now this line is treated
+			as a sub-list.
+
+	Given Markdown's list-creation rules, I'm not sure this can
+	be fixed.
+
++	Standalone HTML comments are now handled; previously, they'd get
+	wrapped in a spurious `<p>` tag.
+
++	Fix for horizontal rules preceded by 2 or 3 spaces.
+
++	`<hr>` HTML tags in must occur within three spaces of left
+	margin. (With 4 spaces or a tab, they should be code blocks, but
+	weren't before this fix.)
+
++	Capitalized "With" in "Markdown With SmartyPants" for
+	consistency with the same string label in SmartyPants.pl.
+	(This fix is specific to the MT plug-in interface.)
+
++	Auto-linked email address can now optionally contain
+	a 'mailto:' protocol. I.e. these are equivalent:
+
+		<mailto:user@example.com>
+		<user@example.com>
+
++	Fixed annoying bug where nested lists would wind up with
+	spurious (and invalid) `<p>` tags.
+
++	You can now write empty links:
+
+		[like this]()
+
+	and they'll be turned into anchor tags with empty href attributes.
+	This should have worked before, but didn't.
+
++	`***this***` and `___this___` are now turned into
+
+		<strong><em>this</em></strong>
+
+	Instead of
+
+		<strong><em>this</strong></em>
+
+	which isn't valid. (Thanks to Michel Fortin for the fix.)
+
++	Added a new substitution in `_EncodeCode()`: s/\$/&#036;/g; This
+	is only for the benefit of Blosxom users, because Blosxom
+	(sometimes?) interpolates Perl scalars in your article bodies.
+
++	Fixed problem for links defined with urls that include parens, e.g.:
+
+		[1]: http://sources.wikipedia.org/wiki/Middle_East_Policy_(Chomsky)
+
+	"Chomsky" was being erroneously treated as the URL's title.
+
++	At some point during 1.0's beta cycle, I changed every sub's
+	argument fetching from this idiom:
+
+		my $text = shift;
+
+	to:
+
+		my $text = shift || return '';
+
+	The idea was to keep Markdown from doing any work in a sub
+	if the input was empty. This introduced a bug, though:
+	if the input to any function was the single-character string
+	"0", it would also evaluate as false and return immediately.
+	How silly. Now fixed.
+
+
+
+Donations
+---------
+
+Donations to support Markdown's development are happily accepted. See:
+<http://daringfireball.net/projects/markdown/> for details.
+
+
+
+Copyright and License
+---------------------
+
+Copyright (c) 2003-2004 John Gruber   
+<http://daringfireball.net/>   
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+
+* Neither the name "Markdown" nor the names of its contributors may
+  be used to endorse or promote products derived from this software
+  without specific prior written permission.
+
+This software is provided by the copyright holders and contributors "as
+is" and any express or implied warranties, including, but not limited
+to, the implied warranties of merchantability and fitness for a
+particular purpose are disclaimed. In no event shall the copyright owner
+or contributors be liable for any direct, indirect, incidental, special,
+exemplary, or consequential damages (including, but not limited to,
+procurement of substitute goods or services; loss of use, data, or
+profits; or business interruption) however caused and on any theory of
+liability, whether in contract, strict liability, or tort (including
+negligence or otherwise) arising in any way out of the use of this
+software, even if advised of the possibility of such damage.

File var/markdown/Markdown.pl

+#!/usr/bin/perl
+
+#
+# Markdown -- A text-to-HTML conversion tool for web writers
+#
+# Copyright (c) 2004 John Gruber
+# <http://daringfireball.net/projects/markdown/>
+#
+
+
+package Markdown;
+require 5.006_000;
+use strict;
+use warnings;
+
+use Digest::MD5 qw(md5_hex);
+use vars qw($VERSION);
+$VERSION = '1.0.1';
+# Tue 14 Dec 2004
+
+## Disabled; causes problems under Perl 5.6.1:
+# use utf8;
+# binmode( STDOUT, ":utf8" );  # c.f.: http://acis.openlib.org/dev/perl-unicode-struggle.html
+
+
+#
+# Global default settings:
+#
+my $g_empty_element_suffix = " />";     # Change to ">" for HTML output
+my $g_tab_width = 4;
+
+
+#
+# Globals:
+#
+
+# Regex to match balanced [brackets]. See Friedl's
+# "Mastering Regular Expressions", 2nd Ed., pp. 328-331.
+my $g_nested_brackets;
+$g_nested_brackets = qr{
+	(?> 								# Atomic matching
+	   [^\[\]]+							# Anything other than brackets
+	 | 
+	   \[
+		 (??{ $g_nested_brackets })		# Recursive set of nested brackets
+	   \]
+	)*
+}x;
+
+
+# Table of hash values for escaped characters:
+my %g_escape_table;
+foreach my $char (split //, '\\`*_{}[]()>#+-.!') {
+	$g_escape_table{$char} = md5_hex($char);
+}
+
+
+# Global hashes, used by various utility routines
+my %g_urls;
+my %g_titles;
+my %g_html_blocks;
+
+# Used to track when we're inside an ordered or unordered list
+# (see _ProcessListItems() for details):
+my $g_list_level = 0;
+
+
+#### Blosxom plug-in interface ##########################################
+
+# Set $g_blosxom_use_meta to 1 to use Blosxom's meta plug-in to determine
+# which posts Markdown should process, using a "meta-markup: markdown"
+# header. If it's set to 0 (the default), Markdown will process all
+# entries.
+my $g_blosxom_use_meta = 0;
+
+sub start { 1; }
+sub story {
+	my($pkg, $path, $filename, $story_ref, $title_ref, $body_ref) = @_;
+
+	if ( (! $g_blosxom_use_meta) or
+	     (defined($meta::markup) and ($meta::markup =~ /^\s*markdown\s*$/i))
+	     ){
+			$$body_ref  = Markdown($$body_ref);
+     }
+     1;
+}
+
+
+#### Movable Type plug-in interface #####################################