[scripts-audit] Rollup PR 2021-02-26 (#16440)

* [scripts-audit rollup] PR #16419

* pull the cmake doc comment parsing out into its own function
* support cmake helper ports
* add real support for deprecation, as opposed to ad-hoc

* [scripts-audit rollup] PR #16192

* add a z_ in front of internal functions
* move internal functions out

set feature_vars again in parent scope

* [scripts-audit rollup] PR #16309

Audit vcpkg_copy_pdbs

* [scripts-audit rollup] PR #16304

* Fix usage, documentation

* [scripts-audit rollup] PR #16393

* [scripts-audit rollup] PR #16377

Deprecate `vcpkg_*_cmake` in favor of `vcpkg_cmake_*` from the
`vcpkg-cmake` port, as well as `vcpkg_fixup_cmake_targets`
in favor of `vcpkg_cmake_config_fixup` from the
`vcpkg-cmake-config` port.

65 files changed, 748 insertions, 200 deletions

diff --git a/docs/maintainers/execute_process.md b/docs/maintainers/execute_process.md
index 21bca7f3a..f8b866ae1 100644
--- a/docs/maintainers/execute_process.md
+++ b/docs/maintainers/execute_process.md
@@ -1,9 +1,11 @@
 # execute_process
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/execute_process.md).
+
 Intercepts all calls to execute_process() inside portfiles and fails when Download Mode
 is enabled.
 
 In order to execute a process in Download Mode call `vcpkg_execute_in_download_mode()` instead.
 
 ## Source
-[scripts/cmake/execute_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/execute_process.cmake)
+[scripts/cmake/execute\_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/execute_process.cmake)
diff --git a/docs/maintainers/internal/vcpkg_internal_get_cmake_vars.md b/docs/maintainers/internal/vcpkg_internal_get_cmake_vars.md
index dbac84587..62ac8080c 100644
--- a/docs/maintainers/internal/vcpkg_internal_get_cmake_vars.md
+++ b/docs/maintainers/internal/vcpkg_internal_get_cmake_vars.md
@@ -1,5 +1,7 @@
 # vcpkg_internal_get_cmake_vars
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/).
+
 **Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
 Runs a cmake configure with a dummy project to extract certain cmake variables
 
@@ -26,4 +28,4 @@ If possible avoid usage in portfiles.
 * [vcpkg_configure_make](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_make.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_internal_get_cmake_vars.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_internal_get_cmake_vars.cmake)
+[scripts/cmake/vcpkg\_internal\_get\_cmake\_vars.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_internal_get_cmake_vars.cmake)
diff --git a/docs/maintainers/internal/z_vcpkg_apply_patches.md b/docs/maintainers/internal/z_vcpkg_apply_patches.md
new file mode 100644
index 000000000..e4d54caf4
--- /dev/null
+++ b/docs/maintainers/internal/z_vcpkg_apply_patches.md
@@ -0,0 +1,32 @@
+# z_vcpkg_apply_patches
+
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/).
+
+**Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
+
+Apply a set of patches to a source tree.
+
+```cmake
+z_vcpkg_apply_patches(
+    SOURCE_PATH <path-to-source>
+    [QUIET]
+    PATCHES <patch>...
+)
+```
+
+The `<path-to-source>` should be set to `${SOURCE_PATH}` by convention,
+and is the path to apply the patches in.
+
+`z_vcpkg_apply_patches` will take the list of `<patch>`es,
+which are by default relative to the port directory,
+and apply them in order using `git apply`.
+Generally, these `<patch>`es take the form of `some.patch`
+to select patches in the port directory.
+One may also download patches and use `${VCPKG_DOWNLOADS}/path/to/some.patch`.
+
+If `QUIET` is not passed, it is a fatal error for a patch to fail to apply;
+otherwise, if `QUIET` is passed, no message is printed.
+This should only be used for edge cases, such as patches that are known to fail even on a clean source tree.
+
+## Source
+[scripts/cmake/z\_vcpkg\_apply\_patches.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_apply_patches.cmake)
diff --git a/docs/maintainers/internal/z_vcpkg_function_arguments.md b/docs/maintainers/internal/z_vcpkg_function_arguments.md
index e60407f20..a31d8b33c 100644
--- a/docs/maintainers/internal/z_vcpkg_function_arguments.md
+++ b/docs/maintainers/internal/z_vcpkg_function_arguments.md
@@ -1,5 +1,7 @@
 # z_vcpkg_function_arguments
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/).
+
 **Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
 Get a list of the arguments which were passed in.
 Unlike `ARGV`, which is simply the arguments joined with `;`,
