improve CODING.md / DESIGN.md formatting

README.md

@@ -3,7 +3,7 @@
 _Elektra provides a universal and secure framework to store configuration
 parameters in a global, hierarchical key database._
 
-![Elektra](doc/images/circle.jpg)
+<img src="https://cdn.rawgit.com/ElektraInitiative/libelektra/master/doc/images/circle.svg" alt="Elektra" width="50" />
 
 The core is a small library implemented in C. The plugin-based framework fulfills many
 configuration-related tasks to avoid any unnecessary code duplication
@@ -55,10 +55,19 @@ kdb qt-gui
 Or you can use the `kdb` command to configure your applications:
 
 ```bash
-kdb set user/test "something"
-kdb get user/test
+kdb set user/env/override/HTTP_PROXY "http://my.proxy:8080"
 ```
 
+This will set the `HTTP_PROXY` environment variable to `http://my.proxy:8080`.
+Configuration can be retrieved with `kdb get`:
+
+```bash
+kdb get user/env/override/HTTP_PROXY
+```
+
+For more information about environment variables and elektra, see
+[src/libgetenv/README.md](src/libgetenv/README.md)
+
 
 ## Goals ##
 

doc/CODING.md

@@ -11,8 +11,11 @@ After you downloaded and unpacked Elektra you see untypically many
 folders. The reason is that Elektra project consists of many activities.
 
 The most important are:
-src ... Here is the source for the library and the tools itself.
-tests ... Is the testing framework for the Source
+
+ * **src:** Here is the source for the library and the tools itself.
+ * **doc:** Documentation for the library.
+ * **example:** Examples of using the library.
+ * **tests:** Is the testing framework for the source.
 
 ## Source Code ##
 
@@ -23,15 +26,15 @@ The plugins have all kinds of dependencies. It is the responsibility of
 the plugins to find and check them using CMake. The same guidelines
 apply for all code in the repository including the plugins.
 
-libloader is responsible for loading the backend modules. It works for
-various operating systems by using libltdl, but has an optimized code
+`libloader` is responsible for loading the backend modules. It works for
+various operating systems by using `libltdl`, but has an optimized code
 for static linking and win32.
 
 kdb is the commandline-tool to access and initialize the Elektra database.
 
 ### General Guidelines ###
 
-It is only allowed to break  a guidelines if there is a good reason
+It is only allowed to break a guideline if there is a good reason
 for it. When doing so, document the fact either in the commit message,
 or as comment next to the code.
 
@@ -46,79 +49,57 @@ TODO marker to make the places visible.
 If you see inconsistency do not hesitate to talk about it with the
 intent to add a new rule here.
 
-See DESIGN document too, they complement each other.
+See [DESIGN](DESIGN.md) document too, they complement each other.
 
 
 ### C Guidelines ###
 
-Functions should not exceed 100 lines.
-Files should not exceed 1000 lines.
-A line should not be longer then 72 characters.
-Split up when those limits are reached.
-Rationale: Readability with split windows.
-
-
-The compiler shall not emit any warning (or error).
-
-Use tabs for indentation.
-
-Prefer to use blocks to single line statements.
-
-Curly braces go on a line on their own on the previous indentation level
-
-Use goto only for error situations.
-
-Use camelCase for functions and variables.
-
-Start types with upper-case, everything else with lower-case.
-
-Avoid spaces between words and round braces.
-
-Use C-comments /**/ with doxygen style for functions.
-
-Use C++-comments // for single line statements about the code in the
+ * Functions should not exceed 100 lines.
+ * Files should not exceed 1000 lines.
+ * A line should not be longer then 72 characters.
+ * Split up when those limits are reached.
+ * Rationale: Readability with split windows.
+ * The compiler shall not emit any warning (or error).
+ * Use tabs for indentation.
+ * Prefer to use blocks to single line statements.
+ * Curly braces go on a line on their own on the previous indentation level
+ * Use goto only for error situations.
+ * Use camelCase for functions and variables.
+ * Start types with upper-case, everything else with lower-case.
+ * Avoid spaces between words and round braces.
+ * Use C-comments `/**/` with doxygen style for functions.
+ * Use C++-comments `//` for single line statements about the code in the
 next line.
-
-Avoid multiple variable declarations at one place and * are next to the
+ * Avoid multiple variable declarations at one place and `*` are next to the
 variable names.
+ * Use `const` as much as possible.
+ * Use `static` methods if they should not be externally visible.
+ * Declare Variables as late as possible, preferable within blocks.
+ * C-Files have extension `.c`, Header files `.h`.
+ * Prefix names with `elektra` for internal usage. External API either starts
+with `ks`, `key` or `kdb`.
 
-Use const as much as possible.
-
-Use static methods if they should not be externally visible.
-
-Declare Variables as late as possible, preferable within blocks.
-
-C-Files have extension .c, Header files .h.
-
-Prefix names with elektra for internal usage. External API either starts
-with ks, key or kdb.
-
-Example: src/libelektra/kdb.c
+**Example:** [src/libelektra/kdb.c](../src/libelektra/kdb.c)
 
 
 ### C++ Guidelines ###
 
-Everything as in C if not noted otherwise.
+ * Everything as in C if not noted otherwise.
+ * Do not use goto at all, use RAII instead.
+ * Do not use raw pointers, use smart pointers instead.
+ * C++-Files have extension `.cpp`, Header files `.hpp`.
+ * Do not use `static`, but anonymous namespaces.
+ * Write everything within namespaces and do not prefix names.
 
-Do not use goto at all, use RAII instead.
-
-Do not use raw pointers, use smart pointers instead.
-
-C++-Files have extension .cpp, Header files .hpp.
-
-Do not use static, but anonymous namespaces.
-
-Write everything within namespaces and do not prefix names.
-
-Example: bindings/cpp/include/kdb.hpp
+**Example:** [src/bindings/cpp/include/kdb.hpp](../src/bindings/cpp/include/kdb.hpp)
 
 
 ### Doxygen Guidelines ###
 
-Use doxygen to document APIs, if available.
+Use `doxygen` to document APIs, if available.
 
 Do not duplicate information available in git in doxygen.
-Use \copydoc, \copybrief and \copydetails intensively.
+Use `\copydoc`, `\copybrief` and `\copydetails` intensively.
 
 
 Files should start with:
@@ -138,4 +119,3 @@ Note:
 
 The duplication of the filename, author and date is not needed, because
 this information is tracked using git.
-

doc/DESIGN.md

@@ -120,7 +120,7 @@ Use the appendant Get functions, to be not depend on that internal facts.
 
 	const void *keyValue(const Key *key);
 does not specify whether it is a binary or string, it will just return
-the pointer to it. When Key is a string (check with keyIsString()) at
+the pointer to it. When Key is a string (check with `keyIsString()`) at
 least "" will be returned, see below Return Values for strings.
 For binary data a NULL pointer is also possible
 to distinguish between no data and '\0'.
@@ -175,7 +175,7 @@ There are some functions which return an internal string:
 	const char *keyOwner(const Key *key);  
 	const char *keyComment(const Key *key);  
 
-and in the case that (keyIsBinary(key)==1) also:  
+and in the case that (`keyIsBinary(key)==1`) also:  
 
 	const void *keyValue(const Key *key);