Help: Organize and revise 3.19 release notes

Add section headers similar to the 3.18 release notes and move each
individual bullet into an appropriate section.  Revise a few bullets.

Help/release/3.19.rst

@@ -7,156 +7,184 @@ CMake 3.19 Release Notes
 
 Changes made since CMake 3.18 include the following.
 
-* The :command:`add_test` command now (officially) supports whitespace and
-  other special characters in the name for the test it creates.
-  See policy :policy:`CMP0110`.
+New Features
+============
 
-* The :prop_tgt:`OSX_ARCHITECTURES` target property is now respected for the
-  ``ASM`` language.
+Presets
+-------
 
-* The :command:`set_property`, :command:`get_property`,
-  and :command:`get_directory_property` commands' ``DIRECTORY``
-  options now accept references to binary directory paths,
-  such as the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
+* :manual:`cmake(1)` and :manual:`cmake-gui(1)` now recognize
+  ``CMakePresets.json`` and ``CMakeUserPresets.json`` files.
 
-* :ref:`Interface Libraries` may now have source files added via
-  :command:`add_library` or :command:`target_sources`.  Those
-  with sources will be generated as part of the build system.
+Generators
+----------
 
-* The :module:`CheckSourceCompiles` module has been added to
-  generalize :module:`CheckCSourceCompiles` and
-  :module:`CheckCXXSourceCompiles` to more languages.
+* The :generator:`Xcode` generator now uses the Xcode "new build system"
+  when generating for Xcode 12.0 or higher.
+  See the :variable:`CMAKE_XCODE_BUILD_SYSTEM` variable.
+  One may use ``-T buildsystem=1`` to switch to the legacy build system.
 
-* The :module:`CheckSourceRuns` module has been added to
-  generalize :module:`CheckCSourceRuns` and
-  :module:`CheckCXXSourceRuns` to more languages.
+* The :generator:`Xcode` generator gained support for linking libraries and
+  frameworks via the *Link Binaries With Libraries* build phase instead of
+  always by embedding linker flags directly.  This behavior is controlled by
+  a new :prop_tgt:`XCODE_LINK_BUILD_PHASE_MODE` target property, which is
+  initialized by a new :variable:`CMAKE_XCODE_LINK_BUILD_PHASE_MODE`
+  variable.
 
-* The :module:`CheckCompilerFlag` module has been added to
-  generalize :module:`CheckCCompilerFlag` and
-  :module:`CheckCXXCompilerFlag` to more languages.
+* The :ref:`Visual Studio Generators` for VS 2015 and above gained support
+  for the Visual Studio Tools for Android.  One may now set
+  :variable:`CMAKE_SYSTEM_NAME` to ``Android`` to generate ``.vcxproj`` files
+  for the Android tools.
 
-* A :variable:`CMAKE_CLANG_VFS_OVERLAY` variable was added to tell
-  Clang to use a VFS overlay to support the Windows SDK when
-  cross-compiling from hosts with case-sensitive filesystems.
+Languages
+---------
+
+* CMake learned to support ``ISPC`` as a first-class language that can be
+  enabled via the :command:`project` and :command:`enable_language` commands.
+  ``ISPC`` is currently supported by the :ref:`Makefile Generators`
+  and the :generator:`Ninja` generator on Linux, macOS, and Windows
+  using the Intel ISPC compiler.
+
+* ``CUDA`` language support for Clang now includes:
+
+  - separable compilation (:prop_tgt:`CUDA_SEPARABLE_COMPILATION`), and
+  - finding scattered toolkit installations when cross-compiling.
+
+File-Based API
+--------------
+
+* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field has
+  been updated to 2.2.
+
+* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object
+  gained a new ``languageStandard`` field in the ``compileGroups`` objects.
 
-* The ``Clang`` compiler gained support for handling system include directories
-  when running on Windows.
+Command-Line
+------------
 
-* The :manual:`cmake(1)` gained a ``-E create_hardlink`` command-line tool
+* The :manual:`cmake(1)` command-line tool's ``--install`` mode gained a
+  ``--default-directory-permissions`` option.
+
+* :manual:`cmake(1)` gained a ``-E create_hardlink`` command-line tool
   that can be used to create hardlinks between files.
 
