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 |
|---|
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 |
|---|
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. |
| 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. |
| {@AutoDocumentConstructors}, {@AutoDocumentDisposeMethods}, {@ShowMissingNamespaces}, {@ShowMissingParams}, {@ShowMissingRemarks}, {@ShowMissingReturns}, {@ShowMissingSummaries}, {@ShowMissingTypeParams}, {@ShowMissingValues} | These tags equates to the ShowMissing* project properties and are used to set the ShowMissingComponent build component configuration settings in the sandcastle.config file templates. |
| {@BinaryTOC} | This tag equates to a Yes or No value based on the BinaryTOC project setting. This is placed in the help file project template. |
| {@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}). |
| {@CopyrightHref} | This tag expands to the CopyrightHref project option. |
| {@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}, {@MRefFrameworkVersion}, {@MRefFrameworkVersionShort} | 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). |
| {@HXCompPath} | This tag expands to the path to the MS Help 2 compiler. This will be the path that the help builder found or the HtmlHelp2xCompilerPath project option if it is specified instead. |
| {@HeaderText} | This tag expands to the value of the HeaderText project option. |
| {@Help1xProjectFiles} and {@Help2xProjectFiles} | These tags appear in the help file project templates and are 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). |
| {@IncludeProjectNode} | This tag expands to the parameter used to indicate that the "Project" root namespace node should be included in the table of contents for the Hana and VS2005 presentation styles based on the setting of the RootNamespaceContainer project property. |
| {@IndentHtml} | This tag expands to the parameter used to indicate whether or not the HTML rendered by BuildAssembler is indented. This is mainly a debugging aid. When true, the HTML is indented to make it more readable. Leave it set to false to produce more compact HTML. |
| {@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. |
| {@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. |
| {@Preliminary} | This tag will expand to the include directive to place the "preliminary documentation" warning in all page headers if the Preliminary project option is set to true. |
| {@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 name 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. |
| {@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. |
| {@RootNamespaceTitle} | This tag expands to the value of the RootNamespaceTitle project option. |
| {@SandcastlePath} | This tag expands to the path to the Sandcastle installation folder. This will be the path that the help builder found or the SandcastlePath project option if it is specified instead. |
| {@HtmlSdkLinkType}, {@MSHelp2SdkLinkType}, {@MSHelpViewerSdkLinkType}, and {@WebsiteSdkLinkType} | These tags expands to the value of the matching named project properties. |
| {@SHFBFolder} | This tag expands to the path to the Sandcastle Help File Builder installation folder. |
| {@StopWordFile} | This tag expands to the StopWordFile option in the Help 2 project file when the IncludeStopWordFile project property is set to true. |
| {@SyntaxFilters} and {@SyntaxFiltersDropDown} | These tags expand to the language filter components that determine which languages appear in the Syntax section of each help topic and the dropdown in the upper right corner of the topic in the Prototype 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. |
| {@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 and Build2xHelpFile.proj | These MSBuild projects are used to build the HTML Help 1 and MS Help 2 help file projects respectively and copy the resulting help file and supporting files to the project's output folder. | ||
| BuildConceptualTopics.proj and BuildReferenceTopics.proj | These MSBuild projects are used to build the conceptual and reference help topics respectively using BuildAssembler. | ||
| conceptual.config | This is the Sandcastle configuration file template used to build conceptual help topics using BuildAssembler. The conceptual help build component stack is currently not dependent on the presentation style so the same one is used for all of them. | ||
| 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. | ||
| FixScriptSharp.xsl | This XSL transformation is used to fix up the reflection information file produced by runing MRefBuilder on assemblies created by the Script# compiler. It adds fixes up some of the entries for use with Sandcastle and adds a scriptSharp element to the members so that the JavaScript syntax generator produces code that matches the actual output of the Script# tools. | ||
| GenerateInheritedDocs.proj and GenerateInheritedDocs.config | This MSBuild project and configuration file are used to generate the inherited documentation file. | ||
| GenerateIntermediateTOC.proj and Generate2xTOC.proj | These MSBuild projects are used to generate the intermediate table of contents file and the MS Help 2 specific 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. | ||
| Hana.config, Prototype.config, and VS2005.config | These are the Sandcastle configuration file templates. One of these will be updated with the necessary paths and project options based on the presentation style selected. The transformed file is used as the sandcastle.config for BuildAssembler to produce the API help topic files. | ||
| Hana.xsl, Prototype.xsl, and VS2005.xsl | These are the default XSL transformation files used to convert
additional content .topic files into HTML files if a
user-defined transformation file is not supplied.
| ||
| 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. | ||
| Help2x*.* | This set of files defines the help file project templates for MS Help 2 help files. | ||
| 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. | ||
| 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, warnings, and build step project names. | ||
| 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. |
CautionSee Also
