[docs/users/manifests.md] Prioritize examples. Fix example. Add MSBuild integration documentation. (#16069)

* [docs/users/manifests.md] Prioritize examples. Fix example. Add MSBuild integration documentation.

* Update docs/users/manifests.md

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

* Update docs/users/manifests.md

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

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

1 files changed, 51 insertions, 33 deletions

diff --git a/docs/users/manifests.md b/docs/users/manifests.md
index e1bc0c58b..6ec2b1915 100644
--- a/docs/users/manifests.md
+++ b/docs/users/manifests.md
@@ -31,6 +31,25 @@ and a little more information on [CMake](#cmake-integration) integration.
 Check out the [manifest cmake example](../examples/manifest-mode-cmake.md) for an example project using CMake and
 manifest mode.
 
+## Simple Example Manifest
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/microsoft/vcpkg/master/scripts/vcpkg.schema.json",
+  "name": "my-application",
+  "version": "0.15.2",
+  "dependencies": [
+    "boost-system",
+    {
+      "name": "cpprestsdk",
+      "default-features": false
+    },
+    "libxml2",
+    "yajl"
+  ]
+}
+```
+
 ## Writing a Manifest
 
 A manifest is a JSON-formatted file named `vcpkg.json` which lies at the root of your project.
@@ -95,13 +114,29 @@ if they were to use you). It's an array of strings and objects:
 * On the other hand, an object dependency (e.g., `"dependencies": [ { "name": "zlib" } ]`)
   allows you to add that extra information.
 
-An object dependency can have the following fields:
+#### Example:
+
+```json
+"dependencies": [
+  {
+    "name": "arrow",
+    "default-features": false,
+    "features": [ "json" ]
+  },
+  "boost-asio",
+  "openssl",
+  {
+    "name": "picosha2",
+    "platform": "!windows"
+  }
+]
+```
 
-#### `"name"`
+#### `"name"` Field
 
 The name of the dependency. This follows the same restrictions as the [`"name"`](#name) property for a project.
 
-#### `"features"` and `"default-features"`
+#### `"features"` and `"default-features"` Fields
 
 `"features"` is an array of feature names which tell you the set of features that the
 dependencies need to have at a minimum,
@@ -120,7 +155,7 @@ Then, you might just ask for:
 }
 ```
 
-#### `"platform"`
+#### `"platform"` Field
 
 The `"platform"` field defines the platforms where the dependency should be installed - for example,
 you might need to use sha256, and so you use platform primitives on Windows, but `picosha2` on non-Windows platforms.
@@ -145,7 +180,7 @@ The common identifiers are:
 
 although one can define their own.
 
-#### `"version>="`
+#### `"version>="` Field
 
 **Experimental behind the `versions` feature flag**
 
@@ -155,26 +190,6 @@ This field specifies the minimum version of the dependency using a '#' suffix to
 
 See also [versioning](versioning.md#constraints) for more semantic details.
 
-#### Example:
-
-```json
-{
-  "dependencies": [
-    {
-      "name": "arrow",
-      "default-features": false,
-      "features": [ "json" ]
-    },
-    "boost-asio",
-    "openssl",
-    {
-      "name": "picosha2",
-      "platform": "!windows"
-    }
-  ]
-}
-```
-
 ### `"overrides"`
 
 **Experimental behind the `versions` feature flag**
@@ -186,13 +201,11 @@ See also [versioning](versioning.md#overrides) for more semantic details.
 #### Example:
 
 ```json
-{
   "overrides": [
     {
       "name": "arrow", "version": "1.2.3", "port-version": 7
     }
   ]
-}
 ```
 
 ### `"supports"`
@@ -219,9 +232,10 @@ and that's the `"default-features"` field, which is an array of feature names.
 
 #### Example:
 
-```
+```json
 {
   "name": "libdb",
+  "version": "1.0.0",
   "description": [
     "An example database library.",
     "Optionally can build with CBOR, JSON, or CSV as backends."
@@ -248,16 +262,12 @@ and that's the `"default-features"` field, which is an array of feature names.
         "fast-cpp-csv-parser"
       ]
     },
-    "gui": {
-      "description": "The GUI libdb database viewer.",
-      "supports": "windows | osx"
-    }
     "json": {
       "description": "The JSON backend",
       "dependencies": [
         "jsoncons"
       ]
-    },
+    }
   }
 }
 ```
@@ -302,3 +312,11 @@ since the CMake integration won't break as long as you depending on the exact na
 ```
 
 with a `vcpkg.json` in the same directory as `CMakeLists.txt` should Just Work!
+
+## MSBuild Integration
+
+To use manifests with MSBuild, first you need to use an [existing integration method](integration.md#with-msbuild). Then, simply add a vcpkg.json above your project file (such as in the root of your source repository) and set the property `VcpkgEnableManifest` to `true`. You can set this property via the IDE in `Project Properties -> Vcpkg -> Use Vcpkg Manifest`.
+
+As part of your project's build, vcpkg automatically be run and install any listed dependencies to `vcpkg_installed/` adjacent to the `vcpkg.json` file; these files will then automatically be included in and linked to your MSBuild projects.
+
+It's critical that all project files consuming the same `vcpkg.json` use the same triplet in a single build; if you need to use different triplets for different projects in your solution, they must consume from different `vcpkg.json` files.