Document CMAKE_CXX_STANDARD

This variable is a CMake community standard to set the C++
standard of a build. Document it in favor of the previous variable,
which stays as a legacy flag for existing projects.

https://cmake.org/cmake/help/v3.17/variable/CMAKE_CXX_STANDARD.html

docs/compiling.rst

@@ -105,18 +105,14 @@ on the target compiler, falling back to C++11 if C++14 support is not
 available.  Note, however, that this default is subject to change: future
 pybind11 releases are expected to migrate to newer C++ standards as they become
 available.  To override this, the standard flag can be given explicitly in
-``PYBIND11_CPP_STANDARD``:
+`CMAKE_CXX_STANDARD <https://cmake.org/cmake/help/v3.17/variable/CMAKE_CXX_STANDARD.html>`_:
 
 .. code-block:: cmake
 
     # Use just one of these:
-    # GCC/clang:
-    set(PYBIND11_CPP_STANDARD -std=c++11)
-    set(PYBIND11_CPP_STANDARD -std=c++14)
-    set(PYBIND11_CPP_STANDARD -std=c++1z) # Experimental C++17 support
-    # MSVC:
-    set(PYBIND11_CPP_STANDARD /std:c++14)
-    set(PYBIND11_CPP_STANDARD /std:c++latest) # Enables some MSVC C++17 features
+    set(CMAKE_CXX_STANDARD 11)
+    set(CMAKE_CXX_STANDARD 14)
+    set(CMAKE_CXX_STANDARD 17) # Experimental C++17 support
 
     add_subdirectory(pybind11)  # or find_package(pybind11)
 

tools/pybind11Config.cmake.in

@@ -28,8 +28,8 @@
 #
 # Python headers, libraries (as needed by platform), and the C++ standard
 # are attached to the target. Set PythonLibsNew variables to influence
-# python detection and PYBIND11_CPP_STANDARD (-std=c++11 or -std=c++14) to
-# influence standard setting. ::
+# python detection and CMAKE_CXX_STANDARD (11 or 14) to influence standard
+# setting. ::
 #
 #   find_package(pybind11 CONFIG REQUIRED)
 #   message(STATUS "Found pybind11 v${pybind11_VERSION}: ${pybind11_INCLUDE_DIRS}")