Click or drag to resize
Sandcastle Help File Builder

Customizing the Build Process

In order to provide the ability to customize the main build steps in earlier versions of the help file builder, the scripts used to run the tools and the related configuration files were placed in the .\Templates folder beneath the main help file builder installation folder rather than embedding them in the executables. In each file are a set of substitution tags that will be resolved to one of the project properties and, in some cases, a list of files at build time.

Note Note

All current and future versions of the help file builder support plug-ins which provide a much more flexible way of altering and extending the build process without the need to modify the supplied templates. You can use the same set of substitution tags in your own scripts, configuration files, and plug-ins and resolve them at build-time as well.

Replacement Tags

The help file builder template files as well as various files in your own projects such as token files may contain one or more of the following substitution tags. At build-time, these tags will be replaced with the appropriate project value in order to produce the help file. Some of these tags also appear in the language resource files and are used to place items in the page header and footer. These tags can also be entered into text project properties such as HeaderText or FooterText to have them appear in the help topics.

Tip Tip

Any MSBuild property can also be referenced using the substitution tag syntax ({@PropertyName}). This allows you to define custom properties via the UserDefinedProperties project property and use them in other project properties such as HelpFileVersion, HeaderText, etc.

For a list of the standard help file builder property names, see the property page help topics. The internal property name of each property option is listed after the property section title in parentheses.

Replacement Tag

Description

{@AppDataFolder} and {@LocalDataFolder}

{@AppDataFolder} is replaced with the common application data folder for the help file builder. This is used to store third-party build components and plug-ins. {@LocalDataFolder} is replaced with the local application data folder for the help file builder. This is used to store cache files and other user settings. See the Special Folder Locations topic for more information.

{@BuildDate} or {@BuildDate:[date-format]}

This tag allows you to insert a build date/time into a project file or a text project property such as HeaderText or FooterText. If {@BuildDate} is used, the full date time is inserted using the default format. You can also specify a custom date format. For example: {@BuildDate:MMMM d, yyyy a\t hh:mm tt}

{@CodeSnippetsFiles}

This tag expands to a list of the conceptual content code snippets files that will be used by the Example Component in conceptual content builds. To be included, the project file must have its BuildAction set to CodeSnippets.

{@CommentFileList}

This tag expands to a list of the XML comment files that will be used to produce the help file. This tag is placed in the Sandcastle configuration file.

{@Comments}

If a FeedbackEMailAddress is specified in the project, this tag expands to the include directive that adds the "send e-mail" note to the page footers.

{@ComponentsFolder}

This tag expands to the path where the custom build components can be found. This will be the Build Components\ folder under common application data folder ({@AppDataFolder}).

{@CopyrightInfo} and {@HtmlEncCopyrightInfo}

These tags expand to an empty string if neither the CopyrightHref nor the CopyrightText project options are specified. If only one or the other is specified, then it results in the value of the project option that is present. If both are specified, it results in a link to the specified URL with the specified copyright text. The first version is plain text, the second version is HTML encoded.

{@CopyrightText} and {@HtmlEncCopyrightText}

These tags expand to the CopyrightText project option (plain text and HTML encoded).

{@Copyright}

If either or both of the copyright project options are specified, this tag will expand to the include directive necessary to place the text in the page footers.

{@DefaultTopic} and {@WebDefaultTopic}

These tags appear in the help file project template and the website index page respectively and expand to the filename of the default topic.

{@DocInternals}

This tag expands to "true" if either the DocumentInternals or DocumentPrivates project property is set to true. If both are set to false, this expands to "false".

{@ExtractFlags}

This tag expands to the flags that tell the HTML extract tool what files to create. It will generate files for the HTML Help 1 and website builds as needed.

{@FeedbackEMailAddress}, {@HtmlEncFeedbackEMailAddress}, {UrlEncFeedbackEMailAddress}, {@FeedbackEMailLinkText}

These tags expand to the FeedbackEMailAddress project option if it is specified (plain text, HTML encoded, and URL encoded) and the FeedbackEMailLinkText project option if specified (plain text). Note that if FeedbackEMailLinkText is specified, it will be used in place of the e-mail address for the {@HtmlEncFeedbackEMailAddress} tag's value.

{@FrameworkVersion}, {@FrameworkVersionShort}

These tags expand to the selected FrameworkVersion project option (full and "major.minor" respectively) and are placed in the sandcastle.config and MRefBuilder.config configuration files.

{@H2RegPlugInEntries} and {@H2RegMergeNamespaces}

These two tags expand to the plug-in and merge namespace entries in the H2Reg.ini file.

{@HHCPath}

This tag expands to the path to the HTML Help 1 compiler. This will be the path that the help builder found or the HtmlHelp1xCompilerPath project option if it is specified instead.

{@HTMLHelpName} and {@HTMLEncHelpName}

These expand to the value of the HtmlHelpName project option (plain text and HTML encoded).

{@Help1xProjectFiles}

This tag appears in the help file project templates and is used to return a list of all files that should be compiled into the help file.

{@HelpTitle}, {@HtmlEncHelpTitle}, {@UrlEncHelpTitle}, and {@ScriptHelpTitle}

These tags expand to the HelpTitle project option (plain text, HTML encoded, URL encoded, and quote-escaped for JavaScript).

{@InheritedCommentFileList}

This tag expands to a list of the XML comment files that will be used to produce the inherited documentation. This tag is placed in the Generate Inherited Documentation tool's configuration file.

{@LanguageFolder}

This tag expands to the language folder to use for the Sandcastle shared content files. If a folder is not found for the selected language, the default US-English Sandcastle shared content files are used.

{@LangId} and {@LanguageName}

These tags expands to the locale ID (LCID) and the locale ID plus language name for the Language project option.

