Help: Organize and revise 3.3 release notes

Add section headers similar to the 3.2 release notes and move each
individual bullet into an appropriate section.  Revise and consolidate
some bullets covering related areas.

Help/release/3.3.rst

@@ -7,14 +7,20 @@ CMake 3.3 Release Notes
 
 Changes made since CMake 3.2 include the following.
 
-* The :module:`CheckFortranCompilerFlag` module was introduced
-  to check ``Fortran`` compiler flags, much like the
-  :module:`CheckCCompilerFlag` module already does for ``C``.
+New Features
+============
 
-* The :command:`add_dependencies` command learned to allow dependencies
-  to be added to :ref:`interface libraries <Interface Libraries>`.
-  Dependencies added to an interface library are followed transitively
-  in its place since the target itself does not build.
+Generators
+----------
+
+* The :ref:`Makefile Generators` now add ``.DELETE_ON_ERROR`` to the
+  makefiles that contain the actual build rules for files on disk.
+  This tells GNU make to remove rule outputs when their recipe
+  modifies an output but fails.
+
+* The :ref:`Visual Studio Generators` learned to support ``.xaml``
+  source files and automatically associate them with corresponding
+  ``.h`` and ``.cpp`` sources.
 
 * A new experimental :generator:`Green Hills MULTI` generator was
   added on Windows.  `Green Hills MULTI`_ is an IDE for embedded
@@ -22,65 +28,76 @@ Changes made since CMake 3.2 include the following.
 
 .. _`Green Hills MULTI`: http://www.ghs.com/products/MULTI_IDE.html
 
-* On OS X the :manual:`cmake-gui(1)` no longer has the
-  ``Install For Command Line Use`` menu item.  Instead there
-  is a ``How to Install For Command Line Use`` menu item
-  that shows an informational dialog box explaining how to
-  make the command line tools available.  For example::
+Commands
+--------
 
-    /Applications/CMake.app/Contents/bin/cmake-gui --install
+* The :command:`add_dependencies` command learned to allow dependencies
+  to be added to :ref:`interface libraries <Interface Libraries>`.
+  Dependencies added to an interface library are followed transitively
+  in its place since the target itself does not build.
 
-* The version of some Fortran compilers is now detected and stored in the
-  :variable:`CMAKE_Fortran_COMPILER_VERSION <CMAKE_<LANG>_COMPILER_VERSION>`
-  variable.
+* The :command:`execute_process` command learned to support specifying
+  the same file for ``OUTPUT_FILE`` and ``ERROR_FILE``.
 
-* The :module:`CPackDeb` module learned a new
-  :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS`
-  variable to specify per-component use of ``dpkg-shlibdeps``.
+* The :command:`file(GLOB)` and :command:`file(GLOB_RECURSE)` commands
+  learned a new ``LIST_DIRECTORIES <bool>`` option to specify whether
+  the glob result should include directories.
 
-* The :module:`CPackDeb` module learned a new
-  :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS`
-  option to specify per-component dependencies.
+* The :command:`find_library`, :command:`find_path`, and :command:`find_file`
+  commands now search in installation prefixes derived from the ``PATH``
+  environment variable.
 
-* The :manual:`cpack(1)` ``IFW`` generator and the :module:`CPackIFW`
-  module learned to support Qt Framework Installer 2.0 tools.
+* The :command:`if` command learned a new ``IN_LIST`` operator that
+  evaluates to true if a given element is contained in a named list.
 
-* The :module:`CPackRPM` module learned to package symbolic links
-  more cleanly and now supports directory symlinks with recent
-  ``rpmbuild`` versions.
+* The :command:`install(EXPORT)` and :command:`export()` commands
+  learned to export targets that populate the :prop_tgt:`INTERFACE_SOURCES`
+  target property.
 
-* The :module:`CPackRPM` module learned a new
-  :variable:`CPACK_RPM_ADDITIONAL_MAN_DIRS` variable to specify
-  directories containing man pages for the brp-compress RPM macro.
+* The :command:`install(TARGETS)` command learned to support
+  generator expressions in the ``DESTINATION`` value.
 
