Doc changes that require more careful review. refs #2345

Signed-off-by: Daira Hopwood <daira@jacaranda.org>

docs/architecture.rst

@@ -486,12 +486,7 @@ validate-capability, but not vice versa). These capabilities may be expressly
 delegated (irrevocably) by simply transferring the relevant secrets.
 
 The application layer can provide whatever access model is desired, built on
-top of this capability access model. The first big user of this system so far
+top of this capability access model.
-is allmydata.com. The allmydata.com access model currently works like a
-normal web site, using username and password to give a user access to her
-"virtual drive". In addition, allmydata.com users can share individual files
-(using a file sharing interface built on top of the immutable file read
-capabilities).
 
 
 Reliability

docs/frontends/CLI.rst

@@ -179,12 +179,14 @@ and later will use it if necessary. However, once you've set a ``tahoe:``
 alias with "``tahoe set-alias``", that will override anything in the old
 ``root_dir.cap`` file.
 
-The Tahoe-LAFS CLI commands use the same path syntax as ``scp`` and
+The Tahoe-LAFS CLI commands use a similar path syntax to ``scp`` and
 ``rsync`` -- an optional ``ALIAS:`` prefix, followed by the pathname or
 filename. Some commands (like "``tahoe cp``") use the lack of an alias to
 mean that you want to refer to a local file, instead of something from the
 Tahoe-LAFS file store. Another way to indicate this is to start the
-pathname with "./", "~/", "~username/", or "/".
+pathname with "./", "~/", "~username/", or "/". On Windows, aliases
+cannot be a single character, so that it is possible to distinguish a
+path relative to an alias from a path starting with a local drive specifier.
 
 When you're dealing a single starting directory, the ``tahoe:`` alias is
 all you need. But when you want to refer to something that isn't yet

docs/frontends/webapi.rst

@@ -1997,20 +1997,22 @@ Summary: use explicit file- and dir- caps whenever possible, to reduce the
 potential for surprises when the file store structure is changed.
 
 Tahoe-LAFS provides a mutable file store, but the ways that the store can
-change are limited. The only thing that can change is that the mapping from
+change are limited. The only things that can change are:
-child names to child objects that each directory contains can be changed by
+ * that the mapping from child names to child objects that each mutable
-adding a new child name pointing to an object, removing an existing child name,
+   directory contains can be changed (by adding a new child name pointing
-or changing an existing child name to point to a different object.
+   to an object, removing an existing child name, or changing an existing
+   child name to point to a different object);
+ * that the contents of mutable files can change.
 
-Obviously if you query Tahoe for information about the filesystem and then act
+Obviously if you query for information about the file store and then act
-to change the filesystem (such as by getting a listing of the contents of a
+to change it (such as by getting a listing of the contents of a mutable
-directory and then adding a file to the directory), then the filesystem might
+directory and then adding a file to the directory), then the store might
-have been changed after you queried it and before you acted upon it.  However,
+have been changed after you queried it and before you acted upon it.
-if you use the URI instead of the pathname of an object when you act upon the
+However, if you use the URI instead of the pathname of an object when you
-object, then the only change that can happen is if the object is a directory
+act upon the object, then it will be the same object; only its contents
-then the set of child names it has might be different. If, on the other hand,
+can change (if it is mutable). If, on the other hand, you act upon the
-you act upon the object using its pathname, then a different object might be in
+object using its pathname, then a different object might be in that place,
-that place, which can result in more kinds of surprises.
+which can result in more kinds of surprises.
 
 For example, suppose you are writing code which recursively downloads the
 contents of a directory. The first thing your code does is fetch the listing
@@ -2018,15 +2020,14 @@ of the contents of the directory. For each child that it fetched, if that
 child is a file then it downloads the file, and if that child is a directory
 then it recurses into that directory. Now, if the download and the recurse
 actions are performed using the child's name, then the results might be
-wrong, because for example a child name that pointed to a sub-directory when
+wrong, because for example a child name that pointed to a subdirectory when
 you listed the directory might have been changed to point to a file (in which
-case your attempt to recurse into it would result in an error and the file
+case your attempt to recurse into it would result in an error), or a child
-would be skipped), or a child name that pointed to a file when you listed the
+name that pointed to a file when you listed the directory might now point to
-directory might now point to a sub-directory (in which case your attempt to
+a subdirectory (in which case your attempt to download the child would result
-download the child would result in a file containing HTML text describing the
+in a file containing HTML text describing the subdirectory!).
-sub-directory!).
 
-If your recursive algorithm uses the uri of the child instead of the name of
+If your recursive algorithm uses the URI of the child instead of the name of
 the child, then those kinds of mistakes just can't happen. Note that both the
 child's name and the child's URI are included in the results of listing the
 parent directory, so it isn't any harder to use the URI for this purpose.

docs/specifications/dirnodes.rst

@@ -422,20 +422,22 @@ Mounting and Sharing Directories
 ================================
 
 The biggest benefit of this dirnode approach is that sharing individual
-directories is almost trivial. Alice creates a subdirectory that she wants to
+directories is almost trivial. Alice creates a subdirectory that she wants
-use to share files with Bob. This subdirectory is attached to Alice's
+to use to share files with Bob. This subdirectory is attached to Alice's
-filesystem at "~alice/share-with-bob". She asks her filesystem for the
+file store at "alice:shared-with-bob". She asks her file store for the
-read-write directory URI for that new directory, and emails it to Bob. When
+read-only directory URI for that new directory, and emails it to Bob. When
-Bob receives the URI, he asks his own local vdrive to attach the given URI,
+Bob receives the URI, he attaches the given URI into one of his own
-perhaps at a place named "~bob/shared-with-alice". Every time either party
+directories, perhaps at a place named "bob:shared-with-alice". Every time
-writes a file into this directory, the other will be able to read it. If
+Alice writes a file into this directory, Bob will be able to read it.
-Alice prefers, she can give a read-only URI to Bob instead, and then Bob will
+(It is also possible to share read-write URIs between users, but that makes
-be able to read files but not change the contents of the directory. Neither
+it difficult to follow the `Prime Coordination Directive`_ .) Neither
-Alice nor Bob will get access to any files above the mounted directory: there
+Alice nor Bob will get access to any files above the mounted directory:
-are no 'parent directory' pointers. If Alice creates a nested set of
+there are no 'parent directory' pointers. If Alice creates a nested set of
-directories, "~alice/share-with-bob/subdir2", and gives a read-only URI to
+directories, "alice:shared-with-bob/subdir2", and gives a read-only URI to
-share-with-bob to Bob, then Bob will be unable to write to either
+shared-with-bob to Bob, then Bob will be unable to write to either
-share-with-bob/ or subdir2/.
+shared-with-bob/ or subdir2/.
+
+.. _`Prime Coordination Directive`: ../write_coordination.rst
 
 A suitable UI needs to be created to allow users to easily perform this
 sharing action: dragging a folder their vdrive to an IM or email user icon,

src/allmydata/scripts/cli.py

@@ -124,8 +124,8 @@ class ListOptions(FilesystemOptions):
     Otherwise the size of the file, when known, is given in bytes.
     The size of mutable files or unknown objects is shown as '?'.
 
-    The date/time shows when this link in the Tahoe filesystem was
+    The date/time shows when this link in the Tahoe grid was last
-    last modified.
+    modified.
     """
 
 class GetOptions(FilesystemOptions):