Magic Folder doc updates.

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

docs/frontends/magic-folder.rst

@@ -88,7 +88,7 @@ page and the node log_ may be helpful to determine the cause of any failures.
 Known Issues and Limitations
 ============================
 
-This frontend only works on Linux and Windows. There is a ticket to add
+This feature only works on Linux and Windows. There is a ticket to add
 support for Mac OS X and BSD-based systems (`#1432`_).
 
 The only way to determine whether uploads have failed is to look at the
@@ -123,11 +123,10 @@ The ``private/magic_folder_dircap`` and ``private/collective_dircap`` files
 cannot use an alias or path to specify the upload directory. (`#1711`_)
 
 If a file in the upload directory is changed (actually relinked to a new
-file), then the old file is still present on the grid, and any other caps to
-it will remain valid. See `docs/garbage-collection.rst`_ for how to reclaim
-the space used by files that are no longer needed. Garbage collection is
-not included as part of the OTF Magic-Folder grant... however we've documented
-this feature here `#2440`_
+file), then the old file is still present on the grid, and any other caps
+to it will remain valid. Eventually it will be possible to use
+`garbage collection`_ to reclaim the space used by these files; however
+currently they are retained indefinitely. (`#2440`_)
 
 Unicode filenames are supported on both Linux and Windows, but on Linux, the
 local name of a file must be encoded correctly in order for it to be uploaded.
@@ -149,5 +148,5 @@ On Windows, when a node has Magic Folder enabled, it is unresponsive to Ctrl-C
 .. _`#2219`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/2219
 .. _`#2440`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/2440
 
-.. _docs/garbage-collection.rst: ../garbage-collection.rst
+.. _`garbage collection`: ../garbage-collection.rst
 .. _`Magic-Folder CLI design documentation`: ../proposed/magic-folder/user-interface-design.rst

docs/magic-folder-howto.rst

@@ -2,10 +2,30 @@
 Magic Folder Set-up Howto
 =========================
 
-1.  `Preparation`_
-2.  `Setting up a local test grid`_
-3.  `Setting up Magic Folder`_
-4.  `Testing`_
+1.  `This document`_
+2.  `Preparation`_
+3.  `Setting up a local test grid`_
+4.  `Setting up Magic Folder`_
+5.  `Testing`_
+
+
+This document
+=============
+
+This is preliminary documentation of how to set up the
+Magic Folder pre-release using a test grid on a single Linux
+or Windows machine, with two clients and one server. It is
+aimed at a fairly technical audience.
+
+For an introduction to Magic Folder and how to configure it
+more generally, see `docs/frontends/magic-folder.rst`_.
+
+It it possible to adapt these instructions to run the nodes on
+different machines, to synchronize between three or more clients,
+to mix Windows and Linux clients, and to use multiple servers
+(if the Tahoe-LAFS encoding parameters are changed).
+
+.. _`docs/frontends/magic-folder.rst`: ../docs/frontends/magic-folder.rst
 
 
 Preparation
@@ -114,7 +134,7 @@ Both Linux and Windows
 (Replace ``/`` with ``\`` for Windows paths.)
 
 Edit ``../grid/alice/tahoe.cfg``, and make the following
-changes to the [node] and [client] sections::
+changes to the ``[node]`` and ``[client]`` sections::
 
   [node]
   nickname = alice
@@ -202,14 +222,10 @@ Note that when a file is deleted, the corresponding file in the
 other directory will be renamed to a filename ending in ``.backup``.
 Deleting a directory will have no effect.
 
-Subdirectories do not currently work on Windows.
-
 For other known issues and limitations, see
 https://github.com/tahoe-lafs/tahoe-lafs/blob/2438.magic-folder-stable.5/docs/frontends/magic-folder.rst#known-issues-and-limitations
 
-For simplicity, this Howto covers only using Magic Folder using a
-test grid on a single machine, with two clients and one server.
-It should also be possible to run the nodes on different machines,
-to synchronize between three or more clients, to mix Windows and
-Linux clients, and to use multiple servers (if the Tahoe-LAFS
-encoding parameters are changed).
+As mentioned earlier, it is also possible to run the nodes on
+different machines, to synchronize between three or more clients,
+to mix Windows and Linux clients, and to use multiple servers
+(if the Tahoe-LAFS encoding parameters are changed).