-* The :manual:`CMake GUI <cmake-gui(1)>` now has an environment variable editor.
+GUI
+---
+
+* The :manual:`CMake GUI <cmake-gui(1)>` now has an environment variable
+  editor.
+
+Commands
+--------
+
+* The :command:`add_test` command now (officially) supports whitespace and
+  other special characters in the name for the test it creates.
+  See policy :policy:`CMP0110`.
 
 * The :command:`cmake_language` command gained a ``DEFER`` mode to
   schedule command calls to occur at the end of processing a directory.
 
-* :module:`CMakePackageConfigHelpers` module learned to manage version range.
-
 * The :command:`cmake_path` command was added for operations on
   filesystem paths.
 
-* :manual:`cmake(1)` and :manual:`cmake-gui(1)` now recognize
-  ``CMakePresets.json`` and ``CMakeUserPresets.json`` files.
-
-* The :variable:`CMAKE_<LANG>_COMPILER` variable may now be used to
-  store "mandatory" compiler flags like the :envvar:`CC` and other environment variables.
-
-* The :variable:`CMAKE_<LANG>_FLAGS_INIT` variable will now be considered during
-  the compiler indentification check if other sources like :variable:`CMAKE_<LANG>_FLAGS`
-  or :envvar:`CFLAGS` are not set.
-
 * The :command:`configure_file` command gained a ``NO_SOURCE_PERMISSIONS``
   option to suppress copying the input file's permissions to the output file.
 
-* :cpack_gen:`CPack External Generator` learned the :variable:`CPACK_EXTERNAL_BUILT_PACKAGES` variable.
+* The :command:`execute_process` command gained a ``COMMAND_ERROR_IS_FATAL``
+  option to specify a fatal error.
 
-* CPack learned the :variable:`CPACK_PRE_BUILD_SCRIPTS`, :variable:`CPACK_POST_BUILD_SCRIPTS`,
-  and :variable:`CPACK_PACKAGE_FILES` variables.
+* The :command:`file(ARCHIVE_CREATE)` command gained a ``COMPRESSION_LEVEL``
+  option to specify the compression level.
 
-* The :cpack_gen:`CPack WIX Generator` gained a
-  :variable:`CPACK_WIX_CUSTOM_XMLNS` option to specify custom XML namespaces.
+* The :command:`file(CHMOD)` and :command:`file(CHMOD_RECURSE)` subcommands
+  were added to set permissions of files and directories.
 
-* :manual:`ctest(1)` gained support for cuda-memcheck as ``CTEST_MEMORYCHECK_COMMAND``.
-  The different tools (memcheck, racecheck, synccheck, initcheck) supplied by
-  cuda-memcheck can be selected by setting the appropriate flags using the
-  ``CTEST_MEMORYCHECK_COMMAND_OPTIONS`` variable.
-  The default flags are `--tool memcheck --leak-check full`.
+* The :command:`file(DOWNLOAD)` command ``<file>`` argument is now
+  optional.  If it is not specified, the file is not saved.
 
-* The :module:`CheckCompilerFlag` module was extended to
-  support 'CUDA'.
+* The :command:`file(GENERATE)` command gained a new ``TARGET`` keyword to
+  support resolving target-dependent generator expressions.
 
-* The :module:`CheckSourceCompiles` module was extended to
-  support 'CUDA'.
+* The :command:`file` gained sub-command `REAL_PATH` to compute a path with
+  symlinks resolved.
 
-* The :module:`CheckSourceRuns` module was extended to
-  support 'CUDA'.
+* The :command:`find_package` command learned to handle a version range.
 
-* The :module:`CheckLinkerFlag` module has been extended to
-  support the validity of CUDA link flags.
+* The :command:`separate_arguments` command gained new ``PROGRAM`` option to
+  search program.
 
-* :prop_tgt:`CUDA_SEPARABLE_COMPILATION` is now supported when using Clang.
+* The :command:`set_property`, :command:`get_property`,
+  and :command:`get_directory_property` commands' ``DIRECTORY``
+  options now accept references to binary directory paths,
+  such as the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
 
