[docs] Remove out-of-date docs, improve header standardization. (micr…

…osoft#24456) * Remove out-of-date docs, improve header standardization. * PR scoping & comments
ndk · May 18, 2022 · 1e91cd3 · 1e91cd3
1 parent 261ca0d
commit 1e91cd3
Show file tree

Hide file tree

Showing 8 changed files with 26 additions and 26 deletions.
diff --git a/docs/examples/installing-and-using-packages.md b/docs/examples/installing-and-using-packages.md
@@ -1,5 +1,7 @@
 ## Installing and Using Packages Example: SQLite
 
+_Note: this old example uses Classic Mode, but most developers will be happier with Manifest Mode. See [Manifest Mode: CMake Example](manifest-mode-cmake.md) for an example of converting to Manifest Mode._
+
   - [Step 1: Install](#install)
   - [Step 2: Use](#use)
     - [VS/MSBuild Project (User-wide integration)](#msbuild)

diff --git a/docs/examples/modify-baseline-to-pin-old-boost.md b/docs/examples/modify-baseline-to-pin-old-boost.md
@@ -1,12 +1,12 @@
 # Pin old Boost versions
-This document will teach you how to set versions of meta-packages like `boost` or `qt5`. 
+This document will teach you how to set versions of meta-packages like `boost` or `qt5`.
 
-**What is a meta-package?**  
-In vcpkg we call meta-packages to ports that by themselves don't install anything but that instead forward installation to another port or ports. The reasons for these meta-packages to exist are plenty: to install different versions of a library depending on platform (like the old OpenSSL port did), to allow for multiple versions to exist in the vcpkg registry at the same time (OpenCV), or to conveniently install/uninstall a catalog of related packages (Boost and Qt).  
+**What is a meta-package?**
+In vcpkg we call meta-packages to ports that by themselves don't install anything but that instead forward installation to another port or ports. The reasons for these meta-packages to exist are plenty: to install different versions of a library depending on platform or to conveniently install/uninstall a catalog of related packages (Boost and Qt).
 
-In the case of Boost, it is unlikely that a user requires all of the 140+ Boost libraries in their project. For the sake of convenience, vcpkg splits Boost into multiple sub-packages broken down to individual libraries. By doing so, users can limit the subset of Boost libraries that they depend on. 
+In the case of Boost, it is unlikely that a user requires all of the 140+ Boost libraries in their project. For the sake of convenience, vcpkg splits Boost into multiple sub-packages broken down to individual libraries. By doing so, users can limit the subset of Boost libraries that they depend on.
 
-If a user wants to install all of the Boost libraries available in vcpkg, they can do so by installing the `boost` meta-package. 
+If a user wants to install all of the Boost libraries available in vcpkg, they can do so by installing the `boost` meta-package.
 
 Due to the nature of meta-packages, some unexpected issues arise when trying to use them with versioning. If a user writes the following manifest file:
 
@@ -17,7 +17,7 @@ Due to the nature of meta-packages, some unexpected issues arise when trying to
     "version": "1.0.0",
     "builtin-baseline": "787fe1418ea968913cc6daf11855ffd8b0b5e9d4",
     "dependencies": [ "boost-tuple" ],
-    "overrides": [ 
+    "overrides": [
         { "name": "boost", "version": "1.72.0" }
     ]
 }
@@ -49,7 +49,7 @@ It is reasonable to expect that overriding `boost` to version 1.72.0 results in
 Below, we describe two methods to pin down Boost versions effectively.
 
 ## Method 1: Pin specific packages
-Use `"overrides"` to force specific versions in a package-by-package basis. 
+Use `"overrides"` to force specific versions in a package-by-package basis.
 
 `vcpkg.json`
 ```json
@@ -72,14 +72,15 @@ This method allows you to quickly set the specific versions you want, but you wi
 The second method makes it easy to pin the entire Boost collection and end up with a very simple manifest file.
 
 ## Method 2: Modify baseline
-An easy way to set the version for the entirety of boost is to use the `"builtin-baseline"` property. 
+An easy way to set the version for the entirety of boost is to use the `"builtin-baseline"` property.
 
-As of right now, it is only possible to go back to Boost version `1.75.0` using a baseline. Since that was the contemporary Boost version when the versioning feature was merged. **But, it is possible to modify the baseline to whatever you like and use that instead.**
+As of right now, it is only possible to go back to Boost version `1.75.0` using a baseline, since that was the contemporary Boost version when the versioning feature was merged. **But, it is possible to modify the baseline to whatever you like and use that instead.**
 
 ### Step 1: Create a new branch
-As described in the versioning documentation. The value that goes in `"builtin-baseline"` is a Git commit in the vcpkg repository's history. Then it stands to reason, that if you want to customize the baseline you should be able to create a new commit with said custom baseline. 
+As described in the versioning documentation. The value that goes in `"builtin-baseline"` is a git commit in the microsoft/vcpkg repository's history. If you want to customize the baseline and have control over the vcpkg instance, you can create a new commit with said custom baseline.
+
+Let's start by creating a new branch to hold our modified baseline.
 
-Let's start by creating a new branch to hold our modified baseline.  
 In the directory containing your clone of the vcpkg Git repository run:
 
 ```
@@ -91,7 +92,7 @@ This will create a new branch named `custom-boost-baseline` and check it out imm
 ### Step 2: Modify the baseline
 The next step is to modify the baseline file, open the file in your editor of choice and modify the entries for the Boost libraries.
 
-Change the `"baseline"` version to your desired version.  
+Change the `"baseline"` version to your desired version.
 _NOTE: Remember to also set the port versions to 0 (or your desired version)._
 
 `${vcpkg-root}/versions/baseline.json`
@@ -126,7 +127,7 @@ _NOTE: Remember to also set the port versions to 0 (or your desired version)._
 ...
 ```
 
-Some `boost-` packages are helpers used by vcpkg and are not part of Boost. For example, `"boost-uninstall"` is a vcpkg helper to conveniently uninstall all Boost libraries, but it didn't exist for Boost version `1.72.0`, in this case it is fine to leave it at `1.75.0` to avoid baseline errors (since all versions in `baseline.json` must have existed). 
+Some `boost-` packages are helpers used by vcpkg and are not part of Boost. For example, `"boost-uninstall"` is a vcpkg helper to conveniently uninstall all Boost libraries, but it didn't exist for Boost version `1.72.0`, in this case it is fine to leave it at `1.75.0` to avoid baseline errors (since all versions in `baseline.json` must have existed).
 
 ### Step 3: Commit your changes
 After saving your modified file, run these commands to commit your changes:

diff --git a/docs/examples/versioning.getting-started.md b/docs/examples/versioning.getting-started.md
@@ -6,8 +6,6 @@ Vcpkg lets you take control of which version of packages to install in your proj
 
 ## Using versions with manifests
 
-With the `versions` feature flag enabled you can start adding version constraints to your dependencies.
-
 Let's start with creating a simple CMake project that depends on `fmt` and `zlib`.
 
 Create a folder with the following files:
@@ -97,7 +95,7 @@ fmt[core]:x86-windows -> 7.1.3#1 -- D:\vcpkg\buildtrees\versioning\versions\fmt\
 zlib[core]:x86-windows -> 1.2.11#9 -- D:\vcpkg\buildtrees\versioning\versions\zlib\827111046e37c98153d9d82bb6fa4183b6d728e4
 ```
 
-Instead of using the portfiles in `ports/`, vcpkg is checking out the files for each version in `buildtrees/versioning/versions/`. The files in `ports/` are still used when running vcpkg in classic mode or when the `versions` feature flag is disabled. 
+Instead of using the portfiles in `ports/`, vcpkg is checking out the files for each version in `buildtrees/versioning/versions/`. The files in `ports/` are still used when running vcpkg in classic mode.
 
 _NOTE: Output from vcpkg while configuring CMake is only available when using CMake version `3.18` or newer. If you're using an older CMake you can check the `vcpkg-manifest-install.log` file in your build directory instead._
 
@@ -234,11 +232,11 @@ Notice how the `fmt` is now at version `6.0.0` just like we wanted.
 
 ## Versions and custom ports
 
-The last thing to discuss is how overlay ports interact with versioning resolution. The answer is: they don't. 
+The last thing to discuss is how overlay ports interact with versioning resolution. The answer is: they don't.
 
 Going into more detail, when you provide an overlay for a port, vcpkg will always use the overlay port without caring what version is contained in it. The reasons are two-fold: (1) it is consistent with the existing behavior of overlay ports of completely masking the existing port, and (2) overlay ports do not (and are not expected to) provide enough information to power vcpkg's versioning feature.
 
-If you want to have flexible port customization along with versioning features, you should consider making your own custom registry. See our [registries specification for more details](../specifications/registries.md).
+If you want to have flexible port customization along with versioning, you should consider making your own custom registry. See our [registries specification for more details](../specifications/registries.md).
 
 ## Further reading
 

diff --git a/docs/specifications/registries-2.md b/docs/specifications/registries-2.md
@@ -2,6 +2,8 @@
 
 **Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.**
 
+**Up-to-date documentation is available at [Registries](../users/registries.md).**
+
 Originally, the design of registries was decided upon and written up in the [Registries RFC](registries.md).
 However, as we've gotten further into the design process of git registries and versioning,
 and discussed the interaction of versioning with registries,

diff --git a/docs/specifications/registries.md b/docs/specifications/registries.md
@@ -2,6 +2,8 @@
 
 **Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.**
 
+**Up-to-date documentation is available at [Registries](../users/registries.md).**
+
 As it is now, vcpkg has over 1400 ports in the default registry (the `/ports` directory).
 For the majority of users, this repository of packages is enough. However, many enterprises
 need to more closely control their dependencies for one reason or another, and this document

diff --git a/docs/users/android.md b/docs/users/android.md
@@ -2,10 +2,7 @@
 
 **The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/android.md).**
 
-Android is not officially supported, and there are no official android triplets at the moment.
-
-However, some packages can compile to Android, and the situation is improving: see the list of [PR related to Android](https://github.com/Microsoft/vcpkg/pulls?q=+android+).
-
+*Android is not tested as part of vcpkg repository's CI process, so regressions can occur as part of library updates. PRs improving support are welcome!*
 
 ## Android build requirements
 

diff --git a/docs/users/config-environment.md b/docs/users/config-environment.md
@@ -14,9 +14,7 @@ This environment variable can be set to an existing directory to use for storing
 This environment variable can be set to a comma-separated list of off-by-default features in vcpkg. These features are
 subject to change without notice and should be considered highly unstable.
 
-Non-exhaustive list of off-by-default features:
-
-- `manifest`
+There are no off-by-default feature flags at this time.
 
 #### EDITOR
 

diff --git a/docs/users/mingw.md b/docs/users/mingw.md
@@ -2,7 +2,7 @@
 
 **The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/mingw.md).**
 
-*MinGW is community-supported and not tested as part of vcpkg repository's CI process.*
+*MinGW is not tested as part of vcpkg repository's CI process, so regressions can occur as part of library updates. PRs improving support are welcome!*
 
 ## Table of Contents