documentation: Update spice-style

4 files changed, 361 insertions, 2 deletions

diff --git a/content/pages/developers.rst b/content/pages/developers.rst
index e0f8c2e..5f6732b 100644
--- a/content/pages/developers.rst
+++ b/content/pages/developers.rst
@@ -6,7 +6,7 @@ Developers
 .. _spice protocol: {filename}/static/docs/spice_protocol.pdf
 .. _VD-Interfaces: {filename}/static/docs/vd_interfaces.pdf
 .. _spice-html5: http://cgit.freedesktop.org/spice/spice-html5
-.. _spice style: {filename}/static/docs/spice_style.pdf
+.. _spice style: spice-project-coding-style-and-coding-conventions
 .. _xf86-video-qxl: http://cgit.freedesktop.org/xorg/driver/xf86-video-qxl
 .. _style: http://cgit.freedesktop.org/pixman/tree/CODING_STYLE
 .. _bug-tracker: https://bugs.freedesktop.org/enter_bug.cgi?product=Spice
diff --git a/content/pages/documentation.rst b/content/pages/documentation.rst
index cb9275d..3f3b75d 100644
--- a/content/pages/documentation.rst
+++ b/content/pages/documentation.rst
@@ -9,7 +9,7 @@ Documentation
 .. _spice protocol: {filename}/static/docs/spice_protocol.pdf
 .. _ODP version: {filename}/static/docs/spice_redhat_summit_2009.odp
 .. _PDF version: {filename}/static/docs/spice_redhat_summit_2009.pdf
-.. _spice style: {filename}/static/docs/spice_style.pdf
+.. _spice style: spice-project-coding-style-and-coding-conventions
 .. _UsbDk Presentation: {filename}/static/docs/UsbDk_at_a_Glance.pdf
 .. _UsbDk Manual: {filename}/static/docs/UsbDk_Software_Development_Manual.pdf
 .. _Spice Reference Manual: spice-user-manual.html