-* If ``CUDA`` compiler detection fails with user-specified
-  :variable:`CMAKE_CUDA_ARCHITECTURES` or :variable:`CMAKE_CUDA_HOST_COMPILER`
-  an error is raised.
+* The :command:`string` command gained set of new ``JSON`` sub commands
+  to provide JSON parsing capabilities.
 
-* Compiler ABI detection now handles NVCC-style ``-Werror`` flags.
+Variables
+---------
 
-* Scattered toolkit installations are now recognized when crosscompiling
-  ``CUDA`` using Clang.
-* :module:`FindCUDAToolkit` now finds scattered toolkit installations when
-  crosscompiling.
+* The :variable:`CMAKE_CLANG_VFS_OVERLAY` variable was added to tell
+  Clang to use a VFS overlay to support the Windows SDK when
+  cross-compiling from hosts with case-sensitive filesystems.
 
-* :ref:`Makefile Generators` no longer repeat custom commands from target
-  dependencies.  See policy :policy:`CMP0113`.
+* The :variable:`CMAKE_MFC_FLAG` variable now supports generator expressions.
 
-* An explicit deprecation diagnostic was added for policy ``CMP0071``
-  (``CMP0071`` and below were already deprecated).
-  The :manual:`cmake-policies(7)` manual explains that the OLD behaviors
-  of all policies are deprecated and that projects should port to the
-  NEW behaviors.
+* The :variable:`CMAKE_OPTIMIZE_DEPENDENCIES` variable was added to
+  initialize the new :prop_tgt:`OPTIMIZE_DEPENDENCIES` target property and
+  avoid unnecessarily building dependencies for a static library.
 
