From 66256c7650d44e2c59878fbef729b70c6c01a0af Mon Sep 17 00:00:00 2001
From: Philippe PITTOLI <karchnu@karchnu.fr>
Date: Wed, 15 May 2024 14:15:20 +0200
Subject: [PATCH] Blah

---
 graphs/Makefile.in |  4 ++--
 graphs/graphs.ms   | 39 ++++++++++++++++++++++++++++++++++-----
 2 files changed, 36 insertions(+), 7 deletions(-)

diff --git a/graphs/Makefile.in b/graphs/Makefile.in
index 6b6a8bd..7afea14 100644
--- a/graphs/Makefile.in
+++ b/graphs/Makefile.in
@@ -19,8 +19,8 @@ EQN = eqn $(EQN_OPTS)
 # GH_OUTRO: ------------ after  ---- ------ ---- -------- -- ----------------
 # GH_INTRO/GH_OUTRO: values are separated by ';'
 #
-GH_INTRO := .b1;.nr DI 0;.DS I;.fam C
-GH_OUTRO := .fam;.DE;.b2
+GH_INTRO := .nr DI 0;.DS I;.fam C;.b1;.sp -0.1i
+GH_OUTRO := .sp -0.2i;.b2;.fam;.DE
 #
 export GH_INTRO
 export GH_OUTRO
diff --git a/graphs/graphs.ms b/graphs/graphs.ms
index 61b2b38..f08388e 100644
--- a/graphs/graphs.ms
+++ b/graphs/graphs.ms
@@ -127,14 +127,43 @@ Even with that motto, the tool still is expected to be convenient for most appli
 .FOOTNOTE2
 
 This document will provide an extensive documentation on how DODB works and how to use it.
+The presented code is in Crystal such as the DODB library for now, but keep in mind that this document is all about the method more that the actual implementation, anyone could implement the exact same library in almost every other language.
 Limitations are also clearly stated in a dedicated section.
 A few experiments are described to provide an overview of the performance you can expect from this approach.
 Finally, a conclusion is drawn based on a real-world usage of this library.
 .
-.SECTION How DODB works
+.SECTION How DODB works and basic usage
 DODB is a hash table.
-The key of the hash is an auto-incremented number, the value is the stored data.
-The following section will explain the file-system representation of the data and the very few added mechanisms to speed-up searches.
+The key of the hash is an auto-incremented number and the value is the stored data.
+The following section will explain how to use DODB for basic cases including the few added mechanisms to speed-up searches.
+Also, the file-system representation of the data will be presented since it enables easy off-application searches.
+.SS Before starting: the example database
+First things first, the following code is the structure used in the rest of the document to present the different aspects of DODB.
+This is a simple object
+.I Car ,
+with a name, a color and a list of associated keywords (fast, elegant, etc.).
+.SOURCE Ruby ps=10
+class Car
+	property name     : String
+	property color    : String
+	property keywords : Array(String)
+end
+.SOURCE
+.SS DODB basic usage
+Let's create a DODB database for our cars.
+.SOURCE Ruby ps=10
+# Database creation
+db = DODB::DataBase(Car).new "path/to/db-cars"
+
+# Adding an element to the db
+db << Car.new "Corvet GT", "red", ["elegant", "fast"]
+
+# Reaching all objects in the db
+db.each do |car|
+	pp! car
+end
+.SOURCE
+
 .SS Storing data
 When a value is added, it is serialized\*[*] and written in a dedicated file.
 .FOOTNOTE1
@@ -148,11 +177,13 @@ The following example shows the content of the file system after adding three va
 .QP
 .KS
 .ft CW
+.b1
 .nf
 ..
 .de TREE2
 .ft
 .fi
+.b2
 .KE
 .QE
 ..
@@ -196,8 +227,6 @@ in the
 .I storage/indexes/by_name/
 directory.
 .TBD
-.SECTION Basic usage of the DODB library
-.TBD
 .SECTION A few more options
 .TBD
 .SECTION Limits of DODB