diff --git a/content/pages/spice-style.asc b/content/pages/spice-style.asc
new file mode 100644
index 0000000..b024b6b
--- /dev/null
+++ b/content/pages/spice-style.asc
@@ -0,0 +1,359 @@
+Spice project coding style and coding conventions
+=================================================
+
+Copyright (C) 2009-2016 Red Hat, Inc.
+Licensed under a Creative Commons Attribution-Share Alike 3.0
+United States License (see http://creativecommons.org/licenses/by-sa/3.0/us/legalcode).
+
+
+Source Files
+------------
+
+Names
+~~~~~
+
+Use lower case and separate words using dashes (e.g., file-name.c, header.h).
+
+Use standard file extension for C source and header files.
+
+Line width
+~~~~~~~~~~
+
+No more then 100 character on a single line
+
+Tabs
+~~~~
+
+Tabs are not allowed, use 4 spaces instead
+
+White spaces
+~~~~~~~~~~~~
+
+Trailing white spaces are not allowed
+
+New Line
+~~~~~~~~
+
+Use Unix style line ending (i.e., LF)
+
+New line (i.e., EOL) must be the last char in the file
+
+Comparing
+---------
+
+Use  right-hand comparison style.
+
+Examples: +
+  use `(var == 7)` instead of  `(7 == var)` +
+  use `(function(var) > 7)` instead of `(7 < function(var))`
+
+TRUE, FALSE and NULL
+--------------------
+
+Use `TRUE`, `FALSE` and `NULL` instead of 1 and 0 in order to improve code readability.
+
+Static storage initialization
+-----------------------------
+
+To improve code readability, explicitly initialize variables that depend on default initialization with zero/null.
+
+FIXME and TODO
+--------------
+
+Comments that are prefixed with `FIXME` describe a bug that need to be fixed. Generally, it is not allowed to commit new code having `FIXME` comment. Committing  `FIXME` is allowed only for existing bugs. Comments that are prefixed with `TODO` describe further features, optimization or code improvements, and they are allowed to be committed along with the relevant code.
+
+ASSERT
+------
+
+Use it freely. ASSERT helps testing function arguments and function results validity.  ASSERT helps detecting bugs and improve code readability and stability.
+
+sizeof
+------
+
+Apply function style to `sizeof` (i.e., use `sizeof(x)`)
+
+const
+-----
+
+Use const keyword when applicable to improve code reliability and celerity.
+
+goto
+----
+
+Using goto is allowed in C code for error handling. In any other case it will be used only as a special exception.
+
+Defining Constant values
+------------------------
+
+Use defines for constant values for improving readability and ease of changes. Alternatively, use global `const` variables.
+
+Short functions
+---------------
+
+Try to split code to short functions, each having simple functionality, in order to improve code readability and re-usability. Prefix with inline short functions or functions that were splitted for readability reason.
+
+Return on if
+------------
+
+Try to return immediately on if in places that can reduce indentation level.
+
+Example:
+
+prefer
+[source,c]
+----
+void function(int *n)
+{
+    if (!n) {
+        return;
+    }
+    ...
+}
+----
+on
+[source,c]
+----
+void function(int *n)
+{
+    if (!n) {
+        return;
+    } else {
+        ...
+    }
+}
+----
+
+Names
+-----
+
+* Don't underestimate the importance of name choosing. Good names make the code more easy to understand and reduce the required level of code documentation. When choosing names, prefer long meaningful names over short vague name.
+* Variable and Function names - use lower case and separate words using underscore (e.g., sample_variable_name)
+* Structures, class and enum names - one or more words, each word start with upper case (e.g., Name, SampleStructName)
+* Defines and enum items names - uppercase words separated using underscores (e.g., NAME, SAMPLE_DEFINE_NAME)
+
+Type prefix
+~~~~~~~~~~~
+In the code there are some common prefixes for types, `Red` and `Spice`.
+As a basic rule `Spice` refers to types in the public external headers while `Red` is used for internal types.
+
+Common abbreviations
+~~~~~~~~~~~~~~~~~~~~
+`rcc` RedChannelClient
+
+`dcc` DisplayChannelClient
+
+`sin` spice instance
+
+`sif` spice interface
+
+`dpi` drawable pipe item
+
+Optimization
+------------
+
+Keep optimization to fast path code. Prefer safe, clear and easy to maintain coding for code that is not on the fast path.
+
+Spacing
+-------
+
+Use spacing for improving code readability.
+
+[source,c]
+for (i = 0; i < 10; ++i) {
+    some_func(var, i * i + *ptr, &var, sizeof(var));
+}
+
+[[function_indentation]]
+Function Indentation
+--------------------
+
+* No spaces between function name to left bracket.
+* Curly bracket start on new line.
+* Functions must be padded with empty lines on both sides
++
+[source,c]
+void function(type1 arg1, type2 arg2, type2 arg3)
+{
+  ...
+}
++
+* In case of a new line in arguments list, align it to the first argument type.
++
+[source,c]
+----
+void function(type1 arg1,
+              type2 arg2,
+              type3 arg3)
+----
++
+Or
++
+[source,c]
+----
+void function(type1 arg1, type2 arg2,
+              type3 arg3)
+----
++
+* New line is acceptable only in arguments list
+
+Branching indentation
+---------------------
+
+* Add space after a branch keyword and after the right bracket.
+* Curly bracket starts on the same line the branch starts.
+* Place curly brackets after all control flow constructs even where optional. This convention reduces branching bugs that are difficult to detect. It also makes it easier to add logging messages during debugging  since it eliminates the need to add the brackets.
++
+[source,c]
+----
+if (condition) {
+    ...
+} else if (condition) {
+    ...
+} else {
+    ...
+}
+----
++
+In case of long condition statement, prefer having additional temporary variable over multiple line condition statement.
++
+In case of new line in condition statement.
++
+[source,c]
+----
+if (long_name && very_long_name && very_long ||
+                                               var_name) {
+----
++
+or indent under the round bracket using spaces
++
+[source,c]
+----
+if (long_name && very_long_name && long_name ||
+    var_name) {
+----
++
+Break function arguments list in long condition statement according to <<function_indentation, Function Indentation>> section.
++
+[source,c]
+----
+while (condition) {
+        ...
+}
+
+do {
+    ...
+} while (condition);
+
+for (i = x; i < y; i++) {
+    ...
+}
+
+
+switch (x) {
+case A: {
+    ...
+    break;
+}
+case B:
+    ...
+    ...
+    break;
+default:
+    ...
+}
+----
+
+Types indentation
+-----------------
+
+[source,c]
+----
+struct StructName {
+    type1 name1;
+    type2 name2;
+
+    ...
+};
+
+enum {
+    A,
+    B,
+    C = 10,
+    D,
+};
+
+union {
+    type1 name1;
+    type2 name2;
+    ...
+} u;
+----
+
+Vertical indentation
+--------------------
+
+Use one space no tabs and no vertical alignment.
+[source,c]
+----
+long var_name_1 = 7;
+int var_name_2 = 1111l;
+unsigned long long_var_name_1 = 666;
+char long_var_name_1 = 'a';
+
+void f1(int a, char ch);
+unsigned long f2(int a, char ch);
+----
+
+Multi line macro indentation
+----------------------------
+
+[source,c]
+#define MACRO_NAME(a, b, c) {        \
+    int ab = a + c;             \
+    int ac = a + b;             \
+    int bc = b + c;             \
+    f(ab, ac, bc);              \
+}
+
+Multi line array indentation
+----------------------------
+
+[source,c]
+char *array[] = {
+    "item_1",
+    "item_2",
+    "item_3",
+};
+
+Header inclusion
+----------------
+
+Headers should be included in this order
+
+[source,c]
+----
+#include <system_headers.h>
+#include <no_spice_no_system_libraries.h>
+#include <spice_protocol.h>
+#include <spice_common.h>
+
+#include "spice_server.h"
+----
+
+(note the empty line between no spice-server and spice-server headers)
+
+Also in source (no header) files you must include `config.h` at the beginning so should start (beside comments and copyright) with
+
+[source,c]
+----
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif
+
+#include <system_headers.h>
+#include <no_spice_no_system_libraries.h>
+#include <spice_protocol.h>
+#include <spice_common.h>
+
+#include "spice_server.h"
+----
diff --git a/content/static/docs/spice_style.pdf b/content/static/docs/spice_style.pdf
deleted file mode 100644
index a00ea51..0000000
--- a/content/static/docs/spice_style.pdf
+++ /dev/null