From 54b35d0fd0e83b92ccdfc054adb4640a12c46a9e Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Mon, 2 Nov 2015 14:14:49 +0000 Subject: [PATCH] Magic Folder doc updates. Signed-off-by: Daira Hopwood --- docs/frontends/magic-folder.rst | 13 +++++----- docs/magic-folder-howto.rst | 42 +++++++++++++++++++++++---------- 2 files changed, 35 insertions(+), 20 deletions(-) diff --git a/docs/frontends/magic-folder.rst b/docs/frontends/magic-folder.rst index 49027cca..855abc4b 100644 --- a/docs/frontends/magic-folder.rst +++ b/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 diff --git a/docs/magic-folder-howto.rst b/docs/magic-folder-howto.rst index 9320093d..53f7050f 100644 --- a/docs/magic-folder-howto.rst +++ b/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). -- 2.37.2