A bug in the standard ResolveConceptualLinksComponent causes any specified inner text on <link> tags to be ignored and instead it always uses the topic's title. This component is a reimplementation that fixes that bug and adds some new features (see below).

Note

Due to the bug fix, any links you may have in your conceptual content files will start showing the inner text when built using this replacement component. You may need to review your documentation and either remove or update the inner text to something more appropriate on your links.

Usage Benefits

The replacement contains the following features and fixes:

  • Broken links use the None style rather than the Index style so that it is apparant that they do not work.
  • The inner text from the conceptual link is used if specified.
  • On broken links, when the showBrokenLinkText option is true and there is no inner text, the target value is displayed.
  • Conceptual link targets can include an optional anchor name from within the target such as "#Name" (i.e. <link xlink:href="3bdb6eb5-5e23-51c2-0051-3e224f82c201#Section2" />).
  • Unnecessary whitespace is removed from the link text.
  • If the companion file contains a <linkText> element and no inner text is specified, its value will be used for the link text rather than the title. This allows for a shorter title or description to use as the default link text.

Example Configuration

The following is the default configuration for the resolve conceptual links component. It should be inserted into the configuration file after the TransformComponent.

CopyExample Configuration
<component type="SandcastleBuilder.Components.ResolveConceptualLinksComponent"
  assembly="{@SHFBFolder}SandcastleBuilder.Components.dll"
  showBrokenLinkText="true">
    <targets base="xmlComp" type="{@ProjectLinks}" />
</component>

The example given above is taken from the Sandcastle Help File Builder's configuration file. When used with it, the replacement tag {@SHFBFolder} is used to insert the help file builder's folder in the file path. This is replaced at build time with the appropriate value. If using the component in your own build scripts, replace the tag with a relative or absolute path to the component assembly. The {@ProjectLinks} option should be replaced with None, Local, or Index based on your preferred link type and help file format.

See Also