attempt to clarify move-vs-relink

diff --git a/docs/frontends/webapi.rst b/docs/frontends/webapi.rst
index 433cd7a370c896c29fd72e48efb883073c3382ea..0f21613096305416a0a02d168fa8f1e5478114b7 100644 (file)
--- a/docs/frontends/webapi.rst
+++ b/docs/frontends/webapi.rst
@@ -29,7 +29,7 @@ The Tahoe REST-ful Web API
     6.  `Attaching an Existing File Or Directory (by URI)`_
     7.  `Unlinking a Child`_
     8.  `Renaming a Child`_
-    9.  `Moving a Child`_
+    9.  `Relinking ("Moving") a Child`_
     10. `Other Utilities`_
     11. `Debugging and Testing Features`_
 
@@ -1287,20 +1287,24 @@ Renaming a Child
  for "False"; and the parameter is case-insensitive.
 
 
-Moving a Child
---------------
+Relinking ("Moving") a Child
+----------------------------
 
 ``POST /uri/$DIRCAP/[SUBDIRS../]?t=relink&from_name=OLD&to_dir=$NEWDIRCAP/[NEWSUBDIRS../]&to_name=NEW``
  ``[&replace=true|false|only-files]``    (Tahoe >= v1.10)
 
- This instructs the node to move a child of the given source directory,
- into a different directory and/or to a different name. The command is
- named ``relink`` because it works by adding a new link from the new
- location, then removing the old link. The source and destination
- directories must be writeable. If {{{to_dir}}} is not present, the child
- link is renamed within the same directory. If {{{to_name}}} is not present
- then it defaults to {{{from_name}}}. If the destination link (directory
- and name) is the same as the source link, the operation has no effect.
+ This instructs the node to move a child of the given source directory, into
+ a different directory and/or to a different name. The command is named
+ ``relink`` because what it does is add a new link to the child from the new
+ location, then remove the old link. Nothing is actually "moved" — the child
+ is still reachable through any path from which it was formerly reachable,
+ and the storage space occupied by its ciphertext is not affected.
+
+ The source and destination directories must be writeable. If {{{to_dir}}} is
+ not present, the child link is renamed within the same directory. If
+ {{{to_name}}} is not present then it defaults to {{{from_name}}}. If the
+ destination link (directory and name) is the same as the source link, the
+ operation has no effect.
 
  Metadata from the source directory entry is preserved. Multiple levels of
  descent in the source and destination paths are supported.