From 3d413edd0fca1aba4ff109d99d96702d828313b2 Mon Sep 17 00:00:00 2001
From: Gintas Grigelionis <gintas@apache.org>
Date: Fri, 8 Jun 2018 20:17:29 +0200
Subject: [PATCH] Bz 22370: document the semantics of followsymlinks

---
 manual/Types/fileset.html   | 17 ++++++++++++++---
 manual/Types/selectors.html | 17 ++++++++++-------
 2 files changed, 24 insertions(+), 10 deletions(-)

diff --git a/manual/Types/fileset.html b/manual/Types/fileset.html
index 89fb14561..8c4ab55d0 100644
--- a/manual/Types/fileset.html
+++ b/manual/Types/fileset.html
@@ -33,7 +33,7 @@ addition, FileSet holds an implicit PatternSet and supports the
 nested <code>&lt;include&gt;</code>, <code>&lt;includesfile&gt;</code>, <code>&lt;exclude&gt;</code>
 and <code>&lt;excludesfile&gt;</code> elements of PatternSet directly, as well as PatternSet's
 attributes.</p>
-<p>Selectors are available as nested elements within the FileSet.  If any of the selectors
+<p>Selectors are available as nested elements within the FileSet. If any of the selectors
 within the FileSet do not select the file, the file is not considered part of the FileSet. This
 makes a FileSet equivalent to an <code>&lt;and&gt;</code> selector container.</p>
 <table class="attr">
@@ -93,7 +93,7 @@ makes a FileSet equivalent to an <code>&lt;and&gt;</code> selector container.</p
   <tr>
     <td>erroronmissingdir</td>
     <td>
-      Specify what happens if the base directory does not exist.  If <q>true</q> a build error
+      Specify what happens if the base directory does not exist. If <q>true</q> a build error
       will happen, if <q>false</q>, the fileset will be ignored/empty.
       <em>Since Apache Ant 1.7.1</em>
     </td>
@@ -102,9 +102,20 @@ makes a FileSet equivalent to an <code>&lt;and&gt;</code> selector container.</p
 </table>
 
 <p id="symlink"><strong>Note</strong>: All files/directories for which the canonical path is
-different from its path are considered symbolic links.  On Unix systems this usually means the
+different from its path are considered symbolic links. On Unix systems this usually means the
 file really is a symbolic link but it may lead to false results on other platforms.</p>
 
+<p>Ant is restricted to features that JRE considers portable, and symbolic links is one such feature
+that was long considered non-portable. That has changed with Java 7 and NIO.2, yet full support for
+symbolic links is still lacking (notably, in Zip files). Full support of symbolic links in Ant would
+require a different implementation of FileSet and revision of all tasks and/or types that derive
+from it. Currently, the semantics of <var>followsymlinks</var> in FileSet is such that <q>false</q>
+excludes symbolic links completely, and <q>true</q> allows symbolic links to be considered by
+selectors, which may have their own <var>followsymlinks</var> attributes with proper semantics;
+i.e., <q>false</q> allows selector to inspect properties of a symbolic link itself, and <q>true</q>
+those of its target.
+</p>
+
 <h4>Examples</h4>
 <pre>
 &lt;fileset dir=&quot;${server.src}&quot; casesensitive=&quot;yes&quot;&gt;
diff --git a/manual/Types/selectors.html b/manual/Types/selectors.html
index ef756a9a6..ca2213a71 100644
--- a/manual/Types/selectors.html
+++ b/manual/Types/selectors.html
@@ -925,11 +925,12 @@
         <td>Username of the expected owner</td>
         <td>Yes</td>
       </tr>
-        <tr>
-          <td>followsymlinks</td>
-          <td>Must the selector follow symbolic links?</td>
-          <td>No; defaults to <q>true</q></td>
-        </tr>
+      <tr>
+        <td>followsymlinks</td>
+        <td>Must the selector follow symbolic links? (see also how the attribute interacts with the
+          corresponding attribute of the <a href="fileset.html#symlink">FileSet</a>)</td>
+        <td>No; defaults to <q>true</q></td>
+      </tr>
     </table>
 
     <h4 id="posixGroup">PosixGroup Selector</h4>
@@ -954,7 +955,8 @@
       </tr>
       <tr>
         <td>followsymlinks</td>
-        <td>Must the selector follow symbolic links?</td>
+        <td>Must the selector follow symbolic links? (see also how the attribute interacts with the
+          corresponding attribute of the <a href="fileset.html#symlink">FileSet</a>)</td>
         <td>No; defaults to <q>true</q></td>
       </tr>
     </table>
@@ -981,7 +983,8 @@
       </tr>
       <tr>
         <td>followsymlinks</td>
-        <td>Must the selector follow symbolic links?</td>
+        <td>Must the selector follow symbolic links? (see also how the attribute interacts with
+          the corresponding attribute of the <a href="fileset.html#symlink">FileSet</a>)</td>
         <td>No; defaults to <q>true</q></td>
       </tr>
     </table>