From 39a9ae0ade2d2312a748809cde95cba5cbe69856 Mon Sep 17 00:00:00 2001
From: Daira Hopwood <daira@jacaranda.org>
Date: Tue, 28 Apr 2015 20:11:40 +0100
Subject: [PATCH] Docs for drop-upload on Windows.

Signed-off-by: Daira Hopwood <daira@jacaranda.org>
---
 docs/configuration.rst         |  6 +++---
 docs/frontends/drop-upload.rst | 38 +++++++++++++++++++++-------------
 2 files changed, 27 insertions(+), 17 deletions(-)

diff --git a/docs/configuration.rst b/docs/configuration.rst
index f9179376..6c38d136 100644
--- a/docs/configuration.rst
+++ b/docs/configuration.rst
@@ -455,9 +455,9 @@ SFTP, FTP
 
 Drop-Upload
 
-    As of Tahoe-LAFS v1.9.0, a node running on Linux can be configured to
-    automatically upload files that are created or changed in a specified
-    local directory. See drop-upload.rst_ for details.
+    A node running on Linux or Windows can be configured to automatically
+    upload files that are created or changed in a specified local directory.
+    See `drop-upload.rst`_ for details.
 
 .. _download-status.rst: frontends/download-status.rst
 .. _CLI.rst: frontends/CLI.rst
diff --git a/docs/frontends/drop-upload.rst b/docs/frontends/drop-upload.rst
index bc92609b..b6fcd92c 100644
--- a/docs/frontends/drop-upload.rst
+++ b/docs/frontends/drop-upload.rst
@@ -14,17 +14,14 @@ Introduction
 
 The drop-upload frontend allows an upload to a Tahoe-LAFS grid to be triggered
 automatically whenever a file is created or changed in a specific local
-directory. This is a preview of a feature that we expect to support across
-several platforms, but it currently works only on Linux.
+directory. It currently works on Linux and Windows.
 
 The implementation was written as a prototype at the First International
 Tahoe-LAFS Summit in June 2011, and is not currently in as mature a state as
 the other frontends (web, CLI, SFTP and FTP). This means that you probably
-should not keep important data in the upload directory, and should not rely
-on all changes to files in the local directory to result in successful uploads.
-There might be (and have been) incompatible changes to how the feature is
-configured. There is even the possibility that it may be abandoned, for
-example if unsolveable reliability issues are found.
+should not rely on all changes to files in the local directory to result in
+successful uploads. There might be (and have been) incompatible changes to
+how the feature is configured.
 
 We are very interested in feedback on how well this feature works for you, and
 suggestions to improve its usability, functionality, and reliability.
@@ -77,9 +74,8 @@ 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. There is an even-more-experimental
-implementation for Windows (`#1431`_), and a ticket to add support for
-Mac OS X and BSD-based systems (`#1432`_).
+This frontend only works on Linux and Windows. There is a ticket to add
+support for Mac OS X and BSD-based systems (`#1432`_).
 
 Subdirectories of the local directory are not monitored. If a subdirectory
 is created, it will be ignored. (`#1433`_)
@@ -101,7 +97,7 @@ would be enough memory and bandwidth to efficiently perform them in parallel.
 A drop-upload can occur in parallel with an upload by a different frontend,
 though. (`#1459`_)
 
-If there are a large number of near-simultaneous file creation or
+On Linux, if there are a large number of near-simultaneous file creation or
 change events (greater than the number specified in the file
 ``/proc/sys/fs/inotify/max_queued_events``), it is possible that some events
 could be missed. This is fairly unlikely under normal circumstances, because
@@ -109,6 +105,11 @@ the default value of ``max_queued_events`` in most Linux distributions is
 16384, and events are removed from this queue immediately without waiting for
 the corresponding upload to complete. (`#1430`_)
 
+The Windows implementation might also occasionally miss file creation or
+change events, due to limitations of the underlying Windows API
+(ReadDirectoryChangesW). We do not know how likely or unlikely this is.
+(`#1431`_)
+
 Some filesystems may not support the necessary change notifications.
 So, it is recommended for the local directory to be on a directly attached
 disk-based filesystem, not a network filesystem or one provided by a virtual
@@ -137,9 +138,16 @@ 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.
 
-Unicode names are supported, but the local name of a file must be encoded
-correctly in order for it to be uploaded. The expected encoding is that
-printed by ``python -c "import sys; print sys.getfilesystemencoding()"``.
+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.
+The expected encoding is that printed by
+``python -c "import sys; print sys.getfilesystemencoding()"``.
+
+On Windows, local directories with non-ASCII names are not currently working.
+(`#2219`_)
+
+On Windows, when a node has drop-upload enabled, it is unresponsive to Ctrl-C
+(it can only be killed using Task Manager or similar). (`#2218`_)
 
 .. _`#1105`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1105
 .. _`#1430`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1430
@@ -153,6 +161,8 @@ printed by ``python -c "import sys; print sys.getfilesystemencoding()"``.
 .. _`#1710`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1710
 .. _`#1711`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1711
 .. _`#1712`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1712
+.. _`#2218`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/2218
+.. _`#2219`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/2219
 
 .. _docs/garbage-collection.rst: ../garbage-collection.rst
 
-- 
2.45.2