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`_
     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`_
 
     10. `Other Utilities`_
     11. `Debugging and Testing Features`_
 


@@ -1287,20 +1287,24 @@ Renaming a Child
  for "False"; and the parameter is case-insensitive.
 
 
  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)
 
 
 ``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.
 
  Metadata from the source directory entry is preserved. Multiple levels of
  descent in the source and destination paths are supported.