From c470483bc824814cd42f9265ceb5b9ed62a05025 Mon Sep 17 00:00:00 2001
From: Edoardo La Greca
Date: Mon, 16 Jun 2025 04:41:08 +0200
Subject: add description, rationale, usage, and notes to readme

---
 README.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 97195d0..5a5d72b 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,50 @@
 NineKt: Teaching Kotlin to speak 9P
 ===================================
 
+NineKt is a library written in Kotlin that eases the process of implementing the
+[9P protocol](https://en.wikipedia.org/wiki/9P_(protocol)) into any JVM application, including those for Android.
 
+Rationale
+---------
+
+There are a bunch of reasons why NineKt was born:
+
+1. [All other JVM implementations](http://9p.cat-v.org/implementations) look dead.
+2. There is no Kotlin implementation yet.
+3. There seems to be no such thing for Android, but Android apps can create custom file systems in a bunch of ways. See
+   the section named "A word on Android" below.
+
+Usage
+-----
+
+The most important class is `NinePConnection`. This class translates file system operations (reading, writing, etc.)
+into 9P network messages and vice versa. It needs basic information about: the connection details (remote host's
+address, port, etc.), the file system handlers (functions for reading, writing, etc.), and network handlers (functions
+for sending and receiving data in the networking scope). Connection details are provided directly to the class, while
+handlers must be provided by implementing the `FileSystemManager` and `NetworkManager` interfaces.
+
+Avoiding using file system and networking primitives directly vastly improves independence from them (and therefore
+portability), in addition to letting NineKt's codebase focus solely on the 9P protocol itself and the translation of one
+set of operations into the other.
+
+Once everything is properly configured, the 9P connection can be started using the `connect` method.
+
+A word on Android
+-----------------
+
+Android 11 introduces ([back](https://source.android.com/docs/core/storage/scoped#fuse-performance-tuning)) the support
+for [FUSE](https://en.wikipedia.org/wiki/Filesystem_in_Userspace) ([source](https://source.android.com/docs/core/storage/scoped#using-scoped-storage-with-fuse)),
+but this limits compatibility with certain versions of Android, and consequently certain devices.
+
+Android has also been supporting the [Storage Access Framework](https://developer.android.com/guide/topics/providers/document-provider)
+since version 4.4. [TODO]
+
+
+Notes
+-----
+
+- Source files live in `src/main/kotlin`.
+- All manual page references (e.g. `dial(2)`) refer to [9front's manual](https://man.9front.org/).
 
 License
 -------
-- 
cgit v1.2.3