{@Locale}

This tag expands to the locale name for the Language project option.

{@ManifestTransformation}

This tag expands to the document model transformation filename for the selected presentation style.

{@ManifestTransformationParameters}

This tag expands to the document model transformation parameters for the selected presentation style.

{@OutputFolder}

This tag expands to the full path to the output folder and is used in the templates to help the tools locate the output folder.

{@PresentationPath} and {@PresentationStyle}

The first tag expands to the path of the presentation folder that contains the art, scripts, style sheets, and transformations for the style selected with the project's PresentationStyle property. The second expands to the ID of the style itself.

{@ProjectFolder} and {@HtmlEncProjectFolder}

These tags expand to the path that contains the project file (plain text and HTML encoded). This is useful for build components that need paths relative to the project.

{@ProjectNodeName}

This expands to the root namespace page ID (the project node ID). The resolved value will be in the format R:Project_[HtmlHelpName] where "HtmlHelpName" is the value of that property from your project.

{@ProjectNodeIDRequired} and {@ProjectNodeIdOptional}

These expand to the root namespace page ID (the project node ID) that gets passed to the document model XSL transformation. The resolved value will be in the format Project_[HtmlHelpName] where "HtmlHelpName" is the value of that property from your project. The "Optional" version may be an empty string if not used for the build.

{@ResourceItemFiles}

This tag expands to a list of the resource item files in the project that contain project overrides for the Sandcastle resource items used in the generated help topics. To be included, the project file must have its BuildAction set to ResourceItems.

{@SHFBFolder}

This tag expands to the path to the Sandcastle Help File Builder installation folder.

{@SyntaxFilters} and {@SyntaxFiltersDropDown}

These tags expand to the language filter components that determine which languages appear in the Syntax section of each help topic.

{@TargetFrameworkIdentifier}

This tag expands to target framework identifier based on the current FrameworkVersion project property setting. It will be .NETFramework for .NET versions, Silverlight for Silverlight versions, .NETPortable for the .NET Portable framework versions, or .NETCore for .NET for Windows Store Apps frameworks.

{@TocTransformation}

This tag expands to the table of contents transformation filename for the selected presentation style.

{@TocTransformationParameters}

This tag expands to the table of contents transformation parameters for the selected presentation style.

{@TokenFiles}

This tag expands to a list of the conceptual content token files that will be used by the token Shared Content Component in conceptual content builds. To appear in the list, the project file must have its BuildAction set to Tokens.

{@TransformComponentArguments}

This expands to the transform component arguments that are passed to the BuildAssembler tool's TransformComponent.

{@WindowOptions}

This tag expands to a value in the help file project that determines the window options available. Currently, a default set of options is used to display most of the common features such as the basic toolbar buttons and the search tab. If the IncludeFavorites project property is set to true, the value includes the option to show the Favorites tab too.

{@WorkingFolder} and {@HtmlEncWorkingFolder}

These tags expand to the full path to the working folder (plain text and HTML encoded) and are used in the templates to help the tools locate the files in the temporary working folder.

Template Files

The following files are found in the .\Templates folder under the main help file builder installation folder.

Template File

Description

Build1xHelpFile.proj, BuildHelpViewerFile.proj, BuildOpenXmlFile.proj, GenerateMarkdownContent.proj

These MSBuild projects are used to build the HTML Help 1, MS Help Viewer, Open XML, and markdown help projects respectively and copy the resulting output and supporting files to the project's output folder. The MS Help Viewer version simply copies the supporting files to the project's output folder as the build engine compresses the topics into the archive that becomes the MSHC file.

BuildConceptualTopics.proj and BuildReferenceTopics.proj

These MSBuild projects are used to build the conceptual and reference help topics respectively using BuildAssembler.

ExtractHtmlInfo.proj

This MSBuild project runs a tool used to generate the index file and table of contents file for HTML Help 1 files and the table of contents file for websites. It can also localize the content files by performing several character replacements and saving the files using a different encoding to work around encoding issues encountered while using the HTML Help 1 compiler with certain languages that require double-byte characters.

GenerateInheritedDocs.proj and GenerateInheritedDocs.config

This MSBuild project and configuration file are used to generate the inherited documentation file.

GenerateIntermediateTOC.proj

This MSBuild projects is used to generate the intermediate table of contents file by performing an XSL transformation on the reflection.xml file.

GenerateRefInfo.proj

This MSBuild project is used to generate the reflection information from the documentation assemblies using MRefBuilder. The result is the reflection.org file that contains information about the types in each assembly.

Help1x.hhp

This is the help file project template for HTML Help 1 help files. This defines the basic help file options and the help window properties.

HelpContentSetup.msha, InstallMSHC.bat, and RemoveMSHC.bat

These are the template file used for the MS Help Viewer content setup file and the example scripts used to install and remove the MS Help Viewer content.

HelpFileBuilderTokens.tokens

This contains a default set of tokens used by all help projects. Currently, it only contains a single entry for the standard autoOutline token.

MRefBuilder.config

This configuration file is used to supply some configuration information to MRefBuilder that it uses when generating the reflection information file.

PlaceHolderNode.aml

This is a blank MAML topic used as the target for empty place holder nodes when generating MS Help Viewer files. MS Help Viewer does not support empty place holder nodes so this topic fills them so that the build succeeds and generates a valid file. A unique ID is generated for each placeholder inserted into the file.

TransformBuildLog.xsl

This XSL transformation file is used to transform the build log into something that is more readable by formatting the build steps into collapsible sections and highlight errors and warnings.

TransformManifest.proj

This MSBuild project applies some XSL transformations to the reflection output file generated by MRefBuilder and results in the production of the reflection.xml and manifest.xml files.

See Also