[docs] Fix issues encountered during publishing 2022-09-01 (microsoft…

…#26794) * [docs] Document 'host' field in manifests * [docs] Assorted fixes found while regenerating website * Update docs/users/manifests.md Co-authored-by: Victor Romero <[email protected]>
Enochack · Sep 23, 2022 · c5ca6fd · c5ca6fd
1 parent 5f6dfcb
commit c5ca6fd
Show file tree

Hide file tree

Showing 5 changed files with 28 additions and 18 deletions.
diff --git a/docs/commands/common-options.md b/docs/commands/common-options.md
@@ -56,7 +56,7 @@ Specifies the path to lay out installed packages.
 
 In Classic Mode, defaults to `installed/` under the vcpkg root folder.
 
-In [Manifest Mode][../users/manifests.md], defaults to `vcpkg_installed/` under the manifest folder.
+In [Manifest Mode](../users/manifests.md), defaults to `vcpkg_installed/` under the manifest folder.
 
 <a name="manifest-root"></a>
 

diff --git a/docs/commands/install.md b/docs/commands/install.md
@@ -45,7 +45,7 @@ All vcpkg commands support a set of [common options](common-options.md).
 
 Instead of stopping on an unsupported port, continue with a warning.
 
-By default, vcpkg refuses to execute an install plan containing a port installation for a triplet outside its [`"supports"`][] clause. The [`"supports"`][] clause of a package describes the full set of platforms a package is expected to be buildable on. This flag instructs vcpkg to warn that the build is expected to fail instead of stopping.
+By default, vcpkg refuses to execute an install plan containing a port installation for a triplet outside its [`"supports"`][supports] clause. The [`"supports"`][supports] clause of a package describes the full set of platforms a package is expected to be buildable on. This flag instructs vcpkg to warn that the build is expected to fail instead of stopping.
 
 ### `--clean-after-build`
 
@@ -103,6 +103,8 @@ Fail install if a port has detected problems or attempts to use a deprecated fea
 
 By default, vcpkg will run several checks on built packages and emit warnings if any issues are detected. This flag upgrades those warnings to an error.
 
+<a name="feature"></a>
+
 ### `--x-feature=<feature>`
 
 **Experimental and may change or be removed at any time**
@@ -111,7 +113,7 @@ By default, vcpkg will run several checks on built packages and emit warnings if
 
 Specify an additional [feature](../users/manifests.md#features) from the `vcpkg.json` to install dependencies for.
 
-By default, only [`"dependencies"`](../users/manifests.md#dependencies) and the dependencies of the [`"default-features"`](../users/manifests.md#default-features) will be installed.
+By default, only [`"dependencies"`][dependencies] and the dependencies of the [`"default-features"`][default-features] will be installed.
 
 ### `--head`
 
@@ -135,7 +137,7 @@ By default, vcpkg will stop at the first package build failure. This flag instru
 
 Don't install the default features from the top-level manifest.
 
-When using `install` in Manifest Mode, by default all dependencies of the features listed in [`"default-features"`][] will be installed. This flag disables that behavior so (without any `TODO` flags) only the dependencies listed in [`"dependencies"`][] will be installed.
+When using `install` in Manifest Mode, by default all dependencies of the features listed in [`"default-features"`][default-features] will be installed. This flag disables that behavior so only features explicitly enabled by [`--x-feature`](#feature) will be installed.
 
 ### `--no-downloads`
 
@@ -186,6 +188,6 @@ Suppress generation of usage text printed at the end of installation.
 [Asset Caching]: ../users/assetcaching.md
 [Binary Caching]: ../users/binarycaching.md
 [Manifest Mode]: ../users/manifests.md
-[`"supports"`]: ../users/manifests.md#supports
-[`"default-features"`]: ../users/manifests.md#default-features
-[`"dependencies"`]: ../users/manifests.md#dependencies
+[supports]: ../users/manifests.md#supports
+[default-features]: ../users/manifests.md#default-features
+[dependencies]: ../users/manifests.md#dependencies
diff --git a/docs/commands/remove.md b/docs/commands/remove.md
@@ -16,7 +16,7 @@ vcpkg remove --outdated [options]
 
 Remove port packages from Classic Mode.
 
-`remove` removes listed packages and any packages that require them from the Classic Mode [installed directory][common-options.md#install-root]. See the [install command documentation](install.md#package-syntax) for detailed syntax of the `<package>` parameter.
+`remove` removes listed packages and any packages that require them from the Classic Mode [installed directory](common-options.md#install-root). See the [install command documentation](install.md#package-syntax) for detailed syntax of the `<package>` parameter.
 
 This command is not currently supported in [Manifest Mode][].
 

diff --git a/docs/commands/update-baseline.md b/docs/commands/update-baseline.md
@@ -14,7 +14,7 @@ vcpkg x-update-baseline [options] [--add-initial-baseline] [--dry-run]
 
 Update baselines for all configured [registries][].
 
-In [Manifest Mode][], this command operates on all [registries][] in the `vcpkg.json` and the [`vcpkg-configuration.json`][]. In Classic Mode, this command operates on the [`vcpkg-configuration.json`][] in the vcpkg instance (`$VCPKG_ROOT`).
+In [Manifest Mode][], this command operates on all [registries][] in the `vcpkg.json` and the [`vcpkg-configuration.json`][vcj]. In Classic Mode, this command operates on the [`vcpkg-configuration.json`][vcj] in the vcpkg instance (`$VCPKG_ROOT`).
 
 See the [versioning documentation](../users/versioning.md#baselines) for more information about baselines.
 
@@ -32,11 +32,11 @@ Print the planned baseline upgrades, but do not modify the files on disk.
 
 **[Manifest Mode][] Only**
 
-Add a [`"builtin-baseline"`][] field to the `vcpkg.json` if it does not already have one.
+Add a [`"builtin-baseline"`][builtin-baseline] field to the `vcpkg.json` if it does not already have one.
 
 Without this flag, it is an error to run this command on a manifest that does not have any [registries][] configured.
 
 [Manifest Mode]: ../users/manifests.md
-[`"builtin-baseline"`]: ../users/manifests.md#builtin-baseline
-[`vcpkg-configuration.json`]: ../users/registries.md#vcpkg-configurationjson
+[builtin-baseline]: ../users/manifests.md#builtin-baseline
+[vcj]: ../users/registries.md#vcpkg-configurationjson
 [registries]: ../users/registries.md
diff --git a/docs/users/manifests.md b/docs/users/manifests.md
@@ -31,15 +31,14 @@ manifest mode.
     - [`"name"`](#dependencies-name)
     - [`"default-features"`](#dependencies-default-features)
     - [`"features"`](#dependencies-features)
+    - [`"host"`](#host)
     - [`"platform"`](#platform)
     - [`"version>="`](#version-gt)
   - [`"overrides"`](#overrides)
   - [`"supports"`](#supports)
   - [`"features"`](#features)
   - [`"default-features"`](#default-features)
 
-See also [the original specification](../specifications/manifests.md) for more low-level details.
-
 ## Simple Example Manifest
 
 ```json
@@ -69,8 +68,9 @@ Manifests follow strict JSON: they can't contain C++-style comments (`//`) nor t
 you can use field names that start with `$` to write your comments in any object that has a well-defined set of keys.
 These comment fields are not allowed in any objects which permit user-defined keys (such as `"features"`).
 
-Each manifest contains a top level object with the fields documented below; the most important ones are
-[`"name"`](#name), the [version fields](#version-fields), and [`"dependencies"`](#dependencies):
+The latest JSON Schema is available at https://raw.githubusercontent.com/microsoft/vcpkg/master/scripts/vcpkg.schema.json. IDEs with JSON Schema support such as Visual Studio and Visual Studio Code can use this file to provide IntelliSense and syntax checking. For most IDEs, you should set `"$schema"` in your `vcpkg.json` to this URL (like the above example).
+
+Each manifest contains a top level object with the following fields:
 
 <a id="name"></a>
 
@@ -80,8 +80,6 @@ This is the name of your project! It must be formatted in a way that vcpkg under
 it must be lowercase alphabetic characters, digits, and hyphens, and it must not start nor end with a hyphen.
 For example, `Boost.Asio` might be given the name `boost-asio`.
 
-This is a required field.
-
 ### Version Fields
 
 There are four version field options, depending on how the port orders its
@@ -190,6 +188,16 @@ Then, you might just ask for:
 }
 ```
 
+<a id="host"></a>
+
+#### `"host"` Field
+
+A boolean indicating that the dependency must be built for the [host triplet](host-dependencies.md) instead of the current port's triplet. Defaults to `false`.
+
+Any dependency that provides tools or scripts which should be "executed" during a build (such as buildsystems, code generators, or helpers) should be marked as `"host": true`. This enables correct cross-compilation in cases that the target is not executable -- such as when compiling for `arm64-android`.
+
+See [Host Dependencies](host-dependencies.md) for more information.
+
 <a id="platform"></a>
 
 #### `"platform"` Field