Click or drag to resize
Sandcastle Help File BuilderMulti-Format Output Component

The Multi-Format Output Component is used to execute a set of build components to generate help topics for one or more help file formats at the same time with differing configuration options.

The following is an example configuration for the Multi-Format Output component. It should be inserted as the last component in the configuration file. All subsequent components are nested within it as child elements, one set for each possible help file format.

Example Configuration
Copy
<!-- Multi-format output component.  This must wrap the component set
     unique to each output file format. -->
<component id="Multi-format Output Component">
  <!-- This defines the formats to generate -->
  <build formats="{@HelpFileFormat}" />

  <!-- This defines the set of components for HTML Help 1 files -->
  <helpOutput format="HtmlHelp1">
    <!-- Add additional header resources -->
    <component id="Additional Header Resources Component">
      <meta http-equiv="X-UA-Compatible" content="IE=EmulateIE9" />
      <stylesheet name="../styles/branding-Help1.css" />
    </component>

    <!-- Resolve shared content -->
    <component id="Shared Content Component">
      <content file="{@ResourceItemsFolder}shared_content.xml" />
      <content file="{@ResourceItemsFolder}reference_content.xml" />
      <content file="{@ResourceItemsFolder}syntax_content.xml" />
      <!-- These must be last in order to override other elements! -->
      <content file="SHFBContent.xml" />
      {@ResourceItemFiles}
    </component>

    <!-- Resolve conceptual links -->
    <component id="Resolve Conceptual Links Component">
      <showBrokenLinkText value="true" />
      <targets base="xmlComp" type="Local" />
    </component>

    <!-- Resolve reference links -->
    <component id="Resolve Reference Links Component">
      <locale value="{@Locale}" />
      <linkTarget value="{@SdkLinkTarget}" />
      <msdnContentIdCache path="{@LocalDataFolder}Cache\MsdnContentId.cache" />
      <targets base="{@SHFBFolder}Data\Reflection" recurse="true" files="*.xml"
        type="{@HtmlSdkLinkType}" id="FrameworkTargets">
        {@ReferenceLinkNamespaceFiles}
      </targets>
      <targets files="reflection.xml" type="Local" id="ProjectTargets" />
    </component>

    <!-- Convert language-specific text spans to script elements -->
    <component id="Language-Specific Text Component" />

    <!-- Save the result -->
    <component id="Save Component">
      <save base="Output\HtmlHelp1\html" path="concat(/html/head/meta[@name='file']/@content,'.htm')"
        indent="{@IndentHtml}" omit-xml-declaration="true" add-xhtml-namespace="false" outputMethod="html" />
    </component>
  </helpOutput>

  <!-- This defines the set of components for MS Help 2 files -->
  <helpOutput format="MSHelp2">
    <!-- Add additional header resources -->
    <component id="Additional Header Resources Component">
      <meta http-equiv="X-UA-Compatible" content="IE=EmulateIE9" />
      <stylesheet name="../styles/branding-Help2.css" />
    </component>

    <!-- Resolve shared content -->
    <component id="Shared Content Component">
      <content file="{@ResourceItemsFolder}shared_content.xml" />
      <content file="{@ResourceItemsFolder}reference_content.xml" />
      <content file="{@ResourceItemsFolder}syntax_content.xml" />
      <!-- These must be last in order to override other elements! -->
      <content file="SHFBContent.xml" />
      {@ResourceItemFiles}
    </component>

    <!-- Insert additional MS Help 2 attributes -->
    <component id="Help 2 Help Attribute Component">
      {@HelpAttributes}
    </component>

    <!-- Resolve conceptual links -->
    <component id="Resolve Conceptual Links Component">
      <showBrokenLinkText value="true" />
      <targets base="xmlComp" type="Index" />
    </component>

    <!-- Resolve reference links -->
    <component id="Resolve Reference Links Component">
      <locale value="{@Locale}" />
      <linkTarget value="{@SdkLinkTarget}" />
      <msdnContentIdCache path="{@LocalDataFolder}Cache\MsdnContentId.cache" />
      <targets base="{@SHFBFolder}Data\Reflection" recurse="true" files="*.xml"
        type="{@MSHelp2SdkLinkType}" id="FrameworkTargets">
        {@ReferenceLinkNamespaceFiles}
      </targets>
      <targets files="reflection.xml" type="Index" id="ProjectTargets" />
    </component>

    <!-- Convert language-specific text spans to script elements -->
    <component id="Language-Specific Text Component" />

    <!-- Save the result -->
    <component id="Save Component">
      <save base="Output\MSHelp2\html" path="concat(/html/head/meta[@name='file']/@content,'.htm')"
        indent="{@IndentHtml}" omit-xml-declaration="true" add-xhtml-namespace="false" outputMethod="html" />
    </component>
  </helpOutput>

  <!-- This defines the set of components for MS Help Viewer files -->
  <helpOutput format="MSHelpViewer">
    <!-- Add additional header resources -->
    <component id="Additional Header Resources Component">
      <meta http-equiv="X-UA-Compatible" content="IE=EmulateIE9" />
      <stylesheet name="styles/branding-HelpViewer.css" />
    </component>

    <!-- Resolve shared content -->
    <component id="Shared Content Component">
      <content file="{@ResourceItemsFolder}shared_content.xml" />
      <!-- Override the paths for MS Help Viewer -->
      <content file="{@ResourceItemsFolder}shared_content_mshc.xml" />
      <content file="{@ResourceItemsFolder}reference_content.xml" />
      <content file="{@ResourceItemsFolder}syntax_content.xml" />
      <!-- These must be last in order to override other elements! -->
      <content file="SHFBContent.xml" />
      {@ResourceItemFiles}
    </component>

    <!-- Resolve conceptual links -->
    <component id="Resolve Conceptual Links Component">
      <showBrokenLinkText value="true" />
      <targets base="xmlComp" type="Id"/>
    </component>

    <!-- Resolve reference links -->
    <component id="Resolve Reference Links Component">
      <locale value="{@Locale}" />
      <linkTarget value="{@SdkLinkTarget}" />
      <msdnContentIdCache path="{@LocalDataFolder}Cache\MsdnContentId.cache" />
      <targets base="{@SHFBFolder}Data\Reflection" recurse="true" files="*.xml"
        type="{@MSHelpViewerSdkLinkType}" id="FrameworkTargets">
        {@ReferenceLinkNamespaceFiles}
      </targets>
      <targets files="reflection.xml" type="Id" id="ProjectTargets" />
    </component>

    <!-- Add MSHC metadata -->
    <component id="Microsoft Help Viewer Metadata Component">
      <data topic-version="{@TopicVersion}" toc-file="toc.xml"
        toc-parent="{@ApiTocParentId}" toc-parent-version="{@TocParentVersion}" locale="{@Locale}" />
    </component>

    <!-- Convert language-specific text spans to script elements -->
    <component id="Language-Specific Text Component" />

    <!-- Save the result -->
    <component id="Save Component">
      <save base="Output\MSHelpViewer\html" path="concat(/html/head/meta[@name='file']/@content,'.htm')"
        indent="{@IndentHtml}" omit-xml-declaration="false" add-xhtml-namespace="true" outputMethod="html" />
    </component>
  </helpOutput>

  <!-- This defines the set of components for websites -->
  <helpOutput format="Website">
    <!-- Add additional header resources -->
    <component id="Additional Header Resources Component">
      <stylesheet name="../styles/branding-Website.css" />
      <script name="../scripts/jquery-1.11.0.min.js" />
      <script name="../scripts/branding-Website.js" />
    </component>

    <!-- Resolve shared content -->
    <component id="Shared Content Component">
      <content file="{@ResourceItemsFolder}shared_content.xml" />
      <content file="{@ResourceItemsFolder}reference_content.xml" />
      <content file="{@ResourceItemsFolder}syntax_content.xml" />
      <!-- These must be last in order to override other elements! -->
      <content file="SHFBContent.xml" />
      {@ResourceItemFiles}
    </component>

    <!-- Resolve conceptual links -->
    <component id="Resolve Conceptual Links Component">
      <showBrokenLinkText value="true" />
      <targets base="xmlComp" type="Local" />
    </component>

    <!-- Resolve reference links -->
    <component id="Resolve Reference Links Component">
      <locale value="{@Locale}" />
      <linkTarget value="{@SdkLinkTarget}" />
      <msdnContentIdCache path="{@LocalDataFolder}Cache\MsdnContentId.cache" />
      <targets base="{@SHFBFolder}Data\Reflection" recurse="true" files="*.xml"
        type="{@WebsiteSdkLinkType}" id="FrameworkTargets">
        {@ReferenceLinkNamespaceFiles}
      </targets>
      <targets files="reflection.xml" type="Local" id="ProjectTargets" />
    </component>

    <!-- Convert language-specific text spans to script elements -->
    <component id="Language-Specific Text Component" />

    <!-- Save the result -->
    <component id="Save Component">
      <save base="Output\Website\html" path="concat(/html/head/meta[@name='file']/@content,'.htm')"
        indent="{@IndentHtml}" omit-xml-declaration="true" add-xhtml-namespace="false" outputMethod="html" />
    </component>
  </helpOutput>
</component>

The example given above is taken from the Sandcastle Help File Builder's configuration template file. When used with it, the replacement tags {@SHFBFolder} and {@OutputFolder} are used to insert the help file builder's folder and the project's output folder in the file paths. These are replaced at build time with the appropriate values. If using the component in your own build scripts, replace the tags with a relative or absolute path to the component assembly and output folder respectively. Likewise, the other tags are replaced with project values. Update them with the appropriate settings for your project.

The build element specifies which help file formats to build. The formats attribute should contain a comma separated list of help file formats. For example:

Copy
<build formats="MSHelpViewer, Website" />

For each possible help file format, a helpOutput element should appear with a format attribute that matches one of the possible help file formats. Nested within that element are the components and their configurations specific to that build format. If a format is not specified in the build element, the components for that format are not created and will be ignored during the build.

See Also