[docs] Improve inter-document linking; add 'latest' links (#16502)

* [docs] Improve inter-document linking; add 'latest' links

* [docs] Apply suggestions from code review

Co-authored-by: nicole mazzuca <mazzucan@outlook.com>

Co-authored-by: nicole mazzuca <mazzucan@outlook.com>
Co-authored-by: Robert Schumacher <roschuma@microsoft.com>

11 files changed, 51 insertions, 296 deletions

diff --git a/docs/users/android.md b/docs/users/android.md
index 6ff1d05d1..b56030f55 100644
--- a/docs/users/android.md
+++ b/docs/users/android.md
@@ -1,5 +1,7 @@
 # Vcpkg and Android
 
+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/android.md).**
+
 Android is not officialy 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+).
diff --git a/docs/users/binarycaching.md b/docs/users/binarycaching.md
index a388e4065..b77836984 100644
--- a/docs/users/binarycaching.md
+++ b/docs/users/binarycaching.md
@@ -1,5 +1,7 @@
 # Binary Caching
 
+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/binarycaching.md).**
+
 Binary caching is vcpkg's method for reusing package builds between projects and between machines. Think of it as a "package restore accelerator" that gives you the same results as though you built from source. Each build is packaged independently, so changing one library only requires rebuilding consuming libraries.
 
 If your CI provider offers a native "caching" function, we recommend using both methods for the most performant results.
diff --git a/docs/users/config-environment.md b/docs/users/config-environment.md
index e164bc0e7..169b2aff7 100644
--- a/docs/users/config-environment.md
+++ b/docs/users/config-environment.md
@@ -1,5 +1,7 @@
 ## Environment and Configuration

 

+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/config-environment.md).**

+

 ### Environment Variables

 

 #### VCPKG_DOWNLOADS

diff --git a/docs/users/integration.md b/docs/users/integration.md
index 933d2ce82..ba8ea4d8b 100644
--- a/docs/users/integration.md
+++ b/docs/users/integration.md
@@ -1,5 +1,7 @@
 ## Buildsystem Integration
 
+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/integration.md).**
+
 Vcpkg offers many ways to integrate into your build so you can do what's right for your project. There are two main categories of integration:
 
 - [`integrate` command](#integrate)
diff --git a/docs/users/manifests.md b/docs/users/manifests.md
index 2ee64ec3e..9cec98cfa 100644
--- a/docs/users/manifests.md
+++ b/docs/users/manifests.md
@@ -1,6 +1,8 @@
 # Manifest Mode
 
-vcpkg has two modes of operation - classic mode and manifest mode.
+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/manifests.md).**
+
+vcpkg has two modes of consuming dependencies - classic mode and manifest mode.
 
 In classic mode, vcpkg produces an "installed" tree, whose contents are changed by explicit calls to `vcpkg install` or
 `vcpkg remove`. The installed tree is intended for consumption by any number of projects: for example, installing a
diff --git a/docs/users/selecting-library-features.md b/docs/users/selecting-library-features.md
index 03c1863b3..51d828280 100644
--- a/docs/users/selecting-library-features.md
+++ b/docs/users/selecting-library-features.md
@@ -1,30 +1,25 @@
 # Selecting library features
 
+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/selecting-library-features.md).**
+
 ## Installing a library
 
