docs/cmake: update references

1 files changed, 54 insertions, 43 deletions

diff --git a/docs/cmake.md b/docs/cmake.md
index aac40e0..d101dc7 100644
--- a/docs/cmake.md
+++ b/docs/cmake.md
@@ -1,55 +1,74 @@
 Default generator
 -----------------
 
-As of CMake 3.18, the default generator (unless set explicitly) is:
+As of CMake 3.26, the default generator (unless set explicitly) is:
 
   * the newest Visual Studio or "NMake Makefiles" on Windows,
   * "Unix Makefiles" otherwise.
 
-This is regardless of whether any executables like gcc, cl or make are
-available ([1][1]).
+This is [regardless] of whether any executables like gcc, cl or make are
+available.
+
+[regardless]: https://github.com/Kitware/CMake/blob/v3.26.4/Source/cmake.cxx#L2484
 
 Makefile generators
 -------------------
 
-CMake has a number of "... Makefiles" generators.  "Unix Makefiles" uses
-gmake/make/smake, whichever is found first, and cc/c++ for compiler detection
-([2][2]).  "MinGW Makefiles" looks for mingw32-make.exe in a number of
-well-known locations, uses gcc/g++ directly, and is aware of windres ([3][3]).
-In addition, "Unix Makefiles" uses /bin/sh as the SHELL value in the Makefile,
-while the MinGW version uses cmd.exe.  I don't think it matters on Windows
-though, since the non-existent /bin/sh is ignored anyway ([4][4]).  "NMake
-Makefiles" is similar, except it defaults to using cl ([5][5]).
+CMake has a number of "... Makefiles" generators.  "Unix Makefiles" [uses
+gmake/make/smake], whichever is found first, and [prefers cc]/[c++] symlinks
+for compiler detection.  "MinGW Makefiles" [looks for mingw32-make.exe] in a
+number of well-known locations instead.  In addition, "Unix Makefiles" [uses
+/bin/sh] as the SHELL value in the Makefile, while the MinGW version [uses
+cmd.exe].  I don't think it matters on Windows though, since the non-existent
+/bin/sh is [ignored anyway].  "NMake Makefiles" is similar, except it defaults
+to [using cl].
+
+[uses gmake/make/smake]: https://github.com/Kitware/CMake/blob/v3.26.4/Modules/CMakeUnixFindMake.cmake
+[prefers cc]: https://github.com/Kitware/CMake/blob/v3.26.4/Modules/CMakeDetermineCCompiler.cmake
+[c++]: https://github.com/Kitware/CMake/blob/v3.26.4/Modules/CMakeDetermineCXXCompiler.cmake
+[looks for mingw32-make.exe]: https://github.com/Kitware/CMake/blob/v3.26.4/Modules/CMakeMinGWFindMake.cmake
+[uses /bin/sh]: https://github.com/Kitware/CMake/blob/v3.26.4/Source/cmLocalUnixMakefileGenerator3.cxx#L651
+[uses cmd.exe]: https://github.com/Kitware/CMake/blob/v3.26.4/Source/cmLocalUnixMakefileGenerator3.cxx#L644
+[ignored anyway]: https://www.gnu.org/software/make/manual/html_node/Choosing-the-Shell.html
+[using cl]: https://github.com/Kitware/CMake/blob/v3.26.4/Source/cmGlobalNMakeMakefileGenerator.cxx#L41
 
 It's important to _not_ use the -A parameter with any of the Makefile
 generators - it's an error.  This goes for "NMake Makefiles" also.  "NMake
