doc: start writing intro, fix broken links

doc/CONTRACT.ini

@@ -127,18 +127,19 @@ description = The full text describing everything relevant for the
 
 [infos/provides]
 type = enum
+	storage
+	resolver
+	backend
+	check
 	apply
 	binary
-	check
 	code
 	conv
 	crypto
 	error
 	filefilter
 	logging
 	notification
-	resolver
-	storage
 	tracing
 status = implemented
 usedby = plugin

doc/dev/plugins-framework_new.md → doc/dev/plugins-framework.md

@@ -1,9 +1,23 @@
 # Plugins Framework
 
-TODO: rewrite intro
+<!-- TODO: integrate and remove doc/dev/plugins-framework_old.md -->
+
+The key database of Elektra basically passes a `KeySet` from plugin to plugin.
+Plugins can be chained or nested.
+The library `libelektra-kdb` only interacts with one special type of plugin called a _backend plugin_, usually with other plugins nested below.
+All other plugins must be called by these backend plugins.
+Backend plugins then usually implement some kind of plugin chaining.
 
 ## Contract
 
+In theory a plugin could do pretty much anything.
+In practice, however, plugins must meet certain expectations, described by the plugin's contract.
+
+Every plugin should provide a full contract to give information how it
+will work with other plugins. Most parts of the contract are obligatory.
+Plugins cannot be loaded without this information. For example, plugins
+must provide the clause `infos/version`.
+
 <!-- TODO: explain contract in general:
 	- explain open, init, get, set, commit, error, close operation basics
 	- explain plugin factory function: return type KeySet*
@@ -32,18 +46,14 @@ TODO: rewrite intro
 
 <!-- TODO: explain open, init, set, commit, error, close in detail -->
 
-## Types of Plugins
-
-In theory a plugin could do pretty much anything.
-However, `libelektra-kdb` only interacts with one special type of plugin called a _backend plugin_.
-All other plugins must be called by these backend plugins.
+## Plugin providers
 
-In addition to backend plugins there a few other common types of plugins that will be explained below.
+Next to the backend plugins, already introduced before, there a few other common types of plugins that will be explained below.
 
 ### Backend Plugins
 
-Backend plugins are a very special type of plugin.
-Compared to other plugins they have a much more strict contract for what they may and may not do in certain situations.
+Backend plugins are a special type of plugin.
+Compared to other plugins they have a more strict contract for what they may and may not do in certain situations.
 This is because they are the only plugins that are invoked by `libelektra-kdb`.
 Other plugins are normally called by a backend plugin, although any plugin may call another.
 

doc/news/_preparation_next_release.md

@@ -158,11 +158,25 @@ _(Michael Tucek)_
 - Add debugging tutorial. _(Tobias Schubert @qwepoizt)_
 - Improve wording and formatting of DESIGN.md _(@lawli3t)_
 - Correct various typing-, spelling- and grammar-errors in the .md-files in the directory doc and its subdirectories. _(Florian Lindner @flo91)_
-- <<TODO>>
 - explained in the docker test tutorial how to run the container with podman instead of docker. _(@muskater)_
-- <<TODO>>
 - Fix some typos in the "Getting Started" page _(Ivaylo Ivanov)_
 
+### New Backend
+
+- Improve [description of plugin framework](doc/dev/plugins-framework.md).
+- <<TODO>>
+- <<TODO>>
+- <<TODO>>
+- <<TODO>>
+- <<TODO>>
+- <<TODO>>
+- <<TODO>>
+- <<TODO>>
+- <<TODO>>
+- <<TODO>>
+- <<TODO>>
+- <<TODO>>
+
 ## Tests
 
 - disable Rust from buster _(Markus Raab)_