-We will look at [llvm](https://llvm.org/) as an example.
-LLVM is a compiler infrasture. It supports optimizing llvm-ir and generating machine code.
-You could install it using:
+We will look at [llvm](https://llvm.org/) as an example. You could install it using:
 
 ```powershell
-> .\vcpkg install llvm
+> vcpkg install llvm
 ```
-
-On Windows, this will install the 32-bit x86 LLVM, since that's the default triplet on Windows.
-If you are building for 64-bit Windows instead, you can use the following command to change the default triplet:
-
-```powershell
-> .\vcpkg install --triplet x64-windows llvm
+or via a manifest with
+```json
+{
+  "dependencies": ["llvm"]
+}
 ```
 
-We have more documentation on triplets [here](triplets.md).
-Currently we can't choose build type `debug` or `release` using command line switches.
-
 With llvm now installed, we can execute:
 
 ```powershell
-> # llc takes llvm IR and generates machine code
-> .\installed\x86-windows\bin\llc.exe --version # or x86-windows, or replace with the actual triplet
+> installed\x86-windows\bin\llc.exe --version
 ```
 
 we see:
@@ -45,7 +40,7 @@ The llvm port allows this via the "target-*" features.
 If we do:
 
 ```powershell
-.\vcpkg search llvm
+> vcpkg search llvm
 ```
 
 We can see:
@@ -64,17 +59,33 @@ llvm[target-arm]                      Build with ARM backend.
 We can install any of these targets by using the install-feature syntax:
 
 ```powershell
-> .\vcpkg install llvm[target-arm] # Installs LLVM with the ARM target
+> vcpkg install llvm[target-arm] # Installs LLVM with the ARM target
+```
+```json
+{
+  "dependencies": [{ "name": "llvm", "features": ["target-arm"] }]
+}
 ```
 
-## Opting out of default feature
+## Opting out of default features
+
 The llvm port includes a few default features that you as a user may not want: for example,
 the `clang` feature is default, which means that `vcpkg install llvm` will also build and install clang.
 If you are writing a compiler that uses LLVM as a backend,
 you're likely not interested in installing clang as well,
 and we can do that by disabling default features with the special `core` "feature":
 ```powershell
-> .\vcpkg install llvm[core,default-targets] # removing the default-feature with "core" also removes all of the default targets you get
+> vcpkg install llvm[core,target-arm] # removing the default-feature with "core" also removes all of the default targets you get
+```
+or in manifest files:
+```json
+{
+  "dependencies": [{
+    "name": "llvm",
+    "default-features": false,
+    "features": ["target-arm"]
+  }]
+}
 ```
 
 # Further reading
diff --git a/docs/users/triplets.md b/docs/users/triplets.md
index 37efd590d..61192575a 100644
--- a/docs/users/triplets.md
+++ b/docs/users/triplets.md
@@ -1,5 +1,7 @@
 # Triplet files
 
+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/triplets.md).**
+
 Triplet is a standard term used in cross compiling as a way to completely capture the target environment (cpu, os, compiler, runtime, etc) in a single convenient name.
 
 In Vcpkg, we use triplets to describe an imaginary "target configuration set" for every library. Within a triplet, libraries are generally built with the same configuration, but it is not a requirement. For example, you could have one triplet that builds `openssl` statically and `zlib` dynamically, one that builds them both statically, and one that builds them both dynamically (all for the same target OS and architecture). A single build will consume files from a single triplet.
diff --git a/docs/users/versioning.getting-started.md b/docs/users/versioning.getting-started.md
deleted file mode 100644
index 6be419adf..000000000
--- a/docs/users/versioning.getting-started.md
+++ /dev/null
@@ -1,274 +0,0 @@
-# Getting started with versioning

-

-Vcpkg lets you take control of which version of packages to install in your projects using manifests. 

-

-## Enabling versions

-

-To start using the versioning feature, first you need to enable the `versions` feature flag in any of the following manners:

-

-* Setting the `VCPKG_FEATURE_FLAGS` environment variable.

-

-```PowerShell

-# Example for PowerShell

-$env:VCPKG_FEATURE_FLAGS="versions"

-./vcpkg install

-```

-

-* Passing the feature flags in the vcpkg command line.

-```PowerShell

-./vcpkg --feature-flags="versions" install

-```

-

-## Using versions with manifests

-

-With the `versions` feature flag enabled you can start addding 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:

-

-**vcpkg.json**

-```

-{

-    "name": "versions-test",

-    "version": "1.0.0",

-    "dependencies": [

-        {

-            "name": "fmt",

-            "version>=": "7.1.3"

-        }, 

-        "zlib"

-    ],

-    "builtin-baseline": "b60f003ccf5fe8613d029f49f835c8929a66eb61"

-}

-```

-

-**main.cpp**

-```c++

-#include <fmt/core.h>

-#include <zlib.h>

-

-int main()

-{

-    fmt::print("fmt version is {}\n"

-               "zlib version is {}\n", 

-               FMT_VERSION, ZLIB_VERSION);

-    return 0;

-}

-```

-

-**CMakeLists.txt**

-```CMake

-cmake_minimum_required(VERSION 3.18)

-

-project(versions-test CXX)

-

-add_executable(main main.cpp)

-

-find_package(ZLIB REQUIRED)

-find_package(fmt CONFIG REQUIRED)

-target_link_libraries(main PRIVATE ZLIB::ZLIB fmt::fmt)

-```

-

-And now we build and run our project with CMake:

-

-1. Create the build directory for the project.

-```

-PS D:\versions-test> mkdir build

-PS D:\versions-test> cd build

-```

-

-2. Configure CMake.  

-```

-PS D:\versions-test\build> cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=D:/vcpkg/scripts/buildsystems/vcpkg.cmake ..

--- Running vcpkg install

-Detecting compiler hash for triplet x86-windows...

-The following packages will be built and installed:

-    fmt[core]:x86-windows -> 7.1.3 -- D:\vcpkg\buildtrees\versioning\versions\fmt\dd8cf5e1a2dce2680189a0744102d4b0f1cfb8b6

-    zlib[core]:x86-windows -> 1.2.11#9 -- D:\vcpkg\buildtrees\versioning\versions\zlib\827111046e37c98153d9d82bb6fa4183b6d728e4

-...

-```

-

-3. Build the project.

-```

-PS D:\versions-test\build> cmake --build .

-[2/2] Linking CXX executable main.exe

-```

-

-4. Run it!

-```

-PS D:\versions-test\build> ./main.exe

-fmt version is 70103

-zlib version is 1.2.11

-```

-

-Take a look at the output:

-

-```

-fmt[core]:x86-windows -> 7.1.3 -- D:\vcpkg\buildtrees\versioning\versions\fmt\dd8cf5e1a2dce2680189a0744102d4b0f1cfb8b6

-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. 

-

-_NOTE: Output from the 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._

-

-Read our [manifests announcement blog post](https://devblogs.microsoft.com/cppblog/vcpkg-accelerate-your-team-development-environment-with-binary-caching-and-manifests/#using-manifests-with-msbuild-projects) to learn how to use manifests with MSBuild.

-

-### Manifest changes

-If you have used manifests before you will notice that there are some new JSON properties. Let's review these changes:

-

-* **`version`**

-```

-{

-    "name": "versions-test",

-    "version": "1.0.0",

-    ...

-}

-```

-

-This is your project's version declaration. Previously, you could only declare versions for your projects using the `version-string` property. Now that versioning has come around, vcpkg is aware of some new versioning schemes.

-

-Version scheme | Description

--- | --

-`version` | Dot-separated numerics: `1.0.0`.

-`version-semver` | Compliant [semantic versions](https://semver.org): `1.2.0` and `1.2.0-rc`.

-`version-date` | Dates in `YYYY-MM-DD` format: `2021-01-01`

-`version-string` | Arbitrary strings: `vista`, `candy`.

-

-* **`version>=`** 

-```

-"dependencies": [

-    {

-        "name": "fmt",

-        "version>=": "7.1.3"

-    }, 

-    "zlib"

-],

-```

-

-This property is used to express minimum version constraints, it is allowed only as part of the `"dependencies"` declarations. In our example we set an explicit constraint on version `7.1.3` of `fmt`. 

-

-Vcpkg is allowed to upgrade this constraint if a transitive dependency requires a newer version. For example, if `zlib` were to declare a dependency on `fmt` version `7.1.4` then vcpkg would install `7.1.4` instead.

-

-Vcpkg uses a minimum version approach, in our example, even if `fmt` version `8.0.0` were to be released, vcpkg would still install version `7.1.3` as that is the minimum version that satisfies the constraint. The advantages of this approach are that you don't get unexpected dependency upgrades when you update vcpkg and you get reproducible builds (in terms of version used) as long as you use the same manifest. 

-

-If you want to upgrade your dependencies, you can bump the minimum version constraint or use a newer baseline.

-

-* **`builtin-baseline`**

-

-```

-"builtin-baseline": "b60f003ccf5fe8613d029f49f835c8929a66eb61"

-```

-

-This field declares the versioning baseline for all ports. Setting a baseline is required to enable versioning, otherwise you will get the current versions on the ports directory. You can run 'git rev-parse HEAD' to get the current commit of vcpkg and set it as the builtin-baseline. But what is a baseline? What does it do? Why is the value a SHA?

-

-From the [versioning documentation](versioning.md):

-

-> The baseline references a commit within the vcpkg repository that

-establishes a minimum version on every dependency in the graph. If

-no other constraints are specified (directly or transitively),

-then the version from the baseline of the top level manifest will

-be used.

-

-In our example, you can notice that we do not declare a version constraint for `zlib`; instead, the version is taken from the baseline. Internally, vcpkg will look in commit `b60f003ccf5fe8613d029f49f835c8929a66eb61` to find out what version of `zlib` was the latest at that point in time (in our case it was `1.2.11#9`).

-

-During version resolution, baseline versions are treated as minimum version constraints. If you declare an explicit constraint that is lower than a baseline version, the explicit constraint will be upgraded to the baseline version. 

-

-For example, if we modified our dependencies like this:

-```

-"dependencies": [

-    {

-        "name": "fmt",

-        "version>=": "7.1.3"

-    },

-    {

-        "name": "zlib",

-        "version>=": "1.2.11#7"

-    }

-]

-```

-

-_NOTE: The value `1.2.11#7` represents version `1.2.11`, port version `7`._

-

-Since the baseline introduces a minimum version constraint for `zlib` at `1.2.11#9` and a higher version does satisfy the minimum version constraint for `1.2.11#7`, vcpkg is allowed to upgrade it. 

-

-Baselines are also a convenient mechanism to upgrade multiple versions at a time, for example, if you wanted to depend on multiple `boost` libraries, it is more convenient to set the `baseline` once than declaring a version constraint on each package.

-

-But what if you want to pin a version older than the baseline? 

-

-* **`overrides`**

-

-Since baselines establish a version floor for all packages and explicit constraints get upgraded when they are lower than the baseline, we need another mechanism to downgrade versions past the baseline.

-

-The mechanism vcpkg provides for that scenario is `overrides`. When an override is declared on a package, vcpkg will ignore all other version constraints either directly declared in the manifest or from transitive dependencies. In short, `overrides` will force vcpkg to use the exact version declared, period.

-

-Let's modify our example once more, this time to force vcpkg to use version `6.0.0` of `fmt`.

-

-```

-{

-    "name": "versions-test",

-    "version": "1.0.0",

-    "dependencies": [

-        {

-            "name": "fmt",

-            "version>=": "7.1.3"

-        },

-        {

-            "name": "zlib",

-            "version>=": "1.2.11#7"

-        }

-    ],

-    "builtin-baseline": "b60f003ccf5fe8613d029f49f835c8929a66eb61",

-    "overrides": [

-        {

-            "name": "fmt",

-            "version": "6.0.0"

-        }

-    ]

-}

-```

-

-Rebuild our project:

-

-```

-PS D:\versions-test\build> rm ./CMakeCache.txt

-PS D:\versions-test\build> rm -r ./vcpkg_installed

-PS D:\versions-test\build> cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=D:/vcpkg/scripts/buildsystems/vcpkg.cmake ..

--- Running vcpkg install

-Detecting compiler hash for triplet x86-windows...

-The following packages will be built and installed:

-    fmt[core]:x86-windows -> 6.0.0 -- D:\vcpkg\buildtrees\versioning\versions\fmt\d99b6a35e1406ba6b6e09d719bebd086f83ed5f3

-    zlib[core]:x86-windows -> 1.2.11#9 -- D:\vcpkg\buildtrees\versioning\versions\zlib\827111046e37c98153d9d82bb6fa4183b6d728e4

-...

-PS D:\versions-test\build> cmake --build .

-[2/2] Linking CXX executable main.exe

-```

-

-And run it!

-```

-PS D:\versions-test\build> .\main.exe

-fmt version is 60000

-zlib version is 1.2.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. 

-

-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).

-

-## Further reading

-

-If you're interested in delving deeper into the details of how versioning works we recommended that you read the [original versioning specification](../specifications/versioning.md) and the [implementation details](versioning.implementation-details.md).

-

-See also:

-

-* [Versioning docs](versioning.md)

-* [Original specification](../specifications/versioning.md)

-* [Versioning reference](versioning.reference.md)

-* [Versioning implementation details](versioning.implementation-details.md)

diff --git a/docs/users/versioning.implementation-details.md b/docs/users/versioning.implementation-details.md
index f363fb438..fc5981e24 100644
--- a/docs/users/versioning.implementation-details.md
+++ b/docs/users/versioning.implementation-details.md
@@ -1,5 +1,7 @@
 # Versioning: Implementation details

 

+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/versioning.implementation-details.md).**

+

 ## Contents

 

 * [Minimum versioning](#minimum-versioning)

diff --git a/docs/users/versioning.md b/docs/users/versioning.md
index 5db7f42c2..6fdc678e5 100644
--- a/docs/users/versioning.md
+++ b/docs/users/versioning.md
@@ -1,11 +1,13 @@
 # Versioning
 
+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/versioning.md).**
+
 **This feature is experimental and requires `--feature-flags=versions`**
 
 Versioning allows you to deterministically control the precise revisions of dependencies used by
 your project from within your manifest file.
 
-See our guide to [getting started with versioning](versioning.getting-started.md).
+See our guide to [getting started with versioning](../examples/versioning.getting-started.md).
 
 ## Version schemes
 
diff --git a/docs/users/versioning.reference.md b/docs/users/versioning.reference.md
index eb49b44e2..976b84612 100644
--- a/docs/users/versioning.reference.md
+++ b/docs/users/versioning.reference.md
@@ -1,5 +1,7 @@
 # Versioning reference

 

+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/versioning.reference.md).**

+

 ## Contents

 

 * [Version schemes](#version-schemes)

@@ -114,7 +116,7 @@ Each port in vcpkg has a corresponding versions file, the location of a port's v
 

 ```

 ${VCPKG_ROOT}/versions/${first-letter-of-portname}-/${portname}.json

-````

+```

 

 For example, for `zlib` the corresponding versions file is: