1 files changed, 23 insertions, 0 deletions
diff --git a/docs/fs.md b/docs/fs.md
index 6060949b..42e4d9b8 100644
--- a/docs/fs.md
+++ b/docs/fs.md
@@ -243,6 +243,29 @@ whole buffer.
 until someone writes or truncates it, so writing an address and reading it
 back evaluates it, which is what acme(4) promises of its own `addr`.
 
+The regular expressions are mvzr's (sets, `\d`/`\w`/`\s`, `{m,n}` and
+lazy `*?` included), searched the way sam searches (editors/acme/regx.c): as
+lines, so `^` and `$` match at the start and end of any line, `.` and a
+negated class never match a newline, and `$` also matches at the end of a
+text with no final newline. A pattern that names a newline (`\n`) runs over
+the whole text instead, its `.` kept to one line. `/re/` searches forward
+from the end of the current range to `limit` if one is set, and otherwise
+wraps to the start of the text; `?re?` finds the last match ending before
+the range, wrapping to the text's last. The match is the leftmost, but of
+the alternatives at that place mvzr takes the first that matches where sam
+takes the longest (`/gam|gamma/` finds `gam`); in a search begun in the
+middle of a line, `^` inside an alternation can match there; and in a
+pattern that spans lines, `^`, `$` and `[^...]` keep mvzr's own meaning.
+pardes has no regex engine of its own on purpose; these are its limits.
+
+An address that does not evaluate fails the write with why: `bad address
+syntax`, `no match for regexp`, `address out of range` or `bad regular
+expression`. A failed write to `addr` leaves no address at all, where acme
+keeps the old one: until an address is written or `addr` is truncated,
+reading `addr`, and reading, writing or truncating `data` and `xdata`, fail
+with `no address: the last one written to addr failed`, so a script that
+missed its target cannot then write at the last one.
+
 The three flag files `dirty`, `mark` and `scroll` read `0` or `1` and take
 `0` or `1`: whether the buffer differs from its file, whether a write pushes
 an undo point (writing `1` pushes one now), and whether a write scrolls the