From a12b81fb538349f5e39eae8c69b5c766b878099e Mon Sep 17 00:00:00 2001
From: Edoardo La Greca
Date: Fri, 25 Jul 2025 17:10:05 +0200
Subject: rephrase and rectify readme

---
 README.md | 32 +++++++++++++++++++-------------
 1 file changed, 19 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 816398b..e12376b 100644
--- a/README.md
+++ b/README.md
@@ -2,8 +2,13 @@ NineKt: Teaching Kotlin to speak 9P
 ===================================
 
 NineKt (I don't really care about pronunciation, "nine-kay-tee" or "nine-Kate" or whatever you want) is a library
-written in Kotlin (and primarily targeting the JVM) that eases the process of implementing the [9P protocol](https://en.wikipedia.org/wiki/9P_(protocol))
-into any JVM application, including those for Android.
+written in Kotlin (and primarily targeting the JVM) that provides a client-side implementation to the
+[9P protocol](https://en.wikipedia.org/wiki/9P_(protocol)). It targets any JVM application, especially those that run on
+Android.
+
+The implementation of client-side 9P provided by NineKt and the expected server-side behavior are those described by the
+[section 5 in 9front's manual pages](https://man.9front.org/5/). All differences between this and the original Plan 9
+from Bell Labs specification, or any other specification (provided by, e.g., forks of it), are therefore ignored.
 
 Rationale
 ---------
@@ -19,16 +24,16 @@ There are a bunch of reasons why NineKt was born:
 Usage
 -----
 
-The most important class, and also the only one you'll need for basic usage, is `NinePConnection`. This class implements
+The most important class, and also the fulcrum of the entire implementation, is `NinePConnection`. This class implements
 the 9P protocol on top of another unknown transport-layer protocol (although it's usually TCP) provided, and managed, by
 a subclass of the `NetworkPacketTransporter` abstract class. For this reason, the `NinePConnection`'s constructor
 requires an instance of another class that implements `NetworkPacketTransporter`. It doesn't need anything else.
 
 The `NetworkPacketTransporter` class provides abstraction over the specific networking methods. This makes the classes
-using `NetworkPacketTransporter` independent from both the specific networking API and the underlying transport-layer
-protocol of choice. This allows swapping the API or protocol at any time and vastly improves portability. With all this
-considered, since Java's standard library provides a networking API already, I thought that an implementation based on
-that would be imperative, appreciated, and especially broadly used.
+using `NetworkPacketTransporter` independent of both the specific networking API and the underlying transport-layer
+protocol of choice, therefore allowing swapping the API or protocol at any time and vastly improves portability. With
+all this considered, since Java's standard library provides a networking API already, I thought that an implementation
+based on that would be imperative, appreciated, and especially broadly used.
 
 ```kotlin
 // This example uses one of the dial(2) formats for the address and port.
@@ -37,15 +42,16 @@ try {
     npconn = NinePConnection(NetworkPacketTransporterJavaNet("net!9p.mydomain.com!564"))
 } catch (uhe: UnresolvableHostException) {
     // failed :(
+    // what now?
 }
 ```
 
-While `NetworkPacketTransporter` implementation initializes the transport-layer connection as soon as it's instanced,
-this is not true for `NinePConnection` and the 9P connection. The reason why the 9P protocol is not immediately
-initialized is that `NinePConnection` only exposes methods that coincide with the protocol messages, which means that
-providing an automated way to initialize the protocol would mix two levels of abstraction in the same class. For this
-purpose, the `initNineP` function is a shorthand that can do it for you, although it's possible to do so manually by
-using the 9P primitives.
+While `NetworkPacketTransporter`'s implementation of choice initializes the transport-layer connection as soon as it's
+instanced, this is not true for `NinePConnection` and the 9P connection it manages. The reason why this class behaves in
+such way lies in its purpose, which is to only expose methods that coincide 1:1 with 9P's protocol message types.
+Therefore, providing an automated way to initialize the protocol would mix two levels of abstraction in the same class.
+For this purpose, the `initNineP` utility function is a shorthand that can do exactly this for you, although it's
+possible to do so manually by using the 9P primitives.
 
 A word on Android
 -----------------
-- 
cgit v1.2.3