diff --git a/src/Docusaurus/docs/tools/heat.md b/src/Docusaurus/docs/tools/heat.md
index 50baaee..41a1791 100644
--- a/src/Docusaurus/docs/tools/heat.md
+++ b/src/Docusaurus/docs/tools/heat.md
@@ -15,41 +15,42 @@ In WiX v4, Heat is available in a WiX extension NuGet Package. To use Heat to ha
## Using `HarvestDirectory` to harvest files from a directory
-`HarvestDirectory` items can contain the following metadata to control harvesting:
-
-| Metadata | Description |
-| -------- | ----------- |
-| `ComponentGroupName` | Optional string metadata. When harvesting multiple directories in a project, specify this metadata to create unique file names for the generated authoring. The name of the ComponentGroup to create for all the generated authoring. |
-| `DirectoryRefId` | Optional string metadata. The ID of the directory to reference instead of TARGETDIR. |
-| `KeepEmptyDirectories` | Optional boolean metadata. Whether to create Directory entries for empty directories. The default is **false**. |
-| `PreprocessorVariable` | Optional string metadata. Substitute `SourceDir` for another a preprocessor variable name. For example, specify `MyDir` to have Heat use `$(MyDir)` instead of `SourceDir`. |
-| `SuppressCom` | Optional boolean metadata. Suppress generation of COM registry elements. The default is **false**. |
-| `SuppressRegistry` | Optional boolean metadata. Suppress generation of any registry elements. The default is **false**. |
-| `SuppressRootDirectory` | Optional boolean metadata. Suppress generation of a Directory element for the parent directory of the file. The default is **false**. |
-| `Transforms` | Optional string metadata. Semicolon-delimited list of paths to XSL transforms to apply to the generated authoring. |
+`HarvestDirectory` items can contain the following options to control harvesting:
+
+| Option | Description |
+| ------ | ----------- |
+| `Include` | Required string attribute. The directory to harvest. This path can be relative to the project file, or it can be an absolute path.
+| `ComponentGroupName` | Optional string element. The name of the ComponentGroup to create for the generated authoring. Useful when harvesting multiple directories in a single project. |
+| `DirectoryRefId` | Optional string. The ID of the directory to reference instead of TARGETDIR. |
+| `KeepEmptyDirectories` | Optional boolean element. Whether to create Directory entries for empty directories. The default is **false**. |
+| `PreprocessorVariable` | Optional string element. Substitute another preprocessor variable name for `SourceDir`. For example, specify `MyDir` to have Heat use `$(MyDir)` instead of `$(SourceDir)`. |
+| `SuppressCom` | Optional boolean element. Suppress generation of COM registry elements. The default is **false**. |
+| `SuppressRegistry` | Optional boolean element. Suppress generation of any registry elements. The default is **false**. |
+| `SuppressRootDirectory` | Optional boolean element. Suppress generation of a Directory element for the top-level harvested directory itself. The default is **false**. |
+| `Transforms` | Optional string element. Semicolon-delimited list of paths to XSL transforms to apply to the generated authoring. |
The following properties control harvesting:
| Property | Description |
| -------- | ----------- |
| `HarvestDirectoryAutogenerateGuids` | Optional boolean property. Whether to generate authoring that relies on auto-generation of component GUIDs. The default is `$(HarvestAutogenerateGuids)` if specified; otherwise, **true**. |
-| `HarvestDirectoryComponentGroupName` | Optional string property. When harvesting multiple directories in a project, specify this metadata to create unique file names for the generated authoring. The component group name that will contain all generated authoring. |
+| `HarvestDirectoryComponentGroupName` | Optional string property. The name of the ComponentGroup to created for the generated authoring. Useful when harvesting multiple directories in a single project. |
| `HarvestDirectoryDirectoryRefId` | Optional string property. The identifier of the Directory element that will contain all generated authoring. |
| `HarvestDirectoryGenerateGuidsNow` | Optional boolean property. Whether to generate authoring that generates durable GUIDs when harvesting. The default is `$(HarvestGenerateGuidsNow)` if specified; otherwise, **false**. |
| `HarvestDirectoryKeepEmptyDirectories` | Optional boolean property. Whether to create Directory entries for empty directories when harvesting. The default is **false**. |
| `HarvestDirectoryNoLogo` | Optional boolean property. Whether to show the logo for heat.exe. The default is `$(NoLogo)` if specified; otherwise, **false**. |
-| `HarvestDirectoryPreprocessorVariable` | Optional string property. Substitute `SourceDir` for another a preprocessor variable name. For example, specify `MyDir` to have Heat use `$(MyDir)` instead of `SourceDir`. |
+| `HarvestDirectoryPreprocessorVariable` | Optional string property. Substitute another preprocessor variable name for `SourceDir`. For example, specify `MyDir` to have Heat use `$(MyDir)` instead of `$(SourceDir)`. |
| `HarvestDirectorySuppressAllWarnings` | Optional boolean parameter. Specifies that all warnings should be suppressed. The default is `$(HarvestSuppressAllWarnings)` if specified; otherwise, **false**. |
| `HarvestDirectorySuppressCom` | Optional boolean property. Whether to suppress generation of COM registry elements when harvesting files in directories. The default is **false**. |
| `HarvestDirectorySuppressFragments` | Optional boolean property. Whether to suppress generation of separate fragments when harvesting. The default is `$(HarvestSuppressFragments)` if specified; otherwise, **true**. |
| `HarvestDirectorySuppressRegistry` | Optional boolean property. Whether to suppress generation of all registry elements when harvesting files in directories. The default is **false**. |
-| `HarvestDirectorySuppressRootDirectory` | Optional boolean property. Whether to suppress generation of a Directory element for all authoring when harvesting. The default is **false**. |
+| `HarvestDirectorySuppressRootDirectory` | Optional boolean property. Whether to suppress generation of a Directory element for the top-level harvested directory itself. The default is **false**. |
| `HarvestDirectorySuppressSpecificWarnings` | Optional string parameter. Specifies that certain warnings should be suppressed. The default is `$(HarvestSuppressSpecificWarnings)` if specified. |
| `HarvestDirectorySuppressUniqueIds` | Optional boolean property. Whether to suppress generation of unique component IDs. The default is `$(HarvestSuppressUniqueIds)` if specified; otherwise, **false**. |
| `HarvestDirectoryTransforms` | Optional string property. Semicolon-delimited list of paths to XSL transforms to apply to the generated authoring. The default is `$(HarvestTransforms)` if specified. |
-| `HarvestDirectoryTreatSpecificWarningsAsErrors` | Optional string parameter. Specifies that certain warnings should be treated as errors. The default is `$(HarvestTreatSpecificWarningsAsErrors)` if specified. |
-| `HarvestDirectoryTreatWarningsAsErrors` | Optional boolean parameter. Specifies that all warnings should be treated as errors. The default is `$(HarvestTreatWarningsAsErrors)` if specified; otherwise, **false**. |
-| `HarvestDirectoryVerboseOutput` | Optional boolean parameter. Specifies that the tool should provide verbose output. The default is `$(HarvestVerboseOutput)` if specified; otherwise, **false**. |
+| `HarvestDirectoryTreatSpecificWarningsAsErrors` | Optional string property. Specifies that certain warnings should be treated as errors. The default is `$(HarvestTreatSpecificWarningsAsErrors)` if specified. |
+| `HarvestDirectoryTreatWarningsAsErrors` | Optional boolean property. Specifies that all warnings should be treated as errors. The default is `$(HarvestTreatWarningsAsErrors)` if specified; otherwise, **false**. |
+| `HarvestDirectoryVerboseOutput` | Optional boolean property. Specifies that the tool should provide verbose output. The default is `$(HarvestVerboseOutput)` if specified; otherwise, **false**. |
Example:
@@ -74,39 +75,42 @@ Example:
## Using `HarvestFile` to harvest data from a file
-`HarvestFile` items can contain the following metadata to control harvesting:
+The `Include` attribute specifies the file to harvest. The path can be relative to the `.wixproj` project file, or it can be an absolute path.
-| Metadata | Description |
-| -------- | ----------- |
-| `ComponentGroupName` | Optional string metadata. The name of the ComponentGroup to create for all the generated authoring. |
-| `DirectoryRefId` | Optional string metadata. The ID of the directory to reference instead of TARGETDIR. |
-| `PreprocessorVariable` | Optional string metadata. Substitute `SourceDir` for another a preprocessor variable name. For example, specify `MyDir` to have Heat use `$(MyDir)` instead of `SourceDir`. |
-| `SuppressCom` | Optional boolean metadata. Suppress generation of COM registry elements. The default is **false**. |
-| `SuppressRegistry` | Optional boolean metadata. Suppress generation of any registry elements. The default is **false**. |
-| `SuppressRootDirectory` | Optional boolean metadata. Suppress generation of a Directory element for the parent directory of the file. The default is **false**. |
-| `Transforms` | Optional string metadata. Semicolon-delimited list of paths to XSL transforms to apply to the generated authoring. |
+`HarvestFile` items can contain the following options to control harvesting:
+
+| Option | Description |
+| ------ | ----------- |
+| `Include` | Required string attribute. The file to harvest. This path can be relative to the project file, or it can be an absolute path.
+| `ComponentGroupName` | Optional string element. The name of the ComponentGroup to create for all the generated authoring. |
+| `DirectoryRefId` | Optional string element. The ID of the directory to reference instead of TARGETDIR. |
+| `PreprocessorVariable` | Optional string element. Substitute another preprocessor variable name for `SourceDir`. For example, specify `MyDir` to have Heat use `$(MyDir)` instead of `$(SourceDir)`. |
+| `SuppressCom` | Optional boolean element. Suppress generation of COM registry elements. The default is **false**. |
+| `SuppressRegistry` | Optional boolean element. Suppress generation of any registry elements. The default is **false**. |
+| `SuppressRootDirectory` | Optional boolean element. Suppress generation of a Directory element for the directory containing the file. The default is **false**. |
+| `Transforms` | Optional string element. Semicolon-delimited list of paths to XSL transforms to apply to the generated authoring. |
The following properties control harvesting:
| Property | Description |
| -------- | ----------- |
| `HarvestFileAutogenerateGuids` | Optional boolean property. Whether to generate authoring that relies on auto-generation of component GUIDs. The default is `$(HarvestAutogenerateGuids)` if specified; otherwise, **true**. |
-| `HarvestFileComponentGroupName` | Optional string property. When harvesting multiple directories in a project, specify this metadata to create unique file names for the generated authoring. The component group name that will contain all generated authoring. |
+| `HarvestFileComponentGroupName` | Optional string property. The ComponentGroup name that will contain all generated authoring. Useful when harvesting multiple items in a single project. |
| `HarvestFileDirectoryRefId` | Optional string property. The identifier of the Directory element that will contain all generated authoring. |
| `HarvestFileGenerateGuidsNow` | Optional boolean property. Whether to generate authoring that generates durable GUIDs when harvesting. The default is `$(HarvestGenerateGuidsNow)` if specified; otherwise, **false**. |
| `HarvestFileNoLogo` | Optional boolean property. Whether to show the logo for heat.exe. The default is `$(NoLogo)` if specified; otherwise, **false**. |
-| `HarvestFilePreprocessorVariable` | Optional string property. Substitute `SourceDir` for another a preprocessor variable name. For example, specify `MyDir` to have Heat use `$(MyDir)` instead of `SourceDir`. |
+| `HarvestFilePreprocessorVariable` | Optional string property. Substitute another preprocessor variable name for `SourceDir`. For example, specify `MyDir` to have Heat use `$(MyDir)` instead of `$(SourceDir)`. |
| `HarvestFileSuppressAllWarnings` | Optional boolean parameter. Specifies that all warnings should be suppressed. The default is `$(HarvestSuppressAllWarnings)` if specified; otherwise, **false**. |
| `HarvestFileSuppressCom` | Optional boolean property. Whether to suppress generation of COM registry elements when harvesting files in directories. The default is **false**. |
| `HarvestFileSuppressFragments` | Optional boolean property. Whether to suppress generation of separate fragments when harvesting. The default is `$(HarvestSuppressFragments)` if specified; otherwise, **true**. |
| `HarvestFileSuppressRegistry` | Optional boolean property. Whether to suppress generation of all registry elements when harvesting files in directories. The default is **false**. |
-| `HarvestFileSuppressRootDirectory` | Optional boolean property. Whether to suppress generation of a Directory element for all authoring when harvesting. The default is **false**. |
+| `HarvestFileSuppressRootDirectory` | Optional boolean property. Whether to suppress generation of a Directory element for the directory containing the harvested file. The default is **false**. |
| `HarvestFileSuppressSpecificWarnings` | Optional string parameter. Specifies that certain warnings should be suppressed. The default is `$(HarvestSuppressSpecificWarnings)` if specified. |
| `HarvestFileSuppressUniqueIds` | Optional boolean property. Whether to suppress generation of unique component IDs. The default is `$(HarvestSuppressUniqueIds)` if specified; otherwise, **false**. |
| `HarvestFileTransforms` | Optional string property. Semicolon-delimited list of paths to XSL transforms to apply to the generated authoring. The default is `$(HarvestTransforms)` if specified. |
-| `HarvestFileTreatSpecificWarningsAsErrors` | Optional string parameter. Specifies that certain warnings should be treated as errors. The default is `$(HarvestTreatSpecificWarningsAsErrors)` if specified. |
-| `HarvestFileTreatWarningsAsErrors` | Optional boolean parameter. Specifies that all warnings should be treated as errors. The default is `$(HarvestTreatWarningsAsErrors)` if specified; otherwise, **false**. |
-| `HarvestFileVerboseOutput` | Optional boolean parameter. Specifies that the tool should provide verbose output. The default is `$(HarvestVerboseOutput)` if specified; otherwise, **false**. |
+| `HarvestFileTreatSpecificWarningsAsErrors` | Optional string property. Specifies that certain warnings should be treated as errors. The default is `$(HarvestTreatSpecificWarningsAsErrors)` if specified. |
+| `HarvestFileTreatWarningsAsErrors` | Optional boolean property. Specifies that all warnings should be treated as errors. The default is `$(HarvestTreatWarningsAsErrors)` if specified; otherwise, **false**. |
+| `HarvestFileVerboseOutput` | Optional boolean property. Specifies that the tool should provide verbose output. The default is `$(HarvestVerboseOutput)` if specified; otherwise, **false**. |
Example:
@@ -140,13 +144,15 @@ Example:
## Using `HarvestProject` to harvest output from a project
Harvesting projects is disabled by default because it may not always work correctly. To enable it, set `EnableProjectHarvesting` to **true** in your project file.
+When project harvesting is enabled, Heat will try to harvest all referenced projects. Use the `DoNotHarvest` flag in any `ProjectReference` element to exclude individual projects.
-`HarvestProject` items can contain the following metadata to control harvesting:
+`HarvestProject` items can contain the following options to control harvesting:
-| Metadata | Description |
+| Option | Description |
| -------- | ----------- |
-| `ProjectOutputGroups` | Semicolon-delimited list of project output groups to harvest. Examples include `Binaries` and `Source`. |
-| `Transforms` | Optional string metadata. Semicolon-delimited list of paths to XSL transforms to apply to the generated authoring. |
+| `Include` | Required attribute. The project file to harvest. The path can be relative to the project file, or it can be an absolute path. |
+| `ProjectOutputGroups` | Required attribute. Semicolon-delimited list of project output groups to harvest. Examples include `Binaries` and `Source`. |
+| `Transforms` | Optional string element. Semicolon-delimited list of paths to XSL transforms to apply to the generated authoring. |
The following properties control harvesting:
@@ -156,14 +162,14 @@ The following properties control harvesting:
| `HarvestProjectsGenerateGuidsNow` | Optional boolean property. Whether to generate authoring that generates durable GUIDs when harvesting. The default is `$(HarvestGenerateGuidsNow)` if specified; otherwise, **false**. |
| `HarvestProjectsNoLogo` | Optional boolean property. Whether to show the logo for heat.exe. The default is `$(NoLogo)` if specified; otherwise, **false**. |
| `HarvestProjectsProjectOutputGroups` | Optional string property. Semicolon-delimited list of project output groups to harvest. Possible Values: `Binaries`, `Symbols`, `Documents`, `Satellites`, `Sources` & `Content`. |
-| `HarvestProjectsSuppressAllWarnings` | Optional boolean parameter. Specifies that all warnings should be suppressed. The default is `$(HarvestSuppressAllWarnings)` if specified; otherwise, **false**. |
+| `HarvestProjectsSuppressAllWarnings` | Optional boolean property. Specifies that all warnings should be suppressed. The default is `$(HarvestSuppressAllWarnings)` if specified; otherwise, **false**. |
| `HarvestProjectsSuppressFragments` | Optional boolean property. Whether to suppress generation of separate fragments when harvesting. The default is `$(HarvestSuppressFragments)` if specified; otherwise, **true**. |
-| `HarvestProjectsSuppressSpecificWarnings` | Optional string parameter. Specifies that certain warnings should be suppressed. The default is `$(HarvestSuppressSpecificWarnings)` if specified. |
+| `HarvestProjectsSuppressSpecificWarnings` | Optional string property. Specifies that certain warnings should be suppressed. The default is `$(HarvestSuppressSpecificWarnings)` if specified. |
| `HarvestProjectsSuppressUniqueIds` | Optional boolean property. Whether to suppress generation of unique component IDs. The default is `$(HarvestSuppressUniqueIds)` if specified; otherwise, **false**. |
| `HarvestProjectsTransforms` | Optional string property. Semicolon-delimited list of paths to XSL transforms to apply to the generated authoring. The default is `$(HarvestTransforms)` if specified. |
-| `HarvestProjectsTreatSpecificWarningsAsErrors` | Optional string parameter. Specifies that certain warnings should be treated as errors. The default is `$(HarvestTreatSpecificWarningsAsErrors)` if specified. |
-| `HarvestProjectsTreatWarningsAsErrors` | Optional boolean parameter. Specifies that all warnings should be treated as errors. The default is `$(HarvestTreatWarningsAsErrors)` if specified; otherwise, **false**. |
-| `HarvestProjectsVerboseOutput` | Optional boolean parameter. Specifies that the tool should provide verbose output. The default is `$(HarvestVerboseOutput)` if specified; otherwise, **false**. |
+| `HarvestProjectsTreatSpecificWarningsAsErrors` | Optional string property. Specifies that certain warnings should be treated as errors. The default is `$(HarvestTreatSpecificWarningsAsErrors)` if specified. |
+| `HarvestProjectsTreatWarningsAsErrors` | Optional boolean property. Specifies that all warnings should be treated as errors. The default is `$(HarvestTreatWarningsAsErrors)` if specified; otherwise, **false**. |
+| `HarvestProjectsVerboseOutput` | Optional boolean property. Specifies that the tool should provide verbose output. The default is `$(HarvestVerboseOutput)` if specified; otherwise, **false**. |
Example:
@@ -178,7 +184,6 @@ Example:
-
@@ -189,7 +194,7 @@ Example:
```
-Once harvested, you can use these ouput groups in your wxs file as with a ComponentGroupRef.
+Heat creates a `ComponentGroup` for each of the selected `ProjectOutputGroups`. Use `ComponentGroupRef`s to include these in your installation.
Example:
```xml