From 91244cb815cfc7e8148ac2c39d994779d574fca4 Mon Sep 17 00:00:00 2001
From: Philippe Pittoli <karchnu@karchnu.fr>
Date: Fri, 24 Jan 2025 06:11:40 +0100
Subject: [PATCH] Add a few explanations (basic stuff).

---
 paper/paper.ms | 36 ++++++++++++++++++++++--------------
 1 file changed, 22 insertions(+), 14 deletions(-)

diff --git a/paper/paper.ms b/paper/paper.ms
index a0926b9..0a25bb5 100644
--- a/paper/paper.ms
+++ b/paper/paper.ms
@@ -187,9 +187,9 @@ This is a simple object
 with a name, a color and a list of associated keywords (fast, elegant, etc.).
 .SOURCE Ruby ps=9 vs=10
 class Car
-	property name     : String
-	property color    : String
-	property keywords : Array(String)
+	property name     : String        # ex: Corvet
+	property color    : String        # ex: red
+	property keywords : Array(String) # ex: [fast, impressive]
 end
 .SOURCE
 .
@@ -200,15 +200,15 @@ Let's create a DODB database for our cars.
 # Database creation
 database = DODB::Storage::Uncached(Car).new "path/to/db-cars"
 
-# Adding an element to the db
+# Add an element to the db
 database << Car.new "Corvet", "red", ["elegant", "fast"]
 
-# Reaching all objects in the database
+# Access all objects in the database
 database.each do |car|
 	pp! car
 end
 .SOURCE
-When a value is added, it is serialized\*[*] and written in a dedicated file.
+Inserted entries are serialized\*[*] and written in a dedicated file.
 .FOOTNOTE1
 Serialization is currently in JSON.
 .[
@@ -250,7 +250,7 @@ The car is serialized as expected in the file
 .QE
 .
 .
-Next step, to retrieve, to modify or to delete a value, its key will be required.
+The key of the entry (its number) is required to retrieve, to modify or to delete it.
 .
 .QP
 .SOURCE Ruby ps=9 vs=10
@@ -284,12 +284,13 @@ That is when indexes come into play.
 A simple way to quickly retrieve a piece of data is to create
 .I indexes
 based on its attributes.
-When a value is added to the database, or when it is modified, a
-.I trigger
-can be called to index it.
-There are currently three main triggers in
-.CLASS DODB
-to index values: basic indexes, partitions and tags.
+When a value is inserted, modified or deleted from the database, an action can be performed automatically thanks to a user recorded callback.
+Callbacks are named
+.I triggers
+in DODB and are used mainly to index data.
+There are currently three main indexing triggers in
+.CLASS DODB :
+basic indexes, partitions and tags.
 .
 .SSS Basic indexes (1 to 1 relations)
 Basic indexes
@@ -310,7 +311,14 @@ end
 cars_by_name = cars.new_index "name", { |car| car.name }
 cars_by_name = cars.new_index "name", &.name
 .SOURCE
-Once the index has been created, every added or modified entry in the database will be indexed.
+The above code presents the creation of a new index on the database
+.I cars .
+An index requires a name (a simple string), which simply is "name" in this case since the indexed value is the name of the cars.
+An index also requires a callback, a procedure to extract the value used for indexing.
+In this case, the procedure takes a car as a parameter and returns its "name" attribute.
+This procedure can be arbitrary complex and include any necessary data transformation.
+
+Once the index has been created, every inserted or modified entry in the database will be indexed.
 Adding a trigger provides an
 .I object
 used to manipulate the database based on the related attribute.