-* The :command:`ctest_build` and :command:`build_command` commands
-  no longer tell ``make`` tools to ignore errors with the ``-i`` option.
-  Previously this was done for :ref:`Makefile Generators` but not others.
-  See policy :policy:`CMP0061`.
+Variables
+---------
 
-* The :manual:`ctest(1)` tool learned a new ``--repeat-until-fail <n>``
-  option to help find sporadic test failures.
+* The version of some Fortran compilers is now detected and stored in the
+  :variable:`CMAKE_Fortran_COMPILER_VERSION <CMAKE_<LANG>_COMPILER_VERSION>`
+  variable.
 
-* Using the output of :command:`export()` with the :command:`install(FILES)`
-  command is no longer allowed.  See policy :policy:`CMP0062` for details.
+* The :ref:`Visual Studio Generators` learned a new
+  :variable:`CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD` option
+  to put the ``INSTALL`` target in the default build of a
+  solution (``.sln``) file.
+
+Properties
+----------
 
 * A :prop_tgt:`CROSSCOMPILING_EMULATOR` target property and supporting
   :variable:`CMAKE_CROSSCOMPILING_EMULATOR` variable were introduced
   to allow target platform binaries to run on the host during cross
   compiling.
 
-* The :command:`execute_process` command learned to support specifying
-  the same file for ``OUTPUT_FILE`` and ``ERROR_FILE``.
-
-* It is now possible to export targets which populate the
-  :prop_tgt:`INTERFACE_SOURCES` target property using the
-  :command:`install(EXPORT)` and :command:`export()` commands.
+* A :prop_tgt:`<LANG>_INCLUDE_WHAT_YOU_USE` target property and supporting
+  :variable:`CMAKE_<LANG>_INCLUDE_WHAT_YOU_USE` variable were introduced
+  to tell the :ref:`Makefile Generators` and the :generator:`Ninja` generator
+  to run ``include-what-you-use`` along with the compiler for ``C`` and
+  ``CXX`` languages.
 
 * The :prop_tgt:`<LANG>_VISIBILITY_PRESET` and
   :prop_tgt:`VISIBILITY_INLINES_HIDDEN` target properties now
   affect compilation in sources of all target types.  See
   policy :policy:`CMP0063`.
 
+* The :prop_tgt:`XCODE_ATTRIBUTE_<an-attribute>` target property learned
+  to support generator expressions.
+
+Modules
+-------
+
+* The :module:`CheckFortranCompilerFlag` module was introduced
+  to check ``Fortran`` compiler flags, much like the
+  :module:`CheckCCompilerFlag` module already does for ``C``.
+
 * The :module:`ExternalData` module learned a new
   :variable:`ExternalData_NO_SYMLINKS` option to disable use of
   symbolic links to populate the real data files and use copies
@@ -104,17 +121,9 @@ Changes made since CMake 3.2 include the following.
   :manual:`generator expressions <cmake-generator-expressions(7)>`
   when using ``LOG_*`` options and in CMake initial cache options.
 
-* The :command:`file(GLOB)` and :command:`file(GLOB_RECURSE)` commands
-  learned a new ``LIST_DIRECTORIES <bool>`` option to specify whether
-  the glob result should include directories.
-
 * The :module:`FindBoost` module now tracks the directories containing
   libraries separately for RELEASE and DEBUG configurations.
 
-* The :command:`find_library`, :command:`find_path`, and :command:`find_file`
-  commands now search in installation prefixes derived from the ``PATH``
-  environment variable.
-
 * The :module:`FindCUDA` module now defaults to using the static
   CUDA runtime library if it is available.  A new
   ``CUDA_USE_STATIC_CUDA_RUNTIME`` option is offered to control
@@ -125,98 +134,101 @@ Changes made since CMake 3.2 include the following.
   multiplatform way.  The module now offers APIs to create mex extensions,
   documentation, and unit tests.
 