-* Compatibility with versions of CMake older than 2.8.12 is now deprecated
-  and will be removed from a future version.  Calls to
-  :command:`cmake_minimum_required` or :command:`cmake_policy` that set
-  the policy version to an older value now issue a deprecation diagnostic.
+* The :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM` variable
+  was added to tell the :ref:`Visual Studio Generators` what maximum
+  version of the Windows SDK to choose.
+
+Properties
+----------
 
-* The :prop_tgt:`EXCLUDE_FROM_ALL` target property gained support for
+* The :prop_tgt:`EXCLUDE_FROM_ALL` target property now supports
   :manual:`generator expressions <cmake-generator-expressions(7)>`.
 
-* The :command:`execute_process` command gained a ``COMMAND_ERROR_IS_FATAL``
-  option to specify a fatal error.
+* The :prop_tgt:`OPTIMIZE_DEPENDENCIES` target property was added to
+  avoid unnecessarily building dependencies for a static library.
 
-* The :module:`ExternalProject` module handling of step target dependencies
-  has been revised.  See policy :policy:`CMP0114`.
+* The :prop_tgt:`PCH_INSTANTIATE_TEMPLATES` target property was added to enable
+  template instantiation in the precompiled header. This is enabled by default
+  and offers a roughly 20% compile time improvement. Currently only supported
+  by Clang 11.
 
-* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field has
-  been updated to 2.2.
-* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object gained
-  a new ``languageStandard`` field in the ``compileGroups`` objects.
+* The :prop_tgt:`WIN32_EXECUTABLE` target property now supports
+  :manual:`generator expressions <cmake-generator-expressions(7)>`.
 
-* The :command:`file(ARCHIVE_CREATE)` command gained a ``COMPRESSION_LEVEL``
-  option to specify the compression level.
+Modules
+-------
 
-* Add :command:`file(CHMOD)` and :command:`file(CHMOD_RECURSE)` to
-  set permissions of files and directories.
+* The :module:`CheckCompilerFlag` module has been added to
+  generalize :module:`CheckCCompilerFlag` and
+  :module:`CheckCXXCompilerFlag` to more languages.
+  It also supports the ``CUDA`` and ``ISPC`` languages.
 
-* The ``<file>`` argument is now optional for :command:`file(DOWNLOAD)`. If it
-  is not specified, the file is not saved.
+* The :module:`CheckLinkerFlag` module now supports the ``CUDA`` language.
 
-* The :command:`file(GENERATE)` command gained a new ``TARGET`` keyword to
-  support resolving target-dependent generator expressions.
+* The :module:`CheckSourceCompiles` module has been added to
+  generalize :module:`CheckCSourceCompiles` and
+  :module:`CheckCXXSourceCompiles` to more languages.
+  It also supports the ``CUDA`` and ``ISPC`` languages.
 
-* The :command:`file` gained sub-command `REAL_PATH` to compute a path with
-  symlinks resolved.
+* The :module:`CheckSourceRuns` module has been added to
+  generalize :module:`CheckCSourceRuns` and
+  :module:`CheckCXXSourceRuns` to more languages.
+  It also supports the ``CUDA`` language.
 
-* The :module:`FindCUDAToolkit` module gained support for finding CUDA toolkits
-  that do not contain ``nvcc``.
+* :module:`CMakePackageConfigHelpers` module learned to manage version range.
 
-* The :command:`find_package` command learned to handle a version range.
+* The :module:`FindCUDAToolkit` module gained support for finding CUDA
+  toolkits that do not contain ``nvcc``, as well as for finding scattered
+  toolkit installations when cross-compiling.
 
-* The :command:`find_program` command now requires permission to execute
-  but not to read the file found.  See policy :policy:`CMP0109`.
+* The :module:`FindPackageHandleStandardArgs` module learned to handle
+  version range. It also gained the ``find_package_check_version()`` command to
+  check the validity of a version against version-related arguments of
+  :command:`find_package` command.
 
 * The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
   modules gained the capability to manage a version range.
@@ -175,113 +203,119 @@ Changes made since CMake 3.18 include the following.
 * The :module:`FindTIFF` module gained a ``CXX`` component to
   find the ``tiffxx`` library containing C++ bindings.
 
-* The :module:`FindVulkan` module gained a new output variable
-  ``Vulkan_GLSLC_EXECUTABLE`` which contains the path to the
-  GLSL SPIR-V compiler.
+* The :module:`FindVulkan` module now provides a ``Vulkan::glslc`` imported
+  target and associated ``Vulkan_GLSLC_EXECUTABLE`` variable which contain
+  the path to the GLSL SPIR-V compiler.
 
-* The :module:`FindVulkan` module gained a new target
-  ``Vulkan::glslc`` which contains the path to the
-  GLSL SPIR-V compiler.
+* :module:`UseSWIG` module gains new source file properties ``OUTPUT_DIR`` and
+  ``OUTFILE_DIR`` to manage output directories on per source basis.
 
-* The :module:`FindPackageHandleStandardArgs` module learned to handle
-  version range. It also gained the ``find_package_check_version()`` command to
-  check the validity of a version against version-related arguments of
-  :command:`find_package` command.
+CTest
+-----
 
-* The :variable:`CMAKE_MFC_FLAG` variable now supports generator expressions.
+* :manual:`ctest(1)` now supports ``compute-sanitizer`` (``cuda-memcheck``) as
+  ``CTEST_MEMORYCHECK_COMMAND``.  The different tools (memcheck, racecheck,
+  synccheck, initcheck) supplied by ``compute-sanitizer`` can be selected by
+  adding appropriate flags to the ``CTEST_MEMORYCHECK_COMMAND_OPTIONS``
+  variable.  The default flags are ``--tool memcheck --leak-check full``.
 
-* A new guide on :guide:`IDE integration <IDE Integration Guide>` has been added.
+CPack
+-----
 
-* An imported target with a missing location now fails during generation if the
-  location is used.  See policy :policy:`CMP0111`.
+* CPack gained the :variable:`CPACK_PRE_BUILD_SCRIPTS`,
+  :variable:`CPACK_POST_BUILD_SCRIPTS`, and :variable:`CPACK_PACKAGE_FILES`
+  variables.
 
-* The ``--install`` argument of the :manual:`cmake(1)` command line tool gained a
-  ``--default-directory-permissions`` argument.
+* The :cpack_gen:`CPack External Generator` gained the
+  :variable:`CPACK_EXTERNAL_BUILT_PACKAGES` variable.
 
-* The :module:`CheckCompilerFlag` module was extended to
-  support 'ISPC'.
+* The :cpack_gen:`CPack WIX Generator` gained a
+  :variable:`CPACK_WIX_CUSTOM_XMLNS` option to specify custom XML namespaces.
 
-* The :module:`CheckSourceCompiles` module was extended to
-  support 'ISPC'.
+Other
+-----
 
+* :ref:`Interface Libraries` may now have source files added via
+  :command:`add_library` or :command:`target_sources`.  Those
+  with sources will be generated as part of the build system.
 
-* CMake learned to support ``ISPC`` as a first-class language that can be
-  enabled via the :command:`project` and :command:`enable_language` commands.
+Deprecated and Removed Features
+===============================
 
-* ``ISPC`` is currently supported by the :ref:`Makefile Generators`
-  and the :generator:`Ninja` generator on Linux, macOS, and Windows.
+* Compatibility with versions of CMake older than 2.8.12 is now deprecated
+  and will be removed from a future version.  Calls to
+  :command:`cmake_minimum_required` or :command:`cmake_policy` that set
+  the policy version to an older value now issue a deprecation diagnostic.
 
-* The Intel ISPC compiler (``ispc``) is supported.
+* An explicit deprecation diagnostic was added for policy ``CMP0071``
+  (``CMP0071`` and below were already deprecated).
+  The :manual:`cmake-policies(7)` manual explains that the OLD behaviors
+  of all policies are deprecated and that projects should port to the
+  NEW behaviors.
 
-* Building for macOS will now use the latest SDK available on the system,
-  unless the user has explicitly chosen a SDK using :variable:`CMAKE_OSX_SYSROOT`.
+* macOS SDKs older than 10.5 are no longer supported.
 
-  The deployment target or system macOS version will not affect
-  the choice of SDK.
+* :manual:`cmake-gui(1)` now requires Qt5.
+  Support for compiling with Qt4 has been removed.
 
-* macOS SDKs older than 10.5 are no longer supported.
+* The :manual:`cmake(1)` command-line option ``--warn-unused-vars`` has
+  been removed and is now silently ignored.  The option has not worked
+  correctly since CMake 3.3.
 
-* A new target property, :prop_tgt:`OPTIMIZE_DEPENDENCIES`, was added to
-  avoid unnecessarily building dependencies for a static library.
-* A new variable, :variable:`CMAKE_OPTIMIZE_DEPENDENCIES`, was added to
-  initialize the :prop_tgt:`OPTIMIZE_DEPENDENCIES` target property.
+Documentation
+=============
 
-* The :prop_tgt:`PCH_INSTANTIATE_TEMPLATES` target property was added to enable
-  template instantiation in the precompiled header. This is enabled by default
-  and offers a roughly 20% compile time improvement. Currently only supported
-  by Clang 11.
+The following guides have been added:
 
-* The following target-based generator expressions that query for directory or
-  file name components no longer add a dependency on the evaluated target.
-  See policy :policy:`CMP0112`.
+* :guide:`IDE Integration Guide`
+* :guide:`Importing and Exporting Guide`
 
-    - ``TARGET_FILE_DIR``
-    - ``TARGET_LINKER_FILE_BASE_NAME``
-    - ``TARGET_LINKER_FILE_NAME``
-    - ``TARGET_LINKER_FILE_DIR``
-    - ``TARGET_SONAME_FILE_NAME``
-    - ``TARGET_SONAME_FILE_DIR``
-    - ``TARGET_PDB_FILE_NAME``
-    - ``TARGET_PDB_FILE_DIR``
-    - ``TARGET_BUNDLE_DIR``
-    - ``TARGET_BUNDLE_CONTENT_DIR``
+Other Changes
+=============
 
-* :manual:`cmake-gui(1)` now requires Qt5. Support for compiling with Qt4 has
-  been removed.
+* Building for macOS will now use the latest SDK available on the system,
+  unless the user has explicitly chosen a SDK using
+  :variable:`CMAKE_OSX_SYSROOT`.  The deployment target or system macOS
+  version will not affect the choice of SDK.
 
-* The :manual:`cmake(1)` command-line option ``--warn-unused-vars`` has
-  been removed and is now silently ignored.  The option has not worked
-  correctly since CMake 3.3.
+* The :variable:`CMAKE_<LANG>_COMPILER` variable may now be used to
+  store "mandatory" compiler flags like the :envvar:`CC` and other environment
+  variables.
 
-* The :command:`separate_arguments` command gained new ``PROGRAM`` option to
-  search program.
+* The :variable:`CMAKE_<LANG>_FLAGS_INIT` variable will now be considered
+  during the compiler identification check if other sources like
+  :variable:`CMAKE_<LANG>_FLAGS` or :envvar:`CFLAGS` are not set.
 
-* The :command:`string` command gained set of new ``JSON`` sub commands to provide JSON
-  parsing capabilities.
+* The :command:`find_program` command now requires permission to execute
+  but not to read the file found.  See policy :policy:`CMP0109`.
 
-* :module:`UseSWIG` module gains new source file properties ``OUTPUT_DIR`` and
-  ``OUTFILE_DIR`` to manage output directories on per source basis.
+* An imported target with a missing location now fails during generation
+  if the location is used.  See policy :policy:`CMP0111`.
 
-* The :ref:`Visual Studio Generators` for Visual Studio 2015 and above gained
-  support for the Visual Studio Tools for Android. This allows you to set
-  :variable:`CMAKE_SYSTEM_NAME` to `Android` to generate `.vcxproj` files for
-  the Android tools.
+* The following target-based generator expressions that query for directory or
+  file name components no longer add a dependency on the evaluated target.
+  See policy :policy:`CMP0112`.
 
-* A :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM` variable
-  was added to tell the :ref:`Visual Studio Generators` what maximumm
-  version of the Windows SDK to choose.
+  - ``TARGET_FILE_DIR``
+  - ``TARGET_LINKER_FILE_BASE_NAME``
+  - ``TARGET_LINKER_FILE_NAME``
+  - ``TARGET_LINKER_FILE_DIR``
+  - ``TARGET_SONAME_FILE_NAME``
+  - ``TARGET_SONAME_FILE_DIR``
+  - ``TARGET_PDB_FILE_NAME``
+  - ``TARGET_PDB_FILE_DIR``
+  - ``TARGET_BUNDLE_DIR``
+  - ``TARGET_BUNDLE_CONTENT_DIR``
 
