Click or drag to resize
Sandcastle Help File BuilderSyntax Component

The Syntax Component is primarily used to insert syntax sections into API reference topics. In addition, it is used by presentation styles that support code snippet grouping to group and sort code snippets into tabbed sections that match the syntax section order. As each tab is clicked, the same language tab in the syntax section and the other code snippet groups is also selected keeping them all in synch. By default, the grouping and sorting is performed based on the sort order defined by the syntax generators. By adding this component to your project you can change the order of the languages within the syntax section and code snippet groups. Adding the component to your project will also allow you to change the settings of each syntax generator if they have any configurable options.

Tip Tip

If you change the sort order of the languages, use the the defaultLangauge transformation argument found on the Transform Args property page to set the default language selected so that it matches the first language in your chosen order.

The following is the default configuration for the Syntax Component. It should be inserted into the configuration file before the TransformComponent. It can be inserted into the configuration file for conceptual builds as well as reference builds. In conceptual builds, no syntax sections are inserted but it will allow for grouping and sorting of code snippets.

Example Configuration
Copy
<component id="Syntax Component">
  <!-- The input element and the output element. -->
  <syntax input="/document/reference" output="/document/syntax" />
  <!-- The list of syntax generators to use -->
  <generators>
    {@SyntaxFilters}
  </generators>
  <!-- Group snippets for languages in the syntax generator set within this element -->
  <containerElement name="codeSnippetGroup" addNoExampleTabs="true" includeOnSingleSnippets="false"
  groupingEnabled="{@CodeSnippetGrouping}" />
</component>

The example given above is taken from the Sandcastle Help File Builder's configuration file. When used with it, the replacement tag {@SyntaxFilters} is used to insert the selected syntax filters from the project. If using the component in your own build scripts, replace the tag with the necessary generator elements for each selected syntax filter.

When added to a project and the syntax generator order is changed or configuration options for a syntax generator are edited, an additional configurations element is added that defines the order of the syntax filters and their custom configuration if any.

The containerElement element defines the name of the container element that will hold the grouped code snippets. The XSL transformations will use this name to find the grouped snippets and transform them into tabbed sections. The addNoExampleTabs attribute defines whether or not to insert "No Example" tabs into groups that do not contain examples for all languages found in the syntax section. The default is true to insert them. When selected, they display a message stating that the selected language has no example or is not supported. The includeOnSingleSnippets attribute specifies whether or not to add "No Example" tabs to groups that only contain a single language (not including standalone snippets that specify a title). The default is false to render single language snippets as standalone groups. The groupingEnabled attribute specifies whether or not the grouping behavior is enabled. The help file builder uses the {@CodeSnippetGrouping} replacement tag to set the option based on the selected presentation style. The presentation style must support code snippet grouping in order for the grouped elements to be handled correctly by the XSL transformations.

See Also