-Makefiles" doesn't attempt to search for installed Visual Studio compilers, you
-need to use it from one of the Visual Studio-provided shells.
+Makefiles" [doesn't attempt] to search for installed Visual Studio compilers,
+you need to use it from one of the Visual Studio-provided shells.
+
+[doesn't attempt]: https://github.com/Kitware/CMake/blob/v3.26.4/Source/cmGlobalNMakeMakefileGenerator.cxx#L93
 
 Visual Studio generators
 ------------------------
 
-These are special.  They ignore the CMAKE_\<LANG\>_COMPILER parameters and use
-cl by default ([9][9]).  They support specifying the toolset to use via the -T
-parameter (the "Platform Toolset" value in the project's properties) since 3.18
-([10][10]).  The toolset list varies between Visual Studio versions, and I'm
-too lazy to learn exactly which version supports which toolsets.
+These are special.  They ignore the CMAKE_\<LANG\>_COMPILER parameters and [use
+cl by default].  They support specifying the toolset to use via the -T
+parameter (the "Platform Toolset" value in the project's properties) [since
+3.8].  The toolset list varies between Visual Studio versions, and I'm too lazy
+to learn exactly which version supports which toolsets.
+
+[use cl by default]: https://gitlab.kitware.com/cmake/cmake/-/issues/19174
+[since 3.8]: https://cmake.org/cmake/help/v3.8/release/3.8.html
 
 `cmake --build` uses msbuild with Visual Studio generators.  You can pass the
 path to a different cl.exe by doing something like
 
     msbuild ... /p:CLToolExe=another-cl.exe /p:CLToolPath=C:\parent\dir
 
-It's important that the generators for Visual Studio 2017 or older use Win32 as
-the default platform ([12][12]).  Because of that, we need to pass the -A
-parameter.
+It's important that the generators for Visual Studio 2017 or older [use Win32]
+as the default platform.  Because of that, we need to pass the -A parameter.
+
+[use Win32]: https://cmake.org/cmake/help/v3.18/generator/Visual%20Studio%2015%202017.html
 
 mingw32-make vs make
 --------------------
 
-No idea what the actual differences are.  The explanation in the FAQ ([6][6])
-about how GNU make "is lacking in some functionality and has modified
-functionality due to the lack of POSIX on Win32" isn't terribly helpful.
+No idea what the actual differences are.  The [explanation] in the FAQ about
+how GNU make "is lacking in some functionality and has modified functionality
+due to the lack of POSIX on Win32" isn't terribly helpful.
+
+[explanation]: http://mingw.org/wiki/FAQ
 
 It's important that you can install either on Windows (`choco install make` for
 GNU make and `choco install mingw` to install a MinGW-w64 distribution with
@@ -80,31 +99,23 @@ Ubuntu, you need to install the gcc-multilib package.
 Windows & Clang
 ---------------
 
-Using Clang on Windows is no easy task, of course.  Prior to 3.15, there was no
-support for building things using the clang++.exe executable, only clang-cl.exe
-was supported ([7][7]).  If you specified `-DCMAKE_CXX_COMPILER=clang++`, CMake
-would stil pass MSVC-style command line options to the compiler (like `/MD`,
-`/nologo`, etc.), which clang++ doesn't like ([8][8]).
+Using Clang on Windows is no easy task, of course.  Prior to 3.15, there was
+[no support] for building things using the clang++.exe executable, only
+clang-cl.exe was supported.  If you specified `-DCMAKE_CXX_COMPILER=clang++`,
+CMake [would still] pass MSVC-style command line options to the compiler (like
+`/MD`, `/nologo`, etc.), which clang++ doesn't like.
+
+[no support]: https://cmake.org/cmake/help/v3.15/release/3.15.html#compilers
+[would still]: https://github.com/Kitware/CMake/blob/v3.14.7/Modules/Platform/Windows-Clang.cmake
 
 So, in summary, you can only use clang++ since 3.15.  clang-cl doesn't work
 with Visual Studio generators unless you specify the proper toolset using the
 -T parameter.  You can set the ClToolExe property using msbuild, but while that
 might work in practice, clang-cl.exe needs to map some unsupported options for
 everything to work properly.  For an example of how this is done, see the
-LLVM.Cpp.Common.* files at ([11][11]).
+[LLVM.Cpp.Common.* files].
+
+[LLVM.Cpp.Common.* files]: https://github.com/llvm/llvm-project/tree/e408935bb5339e20035d84307c666fbdd15e99e0/llvm/tools/msbuild
 
 I recommend using Clang (either clang-cl or clang++ since 3.15) using the
 "NMake Makefiles" generator.
-
-[1]: https://github.com/Kitware/CMake/blob/v3.18.4/Source/cmake.cxx#L1697
-[2]: https://github.com/Kitware/CMake/blob/v3.18.4/Source/cmGlobalUnixMakefileGenerator3.cxx
-[3]: https://github.com/Kitware/CMake/blob/v3.18.4/Source/cmGlobalMinGWMakefileGenerator.cxx
-[4]: https://www.gnu.org/software/make/manual/html_node/Choosing-the-Shell.html
-[5]: https://github.com/Kitware/CMake/blob/v3.18.4/Source/cmGlobalNMakeMakefileGenerator.cxx
-[6]: http://mingw.org/wiki/FAQ
-[7]: https://cmake.org/cmake/help/v3.15/release/3.15.html#compilers
-[8]: https://github.com/Kitware/CMake/blob/v3.14.7/Modules/Platform/Windows-Clang.cmake
-[9]: https://gitlab.kitware.com/cmake/cmake/-/issues/19174
-[10]: https://cmake.org/cmake/help/v3.8/release/3.8.html
-[11]: https://github.com/llvm/llvm-project/tree/e408935bb5339e20035d84307c666fbdd15e99e0/llvm/tools/msbuild
-[12]: https://cmake.org/cmake/help/v3.18/generator/Visual%20Studio%2015%202017.html