From 3e9f5ed10725627405fb36c7a1ea33fa7eb67a1e Mon Sep 17 00:00:00 2001
From: Markus Raab <elektra@markus-raab.org>
Date: Fri, 16 Sep 2022 07:36:55 +0200
Subject: [PATCH] doc: start writing intro, fix broken links

---
 doc/CONTRACT.ini                              |  7 +++--
 ...-framework_new.md => plugins-framework.md} | 28 +++++++++++++------
 doc/news/_preparation_next_release.md         | 18 ++++++++++--
 3 files changed, 39 insertions(+), 14 deletions(-)
 rename doc/dev/{plugins-framework_new.md => plugins-framework.md} (72%)

diff --git a/doc/CONTRACT.ini b/doc/CONTRACT.ini
index 5be75f6e000..16a6496e9f6 100644
--- a/doc/CONTRACT.ini
+++ b/doc/CONTRACT.ini
@@ -127,9 +127,12 @@ description = The full text describing everything relevant for the
 
 [infos/provides]
 type = enum
+	storage
+	resolver
+	backend
+	check
 	apply
 	binary
-	check
 	code
 	conv
 	crypto
@@ -137,8 +140,6 @@ type = enum
 	filefilter
 	logging
 	notification
-	resolver
-	storage
 	tracing
 status = implemented
 usedby = plugin
diff --git a/doc/dev/plugins-framework_new.md b/doc/dev/plugins-framework.md
similarity index 72%
rename from doc/dev/plugins-framework_new.md
rename to doc/dev/plugins-framework.md
index 6580f1c3da3..7bc504eed03 100644
--- a/doc/dev/plugins-framework_new.md
+++ b/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.
 
diff --git a/doc/news/_preparation_next_release.md b/doc/news/_preparation_next_release.md
index d2d726d12d1..c9570a2fcb3 100644
--- a/doc/news/_preparation_next_release.md
+++ b/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)_