-* The :prop_tgt:`WIN32_EXECUTABLE` target property now supports
-  :manual:`generator expressions <cmake-generator-expressions(7)>`.
+* :ref:`Makefile Generators` no longer repeat custom commands from target
+  dependencies.  See policy :policy:`CMP0113`.
 
-* The :generator:`Xcode` generator now uses the Xcode "new build system"
-  when generating for Xcode 12.0 or higher.
-  See the :variable:`CMAKE_XCODE_BUILD_SYSTEM` variable.
-  One may use ``-T buildsystem=1`` to switch to the legacy build system.
+* The :module:`ExternalProject` module handling of step target dependencies
+  has been revised.  See policy :policy:`CMP0114`.
 
-* The Xcode generator gained support for linking libraries and frameworks
-  via the *Link Binaries With Libraries* build phase instead of always by
-  embedding linker flags directly.  This behavior is controlled by a new
-  :prop_tgt:`XCODE_LINK_BUILD_PHASE_MODE` target property, which is
-  initialized by a new :variable:`CMAKE_XCODE_LINK_BUILD_PHASE_MODE`
-  variable.
+* The :prop_tgt:`OSX_ARCHITECTURES` target property is now respected
+  for the ``ASM`` language.
+
+* If ``CUDA`` compiler detection fails with user-specified
+  :variable:`CMAKE_CUDA_ARCHITECTURES` or
+  :variable:`CMAKE_CUDA_HOST_COMPILER`, an error is raised.