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

docs/examples/manifest-mode-cmake.md

@@ -1,6 +1,6 @@
 # Manifest Mode: CMake Example
 
-We would like to add vcpkg manifest support to an existing cmake project!
+We would like to add [vcpkg manifest support](../users/manifests.md) to an existing cmake project!
 Let's create a simple project that prints the fibonacci sequence up to a certain number,
 using some common dependencies.
 

docs/examples/versioning.getting-started.md

@@ -1,22 +1,43 @@
 # Getting started with versioning
 
+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/examples/versioning.getting-started.md).**
+
 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:
+To start using [versioning](../users/versioning.md), first you need to enable the `versions` feature flag in any of the following manners:
 
-* Setting the `VCPKG_FEATURE_FLAGS` environment variable.
+* Setting the `VCPKG_FEATURE_FLAGS` environment variable
 
 ```PowerShell
 # Example for PowerShell
 $env:VCPKG_FEATURE_FLAGS="versions"
-./vcpkg install
+```
+```bash
+# Example for bash
+export VCPKG_FEATURE_FLAGS=versions
+```
+```cmd
+REM Example for cmd
+SET VCPKG_FEATURE_FLAGS=versions
 ```
 
-* Passing the feature flags in the vcpkg command line.
-```PowerShell
-./vcpkg --feature-flags="versions" install
+* Passing the feature flags in the vcpkg command line
+```bash
+./vcpkg install --feature-flags=versions
+```
+
+* Setting `VCPKG_FEATURE_FLAGS` before your `project()` CMake directive
+```cmake
+set(VCPKG_FEATURE_FLAGS versions)
+project(myapp)
+```
+* Setting `VcpkgAdditionalInstallOptions` (Project Properties -> Vcpkg -> Additional Options) in your MSBuild project
+```xml
+<PropertyGroup>
+  <VcpkgAdditionalInstallOptions>--feature-flags=versions</VcpkgAdditionalInstallOptions>
+</PropertyGroup>
 ```
 
 ## Using versions with manifests
@@ -28,7 +49,7 @@ Let's start with creating a simple CMake project that depends on `fmt` and `zlib
 Create a folder with the following files:
 
 **vcpkg.json**
-```
+```json
 {
     "name": "versions-test",
     "version": "1.0.0",
@@ -61,7 +82,7 @@ int main()
 ```CMake
 cmake_minimum_required(VERSION 3.18)
 
-project(versions-test CXX)
+project(versionstest CXX)
 
 add_executable(main main.cpp)
 
@@ -109,42 +130,40 @@ fmt[core]:x86-windows -> 7.1.3 -- D:\vcpkg\buildtrees\versioning\versions\fmt\dd
 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 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._
+_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._
 
 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`**
-```
+#### **`version`**
+```json
 {
     "name": "versions-test",
-    "version": "1.0.0",
-    ...
+    "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 scheme   | Description
+---------------- | ---------------
+`version`        | Dot-separated numerics: `1.0.0.5`.
 `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-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"
-],
+#### **`version>=`** 
+```json
+{
+    "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`. 
@@ -155,7 +174,7 @@ Vcpkg uses a minimum version approach, in our example, even if `fmt` version `8.
 
 If you want to upgrade your dependencies, you can bump the minimum version constraint or use a newer baseline.
 
-* **`builtin-baseline`**
+#### **`builtin-baseline`**
 
 ```
 "builtin-baseline": "b60f003ccf5fe8613d029f49f835c8929a66eb61"
@@ -163,7 +182,7 @@ If you want to upgrade your dependencies, you can bump the minimum version const
 
 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):
+From the [versioning documentation](../users/versioning.md):
 
 > The baseline references a commit within the vcpkg repository that
 establishes a minimum version on every dependency in the graph. If
@@ -197,7 +216,7 @@ Baselines are also a convenient mechanism to upgrade multiple versions at a time
 
 But what if you want to pin a version older than the baseline? 
 
-* **`overrides`**
+#### **`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.
 
@@ -264,11 +283,11 @@ If you want to have flexible port customization along with versioning features,
 
 ## 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).
+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](../users/versioning.implementation-details.md).
 
 See also:
 
-* [Versioning docs](versioning.md)
+* [Versioning docs](../users/versioning.md)
 * [Original specification](../specifications/versioning.md)
-* [Versioning reference](versioning.reference.md)
-* [Versioning implementation details](versioning.implementation-details.md)
+* [Versioning reference](../users/versioning.reference.md)
+* [Versioning implementation details](../users/versioning.implementation-details.md)

docs/index.md

@@ -1,5 +1,7 @@
 ### Quick Start
 
+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/index.md).**
+
 Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This tool and ecosystem are constantly evolving; your involvement is vital to its success!
 
 ### Examples
@@ -8,20 +10,23 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This too
 - [Packaging Zipfiles Example: zlib](examples/packaging-zipfiles.md)
 - [Packaging GitHub Repositories Example: libogg](examples/packaging-github-repos.md)
 - [Patching Example: Patching libpng to work for x86-uwp](examples/patching.md)
