Help: Fix inaccuracies and omissions in MACHO_* property docs

The VERSION and SOVERSION properties are not true fallbacks for
the MACHO_* properties since the MACHO_* properties only affect
the embedded version information, but VERSION and SOVERSION
also affect other things.

1 files changed, 14 insertions, 6 deletions

diff --git a/Help/prop_tgt/VERSION.rst b/Help/prop_tgt/VERSION.rst
index f592f4a611..95db4837be 100644
--- a/Help/prop_tgt/VERSION.rst
+++ b/Help/prop_tgt/VERSION.rst
@@ -23,9 +23,17 @@ Mach-O Versions
 ^^^^^^^^^^^^^^^
 
 For shared libraries and executables on Mach-O systems (e.g. macOS, iOS),
-the ``VERSION`` property is a fallback to :prop_tgt:`MACHO_CURRENT_VERSION`
-property which corresponds to *current version* and :prop_tgt:`SOVERSION`
-is a fallback to :prop_tgt:`MACHO_COMPATIBILITY_VERSION` which corresponds
-to *compatiblity version*.  See the :prop_tgt:`FRAMEWORK` target
-property for an example.  Versions of Mach-O binaries may be checked with the
-``otool -L <binary>`` command.
+the :prop_tgt:`SOVERSION` property corresponds to the *compatibility version*
+and ``VERSION`` corresponds to the *current version* (unless Mach-O specific
+overrides are provided, as discussed below).
+See the :prop_tgt:`FRAMEWORK` target property for an example.
+
+For shared libraries, the :prop_tgt:`MACHO_COMPATIBILITY_VERSION` and
+:prop_tgt:`MACHO_CURRENT_VERSION` properties can be used to
+override the *compatibility version* and *current version* respectively.
+Note that :prop_tgt:`SOVERSION` will still be used to form the
+``install_name`` and both :prop_tgt:`SOVERSION` and ``VERSION`` may also
+affect the file and symlink names.
+
+Versions of Mach-O binaries may be checked with the ``otool -L <binary>``
+command.