From 473dd5f4dceafe8faedd7cba03686d143ee92d8b Mon Sep 17 00:00:00 2001
From: Michael Sippel <micha@fragmental.art>
Date: Thu, 21 Mar 2024 18:17:04 +0100
Subject: [PATCH] add short READMEs for examples

---
 examples/tty-01-hello/README.md    |  8 ++++++++
 examples/tty-01-hello/src/main.rs  | 23 ++++++++++++++++++++---
 examples/tty-02-digit/README.md    |  4 ++++
 examples/tty-02-digit/src/main.rs  |  3 +++
 examples/tty-03-string/README.md   |  8 ++++++++
 examples/tty-03-string/src/main.rs |  9 ++++++++-
 6 files changed, 51 insertions(+), 4 deletions(-)
 create mode 100644 examples/tty-01-hello/README.md
 create mode 100644 examples/tty-02-digit/README.md
 create mode 100644 examples/tty-03-string/README.md

diff --git a/examples/tty-01-hello/README.md b/examples/tty-01-hello/README.md
new file mode 100644
index 0000000..b1be4e7
--- /dev/null
+++ b/examples/tty-01-hello/README.md
@@ -0,0 +1,8 @@
+# tty-01-hello
+
+This example shows how to:
+ - initialize the TTY backend (`lib-nestetd-tty`),
+ - create a simple 'Hello World' output,
+ - create color gradients on the outputted text
+   utilizing basic projection functionality from `lib-r3vi`,
+ - perform basic layouting & compositing.
diff --git a/examples/tty-01-hello/src/main.rs b/examples/tty-01-hello/src/main.rs
index 45856c0..468d8f5 100644
--- a/examples/tty-01-hello/src/main.rs
+++ b/examples/tty-01-hello/src/main.rs
@@ -1,3 +1,10 @@
+//! This example shows how to:
+//!  - initialize the TTY backend (`lib-nestetd-tty`),
+//!  - create a simple 'Hello World' output,
+//!  - create color gradients on the outputted text
+//!    utilizing basic projection functionality from `lib-r3vi`,
+//!  - perform basic layouting & compositing.
+
 extern crate cgmath;
 extern crate nested;
 extern crate nested_tty;
@@ -15,19 +22,29 @@ use {
 
 #[async_std::main]
 async fn main() {
-    /* initialize our terminal
+    /* Initialize our terminal.
      */
     let tty_app = TTYApplication::new(|event| { /* handle event */ });
 
-    /* populate the view in `term_port`
+    /* Setup our "root" view of the application.
+     * This will be the compositor, which is able to
+     * mix multiple `TerminalView`-Views together.
+     * Its output is routed to the `app.port` Viewport,
+     * so it will be displayed on TTY-output.
      */
     let compositor = TerminalCompositor::new(tty_app.port.inner());
 
+    /* Add the label 'test' at position (7, 2)
+     */
     compositor
         .write()
         .unwrap()
         .push(nested_tty::make_label("test").offset(Vector2::new(7, 2)));
 
+    /* Add a 'Hello World' label at position (5, 3)
+     * and set a coloring determined by formula from
+     * the position of each character.
+     */
     compositor.write().unwrap().push(
         nested_tty::make_label("Hello World")
             .map_item(|p, a| {
@@ -36,7 +53,7 @@ async fn main() {
             .offset(Vector2::new(5, 3)),
     );
 
-    /* write the changes in the view of `term_port` to the terminal
+    /* write the changes in the root-view to the terminal
      */
     tty_app.show().await.expect("output error!");
 }
diff --git a/examples/tty-02-digit/README.md b/examples/tty-02-digit/README.md
new file mode 100644
index 0000000..23b502b
--- /dev/null
+++ b/examples/tty-02-digit/README.md
@@ -0,0 +1,4 @@
+# tty-02-digit
+
+This example demonstrates how a very simple editor for hexadecimal digits
+can be created with `lib-nested` and the `lib-nested-tty` backend.
diff --git a/examples/tty-02-digit/src/main.rs b/examples/tty-02-digit/src/main.rs
index 12b4f71..61603b1 100644
--- a/examples/tty-02-digit/src/main.rs
+++ b/examples/tty-02-digit/src/main.rs
@@ -1,3 +1,6 @@
+//! This example demonstrates how a very simple editor for hexadecimal digits
+//! can be created with `lib-nested` and the `lib-nested-tty` backend.
+
 extern crate cgmath;
 extern crate nested;
 extern crate nested_tty;
diff --git a/examples/tty-03-string/README.md b/examples/tty-03-string/README.md
new file mode 100644
index 0000000..85305aa
--- /dev/null
+++ b/examples/tty-03-string/README.md
@@ -0,0 +1,8 @@
+# tty-03-string
+
+Similarly to `tty-02-digit`, a editor is created
+but of type <List Char>.
+The contents of the editor can be retrieved by
+a morphism from the `EditTree` node.
+To demonstrate that, the values are are mapped
+to the TTY-display in different form.
diff --git a/examples/tty-03-string/src/main.rs b/examples/tty-03-string/src/main.rs
index de84271..d0ad31a 100644
--- a/examples/tty-03-string/src/main.rs
+++ b/examples/tty-03-string/src/main.rs
@@ -1,3 +1,10 @@
+//! Similarly to `tty-02-digit`, a editor is created
+//! but of type <List Char>.
+//! The contents of the editor can be retrieved by
+//! a morphism from the `EditTree` node.
+//! To demonstrate that, the values are are mapped
+//! to the TTY-display in different form.
+
 extern crate cgmath;
 extern crate nested;
 extern crate nested_tty;
@@ -100,7 +107,7 @@ async fn main() {
         comp.push(
             nested_tty::make_label(&label_str)
                 .map_item(|_pt, atom| atom.add_style_front(TerminalStyle::fg_color((90,90,90))))
-                .offset(Vector2::new(1, 1)));
+                .offset(Vector2::new(1,1)));
 
         comp.push(
             edittree_list.get()