@@ -24,4 +26,4 @@ endfunction()
 ```
 
 ## Source
-[scripts/cmake/z_vcpkg_function_arguments.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_function_arguments.cmake)
+[scripts/cmake/z\_vcpkg\_function\_arguments.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_function_arguments.cmake)
diff --git a/docs/maintainers/internal/z_vcpkg_prettify_command_line.md b/docs/maintainers/internal/z_vcpkg_prettify_command_line.md
index 1b7636630..9bbb1c457 100644
--- a/docs/maintainers/internal/z_vcpkg_prettify_command_line.md
+++ b/docs/maintainers/internal/z_vcpkg_prettify_command_line.md
@@ -1,5 +1,7 @@
 # z_vcpkg_prettify_command_line
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/).
+
 **Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
 Turn a command line into a formatted string.
 
@@ -16,4 +18,4 @@ This command is for internal use, when printing out to a message.
 * `scripts/cmake/vcpkg_execute_required_process_repeat.cmake`
 
 ## Source
-[scripts/cmake/z_vcpkg_prettify_command_line.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_prettify_command_line.cmake)
+[scripts/cmake/z\_vcpkg\_prettify\_command\_line.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_prettify_command_line.cmake)
diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md
index c92abc2c6..fbad18c8e 100644
--- a/docs/maintainers/portfile-functions.md
+++ b/docs/maintainers/portfile-functions.md
@@ -1,10 +1,10 @@
-<!-- Run regenerate.ps1 to extract documentation from scripts/cmake/*.cmake -->
+<!-- Run regenerate.ps1 to extract scripts documentation -->
 
 # Portfile helper functions
 - [execute\_process](execute_process.md)
 - [vcpkg\_acquire\_msys](vcpkg_acquire_msys.md)
 - [vcpkg\_add\_to\_path](vcpkg_add_to_path.md)
-- [vcpkg\_apply\_patches](vcpkg_apply_patches.md)
+- [vcpkg\_apply\_patches](vcpkg_apply_patches.md) (deprecated)
 - [vcpkg\_build\_cmake](vcpkg_build_cmake.md)
 - [vcpkg\_build\_gn](vcpkg_build_gn.md)
 - [vcpkg\_build\_make](vcpkg_build_make.md)
@@ -58,5 +58,18 @@
 ## Internal Functions
 
 - [vcpkg\_internal\_get\_cmake\_vars](internal/vcpkg_internal_get_cmake_vars.md)
+- [z\_vcpkg\_apply\_patches](internal/z_vcpkg_apply_patches.md)
 - [z\_vcpkg\_function\_arguments](internal/z_vcpkg_function_arguments.md)
 - [z\_vcpkg\_prettify\_command\_line](internal/z_vcpkg_prettify_command_line.md)
+
+## Scripts from Ports
+
+### [vcpkg-cmake](ports/vcpkg-cmake.md)
+
+- [vcpkg\_cmake\_build](ports/vcpkg-cmake/vcpkg_cmake_build.md)
+- [vcpkg\_cmake\_configure](ports/vcpkg-cmake/vcpkg_cmake_configure.md)
+- [vcpkg\_cmake\_install](ports/vcpkg-cmake/vcpkg_cmake_install.md)
+
+### [vcpkg-cmake-config](ports/vcpkg-cmake-config.md)
+
+- [vcpkg\_cmake\_config\_fixup](ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md)
diff --git a/docs/maintainers/ports/vcpkg-cmake-config.md b/docs/maintainers/ports/vcpkg-cmake-config.md
new file mode 100644
index 000000000..18e7bb9ac
--- /dev/null
+++ b/docs/maintainers/ports/vcpkg-cmake-config.md
@@ -0,0 +1,10 @@
+# vcpkg-cmake-config
+
+`vcpkg-cmake-config` provides `vcpkg_cmake_config_fixup()`,
+a function which both:
+
+- Fixes common mistakes in port build systems, like using absolute paths
+- Merges the debug and release config files.
+
+This function should almost always be used when a port has `*config.cmake` files,
+even when the buildsystem of the project is not CMake.
diff --git a/docs/maintainers/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md b/docs/maintainers/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md
new file mode 100644
index 000000000..43d5c56cf
--- /dev/null
+++ b/docs/maintainers/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md
@@ -0,0 +1,51 @@
+# vcpkg_cmake_config_fixup
+
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md).
+
+Merge release and debug CMake targets and configs to support multiconfig generators.
+
+Additionally corrects common issues with targets, such as absolute paths and incorrectly placed binaries.
+
+```cmake
+vcpkg_cmake_config_fixup(
+    [PACKAGE_NAME <name>]
+    [CONFIG_PATH <config-directory>]
+    [DO_NOT_DELETE_CONFIG_PATH_PARENT]
+    [NO_PREFIX_CORRECTION]
+)
+```
+
+For many ports, `vcpkg_cmake_config_fixup()` on its own should work,
+as `PACKAGE_NAME` defaults to `${PORT}` and `CONFIG_PATH` defaults to `share/${PACKAGE_NAME}`.
+For ports where the package name passed to `find_package` is distinct from the port name,
+`PACKAGE_NAME` should be changed to be that name instead.
+For ports where the directory of the `*config.cmake` files cannot be set,
+use the `CONFIG_PATH` to change the directory where the files come from.
+
+By default the parent directory of CONFIG_PATH is removed if it is named "cmake".
+Passing the `DO_NOT_DELETE_PARENT_CONFIG_PATH` option disable such behavior,
+as it is convenient for ports that install
+more than one CMake package configuration file.
+
+The `NO_PREFIX_CORRECTION` option disables the correction of `_IMPORT_PREFIX`
+done by vcpkg due to moving the config files.
+Currently the correction does not take into account how the files are moved,
+and applies a rather simply correction which in some cases will yield the wrong results.
+
+## How it Works
+
+1. Moves `/debug/<CONFIG_PATH>/*targets-debug.cmake` to `/share/${PACKAGE_NAME}`.
+2. Removes `/debug/<CONFIG_PATH>/*config.cmake`.
+3. Transform all references matching `/bin/*.exe` to `/tools/<port>/*.exe` on Windows.
+4. Transform all references matching `/bin/*` to `/tools/<port>/*` on other platforms.
+5. Fixes `${_IMPORT_PREFIX}` in auto generated targets.
+6. Replace `${CURRENT_INSTALLED_DIR}` with `${_IMPORT_PREFIX}` in configs and targets.
+
+## Examples
+
+* [concurrentqueue](https://github.com/Microsoft/vcpkg/blob/master/ports/concurrentqueue/portfile.cmake)
+* [curl](https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake)
+* [nlohmann-json](https://github.com/Microsoft/vcpkg/blob/master/ports/nlohmann-json/portfile.cmake)
+
+## Source
+[ports/vcpkg-cmake-config/vcpkg\_cmake\_config\_fixup.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.cmake)
diff --git a/docs/maintainers/ports/vcpkg-cmake.md b/docs/maintainers/ports/vcpkg-cmake.md
new file mode 100644
index 000000000..b84c58869
--- /dev/null
+++ b/docs/maintainers/ports/vcpkg-cmake.md
@@ -0,0 +1,7 @@
+# vcpkg-cmake
+
+This port contains cmake functions for dealing with a CMake buildsystem.
+
+In the common case, `vcpkg_cmake_configure()` (with appropriate arguments)
+followed by `vcpkg_cmake_install()` will be enough to build and install a port.
+`vcpkg_cmake_build()` is provided for more complex cases.
diff --git a/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_build.md b/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_build.md
new file mode 100644
index 000000000..be64ca1a6
--- /dev/null
+++ b/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_build.md
@@ -0,0 +1,36 @@
+# vcpkg_cmake_build
+
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/ports/vcpkg-cmake/vcpkg_cmake_build.md).
+
+Build a cmake project.
+
+```cmake
+vcpkg_cmake_build(
+    [TARGET <target>]
+    [LOGFILE_BASE <base>]
+    [DISABLE_PARALLEL]
+    [ADD_BIN_TO_PATH]
+)
+```
+
+`vcpkg_cmake_build` builds an already-configured cmake project.
+You can use the alias [`vcpkg_cmake_install()`] function
+if your CMake build system supports the `install` TARGET,
+and this is something we recommend doing whenever possible.
+Otherwise, you can use `TARGET` to set the target to build.
+This function defaults to not passing a target to cmake.
+
+`LOGFILE_BASE` is used to set the base of the logfile names;
+by default, this is `build`, and thus the logfiles end up being something like
+`build-x86-windows-dbg.log`; if you use `vcpkg_cmake_install`,
+this is set to `install`, so you'll get log names like `install-x86-windows-dbg.log`.
+
+For build systems that are buggy when run in parallel,
+using `DISABLE_PARALLEL` will run the build with only one job.
+
+Finally, `ADD_BIN_TO_PATH` adds the appropriate (either release or debug)
+`bin/` directories to the path during the build,
+such that executables run during the build will be able to access those DLLs.
+
+## Source
+[ports/vcpkg-cmake/vcpkg\_cmake\_build.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_build.cmake)
diff --git a/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_configure.md b/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_configure.md
new file mode 100644
index 000000000..23e8c5cf9
--- /dev/null
+++ b/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_configure.md
@@ -0,0 +1,76 @@
+# vcpkg_cmake_configure
+
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/ports/vcpkg-cmake/vcpkg_cmake_configure.md).
+
+Configure a CMake buildsystem.
+
+```cmake
+vcpkg_cmake_configure(
+    SOURCE_PATH <source-path>
+    [LOGFILE_BASE <logname-base>]
+    [DISABLE_PARALLEL_CONFIGURE]
+    [NO_CHARSET_FLAG]
+    [WINDOWS_USE_MSBUILD]
+    [GENERATOR <generator>]
+    [OPTIONS
+        <configure-setting>...]
+    [OPTIONS_RELEASE
+        <configure-setting>...]
+    [OPTIONS_DEBUG
+        <configure-setting>...]
+)
+```
+
+`vcpkg_cmake_configure` configures a CMake build system for use with
+`vcpkg_cmake_buildsystem_build` and `vcpkg_cmake_buildsystem_install`.
+`source-path` is where the source is located; by convention,
+this is usually `${SOURCE_PATH}`, which is set by one of the `vcpkg_from_*` functions.
+This function configures the build system for both Debug and Release builds by default,
+assuming that `VCPKG_BUILD_TYPE` is not set; if it is, then it will only configure for
+that build type.
+
+Use the `OPTIONS` argument to set the configure settings for both release and debug,
+and use `OPTIONS_RELEASE` and `OPTIONS_DEBUG` to set the configure settings for
+release only and debug only repsectively.
+
+By default, when possible, `vcpkg_cmake_configure` uses [ninja-build]
+as its build system. If the `WINDOWS_USE_MSBUILD` argument is passed, then
+`vcpkg_cmake_configure` will use a Visual Studio generator on Windows;
+on every other platform, `vcpkg_cmake_configure` just uses Ninja.
+
+[ninja-build]: https://ninja-build.org/
+
+Additionally, one may pass the specific generator a port should use with `GENERATOR`.
+This is useful if some project-specific buildsystem
+has been wrapped in a CMake build system that doesn't perform an actual build.
+If used for this purpose, it should be set to `"NMake Makefiles"`.
+`vcpkg_cmake_buildsystem_build` and `install` do not support this being set to anything
+except for NMake.
+
+For libraries which cannot be configured in parallel,
+pass the `DISABLE_PARALLEL_CONFIGURE` flag. This is needed, for example,
+if the library's build system writes back into the source directory during configure.
+This also disables the `CMAKE_DISABLE_SOURCE_CHANGES` option.
+
+By default, this function adds flags to `CMAKE_C_FLAGS` and `CMAKE_CXX_FLAGS`
+which set the default character set to utf-8 for MSVC.
+If the library sets its own code page, pass the `NO_CHARSET_FLAG` option.
+
+`LOGFILE_BASE` is used to set the base of the logfile names;
+by default, this is `config`, and thus the logfiles end up being something like
+`config-x86-windows-dbg.log`. You can set it to anything you like;
+if you set it to `config-the-first`,
+you'll get something like `config-the-first-x86-windows.dbg.log`.
+
+## Notes
+This command supplies many common arguments to CMake. To see the full list, examine the source.
+
+## Examples
+
+* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
+* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
+* [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake)
+* [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
+
+## Source
+[ports/vcpkg-cmake/vcpkg\_cmake\_configure.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_configure.cmake)
diff --git a/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_install.md b/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_install.md
new file mode 100644
index 000000000..d328825bd
--- /dev/null
+++ b/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_install.md
@@ -0,0 +1,25 @@
+# vcpkg_cmake_install
+
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/ports/vcpkg-cmake/vcpkg_cmake_install.md).
+
+Build and install a cmake project.
+
+```cmake
+vcpkg_cmake_install(
+    [DISABLE_PARALLEL]
+    [ADD_BIN_TO_PATH]
+)
+```
+
+`vcpkg_cmake_install` transparently forwards to [`vcpkg_cmake_build()`],
+with additional parameters to set the `TARGET` to `install`,
+and to set the `LOGFILE_ROOT` to `install` as well.
+
+[`vcpkg_cmake_build()`]: vcpkg_cmake_build.cmake
+
+## Examples:
+
+* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
+
+## Source
+[ports/vcpkg-cmake/vcpkg\_cmake\_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_install.cmake)
diff --git a/docs/maintainers/vcpkg_acquire_msys.md b/docs/maintainers/vcpkg_acquire_msys.md
index d4969323e..6106a5ada 100644
--- a/docs/maintainers/vcpkg_acquire_msys.md
+++ b/docs/maintainers/vcpkg_acquire_msys.md
@@ -1,5 +1,7 @@
 # vcpkg_acquire_msys
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_acquire_msys.md).
+
 Download and prepare an MSYS2 instance.
 
 ## Usage
@@ -55,4 +57,4 @@ vcpkg_execute_required_process(
 * [libvpx](https://github.com/Microsoft/vcpkg/blob/master/ports/libvpx/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_acquire_msys.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_acquire_msys.cmake)
+[scripts/cmake/vcpkg\_acquire\_msys.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_acquire_msys.cmake)
diff --git a/docs/maintainers/vcpkg_add_to_path.md b/docs/maintainers/vcpkg_add_to_path.md
index 243757638..9c982b41e 100644
--- a/docs/maintainers/vcpkg_add_to_path.md
+++ b/docs/maintainers/vcpkg_add_to_path.md
@@ -1,5 +1,7 @@
 # vcpkg_add_to_path
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_add_to_path.md).
+
 Add a directory or directories to the PATH environment variable
 
 ```cmake
@@ -22,4 +24,4 @@ If no paths are passed, then nothing will be done.
 * [z3](https://github.com/Microsoft/vcpkg/blob/master/ports/z3/portfile.cmake#L13)
 
 ## Source
-[scripts/cmake/vcpkg_add_to_path.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_add_to_path.cmake)
+[scripts/cmake/vcpkg\_add\_to\_path.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_add_to_path.cmake)
diff --git a/docs/maintainers/vcpkg_apply_patches.md b/docs/maintainers/vcpkg_apply_patches.md
index cfcf6ff15..460593b34 100644
--- a/docs/maintainers/vcpkg_apply_patches.md
+++ b/docs/maintainers/vcpkg_apply_patches.md
@@ -1,8 +1,11 @@
 # vcpkg_apply_patches
 
-Apply a set of patches to a source tree. This function is deprecated in favor of the `PATCHES` argument to `vcpkg_from_github()` et al.
+**This function has been deprecated in favor of the `PATCHES` argument to `vcpkg_from_github()` et al.**
+
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_apply_patches.md).
+
+Apply a set of patches to a source tree.
 
-## Usage
 ```cmake
 vcpkg_apply_patches(
     SOURCE_PATH <${SOURCE_PATH}>
@@ -11,24 +14,5 @@ vcpkg_apply_patches(
 )
 ```
 
-## Parameters
-### SOURCE_PATH
-The source path in which apply the patches. By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
-
-### PATCHES
-A list of patches that are applied to the source tree.
-
-Generally, these take the form of `${CMAKE_CURRENT_LIST_DIR}/some.patch` to select patches in the `port\<port>\` directory.
-
-### QUIET
-Disables the warning message upon failure.
-
-This should only be used for edge cases, such as patches that are known to fail even on a clean source tree.
-
-## Examples
-
-* [libbson](https://github.com/Microsoft/vcpkg/blob/master/ports/libbson/portfile.cmake)
-* [gdal](https://github.com/Microsoft/vcpkg/blob/master/ports/gdal/portfile.cmake)
-
 ## Source
-[scripts/cmake/vcpkg_apply_patches.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_apply_patches.cmake)
+[scripts/cmake/vcpkg\_apply\_patches.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_apply_patches.cmake)
diff --git a/docs/maintainers/vcpkg_build_cmake.md b/docs/maintainers/vcpkg_build_cmake.md
index f75d050c3..0856fb71d 100644
--- a/docs/maintainers/vcpkg_build_cmake.md
+++ b/docs/maintainers/vcpkg_build_cmake.md
@@ -1,5 +1,9 @@
 # vcpkg_build_cmake
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_build_cmake.md).
+
+**This function has been deprecated in favor of `vcpkg_cmake_build` from the vcpkg-cmake port.**
+
 Build a cmake project.
 
 ## Usage:
@@ -31,4 +35,4 @@ You can use the alias [`vcpkg_install_cmake()`](vcpkg_configure_cmake.md) functi
 * [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_build_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_cmake.cmake)
+[scripts/cmake/vcpkg\_build\_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_cmake.cmake)
diff --git a/docs/maintainers/vcpkg_build_gn.md b/docs/maintainers/vcpkg_build_gn.md
index 0f5f2e8b0..20930b683 100644
--- a/docs/maintainers/vcpkg_build_gn.md
+++ b/docs/maintainers/vcpkg_build_gn.md
@@ -1,5 +1,7 @@
 # vcpkg_build_gn
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_build_gn.md).
+
 Build a GN project
 
 ## Usage:
@@ -14,4 +16,4 @@ vcpkg_build_gn(
 Only build the specified targets.
 
 ## Source
-[scripts/cmake/vcpkg_build_gn.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_gn.cmake)
+[scripts/cmake/vcpkg\_build\_gn.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_gn.cmake)
diff --git a/docs/maintainers/vcpkg_build_make.md b/docs/maintainers/vcpkg_build_make.md
index 6da602f3e..9f06d5cfc 100644
--- a/docs/maintainers/vcpkg_build_make.md
+++ b/docs/maintainers/vcpkg_build_make.md
@@ -1,5 +1,7 @@
 # vcpkg_build_make
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_build_make.md).
+
 Build a linux makefile project.
 
 ## Usage:
@@ -49,4 +51,4 @@ You can use the alias [`vcpkg_install_make()`](vcpkg_install_make.md) function i
 * [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_build_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_make.cmake)
+[scripts/cmake/vcpkg\_build\_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_make.cmake)
diff --git a/docs/maintainers/vcpkg_build_msbuild.md b/docs/maintainers/vcpkg_build_msbuild.md
index e011bfbc8..3a77bed0d 100644
--- a/docs/maintainers/vcpkg_build_msbuild.md
+++ b/docs/maintainers/vcpkg_build_msbuild.md
@@ -1,5 +1,7 @@
 # vcpkg_build_msbuild
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_build_msbuild.md).
+
 Build a msbuild-based project. Deprecated in favor of `vcpkg_install_msbuild()`.
 
 ## Usage
@@ -61,4 +63,4 @@ Additional options passed to msbuild for Debug builds. These are in addition to
 * [chakracore](https://github.com/Microsoft/vcpkg/blob/master/ports/chakracore/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_build_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_msbuild.cmake)
+[scripts/cmake/vcpkg\_build\_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_msbuild.cmake)
diff --git a/docs/maintainers/vcpkg_build_ninja.md b/docs/maintainers/vcpkg_build_ninja.md
index 758249966..a74de2c6c 100644
--- a/docs/maintainers/vcpkg_build_ninja.md
+++ b/docs/maintainers/vcpkg_build_ninja.md
@@ -1,5 +1,7 @@
 # vcpkg_build_ninja
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_build_ninja.md).
+
 Build a ninja project
 
 ## Usage:
@@ -14,4 +16,4 @@ vcpkg_build_ninja(
 Only build the specified targets.
 
 ## Source
-[scripts/cmake/vcpkg_build_ninja.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_ninja.cmake)
+[scripts/cmake/vcpkg\_build\_ninja.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_ninja.cmake)
diff --git a/docs/maintainers/vcpkg_build_nmake.md b/docs/maintainers/vcpkg_build_nmake.md
index 55257b50d..33160d429 100644
--- a/docs/maintainers/vcpkg_build_nmake.md
+++ b/docs/maintainers/vcpkg_build_nmake.md
@@ -1,5 +1,7 @@
 # vcpkg_build_nmake
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_build_nmake.md).
+
 Build a msvc makefile project.
 
 ## Usage:
@@ -73,4 +75,4 @@ You can use the alias [`vcpkg_install_nmake()`](vcpkg_install_nmake.md) function
 * [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_build_nmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_nmake.cmake)
+[scripts/cmake/vcpkg\_build\_nmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_nmake.cmake)
diff --git a/docs/maintainers/vcpkg_build_qmake.md b/docs/maintainers/vcpkg_build_qmake.md
index c899155bd..96d388f3a 100644
--- a/docs/maintainers/vcpkg_build_qmake.md
+++ b/docs/maintainers/vcpkg_build_qmake.md
@@ -1,5 +1,7 @@
 # vcpkg_build_qmake
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_build_qmake.md).
+
 Build a qmake-based project, previously configured using vcpkg_configure_qmake.
 
 ```cmake
@@ -7,4 +9,4 @@ vcpkg_build_qmake()
 ```
 
 ## Source
-[scripts/cmake/vcpkg_build_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_qmake.cmake)
+[scripts/cmake/vcpkg\_build\_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_qmake.cmake)
diff --git a/docs/maintainers/vcpkg_buildpath_length_warning.md b/docs/maintainers/vcpkg_buildpath_length_warning.md
index fdc7adeda..1b09fca5e 100644
--- a/docs/maintainers/vcpkg_buildpath_length_warning.md
+++ b/docs/maintainers/vcpkg_buildpath_length_warning.md
@@ -1,5 +1,7 @@
 # vcpkg_buildpath_length_warning
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_buildpath_length_warning.md).
+
 Warns the user if their vcpkg installation path might be too long for the package they're installing.
 
 ```cmake
@@ -11,4 +13,4 @@ path to `buildtrees` is bigger than `N`. Note that this is simply a warning,
 and isn't relied on for correctness.
 
 ## Source
-[scripts/cmake/vcpkg_buildpath_length_warning.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_buildpath_length_warning.cmake)
+[scripts/cmake/vcpkg\_buildpath\_length\_warning.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_buildpath_length_warning.cmake)
diff --git a/docs/maintainers/vcpkg_check_features.md b/docs/maintainers/vcpkg_check_features.md
index beb599664..1fb8bb859 100644
--- a/docs/maintainers/vcpkg_check_features.md
+++ b/docs/maintainers/vcpkg_check_features.md
@@ -1,53 +1,45 @@
 # vcpkg_check_features
+
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_check_features.md).
 Check if one or more features are a part of a package installation.
 
-## Usage
 ```cmake
 vcpkg_check_features(
-  OUT_FEATURE_OPTIONS <FEATURE_OPTIONS>
-  [FEATURES
-    <cuda> <WITH_CUDA>
-    [<opencv> <WITH_OPENCV>]
-    ...]
-  [INVERTED_FEATURES
-    <cuda> <IGNORE_PACKAGE_CUDA>
-    [<opencv> <IGNORE_PACKAGE_OPENCV>]
-    ...]
+    OUT_FEATURE_OPTIONS <out-var>
+    [PREFIX <prefix>]
+    [FEATURES
+        [<feature-name> <feature-var>]...
+        ]
+    [INVERTED_FEATURES
+        [<feature-name> <feature-var>]...
+        ]
 )
 ```
-`vcpkg_check_features()` accepts these parameters:
-
-* `OUT_FEATURE_OPTIONS`:
-  An output variable, the function will clear the variable passed to `OUT_FEATURE_OPTIONS`
-  and then set it to contain a list of option definitions (`-D<OPTION_NAME>=ON|OFF`).
-
-  This should be set to `FEATURE_OPTIONS` by convention.
-
-* `FEATURES`:
-  A list of (`FEATURE_NAME`, `OPTION_NAME`) pairs.
-  For each `FEATURE_NAME` a definition is added to `OUT_FEATURE_OPTIONS` in the form of:
-
-    * `-D<OPTION_NAME>=ON`, if a feature is specified for installation,
-    * `-D<OPTION_NAME>=OFF`, otherwise.
-
-* `INVERTED_FEATURES`:
-  A list of (`FEATURE_NAME`, `OPTION_NAME`) pairs, uses reversed logic from `FEATURES`.
-  For each `FEATURE_NAME` a definition is added to `OUT_FEATURE_OPTIONS` in the form of:
-
-    * `-D<OPTION_NAME>=OFF`, if a feature is specified for installation,
-    * `-D<OPTION_NAME>=ON`, otherwise.
 
+The `<out-var>` should be set to `FEATURE_OPTIONS` by convention.
 
-## Notes
+`vcpkg_check_features()` will:
 
-The `FEATURES` name parameter can be omitted if no `INVERTED_FEATURES` are used.
+- for each `<feature-name>` passed in `FEATURES`:
+    - if the feature is set, add `-D<feature-var>=ON` to `<out-var>`,
+      and set `<prefix>_<feature-var>` to ON.
+    - if the feature is not set, add `-D<feature-var>=OFF` to `<out-var>`,
+      and set `<prefix>_<feature-var>` to OFF.
+- for each `<feature-name>` passed in `INVERTED_FEATURES`:
+    - if the feature is set, add `-D<feature-var>=OFF` to `<out-var>`,
+      and set `<prefix>_<feature-var>` to OFF.
+    - if the feature is not set, add `-D<feature-var>=ON` to `<out-var>`,
+      and set `<prefix>_<feature-var>` to ON.
 
-At least one (`FEATURE_NAME`, `OPTION_NAME`) pair must be passed to the function call.
+If `<prefix>` is not passed, then the feature vars set are simply `<feature-var>`,
+not `_<feature-var>`.
 
-Arguments passed to `FEATURES` and `INVERTED_FEATURES` are not validated to prevent duplication.
-If the same (`FEATURE_NAME`, `OPTION_NAME`) pair is passed to both lists,
-two conflicting definitions are added to `OUT_FEATURE_OPTIONS`.
+If `INVERTED_FEATURES` is not passed, then the `FEATURES` keyword is optional.
+This behavior is deprecated.
 
+If the same `<feature-var>` is passed multiple times,
+then `vcpkg_check_features` will cause a fatal error,
+since that is a bug.
 
 ## Examples
 
@@ -58,18 +50,18 @@ $ ./vcpkg install mimalloc[asm,secure]
 
 # ports/mimalloc/portfile.cmake
 vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
-  # Keyword FEATURES is optional if INVERTED_FEATURES are not used
-    asm       MI_SEE_ASM
-    override  MI_OVERRIDE
-    secure    MI_SECURE
+    FEATURES
+        asm       MI_SEE_ASM
+        override  MI_OVERRIDE
+        secure    MI_SECURE
 )
 
 vcpkg_configure_cmake(
-  SOURCE_PATH ${SOURCE_PATH}
-  PREFER_NINJA
-  OPTIONS
-    # Expands to "-DMI_SEE_ASM=ON; -DMI_OVERRIDE=OFF; -DMI_SECURE=ON"
-    ${FEATURE_OPTIONS}
+    SOURCE_PATH ${SOURCE_PATH}
+    PREFER_NINJA
+    OPTIONS
+        # Expands to "-DMI_SEE_ASM=ON;-DMI_OVERRIDE=OFF;-DMI_SECURE=ON"
+        ${FEATURE_OPTIONS}
 )
 ```
 
@@ -79,18 +71,18 @@ vcpkg_configure_cmake(
 $ ./vcpkg install cpprestsdk[websockets]
 
 # ports/cpprestsdk/portfile.cmake
-vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
-  INVERTED_FEATURES # <- Keyword INVERTED_FEATURES required
-    brotli      CPPREST_EXCLUDE_BROTLI
-    websockets  CPPREST_EXCLUDE_WEBSOCKETS
+vcpkg_check_features(
+    INVERTED_FEATURES
+        brotli      CPPREST_EXCLUDE_BROTLI
+        websockets  CPPREST_EXCLUDE_WEBSOCKETS
 )
 
 vcpkg_configure_cmake(
-  SOURCE_PATH ${SOURCE_PATH}
-  PREFER_NINJA
-  OPTIONS
-    # Expands to "-DCPPREST_EXCLUDE_BROTLI=ON; -DCPPREST_EXCLUDE_WEBSOCKETS=OFF"
-    ${FEATURE_OPTIONS}
+    SOURCE_PATH ${SOURCE_PATH}
+    PREFER_NINJA
+    OPTIONS
+        # Expands to "-DCPPREST_EXCLUDE_BROTLI=ON;-DCPPREST_EXCLUDE_WEBSOCKETS=OFF"
+        ${FEATURE_OPTIONS}
 )
 ```
 
@@ -100,18 +92,19 @@ vcpkg_configure_cmake(
 $ ./vcpkg install pcl[cuda]
 
 # ports/pcl/portfile.cmake
-vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
-    cuda  WITH_CUDA
-    cuda  BUILD_CUDA
-    cuda  BUILD_GPU
+vcpkg_check_features(
+    FEATURES
+        cuda  WITH_CUDA
+        cuda  BUILD_CUDA
+        cuda  BUILD_GPU
 )
 
 vcpkg_configure_cmake(
-  SOURCE_PATH ${SOURCE_PATH}
-  PREFER_NINJA
-  OPTIONS
-    # Expands to "-DWITH_CUDA=ON; -DBUILD_CUDA=ON; -DBUILD_GPU=ON"
-    ${FEATURE_OPTIONS}
+    SOURCE_PATH ${SOURCE_PATH}
+    PREFER_NINJA
+    OPTIONS
+        # Expands to "-DWITH_CUDA=ON;-DBUILD_CUDA=ON;-DBUILD_GPU=ON"
+        ${FEATURE_OPTIONS}
 )
 ```
 
@@ -121,19 +114,19 @@ vcpkg_configure_cmake(
 $ ./vcpkg install rocksdb[tbb]
 
 # ports/rocksdb/portfile.cmake
-vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
-  FEATURES # <- Keyword FEATURES is required because INVERTED_FEATURES are being used
-    tbb   WITH_TBB
-  INVERTED_FEATURES
-    tbb   ROCKSDB_IGNORE_PACKAGE_TBB
+vcpkg_check_features(
+    FEATURES
+        tbb   WITH_TBB
+    INVERTED_FEATURES
+        tbb   ROCKSDB_IGNORE_PACKAGE_TBB
 )
 
 vcpkg_configure_cmake(
-  SOURCE_PATH ${SOURCE_PATH}
-  PREFER_NINJA
-  OPTIONS
-    # Expands to "-DWITH_TBB=ON; -DROCKSDB_IGNORE_PACKAGE_TBB=OFF"
-    ${FEATURE_OPTIONS}
+    SOURCE_PATH ${SOURCE_PATH}
+    PREFER_NINJA
+    OPTIONS
+        # Expands to "-DWITH_TBB=ON;-DROCKSDB_IGNORE_PACKAGE_TBB=OFF"
+        ${FEATURE_OPTIONS}
 )
 ```
 
@@ -144,4 +137,4 @@ vcpkg_configure_cmake(
 * [rocksdb](https://github.com/microsoft/vcpkg/blob/master/ports/rocksdb/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_check_features.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_features.cmake)
+[scripts/cmake/vcpkg\_check\_features.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_features.cmake)
diff --git a/docs/maintainers/vcpkg_check_linkage.md b/docs/maintainers/vcpkg_check_linkage.md
index 9c0c823ad..dbda0a33c 100644
--- a/docs/maintainers/vcpkg_check_linkage.md
+++ b/docs/maintainers/vcpkg_check_linkage.md
@@ -1,5 +1,7 @@
 # vcpkg_check_linkage
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_check_linkage.md).
+
 Asserts the available library and CRT linkage options for the port.
 
 ## Usage
@@ -33,4 +35,4 @@ This command will either alter the settings for `VCPKG_LIBRARY_LINKAGE` or fail,
 * [abseil](https://github.com/Microsoft/vcpkg/blob/master/ports/abseil/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_check_linkage.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_linkage.cmake)
+[scripts/cmake/vcpkg\_check\_linkage.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_linkage.cmake)
diff --git a/docs/maintainers/vcpkg_clean_executables_in_bin.md b/docs/maintainers/vcpkg_clean_executables_in_bin.md
index 26f948cbc..518154642 100644
--- a/docs/maintainers/vcpkg_clean_executables_in_bin.md
+++ b/docs/maintainers/vcpkg_clean_executables_in_bin.md
@@ -1,5 +1,7 @@
 # vcpkg_clean_executables_in_bin
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_clean_executables_in_bin.md).
+
 Remove specified executables found in `${CURRENT_PACKAGES_DIR}/bin` and `${CURRENT_PACKAGES_DIR}/debug/bin`. If, after all specified executables have been removed, and the `bin` and `debug/bin` directories are empty, then also delete `bin` and `debug/bin` directories.
 
 ## Usage
@@ -20,4 +22,4 @@ Generally, there is no need to call this function manually. Instead, pass an ext
 * [czmq](https://github.com/microsoft/vcpkg/blob/master/ports/czmq/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_clean_executables_in_bin.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_clean_executables_in_bin.cmake)
+[scripts/cmake/vcpkg\_clean\_executables\_in\_bin.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_clean_executables_in_bin.cmake)
diff --git a/docs/maintainers/vcpkg_clean_msbuild.md b/docs/maintainers/vcpkg_clean_msbuild.md
index 1837bccbb..d83585974 100644
--- a/docs/maintainers/vcpkg_clean_msbuild.md
+++ b/docs/maintainers/vcpkg_clean_msbuild.md
@@ -1,5 +1,7 @@
 # vcpkg_clean_msbuild
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_clean_msbuild.md).
+
 Clean intermediate files generated by `vcpkg_install_msbuild()`.
 
 ## Usage
@@ -12,4 +14,4 @@ vcpkg_clean_msbuild()
 * [xalan-c](https://github.com/Microsoft/vcpkg/blob/master/ports/xalan-c/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_clean_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_clean_msbuild.cmake)
+[scripts/cmake/vcpkg\_clean\_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_clean_msbuild.cmake)
diff --git a/docs/maintainers/vcpkg_common_definitions.md b/docs/maintainers/vcpkg_common_definitions.md
index b93ef4cbd..497900fd0 100644
--- a/docs/maintainers/vcpkg_common_definitions.md
+++ b/docs/maintainers/vcpkg_common_definitions.md
@@ -1,8 +1,9 @@
 # vcpkg_common_definitions
 
-File contains helpful variabls for portfiles which are commonly needed or used.
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_common_definitions.md).
+
+This file defines the following variabls which are commonly needed or used in portfiles:
 
-## The following variables are available:
 ```cmake
 VCPKG_TARGET_IS_<target>                 with <target> being one of the following: WINDOWS, UWP, LINUX, OSX, ANDROID, FREEBSD, OPENBSD. only defined if <target>
 VCPKG_HOST_IS_<target>                   with <host> being one of the following: WINDOWS, LINUX, OSX, FREEBSD, OPENBSD. only defined if <host>
@@ -25,4 +26,4 @@ Furthermore the variables CMAKE_FIND_LIBRARY_(PREFIXES|SUFFIXES) are also define
 portfiles are able to use find_library calls to discover dependent libraries within the current triplet for ports.
 
 ## Source
-[scripts/cmake/vcpkg_common_definitions.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_common_definitions.cmake)
+[scripts/cmake/vcpkg\_common\_definitions.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_common_definitions.cmake)
diff --git a/docs/maintainers/vcpkg_configure_cmake.md b/docs/maintainers/vcpkg_configure_cmake.md
index bd1a31565..3800e32ff 100644
--- a/docs/maintainers/vcpkg_configure_cmake.md
+++ b/docs/maintainers/vcpkg_configure_cmake.md
@@ -1,5 +1,9 @@
 # vcpkg_configure_cmake
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_configure_cmake.md).
+
+**This function has been deprecated in favor of `vcpkg_cmake_configure` from the vcpkg-cmake port.**
+
 Configure CMake for Debug and Release builds of a project.
 
 ## Usage
@@ -65,4 +69,4 @@ This command supplies many common arguments to CMake. To see the full list, exam
 * [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_configure_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_cmake.cmake)
+[scripts/cmake/vcpkg\_configure\_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_cmake.cmake)
diff --git a/docs/maintainers/vcpkg_configure_gn.md b/docs/maintainers/vcpkg_configure_gn.md
index 47742be58..e7a3ef35c 100644
--- a/docs/maintainers/vcpkg_configure_gn.md
+++ b/docs/maintainers/vcpkg_configure_gn.md
@@ -1,5 +1,7 @@
 # vcpkg_configure_gn
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_configure_gn.md).
+
 Generate Ninja (GN) targets
 
 ## Usage:
@@ -27,4 +29,4 @@ Options to be passed to the debug target.
 Options to be passed to the release target.
 
 ## Source
-[scripts/cmake/vcpkg_configure_gn.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_gn.cmake)
+[scripts/cmake/vcpkg\_configure\_gn.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_gn.cmake)
diff --git a/docs/maintainers/vcpkg_configure_make.md b/docs/maintainers/vcpkg_configure_make.md
index fe18edd8b..00d24f424 100644
--- a/docs/maintainers/vcpkg_configure_make.md
+++ b/docs/maintainers/vcpkg_configure_make.md
@@ -1,5 +1,7 @@
 # vcpkg_configure_make
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_configure_make.md).
+
 Configure configure for Debug and Release builds of a project.
 
 ## Usage
@@ -88,4 +90,4 @@ This command supplies many common arguments to configure. To see the full list,
 * [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_configure_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_make.cmake)
+[scripts/cmake/vcpkg\_configure\_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_make.cmake)
diff --git a/docs/maintainers/vcpkg_configure_meson.md b/docs/maintainers/vcpkg_configure_meson.md
index 803ad0b17..8b1681291 100644
--- a/docs/maintainers/vcpkg_configure_meson.md
+++ b/docs/maintainers/vcpkg_configure_meson.md
@@ -1,5 +1,7 @@
 # vcpkg_configure_meson
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_configure_meson.md).
+
 Configure Meson for Debug and Release builds of a project.
 
 ## Usage
@@ -35,4 +37,4 @@ This command supplies many common arguments to Meson. To see the full list, exam
 * [libepoxy](https://github.com/Microsoft/vcpkg/blob/master/ports/libepoxy/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_configure_meson.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_meson.cmake)
+[scripts/cmake/vcpkg\_configure\_meson.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_meson.cmake)
diff --git a/docs/maintainers/vcpkg_configure_qmake.md b/docs/maintainers/vcpkg_configure_qmake.md
index e55600c4e..e31aad814 100644
--- a/docs/maintainers/vcpkg_configure_qmake.md
+++ b/docs/maintainers/vcpkg_configure_qmake.md
@@ -1,5 +1,7 @@
 # vcpkg_configure_qmake
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_configure_qmake.md).
+
 Configure a qmake-based project.
 
 ```cmake
@@ -18,4 +20,4 @@ The path to the *.pro qmake project file.
 The options passed to qmake.
 
 ## Source
-[scripts/cmake/vcpkg_configure_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_qmake.cmake)
+[scripts/cmake/vcpkg\_configure\_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_qmake.cmake)
diff --git a/docs/maintainers/vcpkg_copy_pdbs.md b/docs/maintainers/vcpkg_copy_pdbs.md
index 37592febc..81902c7f1 100644
--- a/docs/maintainers/vcpkg_copy_pdbs.md
+++ b/docs/maintainers/vcpkg_copy_pdbs.md
@@ -1,20 +1,24 @@
 # vcpkg_copy_pdbs
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_copy_pdbs.md).
+
 Automatically locate pdbs in the build tree and copy them adjacent to all DLLs.
 
-## Usage
 ```cmake
-vcpkg_copy_pdbs([BUILD_PATHS <${CURRENT_PACKAGES_DIR}/bin/*.dll> ...])
+vcpkg_copy_pdbs(
+    [BUILD_PATHS <glob>...])
 ```
 
-## Notes
-This command should always be called by portfiles after they have finished rearranging the binary output.
+The `<glob>`s are patterns which will be passed to `file(GLOB_RECURSE)`,
+for locating DLLs. It defaults to using:
 
-## Parameters
-### BUILD_PATHS
-Path patterns passed to `file(GLOB_RECURSE)` for locating dlls.
+- `${CURRENT_PACKAGES_DIR}/bin/*.dll`
+- `${CURRENT_PACKAGES_DIR}/debug/bin/*.dll`
 
-Defaults to `${CURRENT_PACKAGES_DIR}/bin/*.dll` and `${CURRENT_PACKAGES_DIR}/debug/bin/*.dll`.
+since that is generally where DLLs are located.
+
+## Notes
+This command should always be called by portfiles after they have finished rearranging the binary output.
 
 ## Examples
 
@@ -22,4 +26,4 @@ Defaults to `${CURRENT_PACKAGES_DIR}/bin/*.dll` and `${CURRENT_PACKAGES_DIR}/deb
 * [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_copy_pdbs.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_pdbs.cmake)
+[scripts/cmake/vcpkg\_copy\_pdbs.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_pdbs.cmake)
diff --git a/docs/maintainers/vcpkg_copy_tool_dependencies.md b/docs/maintainers/vcpkg_copy_tool_dependencies.md
index 68b1fa09d..e6c046c55 100644
--- a/docs/maintainers/vcpkg_copy_tool_dependencies.md
+++ b/docs/maintainers/vcpkg_copy_tool_dependencies.md
@@ -1,5 +1,7 @@
 # vcpkg_copy_tool_dependencies
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_copy_tool_dependencies.md).
+
 Copy all DLL dependencies of built tools into the tool folder.
 
 ## Usage
@@ -18,4 +20,4 @@ This command should always be called by portfiles after they have finished rearr
 * [fltk](https://github.com/Microsoft/vcpkg/blob/master/ports/fltk/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_copy_tool_dependencies.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_tool_dependencies.cmake)
+[scripts/cmake/vcpkg\_copy\_tool\_dependencies.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_tool_dependencies.cmake)
diff --git a/docs/maintainers/vcpkg_copy_tools.md b/docs/maintainers/vcpkg_copy_tools.md
index 5a3f88602..04c8c6bb5 100644
--- a/docs/maintainers/vcpkg_copy_tools.md
+++ b/docs/maintainers/vcpkg_copy_tools.md
@@ -1,5 +1,7 @@
 # vcpkg_copy_tools
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_copy_tools.md).
+
 Copy tools and all their DLL dependencies into the `tools` folder.
 
 ## Usage
@@ -27,4 +29,4 @@ Auto clean executables in `${CURRENT_PACKAGES_DIR}/bin` and `${CURRENT_PACKAGES_
 * [uriparser](https://github.com/microsoft/vcpkg/blob/master/ports/uriparser/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_copy_tools.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_tools.cmake)
+[scripts/cmake/vcpkg\_copy\_tools.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_tools.cmake)
diff --git a/docs/maintainers/vcpkg_download_distfile.md b/docs/maintainers/vcpkg_download_distfile.md
index 0ff151739..1e66adfd5 100644
--- a/docs/maintainers/vcpkg_download_distfile.md
+++ b/docs/maintainers/vcpkg_download_distfile.md
@@ -1,5 +1,7 @@
 # vcpkg_download_distfile
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_download_distfile.md).
+
 Download and cache a file needed for this port.
 
 This helper should always be used instead of CMake's built-in `file(DOWNLOAD)` command.
@@ -51,4 +53,4 @@ The helper [`vcpkg_from_github`](vcpkg_from_github.md) should be used for downlo
 * [freetype](https://github.com/Microsoft/vcpkg/blob/master/ports/freetype/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_download_distfile.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_download_distfile.cmake)
+[scripts/cmake/vcpkg\_download\_distfile.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_download_distfile.cmake)
diff --git a/docs/maintainers/vcpkg_execute_build_process.md b/docs/maintainers/vcpkg_execute_build_process.md
index 1c81dd1b5..ba491b888 100644
--- a/docs/maintainers/vcpkg_execute_build_process.md
+++ b/docs/maintainers/vcpkg_execute_build_process.md
@@ -1,5 +1,7 @@
 # vcpkg_execute_build_process
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_execute_build_process.md).
+
 Execute a required build process
 
 ## Usage
@@ -33,4 +35,4 @@ conflict when building multiple at once.
 * [icu](https://github.com/Microsoft/vcpkg/blob/master/ports/icu/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_execute_build_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_build_process.cmake)
+[scripts/cmake/vcpkg\_execute\_build\_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_build_process.cmake)
diff --git a/docs/maintainers/vcpkg_execute_in_download_mode.md b/docs/maintainers/vcpkg_execute_in_download_mode.md
index 50ea3786a..c49d8a518 100644
--- a/docs/maintainers/vcpkg_execute_in_download_mode.md
+++ b/docs/maintainers/vcpkg_execute_in_download_mode.md
@@ -1,5 +1,7 @@
 # vcpkg_execute_in_download_mode
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_execute_in_download_mode.md).
+
 Execute a process even in download mode.
 
 ## Usage
@@ -31,4 +33,4 @@ See [`execute_process()`] for a detailed description of the parameters.
 [`execute_process()`]: https://cmake.org/cmake/help/latest/command/execute_process.html
 
 ## Source
-[scripts/cmake/vcpkg_execute_in_download_mode.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_in_download_mode.cmake)
+[scripts/cmake/vcpkg\_execute\_in\_download\_mode.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_in_download_mode.cmake)
diff --git a/docs/maintainers/vcpkg_execute_required_process.md b/docs/maintainers/vcpkg_execute_required_process.md
index 21b1029eb..aad010d5f 100644
--- a/docs/maintainers/vcpkg_execute_required_process.md
+++ b/docs/maintainers/vcpkg_execute_required_process.md
@@ -1,5 +1,7 @@
 # vcpkg_execute_required_process
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_execute_required_process.md).
+
 Execute a process with logging and fail the build if the command fails.
 
 ## Usage
@@ -46,4 +48,4 @@ This should be a unique name for different triplets so that the logs don't confl
 * [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_execute_required_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_required_process.cmake)
+[scripts/cmake/vcpkg\_execute\_required\_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_required_process.cmake)
diff --git a/docs/maintainers/vcpkg_execute_required_process_repeat.md b/docs/maintainers/vcpkg_execute_required_process_repeat.md
index 290ac7fce..97f02eb3e 100644
--- a/docs/maintainers/vcpkg_execute_required_process_repeat.md
+++ b/docs/maintainers/vcpkg_execute_required_process_repeat.md
@@ -1,5 +1,7 @@
 # vcpkg_execute_required_process_repeat
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_execute_required_process_repeat.md).
+
 Execute a process until the command succeeds, or until the COUNT is reached.
 
 ## Usage
@@ -13,4 +15,4 @@ vcpkg_execute_required_process_repeat(
 ```
 
 ## Source
-[scripts/cmake/vcpkg_execute_required_process_repeat.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_required_process_repeat.cmake)
+[scripts/cmake/vcpkg\_execute\_required\_process\_repeat.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_required_process_repeat.cmake)
diff --git a/docs/maintainers/vcpkg_extract_source_archive.md b/docs/maintainers/vcpkg_extract_source_archive.md
index da98a2813..d7dc30c05 100644
--- a/docs/maintainers/vcpkg_extract_source_archive.md
+++ b/docs/maintainers/vcpkg_extract_source_archive.md
@@ -1,5 +1,7 @@
 # vcpkg_extract_source_archive
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_extract_source_archive.md).
+
 Extract an archive into the source directory. Deprecated in favor of [`vcpkg_extract_source_archive_ex`](vcpkg_extract_source_archive_ex.md).
 
 ## Usage
@@ -29,4 +31,4 @@ This command will also create a tracking file named <FILENAME>.extracted in the
 * [msgpack](https://github.com/Microsoft/vcpkg/blob/master/ports/msgpack/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_extract_source_archive.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_extract_source_archive.cmake)
+[scripts/cmake/vcpkg\_extract\_source\_archive.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_extract_source_archive.cmake)
diff --git a/docs/maintainers/vcpkg_extract_source_archive_ex.md b/docs/maintainers/vcpkg_extract_source_archive_ex.md
index 55902b70d..540cc687e 100644
--- a/docs/maintainers/vcpkg_extract_source_archive_ex.md
+++ b/docs/maintainers/vcpkg_extract_source_archive_ex.md
@@ -1,5 +1,7 @@
 # vcpkg_extract_source_archive_ex
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_extract_source_archive_ex.md).
+
 Extract an archive into the source directory. Replaces [`vcpkg_extract_source_archive`](vcpkg_extract_source_archive.md).
 
 ## Usage
@@ -53,4 +55,4 @@ Specifies that the default removal of the top level folder should not occur.
 * [cairo](https://github.com/Microsoft/vcpkg/blob/master/ports/cairo/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_extract_source_archive_ex.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_extract_source_archive_ex.cmake)
+[scripts/cmake/vcpkg\_extract\_source\_archive\_ex.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_extract_source_archive_ex.cmake)
diff --git a/docs/maintainers/vcpkg_fail_port_install.md b/docs/maintainers/vcpkg_fail_port_install.md
index 53b81bd1a..9be31ce50 100644
--- a/docs/maintainers/vcpkg_fail_port_install.md
+++ b/docs/maintainers/vcpkg_fail_port_install.md
@@ -1,5 +1,7 @@
 # vcpkg_fail_port_install
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_fail_port_install.md).
+
 Checks common requirements and fails the current portfile with a (default) error message
 
 ## Usage
@@ -38,4 +40,4 @@ Library linkage for which the build should fail early.
 * [aws-lambda-cpp](https://github.com/Microsoft/vcpkg/blob/master/ports/aws-lambda-cpp/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_fail_port_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fail_port_install.cmake)
+[scripts/cmake/vcpkg\_fail\_port\_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fail_port_install.cmake)
diff --git a/docs/maintainers/vcpkg_find_acquire_program.md b/docs/maintainers/vcpkg_find_acquire_program.md
index 2bdbb7c51..303508000 100644
--- a/docs/maintainers/vcpkg_find_acquire_program.md
+++ b/docs/maintainers/vcpkg_find_acquire_program.md
@@ -1,5 +1,7 @@
 # vcpkg_find_acquire_program
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_find_acquire_program.md).
+
 Download or find a well-known tool.
 
 ## Usage
@@ -46,4 +48,4 @@ Note that msys2 has a dedicated helper function: [`vcpkg_acquire_msys`](vcpkg_ac
 * [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_find_acquire_program.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_find_acquire_program.cmake)
+[scripts/cmake/vcpkg\_find\_acquire\_program.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_find_acquire_program.cmake)
diff --git a/docs/maintainers/vcpkg_find_fortran.md b/docs/maintainers/vcpkg_find_fortran.md
index ffc1b6893..004c3b443 100644
--- a/docs/maintainers/vcpkg_find_fortran.md
+++ b/docs/maintainers/vcpkg_find_fortran.md
@@ -1,5 +1,7 @@
 # vcpkg_find_fortran
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_find_fortran.md).
+
 Checks if a Fortran compiler can be found.
 Windows(x86/x64) Only: If not it will switch/enable MinGW gfortran 
                        and return required cmake args for building. 
@@ -10,4 +12,4 @@ vcpkg_find_fortran(<additional_cmake_args_out>)
 ```
 
 ## Source
-[scripts/cmake/vcpkg_find_fortran.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_find_fortran.cmake)
+[scripts/cmake/vcpkg\_find\_fortran.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_find_fortran.cmake)
diff --git a/docs/maintainers/vcpkg_fixup_cmake_targets.md b/docs/maintainers/vcpkg_fixup_cmake_targets.md
index 01e4fd3e1..ce0de6c27 100644
--- a/docs/maintainers/vcpkg_fixup_cmake_targets.md
+++ b/docs/maintainers/vcpkg_fixup_cmake_targets.md
@@ -1,5 +1,9 @@
 # vcpkg_fixup_cmake_targets
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_fixup_cmake_targets.md).
+
+**This function has been deprecated in favor of `vcpkg_cmake_config_fixup` from the vcpkg-cmake-config port.**
+
 Merge release and debug CMake targets and configs to support multiconfig generators.
 
 Additionally corrects common issues with targets, such as absolute paths and incorrectly placed binaries.
@@ -22,7 +26,7 @@ This needs to be specified if the port name differs from the `find_package()` na
 
 Defaults to `share/${PORT}`.
 
-### DO_NOT_DELETE_PARENT_CONFIG_PATH 
+### DO_NOT_DELETE_PARENT_CONFIG_PATH
 By default the parent directory of CONFIG_PATH is removed if it is named "cmake".
 Passing this option disable such behavior, as it is convenient for ports that install
 more than one CMake package configuration file.
@@ -49,4 +53,4 @@ Replace `${CURRENT_INSTALLED_DIR}` with `${_IMPORT_PREFIX}` in configs and targe
 * [nlohmann-json](https://github.com/Microsoft/vcpkg/blob/master/ports/nlohmann-json/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_fixup_cmake_targets.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fixup_cmake_targets.cmake)
+[scripts/cmake/vcpkg\_fixup\_cmake\_targets.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fixup_cmake_targets.cmake)
diff --git a/docs/maintainers/vcpkg_fixup_pkgconfig.md b/docs/maintainers/vcpkg_fixup_pkgconfig.md
index 23cee6142..ce2a4391b 100644
--- a/docs/maintainers/vcpkg_fixup_pkgconfig.md
+++ b/docs/maintainers/vcpkg_fixup_pkgconfig.md
@@ -1,5 +1,7 @@
 # vcpkg_fixup_pkgconfig
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_fixup_pkgconfig.md).
+
 Fix common paths in *.pc files and make everything relativ to $(prefix)
 
 ## Usage
@@ -40,4 +42,4 @@ Still work in progress. If there are more cases which can be handled here feel f
 * [brotli](https://github.com/Microsoft/vcpkg/blob/master/ports/brotli/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_fixup_pkgconfig.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fixup_pkgconfig.cmake)
+[scripts/cmake/vcpkg\_fixup\_pkgconfig.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fixup_pkgconfig.cmake)
diff --git a/docs/maintainers/vcpkg_from_bitbucket.md b/docs/maintainers/vcpkg_from_bitbucket.md
index ad41a1431..f91040e21 100644
--- a/docs/maintainers/vcpkg_from_bitbucket.md
+++ b/docs/maintainers/vcpkg_from_bitbucket.md
@@ -1,5 +1,7 @@
 # vcpkg_from_bitbucket
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_from_bitbucket.md).
+
 Download and extract a project from Bitbucket.
 Enables support for installing HEAD `vcpkg.exe install --head <port>`.
 
@@ -56,4 +58,4 @@ This exports the `VCPKG_HEAD_VERSION` variable during head builds.
 * [blaze](https://github.com/Microsoft/vcpkg/blob/master/ports/blaze/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_from_bitbucket.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_bitbucket.cmake)
+[scripts/cmake/vcpkg\_from\_bitbucket.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_bitbucket.cmake)
diff --git a/docs/maintainers/vcpkg_from_git.md b/docs/maintainers/vcpkg_from_git.md
index ac8ad6840..0d24aa76f 100644
--- a/docs/maintainers/vcpkg_from_git.md
+++ b/docs/maintainers/vcpkg_from_git.md
@@ -1,5 +1,7 @@
 # vcpkg_from_git
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_from_git.md).
+
 Download and extract a project from git
 
 ## Usage:
@@ -44,4 +46,4 @@ This parameter is used for automatic REF updates for certain ports in the centra
 * [fdlibm](https://github.com/Microsoft/vcpkg/blob/master/ports/fdlibm/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_from_git.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_git.cmake)
+[scripts/cmake/vcpkg\_from\_git.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_git.cmake)
diff --git a/docs/maintainers/vcpkg_from_github.md b/docs/maintainers/vcpkg_from_github.md
index db557c1c8..cfd28c6a7 100644
--- a/docs/maintainers/vcpkg_from_github.md
+++ b/docs/maintainers/vcpkg_from_github.md
@@ -1,5 +1,7 @@
 # vcpkg_from_github
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_from_github.md).
+
 Download and extract a project from GitHub. Enables support for `install --head`.
 
 ## Usage:
@@ -71,4 +73,4 @@ This exports the `VCPKG_HEAD_VERSION` variable during head builds.
 * [beast](https://github.com/Microsoft/vcpkg/blob/master/ports/beast/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_from_github.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_github.cmake)
+[scripts/cmake/vcpkg\_from\_github.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_github.cmake)
diff --git a/docs/maintainers/vcpkg_from_gitlab.md b/docs/maintainers/vcpkg_from_gitlab.md
index e2160b27b..c222aa88d 100644
--- a/docs/maintainers/vcpkg_from_gitlab.md
+++ b/docs/maintainers/vcpkg_from_gitlab.md
@@ -1,5 +1,7 @@
 # vcpkg_from_gitlab
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_from_gitlab.md).
+
 Download and extract a project from Gitlab instances. Enables support for `install --head`.
 
 ## Usage:
@@ -66,4 +68,4 @@ This exports the `VCPKG_HEAD_VERSION` variable during head builds.
 * [z3](https://github.com/Microsoft/vcpkg/blob/master/ports/z3/portfile.cmake#L13)
 
 ## Source
-[scripts/cmake/vcpkg_from_gitlab.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_gitlab.cmake)
+[scripts/cmake/vcpkg\_from\_gitlab.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_gitlab.cmake)
diff --git a/docs/maintainers/vcpkg_from_sourceforge.md b/docs/maintainers/vcpkg_from_sourceforge.md
index 2bf7f25a6..2f34e0766 100644
--- a/docs/maintainers/vcpkg_from_sourceforge.md
+++ b/docs/maintainers/vcpkg_from_sourceforge.md
@@ -1,5 +1,7 @@
 # vcpkg_from_sourceforge
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_from_sourceforge.md).
+
 Download and extract a project from sourceforge.
 
 ## Usage:
@@ -65,4 +67,4 @@ Specifies that the default removal of the top level folder should not occur.
 * [tinyfiledialogs](https://github.com/Microsoft/vcpkg/blob/master/ports/tinyfiledialogs/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_from_sourceforge.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_sourceforge.cmake)
+[scripts/cmake/vcpkg\_from\_sourceforge.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_sourceforge.cmake)
diff --git a/docs/maintainers/vcpkg_get_program_files_platform_bitness.md b/docs/maintainers/vcpkg_get_program_files_platform_bitness.md
index d4d5480d0..653627fed 100644
--- a/docs/maintainers/vcpkg_get_program_files_platform_bitness.md
+++ b/docs/maintainers/vcpkg_get_program_files_platform_bitness.md
@@ -1,5 +1,7 @@
 # vcpkg_get_program_files_platform_bitness
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_get_program_files_platform_bitness.md).
+
 Get the Program Files directory of the current platform's bitness:
 either `$ENV{ProgramW6432}` on 64-bit windows,
 or `$ENV{PROGRAMFILES}` on 32-bit windows.
@@ -10,4 +12,4 @@ vcpkg_get_program_files_platform_bitness(<variable>)
 ```
 
 ## Source
-[scripts/cmake/vcpkg_get_program_files_platform_bitness.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_get_program_files_platform_bitness.cmake)
+[scripts/cmake/vcpkg\_get\_program\_files\_platform\_bitness.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_get_program_files_platform_bitness.cmake)
diff --git a/docs/maintainers/vcpkg_get_windows_sdk.md b/docs/maintainers/vcpkg_get_windows_sdk.md
index 30cac43de..d8fdb8a8b 100644
--- a/docs/maintainers/vcpkg_get_windows_sdk.md
+++ b/docs/maintainers/vcpkg_get_windows_sdk.md
@@ -1,5 +1,7 @@
 # vcpkg_get_windows_sdk
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_get_windows_sdk.md).
+
 Get the Windows SDK number.
 
 ## Usage:
@@ -8,4 +10,4 @@ vcpkg_get_windows_sdk(<variable>)
 ```
 
 ## Source
-[scripts/cmake/vcpkg_get_windows_sdk.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_get_windows_sdk.cmake)
+[scripts/cmake/vcpkg\_get\_windows\_sdk.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_get_windows_sdk.cmake)
diff --git a/docs/maintainers/vcpkg_install_cmake.md b/docs/maintainers/vcpkg_install_cmake.md
index 058a2ef61..55a881084 100644
--- a/docs/maintainers/vcpkg_install_cmake.md
+++ b/docs/maintainers/vcpkg_install_cmake.md
@@ -1,5 +1,9 @@
 # vcpkg_install_cmake
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_install_cmake.md).
+
+**This function has been deprecated in favor of `vcpkg_cmake_install` from the vcpkg-cmake port.**
+
 Build and install a cmake project.
 
 ## Usage:
@@ -22,4 +26,4 @@ parameter.
 * [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_install_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_cmake.cmake)
+[scripts/cmake/vcpkg\_install\_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_cmake.cmake)
diff --git a/docs/maintainers/vcpkg_install_gn.md b/docs/maintainers/vcpkg_install_gn.md
index 48bd81a02..651b3f8f7 100644
--- a/docs/maintainers/vcpkg_install_gn.md
+++ b/docs/maintainers/vcpkg_install_gn.md
@@ -1,5 +1,7 @@
 # vcpkg_install_gn
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_install_gn.md).
+
 Installs a GN project
 
 ## Usage:
@@ -20,4 +22,4 @@ Only install the specified targets.
 Note: includes must be handled separately
 
 ## Source
-[scripts/cmake/vcpkg_install_gn.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_gn.cmake)
+[scripts/cmake/vcpkg\_install\_gn.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_gn.cmake)
diff --git a/docs/maintainers/vcpkg_install_make.md b/docs/maintainers/vcpkg_install_make.md
index c1baa3639..2643db413 100644
--- a/docs/maintainers/vcpkg_install_make.md
+++ b/docs/maintainers/vcpkg_install_make.md
@@ -1,5 +1,7 @@
 # vcpkg_install_make
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_install_make.md).
+
 Build and install a make project.
 
 ## Usage:
@@ -21,4 +23,4 @@ This command transparently forwards to [`vcpkg_build_make()`](vcpkg_build_make.m
 * [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_install_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_make.cmake)
+[scripts/cmake/vcpkg\_install\_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_make.cmake)
diff --git a/docs/maintainers/vcpkg_install_meson.md b/docs/maintainers/vcpkg_install_meson.md
index 8d8cc5bb0..2967dd989 100644
--- a/docs/maintainers/vcpkg_install_meson.md
+++ b/docs/maintainers/vcpkg_install_meson.md
@@ -1,5 +1,7 @@
 # vcpkg_install_meson
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_install_meson.md).
+
 Builds a meson project previously configured with `vcpkg_configure_meson()`.
 
 ## Usage
@@ -13,4 +15,4 @@ vcpkg_install_meson()
 * [libepoxy](https://github.com/Microsoft/vcpkg/blob/master/ports/libepoxy/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_install_meson.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_meson.cmake)
+[scripts/cmake/vcpkg\_install\_meson.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_meson.cmake)
diff --git a/docs/maintainers/vcpkg_install_msbuild.md b/docs/maintainers/vcpkg_install_msbuild.md
index 65da24667..befb29513 100644
--- a/docs/maintainers/vcpkg_install_msbuild.md
+++ b/docs/maintainers/vcpkg_install_msbuild.md
@@ -1,5 +1,7 @@
 # vcpkg_install_msbuild
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_install_msbuild.md).
+
 Build and install a msbuild-based project. This replaces `vcpkg_build_msbuild()`.
 
 ## Usage
@@ -90,4 +92,4 @@ Additional options passed to msbuild for Debug builds. These are in addition to
 * [libimobiledevice](https://github.com/Microsoft/vcpkg/blob/master/ports/libimobiledevice/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_install_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_msbuild.cmake)
+[scripts/cmake/vcpkg\_install\_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_msbuild.cmake)
diff --git a/docs/maintainers/vcpkg_install_nmake.md b/docs/maintainers/vcpkg_install_nmake.md
index f4f490b2b..0855497ca 100644
--- a/docs/maintainers/vcpkg_install_nmake.md
+++ b/docs/maintainers/vcpkg_install_nmake.md
@@ -1,5 +1,7 @@
 # vcpkg_install_nmake
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_install_nmake.md).
+
 Build and install a msvc makefile project.
 
 ## Usage:
@@ -63,4 +65,4 @@ This command transparently forwards to [`vcpkg_build_nmake()`](vcpkg_build_nmake
 * [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_install_nmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_nmake.cmake)
+[scripts/cmake/vcpkg\_install\_nmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_nmake.cmake)
diff --git a/docs/maintainers/vcpkg_install_qmake.md b/docs/maintainers/vcpkg_install_qmake.md
index 51421247b..102a642ec 100644
--- a/docs/maintainers/vcpkg_install_qmake.md
+++ b/docs/maintainers/vcpkg_install_qmake.md
@@ -1,5 +1,7 @@
 # vcpkg_install_qmake
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_install_qmake.md).
+
 Build and install a qmake project.
 
 ## Usage:
@@ -21,4 +23,4 @@ staging directories.
 * [libqglviewer](https://github.com/Microsoft/vcpkg/blob/master/ports/libqglviewer/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_install_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_qmake.cmake)
+[scripts/cmake/vcpkg\_install\_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_qmake.cmake)
diff --git a/docs/maintainers/vcpkg_minimum_required.md b/docs/maintainers/vcpkg_minimum_required.md
index 419338956..aaeee5cbf 100644
--- a/docs/maintainers/vcpkg_minimum_required.md
+++ b/docs/maintainers/vcpkg_minimum_required.md
@@ -1,5 +1,7 @@
 # vcpkg_minimum_required
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_minimum_required.md).
+
 Asserts that the version of the vcpkg program being used to build a port is later than the supplied date, inclusive.
 
 ## Usage
@@ -12,4 +14,4 @@ vcpkg_minimum_required(VERSION 2021-01-13)
 The date-version to check against.
 
 ## Source
-[scripts/cmake/vcpkg_minimum_required.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_minimum_required.cmake)
+[scripts/cmake/vcpkg\_minimum\_required.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_minimum_required.cmake)
diff --git a/docs/maintainers/vcpkg_replace_string.md b/docs/maintainers/vcpkg_replace_string.md
index 926960985..de223c40c 100644
--- a/docs/maintainers/vcpkg_replace_string.md
+++ b/docs/maintainers/vcpkg_replace_string.md
@@ -1,5 +1,7 @@
 # vcpkg_replace_string
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_replace_string.md).
+
 Replace a string in a file.
 
 ```cmake
@@ -8,4 +10,4 @@ vcpkg_replace_string(filename match_string replace_string)
 
 
 ## Source
-[scripts/cmake/vcpkg_replace_string.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_replace_string.cmake)
+[scripts/cmake/vcpkg\_replace\_string.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_replace_string.cmake)
diff --git a/docs/regenerate.ps1 b/docs/regenerate.ps1
index fa80bd62a..61dd50a59 100755
--- a/docs/regenerate.ps1
+++ b/docs/regenerate.ps1
@@ -15,9 +15,73 @@ if (-not (Test-Path "$VcpkgRoot/.vcpkg-root")) {
     throw "Invalid vcpkg instance, did you forget -VcpkgRoot?"
 }
 
-$tableOfContents = @()
-$internalTableOfContents = @()
+class CMakeDocumentation {
+    [String]$Filename
+    [String[]]$ActualDocumentation
+    [Bool]$IsDeprecated
+    [String]$DeprecationMessage
+    [Bool]$HasError
+}
+
+[String[]]$cmakeScriptsPorts = @(
+    'vcpkg-cmake'
+    'vcpkg-cmake-config'
+)
+
+[CMakeDocumentation[]]$tableOfContents = @()
+[CMakeDocumentation[]]$internalTableOfContents = @()
+$portTableOfContents = [ordered]@{}
+
+function RelativeUnixPathTo
+{
+    Param(
+        [Parameter(Mandatory)]
+        [String]$Path,
+        [Parameter(Mandatory)]
+        [String]$Base
+    )
+
+    $Path = Resolve-Path -LiteralPath $Path
+    $Base = Resolve-Path -LiteralPath $Base
+
+    if ($IsWindows)
+    {
+        if ((Split-Path -Qualifier $Path) -ne (Split-Path -Qualifier $Base))
+        {
+            throw "It is not possible to get the relative unix path from $Base to $Path"
+        }
+    }
+
+    $Path = $Path -replace '\\','/'
+    $Base = $Base -replace '\\','/'
+
+    [String[]]$PathArray = $Path -split '/'
+    [String[]]$BaseArray = $Base -split '/'
+
+    [String[]]$Result = @()
+
+    $Idx = 0
+
+    while ($Idx -lt $PathArray.Length -and $Idx -lt $BaseArray.Length)
+    {
+        if ($PathArray[$Idx] -ne $BaseArray[$Idx])
+        {
+            break
+        }
+        ++$Idx
+    }
+
+    for ($BaseIdx = $Idx; $BaseIdx -lt $BaseArray.Length; ++$BaseIdx)
+    {
+        $Result += '..'
+    }
+    for ($PathIdx = $Idx; $PathIdx -lt $PathArray.Length; ++$PathIdx)
+    {
+        $Result += $PathArray[$PathIdx]
+    }
 
+    $Result -join '/'
+}
 function WriteFile
 {
     Param(
@@ -33,41 +97,81 @@ function WriteFile
 function FinalDocFile
 {
     Param(
-        [String[]]$Value,
-        [String]$Name
+        [CMakeDocumentation]$Docs,
+        [String]$PathToFile # something like docs/maintainers/blah.md
     )
-    $Value + @(
+    [String[]]$documentation = @()
+
+    if ($Docs.ActualDocumentation.Length -eq 0)
+    {
+        throw "Invalid documentation: empty docs"
+    }
+
+    $documentation += $Docs.ActualDocumentation[0] # name line
+    if ($Docs.IsDeprecated)
+    {
+        if ($null -eq $Docs.DeprecationMessage)
+        {
+            $documentation += @("", "**This function has been deprecated**")
+        }
+        else
+        {
+            $documentation += @("", "**This function has been deprecated $($Docs.DeprecationMessage)**")
+        }
+    }
+    $documentation += @("", "The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/$PathToFile).")
+
+    $documentation += $Docs.ActualDocumentation[1..$Docs.ActualDocumentation.Length]
+
+    $relativePath = RelativeUnixPathTo $Docs.Filename $VcpkgRoot
+    $documentation += @(
         "",
         "## Source",
-        "[scripts/cmake/$Name](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/$Name)",
+        "[$($relativePath -replace '_','\_')](https://github.com/Microsoft/vcpkg/blob/master/$relativePath)",
         ""
     )
+
+    $documentation
 }
 
-Get-ChildItem "$VcpkgRoot/scripts/cmake" -Filter '*.cmake' | ForEach-Object {
-    $filename = $_
-    [String[]]$contents = Get-Content $filename
+function ParseCmakeDocComment
+{
+    Param(
+        [Parameter(Mandatory)]
+        [System.IO.FileSystemInfo]$Filename
+    )
 
-    if ($contents[0] -eq '# DEPRECATED') {
-        return
+    $Docs = New-Object 'CMakeDocumentation'
+    $Docs.HasError = $False
+    $Docs.IsDeprecated = $False
+    $Docs.Filename = $Filename.FullName
+
+    [String[]]$contents = Get-Content $Filename
+
+    if ($contents[0] -eq '# DEPRECATED')
+    {
+        $Docs.IsDeprecated = $True
+    }
+    elseif($contents[0] -match '^# DEPRECATED: (.*)$')
+    {
+        $Docs.IsDeprecated = $True
+        $Docs.DeprecationMessage = $matches[1]
     }
 
     [String]$startCommentRegex = '#\[(=*)\['
     [String]$endCommentRegex = ''
     [Bool]$inComment = $False
-    [Bool]$failThisFile = $False
-    [Bool]$isInternalFunction = $filename.Name.StartsWith("vcpkg_internal") -or $filename.Name.StartsWith("z_vcpkg")
 
     $contents = $contents | ForEach-Object {
         if (-not $inComment) {
             if ($_ -match "^\s*${startCommentRegex}(\.[a-z]*)?:?\s*$") {
                 if (-not [String]::IsNullOrEmpty($matches[2]) -and $matches[2] -ne '.md') {
-                    Write-Warning "The documentation in ${filename} doesn't seem to be markdown (extension: $($matches[2])). Only markdown is supported; please rewrite the documentation in markdown."
+                    Write-Warning "The documentation in $($Filename.FullName) doesn't seem to be markdown (extension: $($matches[2])). Only markdown is supported; please rewrite the documentation in markdown."
                 }
                 $inComment = $True
                 $endCommentRegex = "\]$($matches[1])\]"
             } elseif ($_ -match $startCommentRegex) {
-                $failThisFile = $True
+                $Docs.HasError = $True
                 Write-Warning "Invalid start of comment -- the comment start must be at the beginning of the line.
     (on line: `"$_`")"
             } else {
@@ -78,7 +182,7 @@ Get-ChildItem "$VcpkgRoot/scripts/cmake" -Filter '*.cmake' | ForEach-Object {
                 $inComment = $False
                 $endCommentRegex = ''
             } elseif ($_ -match $endCommentRegex) {
-                $failThisFile = $True
+                $Docs.HasError = $True
                 Write-Warning "Invalid end of comment -- the comment end must be on it's own on a line.
     (on line: `"$_`")"
             } else {
@@ -89,47 +193,147 @@ Get-ChildItem "$VcpkgRoot/scripts/cmake" -Filter '*.cmake' | ForEach-Object {
     }
 
     if ($inComment) {
-        Write-Warning "File ${filename} has an unclosed comment."
-        return
+        Write-Warning "File $($Filename.FullName) has an unclosed comment."
+        $Docs.HasError = $True
     }
 
-    if ($failThisFile) {
-        return
+    if ($contents.Length -ne 0)
+    {
+        $Docs.ActualDocumentation = $contents
     }
 
+    $Docs
+}
+
+Get-ChildItem "$VcpkgRoot/scripts/cmake" -Filter '*.cmake' | ForEach-Object {
+    $docs = ParseCmakeDocComment $_
+    [Bool]$isInternalFunction = $_.Name.StartsWith("vcpkg_internal") -or $_.Name.StartsWith("z_vcpkg")
+
+    if ($docs.IsDeprecated -and $null -eq $docs.ActualDocumentation)
+    {
+        return
+    }
+    if ($docs.HasError)
+    {
+        return
+    }
 
-    if ($contents) {
-        if ($isInternalFunction) {
+    if ($null -ne $docs.ActualDocumentation)
+    {
+        if ($isInternalFunction)
+        {
+            $pathToFile = "maintainers/internal/$($_.BaseName).md"
             WriteFile `
-                -Path "$PSScriptRoot/maintainers/internal/$($filename.BaseName).md" `
-                -Value (FinalDocFile $contents $filename.Name)
+                -Path "$PSScriptRoot/$pathToFile" `
+                -Value (FinalDocFile $docs)
 
-            $internalTableOfContents += $filename.BaseName
-        } else {
+            $internalTableOfContents += $docs
+        }
+        else
+        {
+            $pathToFile = "maintainers/$($_.BaseName).md"
             WriteFile `
-                -Path "$PSScriptRoot/maintainers/$($filename.BaseName).md" `
-                -Value (FinalDocFile $contents $filename.Name)
+                -Path "$PSScriptRoot/$pathToFile" `
+                -Value (FinalDocFile $docs $pathToFile)
 
-            $tableOfContents += $filename.BaseName
+            $tableOfContents += $docs
         }
-    } elseif (-not $isInternalFunction) {
+    }
+    elseif (-not $isInternalFunction)
+    {
         # don't worry about undocumented internal functions
-        Write-Warning "The cmake function in file $filename doesn't seem to have any documentation. Make sure the documentation comments are correctly written."
+        Write-Warning "The cmake function in file $($_.FullName) doesn't seem to have any documentation. Make sure the documentation comments are correctly written."
+    }
+}
+
+$cmakeScriptsPorts | ForEach-Object {
+    $portName = $_
+
+    Copy-Item "$VcpkgRoot/ports/$portName/README.md" "$PSScriptRoot/maintainers/ports/$portName.md"
+    New-Item -Path "$PSScriptRoot/maintainers/ports/$portName" -Force -ItemType 'Directory' | Out-Null
+
+    $portTableOfContents[$portName] = @()
+
+    Get-ChildItem "$VcpkgRoot/ports/$portName" -Filter '*.cmake' | ForEach-Object {
+        if ($_.Name -eq 'vcpkg-port-config.cmake' -or $_.Name -eq 'portfile.cmake')
+        {
+            return
+        }
+
+        $docs = ParseCmakeDocComment $_
+
+        if ($docs.IsDeprecated -and $null -eq $docs.ActualDocumentation)
+        {
+            return
+        }
+        if ($docs.HasError)
+        {
+            return
+        }
+
+        if ($null -ne $docs.ActualDocumentation)
+        {
+            $pathToFile = "maintainers/ports/$portName/$($_.BaseName).md"
+            WriteFile `
+                -Path "$PSScriptRoot/$pathToFile" `
+                -Value (FinalDocFile $docs $pathToFile)
+            $portTableOfContents[$portName] += $docs
+        }
+        else
+        {
+            Write-Warning "The cmake function in file $($_.FullName) doesn't seem to have any documentation. Make sure the documentation comments are correctly written."
+        }
     }
 }
 
 $portfileFunctionsContent = @(
-    '<!-- Run regenerate.ps1 to extract documentation from scripts/cmake/*.cmake -->',
+    '<!-- Run regenerate.ps1 to extract scripts documentation -->',
     '',
     '# Portfile helper functions')
 
-$tableOfContents | Sort-Object -Culture '' | ForEach-Object {
-    $portfileFunctionsContent += "- [$($_ -replace '_','\_')]($_.md)"
+$DocsName = @{ expression = { Split-Path -LeafBase $_.Filename } }
+$tableOfContents | Sort-Object -Property $DocsName -Culture '' | ForEach-Object {
+    $name = Split-Path -LeafBase $_.Filename
+    if ($_.IsDeprecated)
+    {
+        $portfileFunctionsContent += "- [$($name -replace '_','\_')]($name.md) (deprecated)"
+    }
+    else
+    {
+        $portfileFunctionsContent += "- [$($name -replace '_','\_')]($name.md)"
+    }
 }
 $portfileFunctionsContent += @("", "## Internal Functions", "")
-$internalTableOfContents | Sort-Object -Culture '' | ForEach-Object {
-    $portfileFunctionsContent += "- [$($_ -replace '_','\_')](internal/$_.md)"
+$internalTableOfContents | Sort-Object -Property $DocsName -Culture '' | ForEach-Object {
+    $name = Split-Path -LeafBase $_.Filename
+    if ($_.IsDeprecated)
+    {
+        $portfileFunctionsContent += "- [$($name -replace '_','\_')](internal/$name.md) (deprecated)"
+    }
+    else
+    {
+        $portfileFunctionsContent += "- [$($name -replace '_','\_')](internal/$name.md)"
+    }
 }
+
+$portfileFunctionsContent += @("", "## Scripts from Ports")
+$portTableOfContents.GetEnumerator() | ForEach-Object {
+    $portName = $_.Name
+    $cmakeDocs = $_.Value
+    $portfileFunctionsContent += @("", "### [$portName](ports/$portName.md)", "")
+    $cmakeDocs | ForEach-Object {
+        $name = Split-Path -LeafBase $_.Filename
+        if ($_.IsDeprecated)
+        {
+            $portfileFunctionsContent += "- [$($name -replace '_','\_')](ports/$portName/$name.md) (deprecated)"
+        }
+        else
+        {
+            $portfileFunctionsContent += "- [$($name -replace '_','\_')](ports/$portName/$name.md)"
+        }
+    }
+}
+
 $portfileFunctionsContent += "" # final newline
 
 WriteFile `