-* The :command:`find_package` command no longer considers project
-  build trees recently configured in a :manual:`cmake-gui(1)`.
-  This was previously done only on Windows and is now never done.
-  The ``NO_CMAKE_BUILDS_PATH`` option is now ignored if given
-  and effectively always on.
-  Projects may populate the :ref:`User Package Registry` to aid
-  users building multiple dependent projects one after another.
-
 * The :module:`FindPackageHandleStandardArgs` module
   ``FIND_PACKAGE_HANDLE_STANDARD_ARGS`` function now
-  always populates the both ``<PackageName>_FOUND``
+  always populates both the ``<PackageName>_FOUND``
   and ``<UPPERCASE_NAME>_FOUND`` variables (the latter
   for backwards compatibility).  The ``FOUND_VAR``
   option is now ignored except to enforce its allowed
   values.
 
-* The :module:`CTestCoverageCollectGCOV` module learned to support
-  the same ``CTEST_CUSTOM_COVERAGE_EXCLUDE`` option as the
-  :command:`ctest_coverage` command.
-
-* Add a new IN_LIST operator to if() that evaluates true
-  if a given element is contained in a named list.
-
-* The :command:`install(TARGETS)` command learned to support
-  generator expressions in the ``DESTINATION`` value.
-
 * The :module:`InstallRequiredSystemLibraries` module learned a new
   ``CMAKE_INSTALL_SYSTEM_RUNTIME_COMPONENT`` option to specify the
   installation component.
 
-* Linking to library files by a full path in an implicit linker search
-  directory (e.g. ``/usr/lib/libfoo.a``) no longer asks the linker to
-  search for the library (e.g. ``-lfoo``).  See policy :policy:`CMP0060`.
+Generator Expressions
+---------------------
 
-* The Makefile generators now add ``.DELETE_ON_ERROR`` to the
-  makefiles that contain the actual build rules for files on disk.
-  This tells GNU make to remove rule outputs when their recipe
-  modifies an output but fails.
+* A new ``COMPILE_LANGUAGE`` generator expression was introduced to
+  allow specification of compile options for target files based on the
+  :prop_sf:`LANGUAGE` of each source file.  Due to limitations of the
+  underlying native build tools, this feature has varying support across
+  generators.  See the :manual:`cmake-generator-expressions(7)` manual
+  for details.
 
-* With Makefile generators, the build-time progress output has been improved.
-  It no longer mixes progress and build rule messages during parallel builds.
-  The link rule messages now have progress and are displayed as bold green
-  instead of bold red (since red is often associated with an error message).
+CTest
+-----
 
-* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
-  is now aware of features supported by GNU compilers on Windows, versions
-  4.4 through 5.0.
+* The :manual:`ctest(1)` tool learned a new ``--repeat-until-fail <n>``
+  option to help find sporadic test failures.
 
-* When building with GNU tools on Windows (MinGW tools), the
-  :command:`find_library` command will no longer consider
-  ``.dll`` files to be linkable libraries.  All dynamic link
-  libraries are expected to provide separate ``.dll.a`` or
-  ``.lib`` import libraries.
+* The :module:`CTestCoverageCollectGCOV` module learned to support
+  the same ``CTEST_CUSTOM_COVERAGE_EXCLUDE`` option as the
+  :command:`ctest_coverage` command.
 
-* The :generator:`Ninja` generator now requires that calls to the
-  :command:`add_custom_command` and :command:`add_custom_target`
-  commands use the ``BYPRODUCTS`` option to explicitly specify any
-  files generated by the custom commands that are not listed as
-  outputs (perhaps because their timestamps are allowed to be older
-  than the inputs).  See policy :policy:`CMP0058`.
+CPack
+-----
 
