Help: Separate C++ compile feature by standard

Additionally, mention that no fine-grained features are available for
C++ 17 and beyond.

Co-Authored-By: Craig Scott <craig.scott@crascit.com>

1 files changed, 87 insertions, 55 deletions

diff --git a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst
index 9b53282..bac3274 100644
--- a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst
+++ b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst
@@ -13,8 +13,14 @@ The features listed here may be used with the :command:`target_compile_features`
 command.  See the :manual:`cmake-compile-features(7)` manual for information on
 compile features and a list of supported compilers.
 
+The features known to this version of CMake are listed below.
 
-The features known to this version of CMake are:
+High level meta features indicating C++ standard support
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following meta features indicate general support for the associated
+language standard.  It reflects the language support claimed by the compiler,
+but it does not necessarily imply complete conformance to that standard.
 
 ``cxx_std_98``
   Compiler mode is at least C++ 98.
@@ -31,10 +37,29 @@ The features known to this version of CMake are:
 ``cxx_std_20``
   Compiler mode is at least C++ 20.
 
-``cxx_aggregate_default_initializers``
-  Aggregate default initializers, as defined in N3605_.
 
-  .. _N3605: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3605.html
+Low level individual compile features
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For C++ 11 and C++ 14, compilers were sometimes slow to implement certain
+language features.  CMake provided some individual compile features to help
+projects determine whether specific features were available.  These individual
+features are now less relevant and projects should generally prefer to use the
+high level meta features instead.  Individual compile features are not provided
+for C++ 17 or later.
+
+See the :manual:`cmake-compile-features(7)` manual for further discussion of
+the use of individual compile features.
+
+Individual features from C++ 98
+"""""""""""""""""""""""""""""""
+
+``cxx_template_template_parameters``
+  Template template parameters, as defined in ``ISO/IEC 14882:1998``.
+
+
+Individual features from C++ 11
+"""""""""""""""""""""""""""""""
 
 ``cxx_alias_templates``
   Template aliases, as defined in N2258_.
@@ -56,30 +81,16 @@ The features known to this version of CMake are:
 
   .. _N2761: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2761.pdf
 
-``cxx_attribute_deprecated``
-  ``[[deprecated]]`` attribute, as defined in N3760_.
-
-  .. _N3760: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3760.html
-
 ``cxx_auto_type``
   Automatic type deduction, as defined in N1984_.
 
   .. _N1984: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1984.pdf
 
-``cxx_binary_literals``
-  Binary literals, as defined in N3472_.
-
-  .. _N3472: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3472.pdf
-
 ``cxx_constexpr``
   Constant expressions, as defined in N2235_.
 
   .. _N2235: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2235.pdf
 
-``cxx_contextual_conversions``
-  Contextual conversions, as defined in N3323_.
-
-  .. _N3323: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3323.pdf
 
 ``cxx_decltype_incomplete_return_types``
   Decltype on incomplete return types, as defined in N3276_.
@@ -91,11 +102,6 @@ The features known to this version of CMake are:
 
   .. _N2343: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2343.pdf
 
-``cxx_decltype_auto``
-  ``decltype(auto)`` semantics, as defined in N3638_.
-
-  .. _N3638: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3638.html
-
 ``cxx_default_function_template_args``
   Default template arguments for function templates, as defined in DR226_
 
@@ -121,11 +127,6 @@ The features known to this version of CMake are:
 
   .. _N2346: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm
 
-``cxx_digit_separators``
-  Digit separators, as defined in N3781_.
-
-  .. _N3781: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3781.pdf
-
 ``cxx_enum_forward_declarations``
   Enum forward declarations, as defined in N2764_.
 
@@ -163,11 +164,6 @@ The features known to this version of CMake are:
 
   .. _N2672: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2672.htm
 
-``cxx_generic_lambdas``
-  Generic lambdas, as defined in N3649_.
-
-  .. _N3649: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3649.html
-
 ``cxx_inheriting_constructors``
   Inheriting constructors, as defined in N2540_.
 
@@ -183,11 +179,6 @@ The features known to this version of CMake are:
 
   .. _N2927: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2927.pdf
 
-``cxx_lambda_init_captures``
-  Initialized lambda captures, as defined in N3648_.
-
-  .. _N3648: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3648.html
-
 ``cxx_local_type_template_args``
   Local and unnamed types as template arguments, as defined in N2657_.
 
@@ -236,16 +227,6 @@ The features known to this version of CMake are:
 
   .. _N2439: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2439.htm
 
-``cxx_relaxed_constexpr``
-  Relaxed constexpr, as defined in N3652_.
-
-  .. _N3652: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3652.html
-
-``cxx_return_type_deduction``
-  Return type deduction on normal functions, as defined in N3386_.
-
-  .. _N3386: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3386.html
-
 ``cxx_right_angle_brackets``
   Right angle bracket parsing, as defined in N1757_.
 
@@ -301,11 +282,6 @@ The features known to this version of CMake are:
 
   .. _N2765: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2765.pdf
 
-``cxx_variable_templates``
-  Variable templates, as defined in N3651_.
-
-  .. _N3651: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3651.pdf
-
 ``cxx_variadic_macros``
   Variadic macros, as defined in N1653_.
 
@@ -316,5 +292,61 @@ The features known to this version of CMake are:
 
   .. _N2242: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2242.pdf
 
-``cxx_template_template_parameters``
-  Template template parameters, as defined in ``ISO/IEC 14882:1998``.
+
+Individual features from C++ 14
+"""""""""""""""""""""""""""""""
+
+``cxx_aggregate_default_initializers``
+  Aggregate default initializers, as defined in N3605_.
+
+  .. _N3605: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3605.html
+
+``cxx_attribute_deprecated``
+  ``[[deprecated]]`` attribute, as defined in N3760_.
+
+  .. _N3760: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3760.html
+
+``cxx_binary_literals``
+  Binary literals, as defined in N3472_.
+
+  .. _N3472: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3472.pdf
+
+``cxx_contextual_conversions``
+  Contextual conversions, as defined in N3323_.
+
+  .. _N3323: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3323.pdf
+
+``cxx_decltype_auto``
+  ``decltype(auto)`` semantics, as defined in N3638_.
+
+  .. _N3638: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3638.html
+
+``cxx_digit_separators``
+  Digit separators, as defined in N3781_.
+
+  .. _N3781: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3781.pdf
+
+``cxx_generic_lambdas``
+  Generic lambdas, as defined in N3649_.
+
+  .. _N3649: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3649.html
+
+``cxx_lambda_init_captures``
+  Initialized lambda captures, as defined in N3648_.
+
+  .. _N3648: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3648.html
+
+``cxx_relaxed_constexpr``
+  Relaxed constexpr, as defined in N3652_.
+
+  .. _N3652: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3652.html
+
+``cxx_return_type_deduction``
+  Return type deduction on normal functions, as defined in N3386_.
+
+  .. _N3386: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3386.html
+
+``cxx_variable_templates``
+  Variable templates, as defined in N3651_.
+
+  .. _N3651: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3651.pdf