From 16307cd2355a792bd9a388ec7bdf00ffa60f7cf2 Mon Sep 17 00:00:00 2001
From: Michael Sippel <micha@fragmental.art>
Date: Mon, 24 Jun 2024 12:19:15 +0200
Subject: [PATCH] elaborated README

---
 README.md | 77 ++++++++++++++++++++++++++++++++++---------------------
 1 file changed, 48 insertions(+), 29 deletions(-)

diff --git a/README.md b/README.md
index 1b45710..02a24f9 100644
--- a/README.md
+++ b/README.md
@@ -1,48 +1,67 @@
 # r3vi
 
-Rust Runtime for Reactive View-Projections
+### Rust Runtime for Reactive View-Projections
 
-Using **r3vi** you can define *Projections*, i.e. transformations on *Views* that are
-updated *reactively* on changes in the source-view.
-These updates are performed incrementally using fine-granuar diffs.
+r3vi is a Rust library designed to handle reactive transformations on data views, known as Projections. These projections are updated incrementally and efficiently whenever the source data changes, utilizing fine-grained diffs.
 
-*Views* are abstract accessor-interfaces that also define the update protocol (the diff).
-*Observers* can register to observe a *View* and are notified with the according diff-message
-whenever the view changes.
-*Projections* are transformations from one view into antoher.
-They are made of the target view and an observer that observes the source view.
+Key Concepts
+- **Views**: Abstract accessor interfaces that define the protocol for updates, including the structure of the diffs.
+- **Observers**: Entities that can register to monitor a View and receive notifications with the appropriate diff messages whenever the view undergoes changes.
+- **Projections**: Transformations from one view to another. A projection comprises a target view and an observer that listens to changes in the source view and updates the target view accordingly.
+r3vi provides essential data structures and projections to build projectional pipelines with an interface similar to native Rust iterators, enabling seamless and reactive data transformations.
 
-R3vi provides basic data-structures and projections to build projectional pipelines
-with an interface similar to native rust iterators.
-
-
-## Examples
+### Examples
+Below is an example demonstrating how to use r3vi to create and manipulate reactive views:
 
 ```rust
 use r3vi::buffer::vec::*;
 
-let mut buffer = VecBuffer::<i32>::new();
-buffer.push(3);
+fn main() {
+    // Create a new VecBuffer of i32
+    let mut buffer = VecBuffer::<i32>::new();
+    buffer.push(3);
 
-let projected_port = buffer.get_port()
-                      .to_sequence()     // make SequenceView from Vec
-                      .map(|x| x + 10)
-                      .filter(|x| x > 10);
+    // Create a projected port from the buffer
+    let projected_port = buffer.get_port()
+                          .to_sequence()  // Convert VecBuffer to SequenceView
+                          .map(|x| x + 10)
+                          .filter(|x| *x > 10);
 
-let projected_view = projected_port.get_view();
+    // Obtain the projected view
+    let projected_view = projected_port.get_view();
 
-assert_eq!(projected_view.get(&0), Some(13));
+    // Assert initial values in the projected view
+    assert_eq!(projected_view.get(&0), Some(13));
 
-buffer.push(5);   // maps to 15
-buffer.push(-9);  // maps to 1, is eliminated by filter
-buffer.push(1);   // maps to 11
-
-assert_eq!(projected_view.get(&1), Some(15));
-assert_eq!(projected_view.get(&2), Some(11));
+    // Add more elements to the buffer and observe changes in the projected view
+    buffer.push(5);   // 5 maps to 15 in the projection
+    buffer.push(-9);  // -9 maps to 1, which is filtered out
+    buffer.push(1);   // 1 maps to 11 in the projection
 
+    // Assert updated values in the projected view
+    assert_eq!(projected_view.get(&1), Some(15));
+    assert_eq!(projected_view.get(&2), Some(11));
+}
 ```
 
+#### How It Works
+1. **Creating a Buffer**: We start by creating a `VecBuffer` to store integers.
+2. **Defining a Projection**: Using `get_port()`, we convert the buffer to a sequence view, apply a map transformation to add 10 to each element, and then filter out values less than or equal to 10.
+3. **Obtaining a View**: The transformed data is accessed through `get_view()`, allowing us to interact with the projected data.
+4. **Reactive Updates**: As new elements are added to the buffer, the projections update reactively, maintaining the transformations and filters defined.
+
+This example demonstrates the reactive nature of r3vi's projections, where changes in the source data are automatically and incrementally propagated to the target view.
+
+### Getting Started
+To start using **r3vi**, add it to your `Cargo.toml`:
+
+```toml
+[dependencies]
+r3vi = "0.1"
+```
+
+For detailed documentation and more examples, please refer to the official documentation.
 
 ## License
+This project is licensed under the [GPLv3](COPYING) License.
 
-[GPLv3](COPYING)