From 3b0029335ad4cedde308a42dfc1594f864435125 Mon Sep 17 00:00:00 2001
From: Virgil Dupras <hsoft@hardcoded.net>
Date: Sun, 14 Jul 2019 11:30:28 -0400
Subject: [PATCH] ed: add README

---
 apps/ed/README.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 apps/ed/main.asm  | 14 --------------
 2 files changed, 57 insertions(+), 14 deletions(-)
 create mode 100644 apps/ed/README.md

diff --git a/apps/ed/README.md b/apps/ed/README.md
new file mode 100644
index 0000000..c16c7b5
--- /dev/null
+++ b/apps/ed/README.md
@@ -0,0 +1,57 @@
+# ed - line editor
+
+Collapse OS's `ed` is modeled after UNIX's ed (let's call it `Ued`). The goal
+is to have an editor that is tight on resources and that doesn't require
+ncurses-like screen management.
+
+In general, we try to follow `Ued`'s conventions and the "Usage" section is
+mostly a repeat of `Ued`'s man page.
+
+## Differences
+
+There are a couple of differences with `Ued` that are intentional. Differences
+not listed here are either bugs or simply arent implemented yet.
+
+* Always has a prompt, `:`.
+* No size printing on load
+* Initial line is the first one
+
+## Usage
+
+`ed` is invoked from the shell with no argument. ed takes no argument.
+It reads from the currently selected blkdev and writes to it.
+
+In normal mode, `ed` waits for a command and executes it. If the command is
+invalid, a line with `?` is printed and `ed` goes back to waiting for a command.
+
+A command can be invalid because it is unknown, malformed or if its address
+range is out of bounds.
+
+### Commands
+
+* `(addrs)p`: Print lines specified in `addrs` range. This is the default
+  command. If only `(addrs)` is specified, it has the same effect.
+* `(addrs)d`: Delete lines specified in `addrs` range.
+* `q`: quit `ed`
+
+### Current line
+
+The current line is central to `ed`. Address ranges can be expressed relatively
+to it and makes the app much more usable. The current line starts at `1` and
+every command changes the current line to the last line that the command
+affects. For example, `42p` changes the current line to `42`, `3,7d`, to 7.
+
+### Address ranges
+
+An "address" is a line number. The first line is `1`. An address range is a
+start line and a stop line, expressed as `start,stop`. For example, `2,4` refer
+to lines 2, 3 and 4.
+
+When expressing ranges, `stop` can be omitted. It will then have the same value
+as `start`. `42` is equivalent to `42,42`.
+
+Addresses can be expressed relatively to the current line with `+` and `-`.
+`+3` means "current line + 3", `-5, +2` means "address range starting at 5
+lines before current line and ending 2 lines after it`.
+
+`+` alone means `+1`, `-` means `-1`.
diff --git a/apps/ed/main.asm b/apps/ed/main.asm
index 5a7e1a0..7e6268f 100644
--- a/apps/ed/main.asm
+++ b/apps/ed/main.asm
@@ -29,20 +29,6 @@
 ; around whenever we add or delete lines. Hopefully, "LDIR" will be our friend
 ; here...
 ;
-; *** Usage ***
-;
-; ed takes no argument. It reads from the currently selected blkdev and writes
-; to it. It repeatedly presents a prompt, waits for a command, execute the
-; command. 'q' to quit.
-;
-; Enter a number to print this line's number. For ed, we break with Collapse
-; OS's tradition of using hex representation. It would be needlessly confusing
-; when combined with commands (p, c, d, a, i). All numbers in ed are
-; represented in decimals.
-;
-; Like in ed, line indexing is one-based. This is only in the interface,
-; however. In the code, line indexes are zero-based.
-;
 ; *** Requirements ***
 ; BLOCKDEV_SIZE
 ; addHL