Merge branch 'master' into readability_improvements

README.md

@@ -172,7 +172,9 @@ Elektra uses a [git repository at GitHub](https://github.com/ElektraInitiative/l
 
 You can clone the latest version of Elektra by running:
 
-         git clone https://github.com/ElektraInitiative/libelektra.git
+```sh
+git clone https://github.com/ElektraInitiative/libelektra.git
+```
 
 Releases can be downloaded from [here](https://www.libelektra.org/ftp/elektra/releases/).
 

benchmarks/README.md

@@ -14,9 +14,11 @@ and run the same benchmarks again.
 
 For running benchmarks you can use on Unix:
 
-    make benchmark_<filename>_callgrind
+```sh
+make benchmark_<filename>_callgrind
+```
 
-which will run the callgrind tool of Valgrind on it.
+which will run the `callgrind` tool of Valgrind on it.
 
 The old STATISTICS file is no longer used and will be
 removed with this commit.
@@ -28,18 +30,24 @@ to generate a file containing the seeds. The number of seeds vary, execute the
 `benchmark_opmphm` without parameter to get the number of seeds.
 Then execute:
 
-    cat <fileWithSeeds> | benchmark_opmphm <benchmark>
+```sh
+cat <fileWithSeeds> | benchmark_opmphm <benchmark>
+```
 
 Example:
 
 To run the OPMPHM build time benchmark you need 2008 seeds.
 First generate the seeds:
 
-    scripts/generate-seeds 2008 mySeedFile
+```sh
+scripts/generate-seeds 2008 mySeedFile
+```
 
 Then pass it to the benchmark:
 
-    cat mySeedFile | benchmark_opmphm opmphmbuildtime
+```sh
+cat mySeedFile | benchmark_opmphm opmphmbuildtime
+```
 
 ## plugingetset
 

doc/API.md

@@ -41,18 +41,24 @@ reading in one of these links above.
 
 A C or C++ source file that wants to use Elektra should include:
 
-    #include <kdb.h>
+```c
+#include <kdb.h>
+```
 
 To link an executable with the Elektra library, one way is to
 use the `pkg-config` tool:
 
-    $ gcc -o application `pkg-config --cflags --libs elektra` application.c
+```sh
+gcc -o application `pkg-config --cflags --libs elektra` application.c
+```
 
 Another way is to use CMake:
 
-    find_package(Elektra REQUIRED)
-    include_directories (${ELEKTRA_INCLUDE_DIR})
-    target_link_libraries (application ${ELEKTRA_LIBRARIES})
+```cmake
+find_package(Elektra REQUIRED)
+include_directories (${ELEKTRA_INCLUDE_DIR})
+target_link_libraries (application ${ELEKTRA_LIBRARIES})
+```
 
 Read about [compiling elektra](/doc/COMPILE.md).
 

doc/BUILDSERVER.md

@@ -47,7 +47,7 @@ Currently Elektra uses two different files.
 
 #### Jenkinsfile.daily
 
-- Jenkinsfile.daily is for daily maintanence tasks, like cleaning up build servers.
+- Jenkinsfile.daily is for daily maintenance tasks, like cleaning up build servers.
 - [Buildjob: libelektra-daily](https://build.libelektra.org/jenkins/job/libelektra-daily/)
 - [Jenkinsfile.daily](https://master.libelektra.org/scripts/jenkins/Jenkinsfile.daily)
 
@@ -81,7 +81,7 @@ documented at the function head.
 Most common use cases, for example adding a new build with certain cmake flags,
 are easy to add because of them.
 For example, the configuration that is responsible for the `debian-stable-full`
-stage is generated completly by a single helper function called `buildAndTest`:
+stage is generated completely by a single helper function called `buildAndTest`:
 
 ```groovy
 tasks << buildAndTest(
@@ -146,7 +146,7 @@ uploaded to https://doc.libelektra.org/coverage/.
 
 Artifacts from `ctest` are also preserved automatically when using
 buildAndTest.
-The function also takes care of providing a stagename based path so multiple tests
+The function also takes care of providing a stage name based path so multiple tests
 can not overwrite files that share the same name.
 
 Tests are executed in order dictated by the Jenkinsfile.
@@ -170,15 +170,15 @@ Additionally we recompile the homepage and deploy it on the a7 node.
 
 This section describes how to replicate the current Jenkins configuration.
 
-### Jenkins libelektra configuration
+### Jenkins libelektra Configuration
 
 The `libelektra` build job is a multibranch pipeline job.
 It is easiest to add via the BlueOcean interface.
 
 Most of the default settings should be ok, however some settings need to be
 verified or added to build Elektra correctly:
 
-- In Branch Sources under Behaviours `Filter by name` should be
+- In Branch Sources under Behaviors `Filter by name` should be
   added to exclude the `debian` branch from being build.
   The reason for this is that the `debian` branch is not providing a
   Jenkinsfile.
@@ -193,15 +193,15 @@ verified or added to build Elektra correctly:
 - For Build Configuration you want to specify `by Jenkinsfile` and add the
   script path: `scripts/jenkins/Jenkinsfile`.
 
-### Adding a Jenkins node
+### Adding a Jenkins Node
 
 A node needs to have a JRE (Java Runtime Environment) installed.
 Further it should run an SSH (Secure SHell) server.
 If you want to provide environments via Docker you need to install that as well.
 
 A `jenkins` user with 47000:47000 ids should be created as this is what is
 expected in Docker images.
-Additionally a public key authentification should be set up so the jenkins
+Additionally a public key authentication should be set up so the jenkins
 master can establish an ssh connection with the node.
 If the node should be able to interact with Docker the jenkins user should be
 added to the `docker` group.
@@ -212,7 +212,7 @@ As for labels `gitmirror` should be if you want to cache repositories on this
 node.
 If Docker is available the `docker` label should be set.
 
-## Understanding Jenkins output
+## Understanding Jenkins Output
 
 Our jenkins build uses parallel steps inside a single build job to do most of
 the work.
@@ -231,17 +231,17 @@ used to run the stage.
 You also want to look for whatever failed (which should be in a step also marked
 red to indicate failure).
 
-## Reproducing buildserver errors locally
+## Reproducing Build Server Errors Locally
 
 First you have to determine which image is used.
 This is described above in _Understanding Jenkins output_.
 
 Afterwards you can download it from our registry via `docker pull`.
 Pay attention that you have to use **hub-public.libelektra.org** as this subdomain
-does not require authentification for GET operations used by the Docker client.
+does not require authentication for GET operations used by the Docker client.
 As an example:
 
-```
+```sh
 docker pull hub-public.libelektra.org/build-elektra-alpine:201809-791f9f388cbdff0db544e02277c882ad6e8220fe280cda67e6ea6358767a065e
 ```
 
@@ -258,7 +258,7 @@ Now you can build the image as described in
 You can find more information on how to use our images in
 [scripts/docker/README.md](https://master.libelektra.org/scripts/docker/README.md#testing-elektra-via-docker-images).
 
-## Modify test environments
+## Modify Test Environments
 
 You can also modify the test environments (update a dependency, install a new
 dependency, ...) by editing the Dockerfiles checked into SCM.
@@ -322,7 +322,7 @@ or if just the pull request should be checked:
 
     .*build\W+allow.*
 
-## Issues with the build environment
+## Issues with the Build Environment
 
 If you have issues that are related to the build system you can open a normal
 issue and tag it with `build` and `question`.

doc/CODING.md

@@ -184,7 +184,7 @@ Most notably use:
 
 - File Ending is `.md` or integrated within Doxygen comments
 - Only use `#` characters at the left side of headers/titles
-- Use fences for code/examples
+- Use [fences](https://help.github.com/en/articles/creating-and-highlighting-code-blocks) for code/examples
 - Prefer fences which indicate the used language for better syntax highlighting
 - Fences with sh are for the [shell recorder syntax](/tests/shell/shell_recorder/tutorial_wrapper)
 - `README.md` and tutorials should be written exclusively with shell recorder syntax

doc/DESIGN.md

@@ -40,21 +40,27 @@ to find bugs.
 Some calls that create data, have an opposite call that frees this
 data. For example after you call:
 
-    KDB * kdbOpen();
+```c
+KDB * kdbOpen();
+```
 
 you need to use:
 
-    int kdbClose(KDB *handle);
+```c
+int kdbClose(KDB *handle);
+```
 
 to get rid of the resources again. The second function may also shut
 down connections. Therefore it really must be called at the end of a
 program.
 
-    Key *keyNew(const char *keyName, ...);
-    int keyDel(Key *key);
+```c
+Key *keyNew(const char *keyName, ...);
+int keyDel(Key *key);
 
-    KeySet *ksNew(int alloc, ...);
-    int ksDel(KeySet *ks);
+KeySet *ksNew(int alloc, ...);
+int ksDel(KeySet *ks);
+```
 
 In the above pairs, the first function uses `elektraMalloc` to reserve
 the necessary amount of memory. The second function frees the allocated
@@ -67,19 +73,25 @@ does not provide a string library. There are 2 ways to access the
 mentioned attributes. We show these methods here, using the comment
 attribute as an example. The function
 
-    char *keyString(const Key *key);
+```c
+char *keyString(const Key *key);
+```
 
 just returns a string. Your are not allowed to change the returned string.
 The function
 
-    ssize_t keyGetValueSize(const Key *key);
+```c
+ssize_t keyGetValueSize(const Key *key);
+```
 
 shows how long the string is for the specified key. The returned value
 also specifies the minimum buffer size that `keyGetString` will
 reserve for the copy of the key. The return value can be directly
 passed to `elektraMalloc`.
 
-    ssize_t keyGetString(const Key *key, char *returnedValue, size_t maxSize);
+```c
+ssize_t keyGetString(const Key *key, char *returnedValue, size_t maxSize);
+```
 
 writes the comment in a buffer maintained by you.
 
@@ -93,11 +105,15 @@ programmatically by the plugin `c`.
 
 To just retrieve a key, use
 
-    Key *k = keyNew(0);
+```c
+Key *k = keyNew(0);
+```
 
 To obtain a `keyset`, use
 
-    KeySet *k = ksNew(0, KS_END);
+```c
+KeySet *k = ksNew(0, KS_END);
+```
 
 The macros `va_start` and `va_end` will not be used then. Alternatively
 pass a list as described in the documentation.
@@ -136,7 +152,9 @@ terminology.
 In Elektra `char*` are used as null-terminated strings, while `void*`
 might contain `0`-bytes:
 
-    const void *keyValue(const Key *key);
+```c
+const void *keyValue(const Key *key);
+```
 
 does not specify whether the returned value is binary or a string. The
 function just returns the pointer to the value. When `key` is a string
@@ -145,25 +163,35 @@ function just returns the pointer to the value. When `key` is a string
 functions. For binary data a `NULL` pointer is also possible to
 distinguish between no data and `'\0'`.
 
-    ssize_t keyGetValueSize(const Key *key);
+```c
+ssize_t keyGetValueSize(const Key *key);
+```
 
 does not specify whether the key type is binary or string. The function
 just returns the size which can be passed to `elektraMalloc` to hold
 the entire value.
 
-    ssize_t keyGetString(const Key *key, char *returnedString, size_t maxSize);
+```c
+ssize_t keyGetString(const Key *key, char *returnedString, size_t maxSize);
+```
 
 stores the string into a buffer maintained by you.
 
-    ssize_t keySetString(Key *key, const char *newString);
+```c
+ssize_t keySetString(Key *key, const char *newString);
+```
 
 sets the null terminated string value for a certain key.
 
-    ssize_t keyGetBinary(const Key *key, void *returnedBinary, size_t maxSize);
+```c
+ssize_t keyGetBinary(const Key *key, void *returnedBinary, size_t maxSize);
+```
 
 retrieves binary data which might contain `'\0'`.
 
-    ssize_t keySetBinary(Key *key, const void *newBinary, size_t dataSize);
+```c
+ssize_t keySetBinary(Key *key, const void *newBinary, size_t dataSize);
+```
 
 sets the binary data which might contain `'\0'`. The length is given
 by `dataSize`.
@@ -188,14 +216,18 @@ must be checked in every function. When a string exceeds that limit
 
 The following functions return an internal string:
 
-    const char *keyName(const Key *key);
-    const char *keyBaseName(const Key *key);
-    const char *keyOwner(const Key *key);
-    const char *keyComment(const Key *key);
+```c
+const char *keyName(const Key *key);
+const char *keyBaseName(const Key *key);
+const char *keyOwner(const Key *key);
+const char *keyComment(const Key *key);
+```
 
 and in the case that `keyIsBinary(key)==0`:
 
-    const void *keyValue(const Key *key);
+```c
+const void *keyValue(const Key *key);
+```
 
 does so too. If in any of the functions above `key` is a `NULL`
 pointer, then they also return `NULL`.
@@ -235,9 +267,9 @@ with `KEY_TYPE`.
 
 Data structures start with a capital letter for every part of the word:
 
-    KDB ... Key Data Base Handle
-    KeySet ... Key Set
-    Key ... Key
+- `KDB` ... Key Data Base Handle
+- `KeySet` ... Key Set
+- `Key` ... Key
 
 We use singular for all names.
 
@@ -252,12 +284,14 @@ parameters. The API uses this keyword for parameters, to show that a
 function does not modify a `Key` or a `KeySet`. We do not use `const`
 for return values, except for the following functions:
 
-    const char *keyName(const Key *key);
-    const char *keyBaseName(const Key *key);
-    const char *keyComment(const Key *key);
-    const void *keyValue(const Key *key);
-    const char *keyString(const Key *key);
-    const Key  *keyGetMeta(const Key *key, const char* metaName)
+```c
+const char *keyName(const Key *key);
+const char *keyBaseName(const Key *key);
+const char *keyComment(const Key *key);
+const void *keyValue(const Key *key);
+const char *keyString(const Key *key);
+const Key  *keyGetMeta(const Key *key, const char* metaName);
+```
 
 The reason behind this is, that the above functions – as their name
 suggest – only retrieve values. The returned value must not be modified