From d713d8f45f4de3a822141941bd9aecb366765b57 Mon Sep 17 00:00:00 2001
From: "Shahar \"Dawn\" Or" <mightyiampresence@gmail.com>
Date: Tue, 20 Feb 2024 12:36:35 +0700
Subject: [PATCH] docs: readme

---
 README.md | 42 ++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 40 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index b21ecdc..843fe64 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,41 @@
-# eelco
+This is a CLI that reads markdown files,
+extracts Nix examples from them and
+tests these examples.
 
-> [Nix](https://nixos.org) doctests CLI
+Two kinds of examples are supported:
+
+1. expression examples
+2. repl examples
+
+Expression examples look like this:
+
+````md
+```nix
+assert 1 + 1 == 2; null
+```
+````
+
+They are nix expressions inside of fenced code blocks.
+The first word in their info string is `nix`.
+The expression is passed to Nix for evaluation as `nix eval --expr <EXPRESSION>`.
+For future compatibility, to be considered passing,
+it must successfully evaluate into `null`.
+It is expected of the author to demonstrate and prove their points
+using assertions.
+
+Repl exaples look like this;
+
+````md
+```nix-repl
+nix-repl> a = 1
+
+nix-repl> a + 1
+2
+
+```
+````
+
+Repl examples will be evaluated by the real Nix repl.
+At the moment, expressions and assignments queries are supported.
+A line that follows an expression query will be used as an assertion.
+Blank lines matter. Even trailing ones.