Help: Clarify wording of dir-related source property options

1 files changed, 25 insertions, 16 deletions

diff --git a/Help/command/get_source_file_property.rst b/Help/command/get_source_file_property.rst
index 1060251..76ed776 100644
--- a/Help/command/get_source_file_property.rst
+++ b/Help/command/get_source_file_property.rst
@@ -5,24 +5,33 @@ Get a property for a source file.
 
 .. code-block:: cmake
 
-  get_source_file_property(VAR file [TARGET_DIRECTORY <target> | DIRECTORY <dir>] property)
+  get_source_file_property(<variable> <file>
+                           [DIRECTORY <dir> | TARGET_DIRECTORY <target>]
+                           <property>)
 
 Gets a property from a source file.  The value of the property is
-stored in the variable ``VAR``.  If the source property is not found, the
-behavior depends on whether it has been defined to be an ``INHERITED`` property
-or not (see :command:`define_property`).  Non-inherited properties will set
-``VAR`` to "NOTFOUND", whereas inherited properties will search the relevant
-parent scope as described for the :command:`define_property` command and
-if still unable to find the property, ``VAR`` will be set to an empty string.
-
-The queried source file scope can be changed by specifying one of the
-additional options: ``DIRECTORY`` or ``TARGET_DIRECTORY``.
-
-``DIRECTORY`` takes a path to a processed directory, and the source file property
-will be read from that directory scope.
-
-``TARGET_DIRECTORY`` takes the name of an existing target. The source file
-property will be read from this target's directory scope.
+stored in the specified ``<variable>``.  If the source property is not found,
+the behavior depends on whether it has been defined to be an ``INHERITED``
+property or not (see :command:`define_property`).  Non-inherited properties
+will set ``variable`` to ``NOTFOUND``, whereas inherited properties will search
+the relevant parent scope as described for the :command:`define_property`
+command and if still unable to find the property, ``variable`` will be set to
+an empty string.
+
+By default, the source file's property will be read from the current source
+directory's scope, but this can be overridden with one of the following
+sub-options:
+
+``DIRECTORY <dir>``
+  The source file property will be read from the ``<dir>`` directory's
+  scope.  CMake must already know about that source directory, either by
+  having added it through a call to :command:`add_subdirectory` or ``<dir>``
+  being the top level source directory.  Relative paths are treated as
+  relative to the current source directory.
+
+``TARGET_DIRECTORY <target>``
+  The source file property will be read from the directory scope in which
+  ``<target>`` was created (``<target>`` must therefore already exist).
 
 Use :command:`set_source_files_properties` to set property values.  Source
 file properties usually control how the file is built. One property that is