From d5aa061abe4b81273ea02744d82330985a2fa70d Mon Sep 17 00:00:00 2001
From: Adam Spiers <stow@adamspiers.org>
Date: Fri, 25 Nov 2011 15:23:08 +0000
Subject: [PATCH] Fix documentation regarding splitting of symlinks across
 multiple stow directories.

---
 doc/stow.texi  | 16 +++++++---------
 lib/Stow.pm.in |  6 +++---
 2 files changed, 10 insertions(+), 12 deletions(-)

diff --git a/doc/stow.texi b/doc/stow.texi
index 620f0a5..61ee4f9 100644
--- a/doc/stow.texi
+++ b/doc/stow.texi
@@ -739,20 +739,18 @@ software separately, or if there is any other reason to want two or more
 stow directories, it can be done by creating a file named @file{.stow}
 in each stow directory.  The presence of @file{/usr/local/foo/.stow}
 informs Stow that, though @file{foo} is not the current stow
-directory, and though it is a subdirectory of the target directory,
+directory, even if it is a subdirectory of the target directory,
 nevertheless it is @emph{a} stow directory and as such Stow
 doesn't ``own'' anything in it (@pxref{Installing Packages}).  This will
 protect the contents of @file{foo} from a @samp{stow -D}, for instance.
 
-XXX is this still true? XXX
-
-When multiple stow directories share a target tree, the effectiveness
-of Stow is reduced.  If a tree-folding symlink is encountered and
-needs to be split open during an installation, but the symlink points
-into the wrong stow directory, Stow will report a conflict rather
-than split open the tree (because it doesn't consider itself to own the
-symlink, and thus cannot remove it).
+@c There is a test for the following case in t/examples.t:
 
+When multiple stow directories share a target tree, if a tree-folding
+symlink is encountered and needs to be split open during an
+installation, as long as the top-level stow directory into which the
+existing symlink points contains @file{.stow}, Stow knows how to split
+open the tree in the correct manner.
 
 @c ===========================================================================
 @node Target Maintenance, Resource Files, Multiple Stow Directories, Top
diff --git a/lib/Stow.pm.in b/lib/Stow.pm.in
index bf4df60..3d8fa89 100755
--- a/lib/Stow.pm.in
+++ b/lib/Stow.pm.in
@@ -416,7 +416,7 @@ sub stow_node {
         }
         debug(3, "--- Evaluate existing link: $target => $existing_source");
 
-        # Does it point to a node under our stow directory?
+        # Does it point to a node under any stow directory?
         my ($existing_path, $existing_stow_path, $existing_package) =
             $self->find_stowed_path($target, $existing_source);
         if (not $existing_path) {
@@ -620,7 +620,7 @@ sub unstow_node_orig {
             error("Could not read link: $target");
         }
 
-        # Does it point to a node under our stow directory?
+        # Does it point to a node under any stow directory?
         my ($existing_path, $existing_stow_path, $existing_package) =
             $self->find_stowed_path($target, $existing_source);
         if (not $existing_path) {
@@ -755,7 +755,7 @@ sub unstow_node {
             return; # XXX #
         }
 
-        # Does it point to a node under our stow directory?
+        # Does it point to a node under any stow directory?
         my ($existing_path, $existing_stow_path, $existing_package) =
             $self->find_stowed_path($target, $existing_source);
         if (not $existing_path) {