|
|
<html>
<head>
<link rel="stylesheet" type="text/css" href="styles/Styles.css">
<title>Customizing the Build Process</title>
</head>
<body>
<h2>Customizing the Build Process</h2>
In order to provide the ability to customize the main build steps, I opted
to place the scripts used to run the tools and the configuration files in
the <b>.\Templates</b> folder beneath the installation folder rather than
embedding them in the executables. This should allow you to further modify
them to add steps or modify the final output without having to recompile
the build tools. 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.
<p/>The following files are found in the <b>.\Templates</b> folder.<br/><br/>
<table cellSpacing="0" cellPadding="5" width="80%" border="1">
<tr>
<th><b>Template File</b></td>
<th><b>Description</b></td>
</tr>
<tr>
<td valign="top">Build1xHelpFile.bat and Build2xHelpFile.bat</td>
<td>These scripts are used to build the HTML 1.x and HTML 2.x help file
project respectively and copy the resulting .CHM file to the project's output
folder.</td>
</tr>
<tr>
<td valign="top">BuildHelpTopics.bat</td>
<td>This script is used to build the help topics using
<b>BuildAssembler</b>, the <b>sandcastle.config</b> file, and the
<b>manifest.xml</b> file.</td>
</tr>
<tr>
<td valign="top">Generate1xIndex.bat</td>
<td>This script is used to generate the index file for HTML 1.x files by
performing an XSLT transformation on the <b>reflection.xml</b> file.</td>
</tr>
<tr>
<td valign="top">Generate1xTOC.bat and Generate2xTOC.bat</td>
<td>These scripts are used to generate the table of content file for
HTML 1.x and HTML 2.x files respectively by performing an XSLT
transformation on the <b>reflection.xml</b> file.</td>
</tr>
<tr>
<td valign="top">GenerateRefInfo.bat</td>
<td>This script is used to generate the reflection information from the
documentation assemblies using <b>MRefBuilder</b>. The result is the
<b>reflection.org</b> file that contains information about the types in
each assembly.</td>
</tr>
<tr>
<td valign="top">Help1x.hhp</td>
<td>This is the help file project template for HTML 1.x help files. This
defines the basic help file options and the help window properties.</td>
</tr>
<tr>
<td valign="top">Help2x*.*</td>
<td>This set of files defines the help file project templates for
HTML 2.x help files.</td>
</tr>
<tr>
<td valign="top">sandcastle.config</td>
<td>This is the Sandcastle configuration file template. It will be
updated with the necessary paths and project options for use by
<b>BuildAssembler</b> to produce the help topic files.</td>
</tr>
<tr>
<td valign="top">TransformManifest.bat</td>
<td>This script applies some XSLT transformations to the reflection
output file generated by <b>MRefBuilder</b> and results in the production of
the <b>reflection.xml</b> and <b>manifest.xml</b> files.</td>
</tr>
</table>
<p/>The files above 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.<br/><br/>
<table cellSpacing="0" cellPadding="5" width="80%" border="1">
<tr>
<th><b>Template File</b></td>
<th><b>Description</b></td>
</tr>
<tr>
<td valign="top">{@AutoDocumentConstructors}, {@ShowMissingParams},
{@ShowMissingRemarks}, {@ShowMissingReturns}, {@ShowMissingSummaries},
{@ShowMissingValues}</td>
<td>These tags equates to the <code>ShowMissing*</code> project properties
and are used to set the <code>ShowMissingComponent</code> build component
configuration settings in the <b>sandcastle.config</b> file template.</td>
</tr>
<tr>
<td valign="top">{@BinaryTOC}</td>
<td>This tag equates to a Yes or No value based on the
<code>BinaryTOC</code> project setting. This is placed in the help file
project template.</td>
</tr>
<tr>
<td valign="top">{@CommentFileList}</td>
<td>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.</td>
</tr>
<tr>
<td valign="top">{@Comments}</td>
<td>If a <code>FeedbackEMailAddress</code> is specified in the project,
this tag expands to the include directive that adds the "send e-mail" note
to the page footers.</td>
</tr>
<tr>
<td valign="top">{@CopyrightHref}</td>
<td>This tag expands to the <code>CopyrightHref</code> project option.</td>
</tr>
<tr>
<td valign="top">{@CopyrightInfo} and {@HtmlEncCopyrightInfo}</td>
<td>This tag expands to an empty string if neither the
<code>CopyrightHref</code> nor the <code>CopyrightText</code> 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.</td>
</tr>
<tr>
<td valign="top">{@CopyrightText} and {@HtmlEncCopyrightText}</td>
<td>This tag expands to the <code>CopyrightText</code> project option
(plain text and HTML encoded).</td>
</tr>
<tr>
<td valign="top">{@Copyright}</td>
<td>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.</td>
</tr>
<tr>
<td valign="top">{@DefaultTopic} and {@WebDefaultTopic}</td>
<td>These tags appears in the help file project template and the website
index page respectively and expand to the filename of the default topic.</td>
</tr>
<tr>
<td valign="top">{@Dependencies}</td>
<td>This tag expands to the <b>/dep</b> command line option for
<b>MRefBuilder</b> for each assembly specified in the project's
<code>Dependencies</code> option (if any). The referenced assemblies are
copied to the <b>.\DLL</b> folder under the working folder to keep the command
line as short as possible in case the project has many dependencies.</td>
</tr>
<tr>
<td valign="top">{@DocInternals}</td>
<td>This tag expands to the <b>/internal+</b> command line option for
<b>MRefBuilder</b> if the <code>DocumentInternals</code> property is set to
true.</td>
</tr>
<tr>
<td valign="top">{@FeedbackEMailAddress}, {@HtmlEncFeedbackEMailAddress},
{UrlEncFeedbackEMailAddress}</td>
<td>This tag expands to the <code>FeedbackEMailAddress</code> project
option if it is specified (plain text, HTML encoded, and URL encoded).</td>
</tr>
<tr>
<td valign="top">{@FrameworkVersion} and {@FrameworkVersionShort}</td>
<td>These tags expand to the selected <code>FrameworkVersion</code>
project option (full and "major.minor" respectively) and are placed in the
Sandcastle and MRefBuilder configuration files.</td>
</tr>
<tr>
<td valign="top">{@HHCPath}</td>
<td>This tag expands to the path to the HTML help 1.x compiler. This will
be the path that the help builder found or the <code>HtmlHelp1xCompilerPath</code>
project option if it is specified instead.</td>
</tr>
<tr>
<td valign="top">{@HTMLHelpName}</td>
<td>This expands to the value of the <code>HtmlHelpName</code> project
option.</td>
</tr>
<tr>
<td valign="top">{@HXCompPath}</td>
<td>This tag expands to the path to the HTML help 2.x compiler. This will
be the path that the help builder found or the <code>HtmlHelp2xCompilerPath</code>
project option if it is specified instead.</td>
</tr>
<tr>
<td valign="top">{@HeaderText}</td>
<td>This tag expands to the value of the <code>HeaderText</code> project
option.</td>
</tr>
<tr>
<td valign="top">{@Help1xProjectFiles} and {@Help2xProjectFiles}</td>
<td>These tags appears in the help file project templates and are used to
return a list of all files that should be compiled into the help file.</td>
</tr>
<tr>
<td valign="top">{@HelpTitle}, {@HtmlEncHelpTitle}, {@UrlEncHelpTitle}</td>
<td>The tag expands to the <code>HelpTitle</code> project option (plain
text, HTML encoded, and URL encoded).</td>
</tr>
<tr>
<td valign="top">{@LanguageId}</td>
<td>This tag expands to the language ID for the <code>Language</code>
project option.</td>
</tr>
<tr>
<td valign="top">{@Locale}</td>
<td>This tag expands to the locale name for the <code>Language</code>
project option.</td>
</tr>
<tr>
<td valign="top">{@OutputFolder}</td>
<td>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.</td>
</tr>
<tr>
<td valign="top">{@Preliminary}</td>
<td>This tag will expand to the include directive to place the
"preliminary documentation" warning in all page headers if the
<code>Preliminary</code> project option is set to true.</td>
</tr>
<tr>
<td valign="top">{@PresentationPath} and {@PresentationStyle}</td>
<td>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 <code>PresentationStyle</code> property. The
second expands to the name of the style itself.</td>
</tr>
<tr>
<td valign="top">{@ProjectFolder}</td>
<td>This tag expands to the path that contains the project file. This is
useful for build components that need paths relative to the project.</td>
</tr>
<tr>
<td valign="top">{@ProjectLinks}</td>
<td>This tag expands to the value of the <code>ProjectLinkType</code>
project option.</td>
</tr>
<tr>
<td valign="top">{@RootNamespaceTitle}</td>
<td>This tag expands to the value of the <code>RootNamespaceTitle</code>
project option.</td>
</tr>
<tr>
<td valign="top">{@SandcastlePath}</td>
<td>This tag expands to the path to the Sandcastle installation folder.
This will be the path that the help builder found or the
<code>SandcastlePath</code> project option if it is specified instead.</td>
</tr>
<tr>
<td valign="top">{@SDKLinks}</td>
<td>This tag expands to the value of the <code>SdkLinkType</code> project
option.</td>
</tr>
<tr>
<td valign="top">{@SHFBFolder}</td>
<td>This tag expands to the path to the Sandcastle Help File Builder
installation folder.</td>
</tr>
<tr>
<td valign="top">{@SyntaxFilters} and {@SyntaxFiltersDropDown}</td>
<td>This tag expands to the language filter components that determine which
languages appear in the <b>Syntax</b> section of each help topic and the
dropdown in the upper right corner of the topic.</td>
</tr>
<tr>
<td valign="top">{@WindowOptions}</td>
<td>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 <code>IncludeFavorites</code> project property is
set to true, the value includes the option to show the Favorites tab too.</td>
</tr>
<tr>
<td valign="top">{@WorkingFolder}</td>
<td>This tag expands to the full path to the working folder and is used in
the templates to help the tools locate the files in the temporary working
folder.</td>
</tr>
</table>
<br/><br/>
<include item="footer"/>
</body>
</html>
<!-- @SortOrder 10 -->
|
By viewing downloads associated with this article you agree to the Terms of Service and the article's licence.
If a file you wish to view isn't highlighted, and is a text file (not binary), please
let us know and we'll add colourisation support for it.
Eric Woodruff is an Analyst/Programmer for Spokane County, Washington where he helps develop and support various applications, mainly criminal justice systems, using Windows Forms (C#) and SQL Server as well as some ASP.NET applications.
He is also the author of various open source projects for .NET including:
The Sandcastle Help File Builder - A front end and project management system that lets you build help file projects using Microsoft's Sandcastle documentation tools. It includes a standalone GUI and a package for Visual Studio integration.
Visual Studio Spell Checker - A Visual Studio editor extension that checks the spelling of comments, strings, and plain text as you type or interactively with a tool window. This can be installed via the
Visual Studio Gallery.
Image Map Controls - Windows Forms and web server controls that implement image maps.
PDI Library - A complete set of classes that let you have access to all objects, properties, parameter types, and data types as defined by the vCard (RFC 2426), vCalendar, and iCalendar (RFC 2445) specifications. A recurrence engine is also provided that allows you to easily and reliably calculate occurrence dates and times for even the most complex recurrence patterns.
Windows Forms List Controls - A set of extended .NET Windows Forms list controls. The controls include an auto-complete combo box, a multi-column combo box, a user control dropdown combo box, a radio button list, a check box list, a data navigator control, and a data list control (similar in nature to a continuous details section in Microsoft Access or the DataRepeater from VB6).
For more information see
http://www.EWoodruff.us
Submit an article or tip