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.

4 files changed, 65 insertions, 26 deletions

diff --git a/Help/prop_tgt/MACHO_COMPATIBILITY_VERSION.rst b/Help/prop_tgt/MACHO_COMPATIBILITY_VERSION.rst
index f3fedbabe8..26d5cc86c9 100644
--- a/Help/prop_tgt/MACHO_COMPATIBILITY_VERSION.rst
+++ b/Help/prop_tgt/MACHO_COMPATIBILITY_VERSION.rst
@@ -4,11 +4,22 @@ MACHO_COMPATIBILITY_VERSION
 What compatibility version number is this target for Mach-O binaries.
 
 For shared libraries on Mach-O systems (e.g. macOS, iOS)
-the ``MACHO_COMPATIBILITY_VERSION`` property correspond to
-``compatibility version`` and :prop_tgt:`MACHO_CURRENT_VERSION` to
-``current 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.  If ``MACHO_COMPATIBILITY_VERSION`` is not set, the value of
-the :prop_tgt:`SOVERSION` property will be used.
+the ``MACHO_COMPATIBILITY_VERSION`` property corresponds to the
+*compatibility version* and :prop_tgt:`MACHO_CURRENT_VERSION` corresponds to
+the *current version*.  These are both embedded in the shared library binary
+and can be checked with the ``otool -L <binary>`` command.
+
+It should be noted that the :prop_tgt:`MACHO_CURRENT_VERSION` and
+``MACHO_COMPATIBILITY_VERSION`` properties do not affect the file
+names or version-related symlinks that CMake generates for the library.
+The :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` target properties still
+control the file and symlink names.  The ``install_name`` is also still
+controlled by :prop_tgt:`SOVERSION`.
+
+When :prop_tgt:`MACHO_CURRENT_VERSION` and ``MACHO_COMPATIBILITY_VERSION``
+are not given, :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` are used for
+the version details to be embedded in the binaries respectively.
+The :prop_tgt:`MACHO_CURRENT_VERSION` and ``MACHO_COMPATIBILITY_VERSION``
+properties only need to be given if the project needs to decouple the file
+and symlink naming from the version details embedded in the binaries
+(e.g. to match libtool conventions).
diff --git a/Help/prop_tgt/MACHO_CURRENT_VERSION.rst b/Help/prop_tgt/MACHO_CURRENT_VERSION.rst
index 4a1d3f0638..9afb356995 100644
--- a/Help/prop_tgt/MACHO_CURRENT_VERSION.rst
+++ b/Help/prop_tgt/MACHO_CURRENT_VERSION.rst
@@ -4,10 +4,22 @@ MACHO_CURRENT_VERSION
 What current version number is this target for Mach-O binaries.
 
 For shared libraries on Mach-O systems (e.g. macOS, iOS)
-the :prop_tgt:`MACHO_COMPATIBILITY_VERSION` property correspond to
-``compatibility version`` and ``MACHO_CURRENT_VERSION`` to ``current version``.
-See the :prop_tgt:`FRAMEWORK` target property for an example.
+the :prop_tgt:`MACHO_COMPATIBILITY_VERSION` property corresponds to the
+*compatibility version* and ``MACHO_CURRENT_VERSION`` corresponds to the
+*current version*.  These are both embedded in the shared library binary
+and can be checked with the ``otool -L <binary>`` command.
 
-Versions of Mach-O binaries may be checked with the ``otool -L <binary>``
-command.  If ``MACHO_CURRENT_VERSION`` is not set, the value of
-the :prop_tgt:`VERSION` property will be used.
+It should be noted that the ``MACHO_CURRENT_VERSION`` and
+:prop_tgt:`MACHO_COMPATIBILITY_VERSION` properties do not affect the file
+names or version-related symlinks that CMake generates for the library.
+The :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` target properties still
+control the file and symlink names.  The ``install_name`` is also still
+controlled by :prop_tgt:`SOVERSION`.
+
+When ``MACHO_CURRENT_VERSION`` and :prop_tgt:`MACHO_COMPATIBILITY_VERSION`
+are not given, :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` are used for
+the version details to be embedded in the binaries respectively.
+The ``MACHO_CURRENT_VERSION`` and :prop_tgt:`MACHO_COMPATIBILITY_VERSION`
+properties only need to be given if the project needs to decouple the file
+and symlink naming from the version details embedded in the binaries
+(e.g. to match libtool conventions).
diff --git a/Help/prop_tgt/SOVERSION.rst b/Help/prop_tgt/SOVERSION.rst
index d6f8a941f7..b377f22288 100644
--- a/Help/prop_tgt/SOVERSION.rst
+++ b/Help/prop_tgt/SOVERSION.rst
@@ -21,9 +21,17 @@ Mach-O Versions
 ^^^^^^^^^^^^^^^
 
 For shared libraries and executables on Mach-O systems (e.g. macOS, iOS),
-the ``SOVERSION`` property is a fallback to
-:prop_tgt:`MACHO_COMPATIBILITY_VERSION` property which corresponds to
-*compatiblity version* and :prop_tgt:`VERSION` is a fallback to
-:prop_tgt:`MACHO_CURRENT_VERSION` which corresponds to *current 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 ``SOVERSION`` property corresponds to the *compatibility version* and
+:prop_tgt:`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 ``SOVERSION`` will still be used to form the ``install_name``
+and both ``SOVERSION`` and :prop_tgt:`VERSION` may also affect the file
+and symlink names.
+
+Versions of Mach-O binaries may be checked with the ``otool -L <binary>``
+command.
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.