-* The :command:`add_definitions()` command no longer causes a
-  :prop_dir:`DEFINITIONS` directory property to be populated. See policy
-  :policy:`CMP0059`.
+* The :manual:`cpack(1)` ``IFW`` generator and the :module:`CPackIFW`
+  module learned to support Qt Framework Installer 2.0 tools.
+
+* The :module:`CPackDeb` module learned a new
+  :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS`
+  variable to specify per-component use of ``dpkg-shlibdeps``.
+
+* The :module:`CPackDeb` module learned a new
+  :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS`
+  option to specify per-component dependencies.
+
+* The :module:`CPackRPM` module learned to package symbolic links
+  more cleanly and now supports directory symlinks with recent
+  ``rpmbuild`` versions.
+
+* The :module:`CPackRPM` module learned a new
+  :variable:`CPACK_RPM_ADDITIONAL_MAN_DIRS` variable to specify
+  directories containing man pages for the brp-compress RPM macro.
 
 * The :module:`CPackRPM` module learned a new
   :variable:`CPACK_RPM_<component>_PACKAGE_ARCHITECTURE` variable
   to specify a component-specific package architecture.
 
-* The :ref:`Makefile Generators` and the :generator:`Ninja` generator
-  learned to optionally run ``include-what-you-use`` along with the
-  compiler for ``C`` and ``CXX`` languages.  See the
-  :variable:`CMAKE_<LANG>_INCLUDE_WHAT_YOU_USE` variable and
-  :prop_tgt:`<LANG>_INCLUDE_WHAT_YOU_USE` target property for details.
+* The CPack WIX generator learned the new
+  :prop_inst:`CPACK_START_MENU_SHORTCUTS`,
+  :prop_inst:`CPACK_DESKTOP_SHORTCUTS` and
+  :prop_inst:`CPACK_STARTUP_SHORTCUTS` installed file properties which can
+  be used to install shorcuts in the Start Menu, on the Desktop and
+  in the Startup Folder respectively.
 
-* A new ``COMPILE_LANGUAGE`` generator expression was introduced to
-  allow specification of compile options for target files based on the
-  :prop_sf:`LANGUAGE` of each source file.  Due to limitations of the
-  underlying native build tools, this feature has varying support across
-  generators.  See the :manual:`cmake-generator-expressions(7)` manual
-  for details.
+Other
+-----
+
+* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
+  is now aware of features supported by GNU compilers on Windows, versions
+  4.4 through 5.0.
 
 * The :manual:`cmake(1)` ``-E tar`` command learned a new
   ``--format<format>`` option to specify the archive format to
   be written.
 
-* The :module:`UseSWIG` module ``SWIG_ADD_MODULE`` macro no
-  longer attaches the swig invocation custom command to the
-  ``.i`` source file in IDE projects.  This is because only
-  one custom command can be safely attached to a given source
-  file, and adding multiple modules with the same ``.i`` file
-  for different languages requires more than one such command.
+* On OS X, CMake learned to create XCTest bundles to test Frameworks
+  and App Bundles within Xcode.  The :module:`FindXCTest` module
+  provides convenience functions to handle :prop_tgt:`XCTEST` bundles.
+
+Deprecated and Removed Features
+===============================
+
+* On OS X the :manual:`cmake-gui(1)` no longer has the
+  ``Install For Command Line Use`` menu item.  Instead there
+  is a ``How to Install For Command Line Use`` menu item
+  that shows an informational dialog box explaining how to
+  make the command line tools available.  For example::
+
+    /Applications/CMake.app/Contents/bin/cmake-gui --install
+
+* The :command:`ctest_build` and :command:`build_command` commands
+  no longer tell ``make`` tools to ignore errors with the ``-i`` option.
+  Previously this was done for :ref:`Makefile Generators` but not others.
+  See policy :policy:`CMP0061`.
 
 * The :generator:`Visual Studio 10 2010` generator no longer checks
   for running VS IDEs with the project open or asks them to reload.
@@ -225,39 +237,57 @@ Changes made since CMake 3.2 include the following.
   Since VS >= 10 allow the whole solution to reload at once they
   do not need CMake to help them.
 
