[nongnu] elpa/hyperdrive 1e71cec4d0 074/102: Docs: Improve versioning section

[ELPA Syncer]

branch: elpa/hyperdrive
commit 1e71cec4d0385c370e36d2089e5c2e0fc0d453b3
Author: Joseph Turner <joseph@ushin.org>
Commit: Adam Porter <adam@alphapapa.net>

    Docs: Improve versioning section
---
 doc/hyperdrive.org | 44 +++++++++++++++++++++++++-------------------
 1 file changed, 25 insertions(+), 19 deletions(-)

diff --git a/doc/hyperdrive.org b/doc/hyperdrive.org
index 2fd7b92379..cd747b5a39 100644
--- a/doc/hyperdrive.org
+++ b/doc/hyperdrive.org
@@ -605,19 +605,23 @@ Hyperdrives are versioned, meaning that it is possible to 
explore a
 hyperdrive as it was in the past. Version numbers indicate the
 hyperdrive's version. For example, ~hyper://PUBLIC-KEY/$/version/50/~
 refers to the fiftieth version of the hyperdrive identified by
-~PUBLIC-KEY~. Loading a hyperdrive entry without specifying a version
-number always loads the most recent version of that hyperdrive. If you
-pass ~hyper://PUBLIC-KEY/foo.org~ to ~hyperdrive-open-url~, ~hyperdrive.el~
-will always attempt to find ~/foo.org~ inside the latest version of that
-hyperdrive.
-
-Whenever you update an entry, the hyperdrive's version number gets
-incremented by 1. The version number tells you how many times the
-hyperdrive has been modified, not how many times a particular entry
-has been modified. For example, let's say that the current version of
-your hyperdrive at ~hyper://PUBLIC-KEY/~ is 50. If you add a new entry
-at ~hyper://PUBLIC-KEY/bar.org~, the latest version of your hyperdrive
-will become 51.
+~PUBLIC-KEY~. If you want to load the latest version, leave out the
+~/$/version/N~ part.  For example, if you run...
+
+#+begin_example
+M-x hyperdrive-open-url RET hyper://PUBLIC-KEY/foo.org RET
+#+end_example
+
+...then ~hyperdrive.el~ will attempt to find ~/foo.org~ inside the latest 
version
+of that hyperdrive.
+
+Whenever you add a file, remove a file, or change a file, the
+hyperdrive's version number gets incremented by 1. The version number
+tells you how many times the hyperdrive has been modified, not how
+many times a particular file has been modified. For example, let's say
+that the current version of your hyperdrive at ~hyper://PUBLIC-KEY/~
+is 50. If you add a new file at ~hyper://PUBLIC-KEY/bar.org~, the latest
+version of your hyperdrive will become 51.
 
 Since ~/bar.org~ did not exist before version 51, ~hyperdrive.el~ should
 warn you that nothing exists at
@@ -625,10 +629,9 @@ warn you that nothing exists at
 ~hyper://PUBLIC-KEY/quux.org~, your hyperdrive's latest version will
 become 52. For the moment, ~hyper://PUBLIC-KEY/bar.org~,
 ~hyper://PUBLIC-KEY/$/version/51/bar.org~, and
-~hyper://PUBLIC-KEY/$/version/52/bar.org~, all point to the same
-version of ~/bar.org~. If you then make a change to ~/bar.org~, your
-hyperdrive's latest version will become 53. Now
-~hyper://PUBLIC-KEY/bar.org~ and
+~hyper://PUBLIC-KEY/$/version/52/bar.org~, all point to the same version
+of ~/bar.org~. If you then make a change to ~/bar.org~, your hyperdrive's
+latest version will become 53. Now ~hyper://PUBLIC-KEY/bar.org~ and
 ~hyper://PUBLIC-KEY/$/version/53/bar.org~ will point to the latest
 version of ~/bar.org~, while the 51- and 52-versioned URLs will continue
 to point to the original version.
@@ -647,8 +650,11 @@ hyperdrive history until version 51 (when it was created) 
and that it
 was modified at version 53.  Since the final range number in the table
 is 53, we also know that the hyperdrive's latest version is 53.
 
-If you delete ~/bar.org~, ~hyper://PUBLIC-KEY/bar.org~ will no longer
-point to anything, but the versioned URLs will still work.
+If you delete ~/bar.org~ then try to load ~hyper://PUBLIC-KEY/bar.org~,
+~hyperdrive.el~ will open an empty buffer for you to author a new file.
+If another user (not you) attempts to load that URL, ~hyperdrive.el~
+will warn ~"URL not found"~.  All users can still access the old file
+contents at the versioned URLs.
 
 Since only the current version of a hyperdrive entry can be updated,
 ~hyperdrive.el~ sets the buffer to read-only whenever a version number