From 1fffd38b568250ee8f54dc837ff1bf3ecb451a7c Mon Sep 17 00:00:00 2001
From: Tim Allen <screwtape@froup.com>
Date: Fri, 6 Dec 2019 18:41:27 +1100
Subject: [PATCH 1/3] registers.asciidoc: Link from registers back to the keys
 that use them.

---
 doc/pages/registers.asciidoc | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/doc/pages/registers.asciidoc b/doc/pages/registers.asciidoc
index f6ce7f4b..ac0f08a8 100644
--- a/doc/pages/registers.asciidoc
+++ b/doc/pages/registers.asciidoc
@@ -27,23 +27,28 @@ All normal-mode commands using a register default to a specific one if not speci
 *"* (dquote)::
     default delete / copy / paste / replace register, used by:
     *c*, *d*, *y*, *p*, *<a-p>*, *<P>*, *<a-P>*, *R* and *<a-R>*
+    (see <<keys#changes, `:doc keys changes`>>)
 
 */* (slash)::
     default search / regex register, used by:
     */*, *<a-/>*, *?*, *<a-?>*, *n*, *<a-n>*, *N*, *<a-N>*, ***, *<a-*>*,
     *s*, *S*, *<a-k>* and *<a-K>*
+    (see <<keys#searching, `:doc keys searching`>>)
 
 *@* (arobase)::
     default macro register, used by:
     *q* and *Q*
+    (see <<keys#macros, `:doc keys macros`>>)
 
 *^* (caret)::
     default mark register, used by:
     *z*, *<a-z>*, *Z* and *<a-Z>*
+    (see <<keys#marks, `:doc keys marks`>>)
 
 *|* (pipe)::
     default shell command register, used by commands that spawn a subshell:
     *|*, *<a-|>*, *!* and *<a-!>*
+    (see <<keys#changes-through-external-programs, `:doc keys changes-through-external-programs`>>)
 
 == Special registers
 

From 3a23fdf15a4e8d40feeb2c2134251fd1c9d4a9b1 Mon Sep 17 00:00:00 2001
From: Tim Allen <screwtape@froup.com>
Date: Fri, 6 Dec 2019 20:00:05 +1100
Subject: [PATCH 2/3] registers.asciidoc: I don't think selections have
 captured groups.

---
 doc/pages/registers.asciidoc | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/doc/pages/registers.asciidoc b/doc/pages/registers.asciidoc
index ac0f08a8..5e43050f 100644
--- a/doc/pages/registers.asciidoc
+++ b/doc/pages/registers.asciidoc
@@ -4,7 +4,8 @@
 
 Registers are named lists of text -instead of simply text- in order to interact
 well with multiselection. They are used for various purposes, like storing
-the last yanked text, or the captured groups associated with the selections.
+yanked text, the locations of selections in a buffer, or groups captured by a
+regular expression.
 
 == Interacting
 

From 31162bdbb78d41c695a5e7b1a9e448ec0e1144f1 Mon Sep 17 00:00:00 2001
From: Tim Allen <screwtape@froup.com>
Date: Fri, 6 Dec 2019 20:01:30 +1100
Subject: [PATCH 3/3] registers.asciidoc: Document the format of marks.

---
 doc/pages/registers.asciidoc | 33 ++++++++++++++++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

diff --git a/doc/pages/registers.asciidoc b/doc/pages/registers.asciidoc
index 5e43050f..db4b46fe 100644
--- a/doc/pages/registers.asciidoc
+++ b/doc/pages/registers.asciidoc
@@ -44,7 +44,8 @@ All normal-mode commands using a register default to a specific one if not speci
 *^* (caret)::
     default mark register, used by:
     *z*, *<a-z>*, *Z* and *<a-Z>*
-    (see <<keys#marks, `:doc keys marks`>>)
+    (see <<keys#marks, `:doc keys marks`>>
+    and <<registers#marks, `:doc registers marks`>>)
 
 *|* (pipe)::
     default shell command register, used by commands that spawn a subshell:
@@ -82,3 +83,33 @@ month in register *3*, but select the entire date:
 --------------------
 (\w+) (\w+) (\d+) .+
 --------------------
+
+== Marks
+
+When a register is used to store a set of selections with the *Z* key (see
+<<keys#marks, `:doc keys marks`>>), the selections are stored as a list of
+spans, in a format similar to `%val{selections_desc}` (see
+<<expansions#value-expansions, `:doc expansions value-expansions`). However,
+the very first item of the list is of the form:
+
+---------------------
+/path/to/file@123@456
+---------------------
+
+...where:
+
+/path/to/file::
+    represents the filesystem path of the file where the selections were saved,
+    like `%val{buffile}`.
+
+123::
+    represents the value of `%val{timestamp}` when the selections were saved,
+    so the selections can still be restored after the buffer has been modified,
+    or modifications undone.
+
+456::
+    indicates which was the main selection, when the selections were saved
+    (zero-based).
+
+You can examine the content of a mark register by using `<a-p>` to paste it,
+so you can see all its items, not limited to the current number of selections.