Merge topic 'doc-cleanup-3.26-rc4'

b39b3e3bdb Help: Fix typos and grammar in 3.26 release notes
9f1360ae19 Help: Improve wording of FOLDER-related properties and policies

Acked-by: Kitware Robot <[email protected]>
Merge-request: !8264

Help/policy/CMP0143.rst

@@ -5,7 +5,7 @@ CMP0143
 
 :prop_gbl:`USE_FOLDERS` global property is treated as ``ON`` by default.
 
-When using CMake 3.25 and below, :prop_gbl:`USE_FOLDERS` is treated
+When using CMake 3.25 or earlier, :prop_gbl:`USE_FOLDERS` is treated
 as ``OFF`` by default unless projects enable the feature.  For example:
 
 .. code-block:: cmake
@@ -16,15 +16,15 @@ as ``OFF`` by default unless projects enable the feature.  For example:
 
 CMake 3.26 and later prefer to enable the feature by default.
 
+Note that it is the policy setting at the `end` of the top level
+``CMakeLists.txt`` file that matters.  The policy setting applies globally
+to the whole project.
+
 This policy provides compatibility with projects that have not been updated
 to expect enabling of folders.  Enabling folders causes projects to appear
-differently in IDEs.
-
-This policy was introduced in CMake version 3.26.  Use the
+differently in IDEs.  The policy was introduced in CMake version 3.26.  Use the
 :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
 Unlike many policies, CMake version |release| does *not* warn
 when this policy is not set and simply uses ``OLD`` behavior.
-The policy setting must be in scope at the end of the top-level
-``CMakeLists.txt`` file of the project and has global effect.
 
 .. include:: DEPRECATED.txt

Help/prop_gbl/USE_FOLDERS.rst

@@ -1,19 +1,17 @@
 USE_FOLDERS
 -----------
 
-Use the :prop_tgt:`FOLDER` target property to organize targets into
-folders.
+Controls whether to use the :prop_tgt:`FOLDER` target property to organize
+targets into folders.  The value of ``USE_FOLDERS`` at the end of the top level
+``CMakeLists.txt`` file is what determines the behavior.
 
 .. versionchanged:: 3.26
 
   CMake treats this property as ``ON`` by default.
   See policy :policy:`CMP0143`.
 
-CMake generators that are capable of organizing into a hierarchy of folders
-use the values of the :prop_tgt:`FOLDER` target property to name those
-folders. (i.e.: ``Visual Studio`` or ``XCode``)
-
-IDE's can also take advantage of this property to organize CMake targets.
-Regardless of generator support.
-
-See also the documentation for the :prop_tgt:`FOLDER` target property.
+Not all CMake generators support recording folder details for targets.
+The :generator:`Xcode` and :ref:`Visual Studio <Visual Studio Generators>`
+generators are examples of generators that do.  Similarly, not all IDEs
+support presenting targets using folder hierarchies, even if the CMake
+generator used provides the necessary information.

Help/prop_tgt/FOLDER.rst

@@ -1,16 +1,20 @@
 FOLDER
 ------
 
-Set the folder name. Use to organize targets in an IDE.
+For IDEs that present targets using a folder hierarchy, this property
+specifies the name of the folder to place the target under.
+To nest folders, use ``FOLDER`` values such as ``GUI/Dialogs`` with ``/``
+characters separating folder levels.  Targets with no ``FOLDER`` property
+will appear as top level entities.  Targets with the same ``FOLDER``
+property value will appear in the same folder as siblings.
 
-Targets with no ``FOLDER`` property will appear as top level entities in
-IDEs like Visual Studio.  Targets with the same ``FOLDER`` property value
-will appear next to each other in a folder of that name.  To nest
-folders, use ``FOLDER`` values such as 'GUI/Dialogs' with '/' characters
-separating folder levels.
+Only some CMake generators honor the ``FOLDER`` property
+(e.g. :generator:`Xcode` or any of the
+:ref:`Visual Studio <Visual Studio Generators>` generators).
+Those generators that don't will simply ignore it.
 
 This property is initialized by the value of the variable
 :variable:`CMAKE_FOLDER` if it is set when a target is created.
 
-The global property :prop_gbl:`USE_FOLDERS` must be set to ON, otherwise
+The global property :prop_gbl:`USE_FOLDERS` must be set to true, otherwise
 the ``FOLDER`` property is ignored.

Help/release/3.26.rst

@@ -87,7 +87,7 @@ Properties
   initialize this property.
 
 * The :prop_tgt:`XCODE_EMBED_EXTENSIONKIT_EXTENSIONS <XCODE_EMBED_<type>>`
-  target property was added to tell the :generator:`Xcode` generator to
+  target property was added to tell the :generator:`Xcode` generator to embed
   ExtensionKit-based extensions such as extensions using the Background
   Assets framework.  Aspects of the embedding can be customized with:
 
@@ -98,7 +98,7 @@ Properties
 Modules
 -------
 
-* The :module:`ExternalProject` module :command:`ExternalProject_Add` command
+* The :module:`ExternalProject` module's :command:`ExternalProject_Add` command
   gained an ``INSTALL_BYPRODUCTS`` option to specify files generated by the
   ``install`` step.
 
@@ -113,7 +113,7 @@ Modules
 * The :module:`FindPython3` and :module:`FindPython` modules gained
   support for the `Stable Application Binary Interface`_.
 
-* The :module:`UseSWIG` module gained the support for the ``perl5`` language.
+* The :module:`UseSWIG` module gained support for the ``perl5`` language.
 
 .. _`Stable Application Binary Interface`: https://docs.python.org/3/c-api/stable.html
 
@@ -135,11 +135,10 @@ Deprecated and Removed Features
 ===============================
 
 * The ``CMakeFiles/CMakeOutput.log`` and ``CMakeFiles/CMakeError.log``
-  files are no longer populated by CMake's builtin modules, and
+  files are no longer populated by CMake's built-in modules.
   :manual:`cmake(1)` no longer suggests looking at them after a
   ``CMake Error`` occurs.  Information previously logged to those
-  files is instead logged to ``CMakeFiles/CMakeConfigureLog.yaml``,
-  the :manual:`cmake-configure-log(7)`.
+  files is instead logged to the :manual:`cmake-configure-log(7)`.
 
 * On CYGWIN, the undocumented ``CMAKE_LEGACY_CYGWIN_WIN32`` mode for
   compatibility with CMake versions older than 2.8.4 has been removed.