+* The :generator:`Visual Studio 7` generator (.NET 2002) is now
+  deprecated and will be removed in a future version of CMake.
+
 * The :generator:`Visual Studio 6` generator is now deprecated
   and will be removed in a future version of CMake.
 
-* The :generator:`Visual Studio 7` generator (.NET 2002) is now
-  deprecated and will be removed in a future version of CMake.
+* The :command:`find_package` command no longer considers project
+  build trees recently configured in a :manual:`cmake-gui(1)`.
+  This was previously done only on Windows and is now never done.
+  The ``NO_CMAKE_BUILDS_PATH`` option is now ignored if given
+  and effectively always on.
+  Projects may populate the :ref:`User Package Registry` to aid
+  users building multiple dependent projects one after another.
 
-* The :variable:`CMAKE_CFG_INTDIR` variable value for Visual Studio
-  7, 8, and 9 is now ``$(ConfigurationName)`` instead of ``$(OutDir)``.
-  This should have no effect on the intended use cases of the variable.
+* When building with GNU tools on Windows (MinGW tools), the
+  :command:`find_library` command will no longer consider
+  ``.dll`` files to be linkable libraries.  All dynamic link
+  libraries are expected to provide separate ``.dll.a`` or
+  ``.lib`` import libraries.
+
+* The :command:`add_definitions()` command no longer causes a
+  :prop_dir:`DEFINITIONS` directory property to be populated. See policy
+  :policy:`CMP0059`.
 
 * With Visual Studio 7, 8, and 9 generators the value of the ``$(OutDir)``
   placeholder no longer evaluates to the configuration name.  Projects
   should use ``$(ConfigurationName)`` for that instead.
 
-* The :ref:`Visual Studio Generators` learned a new
-  :variable:`CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD` option
-  to put the ``INSTALL`` target in the default build of a
-  solution (``.sln``) file.
+* Using the output of :command:`export()` with the :command:`install(FILES)`
+  command is no longer allowed.  See policy :policy:`CMP0062` for details.
 
-* The :ref:`Visual Studio Generators` learned to support ``.xaml``
-  source files and automatically associate them with corresponding
-  ``.h`` and ``.cpp`` sources.
+Other Changes
+=============
 
-* The CPack WIX generator learned the new
-  :prop_inst:`CPACK_START_MENU_SHORTCUTS`,
-  :prop_inst:`CPACK_DESKTOP_SHORTCUTS` and
-  :prop_inst:`CPACK_STARTUP_SHORTCUTS` installed file properties which can
-  be used to install shorcuts in the Start Menu, on the Desktop and
-  in the Startup Folder respectively.
+* The :generator:`Ninja` generator now requires that calls to the
+  :command:`add_custom_command` and :command:`add_custom_target`
+  commands use the ``BYPRODUCTS`` option to explicitly specify any
+  files generated by the custom commands that are not listed as
+  outputs (perhaps because their timestamps are allowed to be older
+  than the inputs).  See policy :policy:`CMP0058`.
 
-* The :prop_tgt:`XCODE_ATTRIBUTE_<an-attribute>` target property learned
-  to support generator expressions.
+* Build-time progress output of :ref:`Makefile Generators` has been improved.
+  It no longer mixes progress and build rule messages during parallel builds.
+  The link rule messages now have progress and are displayed as bold green
+  instead of bold red (since red is often associated with an error message).
 
-* On OS X, CMake learned to create XCTest bundles to test Frameworks
-  and App Bundles within Xcode.  The :module:`FindXCTest` module
-  provides convenience functions to handle :prop_tgt:`XCTEST` bundles.
+* The :variable:`CMAKE_CFG_INTDIR` variable value for Visual Studio
+  7, 8, and 9 is now ``$(ConfigurationName)`` instead of ``$(OutDir)``.
+  This should have no effect on the intended use cases of the variable.
+
+* Linking to library files by a full path in an implicit linker search
+  directory (e.g. ``/usr/lib/libfoo.a``) no longer asks the linker to
+  search for the library (e.g. ``-lfoo``) and now links by full path.
+  See policy :policy:`CMP0060`.