+- [Getting Started with Versioning](examples/versioning.getting-started.md)
 
 ### User Help
 
 - [Integration with build systems](users/integration.md)
 - [Triplet files](users/triplets.md)
 - [Configuration and Environment](users/config-environment.md)
+- [Manifests](users/manifests.md)
+- [Binary Caching](users/binarycaching.md)
+- [Versioning](users/versioning.md)
 - [Usage with Android](users/android.md)
-- [Using a manifest file to declare your dependencies](users/manifests.md)
 - [Host Dependencies](users/host-dependencies.md)
 
-### Maintainer help
+### Maintainer Help
 
-- [Control files](maintainers/control-files.md) - in general, one should use manifest files instead
-- [Manifest files](maintainers/manifest-files.md)
+- [Manifest files - vcpkg.json](maintainers/manifest-files.md)
+- [Control files](maintainers/control-files.md)
 - [Portfile functions](maintainers/portfile-functions.md)
 - [Maintainer Guidelines](maintainers/maintainer-guide.md)
 

docs/maintainers/control-files.md

@@ -1,7 +1,7 @@
 # CONTROL files
 
-CONTROL files are retained for backwards compatibility with earlier versions of vcpkg;
-all new features are added only to vcpkg.json, and we recommend using vcpkg.json for any newly authored port.
+**CONTROL files are retained for backwards compatibility with earlier versions of vcpkg;
+all new features are added only to [vcpkg.json](manifests.md), and we recommend using vcpkg.json for any newly authored port.**
 
 The `CONTROL` file contains metadata about the port.  The syntax is based on [the Debian `control` format][debian] although we only support the subset of fields documented here.
 

docs/specifications/binarycaching.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 [Binarycaching](../users/binarycaching.md).**
+
 ## Motivation
 
 The primary motivation of binary caching is to accelerate two broad scenarios in an easily accessible way

docs/specifications/export-command.md

@@ -1,5 +1,7 @@
 # Binary Export (Apr 28, 2017)
 
+**Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.**
+
 ## 1. Motivation
 
 ### A. Build once and share

docs/specifications/feature-packages.md

@@ -1,6 +1,8 @@
 # Proposal: Features / Feature packages (Feb 23 2017)
 
-**Note: this is the proposal as it was initially accepted and does not necessarily reflect the current behavior.**
+**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 [Selecting Library Features](../users/selecting-library-features.md).**
 
 ## 1. Motivation
 

docs/specifications/manifests.md

@@ -1,5 +1,9 @@
 # Manifests -- `vcpkg.json`
 
+**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 [Manifests](../users/manifests.md).**
+
 For many other language package managers, there exists a way of writing one's dependencies in a declarative
 manifest format; we want something similar for vcpkg. What follows is the specification of that feature;
 this should mean that vcpkg becomes far more user and enterprise-friendly, and is additionally an important

docs/specifications/ports-overlay.md

@@ -1,5 +1,6 @@
 # Ports Overlay (Jun 19, 2019)
 
+**Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.**
 
 ## 1. Motivation
 

docs/specifications/prefab.md

@@ -1,5 +1,7 @@
 # Vcpkg: export Android prefab Archives (AAR files)
 
+**Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.**
+
 Vcpkg can export android archives ([AAR files](https://developer.android.com/studio/projects/android-library)). Once an archive is created, it can imported in Android Studio as a native dependent.  The archive is automatically consumed using [android studio's prefab tool](https://github.com/google/prefab). 
 
 For more information on Prefab, refer to:

docs/specifications/registries-2.md

@@ -1,5 +1,7 @@
 # Registries: Take 2 (including Git Registries)
 
+**Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.**
+
 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,

docs/specifications/registries.md

@@ -1,5 +1,7 @@
 # Package Federation: Custom Registries
 
+**Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.**
+
 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

docs/specifications/scripts-extraction.md

@@ -1,5 +1,7 @@
 # Scripts Tree Extraction
 
+**Note: this is the feature as it was initially specified and does not necessarily reflect the current behavior.**
+
 ## Background
 
 We extracted vcpkg-tool as part of a future wherein Registries are the primary mechanism for interacting with the ports tree, which would allow the vcpkg tool and associated artifacts to be deployed and figure the rest out on their own. Unfortunately, we have concurrently edited things in the so called "scripts" tree which lives in support of ports but really probably belongs in the vcpkg-tool repo.

docs/specifications/versioning.md

@@ -1,5 +1,9 @@
 # Versioning Specification 
 
+**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 [Versioning](../users/versioning.md).**
+
 ## Glossary
 Some of the terms used in this document have similar meaning when discussed by the community, and because of that, they can cause confusion and ambiguity. To solve this issue, we will assign specific meaning to these terms and try to keep a consistent usage through the document.
 

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

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.

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

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)

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

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

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.

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)

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
 

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: