From 3feff8379b05332035319de4f733549695fcc6de Mon Sep 17 00:00:00 2001
From: Raul Tambre <raul@tambre.ee>
Date: Sat, 28 Aug 2021 18:00:28 +0300
Subject: Help: Generic language standard and extension variables documentation

Add generic documentation to improve the discoverability of language-specific
ones and to make it possible to refer to them generically from other language
generic documentation.
---
 Help/manual/cmake-properties.7.rst             |  3 +++
 Help/manual/cmake-variables.7.rst              |  3 +++
 Help/prop_tgt/LANG_EXTENSIONS.rst              | 23 +++++++++++++++++++++++
 Help/prop_tgt/LANG_STANDARD.rst                | 26 ++++++++++++++++++++++++++
 Help/prop_tgt/LANG_STANDARD_REQUIRED.rst       | 26 ++++++++++++++++++++++++++
 Help/variable/CMAKE_LANG_EXTENSIONS.rst        | 19 +++++++++++++++++++
 Help/variable/CMAKE_LANG_STANDARD.rst          | 19 +++++++++++++++++++
 Help/variable/CMAKE_LANG_STANDARD_REQUIRED.rst | 19 +++++++++++++++++++
 8 files changed, 138 insertions(+)
 create mode 100644 Help/prop_tgt/LANG_EXTENSIONS.rst
 create mode 100644 Help/prop_tgt/LANG_STANDARD.rst
 create mode 100644 Help/prop_tgt/LANG_STANDARD_REQUIRED.rst
 create mode 100644 Help/variable/CMAKE_LANG_EXTENSIONS.rst
 create mode 100644 Help/variable/CMAKE_LANG_STANDARD.rst
 create mode 100644 Help/variable/CMAKE_LANG_STANDARD_REQUIRED.rst

diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index c71e8ff..d04a864 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -274,8 +274,11 @@ Properties on Targets
    /prop_tgt/LANG_COMPILER_LAUNCHER
    /prop_tgt/LANG_CPPCHECK
    /prop_tgt/LANG_CPPLINT
+   /prop_tgt/LANG_EXTENSIONS
    /prop_tgt/LANG_INCLUDE_WHAT_YOU_USE
    /prop_tgt/LANG_LINKER_LAUNCHER
+   /prop_tgt/LANG_STANDARD
+   /prop_tgt/LANG_STANDARD_REQUIRED
    /prop_tgt/LANG_VISIBILITY_PRESET
    /prop_tgt/LIBRARY_OUTPUT_DIRECTORY
    /prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 7cfa0c8..bab53f0 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -549,6 +549,7 @@ Variables for Languages
    /variable/CMAKE_LANG_CREATE_SHARED_LIBRARY
    /variable/CMAKE_LANG_CREATE_SHARED_MODULE
    /variable/CMAKE_LANG_CREATE_STATIC_LIBRARY
+   /variable/CMAKE_LANG_EXTENSIONS
    /variable/CMAKE_LANG_FLAGS
    /variable/CMAKE_LANG_FLAGS_CONFIG
    /variable/CMAKE_LANG_FLAGS_CONFIG_INIT
@@ -577,8 +578,10 @@ Variables for Languages
    /variable/CMAKE_LANG_SIMULATE_VERSION
    /variable/CMAKE_LANG_SIZEOF_DATA_PTR
    /variable/CMAKE_LANG_SOURCE_FILE_EXTENSIONS
+   /variable/CMAKE_LANG_STANDARD
    /variable/CMAKE_LANG_STANDARD_INCLUDE_DIRECTORIES
    /variable/CMAKE_LANG_STANDARD_LIBRARIES
+   /variable/CMAKE_LANG_STANDARD_REQUIRED
    /variable/CMAKE_OBJC_EXTENSIONS
    /variable/CMAKE_OBJC_STANDARD
    /variable/CMAKE_OBJC_STANDARD_REQUIRED
diff --git a/Help/prop_tgt/LANG_EXTENSIONS.rst b/Help/prop_tgt/LANG_EXTENSIONS.rst
new file mode 100644
index 0000000..2add21d
--- /dev/null
+++ b/Help/prop_tgt/LANG_EXTENSIONS.rst
@@ -0,0 +1,23 @@
+<LANG>_EXTENSIONS
+-----------------
+
+The variations are:
+
+* :prop_tgt:`C_EXTENSIONS`
+* :prop_tgt:`CXX_EXTENSIONS`
+* :prop_tgt:`CUDA_EXTENSIONS`
+* :prop_tgt:`HIP_EXTENSIONS`
+* :prop_tgt:`OBJC_EXTENSIONS`
+* :prop_tgt:`OBJCXX_EXTENSIONS`
+
+These properties specify whether compiler-specific extensions are requested.
+
+These properties are initialized by the value of the
+:variable:`CMAKE_<LANG>_EXTENSIONS` variable if it is set when a target is
+created.
+
+For supported CMake versions see the respective pages.
+To control language standard versions see :prop_tgt:`<LANG>_STANDARD`.
+
+See the :manual:`cmake-compile-features(7)` manual for information on
+compile features and a list of supported compilers.
diff --git a/Help/prop_tgt/LANG_STANDARD.rst b/Help/prop_tgt/LANG_STANDARD.rst
new file mode 100644
index 0000000..bd377ec
--- /dev/null
+++ b/Help/prop_tgt/LANG_STANDARD.rst
@@ -0,0 +1,26 @@
+<LANG>_STANDARD
+---------------
+
+The variations are:
+
+* :prop_tgt:`C_STANDARD`
+* :prop_tgt:`CXX_STANDARD`
+* :prop_tgt:`CUDA_STANDARD`
+* :prop_tgt:`HIP_STANDARD`
+* :prop_tgt:`OBJC_STANDARD`
+* :prop_tgt:`OBJCXX_STANDARD`
+
+These properties specify language standard versions which are requested. When a
+newer standard is specified than is supported by the compiler, then it will
+fallback to the latest supported standard. This "decay" behavior may be
+controlled with the :prop_tgt:`<LANG>_STANDARD_REQUIRED` target property.
+
+These properties are initialized by the value of the
+:variable:`CMAKE_<LANG>_STANDARD` variable if it is set when a target is
+created.
+
+For supported values and CMake versions see the respective pages.
+To control compiler-specific extensions see :prop_tgt:`<LANG>_EXTENSIONS`.
+
+See the :manual:`cmake-compile-features(7)` manual for information on
+compile features and a list of supported compilers.
diff --git a/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst b/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst
new file mode 100644
index 0000000..56ecef8
--- /dev/null
+++ b/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst
@@ -0,0 +1,26 @@
+<LANG>_STANDARD_REQUIRED
+------------------------
+
+The variations are:
+
+* :prop_tgt:`C_STANDARD_REQUIRED`
+* :prop_tgt:`CXX_STANDARD_REQUIRED`
+* :prop_tgt:`CUDA_STANDARD_REQUIRED`
+* :prop_tgt:`HIP_STANDARD_REQUIRED`
+* :prop_tgt:`OBJC_STANDARD_REQUIRED`
+* :prop_tgt:`OBJCXX_STANDARD_REQUIRED`
+
+These properties specify whether the value of :prop_tgt:`<LANG>_STANDARD` is a
+requirement. When ``OFF`` or unset, the :prop_tgt:`<LANG>_STANDARD` target
+property is treated as optional and may "decay" to a previous standard if the
+requested is not available.
+
+These properties are initialized by the value of the
+:variable:`CMAKE_<LANG>_STANDARD_REQUIRED` variable if it is set when a target
+is created.
+
+For supported CMake versions see the respective pages.
+To control language standard versions see :prop_tgt:`<LANG>_STANDARD`.
+
+See the :manual:`cmake-compile-features(7)` manual for information on
+compile features and a list of supported compilers.
diff --git a/Help/variable/CMAKE_LANG_EXTENSIONS.rst b/Help/variable/CMAKE_LANG_EXTENSIONS.rst
new file mode 100644
index 0000000..84e5e3a
--- /dev/null
+++ b/Help/variable/CMAKE_LANG_EXTENSIONS.rst
@@ -0,0 +1,19 @@
+CMAKE_<LANG>_EXTENSIONS
+-----------------------
+
+The variations are:
+
+* :variable:`CMAKE_C_EXTENSIONS`
+* :variable:`CMAKE_CXX_EXTENSIONS`
+* :variable:`CMAKE_CUDA_EXTENSIONS`
+* :variable:`CMAKE_HIP_EXTENSIONS`
+* :variable:`CMAKE_OBJC_EXTENSIONS`
+* :variable:`CMAKE_OBJCXX_EXTENSIONS`
+
+Default values for :prop_tgt:`<LANG>_EXTENSIONS` target properties if set when
+a target is created.
+
+For supported CMake versions see the respective pages.
+
+See the :manual:`cmake-compile-features(7)` manual for information on
+compile features and a list of supported compilers.
diff --git a/Help/variable/CMAKE_LANG_STANDARD.rst b/Help/variable/CMAKE_LANG_STANDARD.rst
new file mode 100644
index 0000000..0c41e19
--- /dev/null
+++ b/Help/variable/CMAKE_LANG_STANDARD.rst
@@ -0,0 +1,19 @@
+CMAKE_<LANG>_STANDARD
+---------------------
+
+The variations are:
+
+* :variable:`CMAKE_C_STANDARD`
+* :variable:`CMAKE_CXX_STANDARD`
+* :variable:`CMAKE_CUDA_STANDARD`
+* :variable:`CMAKE_HIP_STANDARD`
+* :variable:`CMAKE_OBJC_STANDARD`
+* :variable:`CMAKE_OBJCXX_STANDARD`
+
+Default values for :prop_tgt:`<LANG>_STANDARD` target properties if set when a
+target is created.
+
+For supported CMake versions see the respective pages.
+
+See the :manual:`cmake-compile-features(7)` manual for information on
+compile features and a list of supported compilers.
diff --git a/Help/variable/CMAKE_LANG_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_LANG_STANDARD_REQUIRED.rst
new file mode 100644
index 0000000..d7fa9b6
--- /dev/null
+++ b/Help/variable/CMAKE_LANG_STANDARD_REQUIRED.rst
@@ -0,0 +1,19 @@
+CMAKE_<LANG>_STANDARD_REQUIRED
+------------------------------
+
+The variations are:
+
+* :variable:`CMAKE_C_STANDARD_REQUIRED`
+* :variable:`CMAKE_CXX_STANDARD_REQUIRED`
+* :variable:`CMAKE_CUDA_STANDARD_REQUIRED`
+* :variable:`CMAKE_HIP_STANDARD_REQUIRED`
+* :variable:`CMAKE_OBJC_STANDARD_REQUIRED`
+* :variable:`CMAKE_OBJCXX_STANDARD_REQUIRED`
+
+Default values for :prop_tgt:`<LANG>_STANDARD_REQUIRED` target properties if
+set when a target is created.
+
+For supported CMake versions see the respective pages.
+
+See the :manual:`cmake-compile-features(7)` manual for information on
+compile features and a list of supported compilers.
-- 
cgit v0.12