This topic describes the parts of a syntax filter generator definition file and how to create one.

Syntax Filter Generator Definition Files

Syntax filter generators are used to add syntax sections to each API topic for a programming language. Several default language syntax generators are supplied with Sandcastle by default. Custom syntax filter generators can easily be added to the help file builder without having to modify its configuration template files. This is accomplished by creating an XML configuration file that describes the syntax filter generators. The custom syntax generator assembly, configuration file, and any supporting files are copied into the .\Components and Plug-Ins folder or a subfolder beneath it in the help file builder's Common Application Data folder. See the Special Folder Locations topic for more information. The syntax filter definition files must use the extension .filters. The default syntax filters file is shown below:

CopyDefault Syntax Filters Definition File
<?xml version="1.0" encoding="utf-8"?>
<!-- This file contains a set of configuration settings for the language syntax
     filter generators used by BuildAssembler to generate the Syntax sections
     in each topic.  These settings are read by the Sandcastle Builder GUI and
     made available in the designer via the SyntaxFilters project property.
     -->
<syntaxFilters>
  <!-- The filter element defines the basic properties of the filter.  The
       ID attribute is used to give each one a unique ID used by the designer.
       The optional sortOrder attribute is used to define the order in which
       they are added to the BuildAssembler configuration file.  The optional
       alternateNames attribute can be used to provide a comma-separated list
       of alternate language names that will be translated by the designer to
       the associated syntax filter ID. -->
  <filter id="CSharp" sortOrder="10" alternateNames="cs, c#">
    <!-- The generator element defines the syntax generator class.  The type
         attribute defines the fully qualified type name.  The assembly
         attribute defines the path to the assembly containing the type.
         Substitution tags can be used in the assembly path. -->
    <generator type="Microsoft.Ddue.Tools.CSharpDeclarationSyntaxGenerator"
      assembly="{@SandcastlePath}ProductionTools\SyntaxComponents.dll" />
    <!-- The language element defines the properties used by the script in
         the API topic filter dropdown used to show and hide the syntax
         sections.  The label and name attributes are used as prefixes for
         resource items used during transformation.  The style attribute is
         used as a parameter to the script used in each topic and defines the
         language style (cs, cpp, or vb). -->
    <language label="CSharp" name="CSharp" style="cs" />
  </filter>

  <filter id="VisualBasic" sortOrder="20" alternateNames="vb, vb#, vbnet, vb.net">
    <generator type="Microsoft.Ddue.Tools.VisualBasicDeclarationSyntaxGenerator"
      assembly="{@SandcastlePath}ProductionTools\SyntaxComponents.dll" />
    <language label="VisualBasic" name="VisualBasic" style="vb" />
  </filter>

  <filter id="VisualBasicUsage" sortOrder="30" alternateNames="vbusage, vbnetusage">
    <generator type="Microsoft.Ddue.Tools.VisualBasicUsageSyntaxGenerator"
      assembly="{@SandcastlePath}ProductionTools\SyntaxComponents.dll" />
    <language label="VisualBasicUsage" name="VisualBasicUsage" style="vb" />
  </filter>

  <filter id="CPlusPlus" sortOrder="40" alternateNames="cpp, cpp#, c++">
    <generator type="Microsoft.Ddue.Tools.CPlusPlusDeclarationSyntaxGenerator"
      assembly="{@SandcastlePath}ProductionTools\SyntaxComponents.dll" />
    <language label="ManagedCPlusPlus" name="ManagedCPlusPlus" style="cpp" />
  </filter>

  <filter id="FSharp" sortOrder="50" alternateNames="fs, f#, fsscript">
    <generator type="Microsoft.Ddue.Tools.FSharpDeclarationSyntaxGenerator"
      assembly="{@SandcastlePath}ProductionTools\SyntaxComponents.dll" />
    <language label="FSharp" name="FSharp" style="fs" />
  </filter>

  <filter id="JSharp" sortOrder="60" alternateNames="j#">
    <generator type="Microsoft.Ddue.Tools.JSharpDeclarationSyntaxGenerator"
      assembly="{@SandcastlePath}ProductionTools\SyntaxComponents.dll" />
    <language label="JSharp" name="JSharp" style="cs" />
  </filter>

  <filter id="JScript" sortOrder="70" alternateNames="jscript#, jscript.net">
    <generator type="Microsoft.Ddue.Tools.JScriptDeclarationSyntaxGenerator"
      assembly="{@SandcastlePath}ProductionTools\SyntaxComponents.dll" />
    <language label="JScript" name="JScript" style="cs" />
  </filter>

  <filter id="JavaScript" sortOrder="80" alternateNames="js, ecmascript">
    <generator type="SandcastleBuilder.Components.JavaScriptDeclarationSyntaxGenerator"
      assembly="{@SHFBFolder}SandcastleBuilder.Components.dll" />
    <language label="JavaScript" name="JavaScript" style="cs" />
  </filter>

  <filter id="XamlUsage" sortOrder="90" alternateNames="xml">
    <generator type="Microsoft.Ddue.Tools.XamlUsageSyntaxGenerator"
      assembly="{@SandcastlePath}ProductionTools\SyntaxComponents.dll">
        <filter files="{@SandcastlePath}Presentation\Shared\configuration\xamlSyntax.config" />
    </generator>
    <language label="XAML" name="XAML" style="cs" />
  </filter>

  <filter id="AspNet" sortOrder="100" alternateNames="asp, asp.net">
    <generator type="Microsoft.Ddue.Tools.AspNetSyntaxGenerator"
      assembly="{@SandcastlePath}ProductionTools\SyntaxComponents.dll" />
    <language label="AspNet" name="AspNet" style="cs" />
  </filter>
</syntaxFilters>

Syntax Filter Generator Elements

The root syntaxFilters node contains one or more filter nodes that describe the syntax generator filter components. The order of the component definitions is not significant. The help file builder uses this information to merge them with the configuration file at build time. The Sandcastle Help File Builder supports several replacement tags that can be specified in place of such things as the components folder, the project folder, etc. These will be replaced before use with the physical path associated with the project.

The following sections list the elements and their attributes that make up the definition for a filter node.

For a working example of a component configuration file, see the SandcastleBuilder.filters file in the help file builder installation folder. It contains a fully commented set of configurations for the standard set of syntax filter generators.

filter

This element contains all of the other elements and defines the basic properties of the filter. The element itself has one required attribute and two optional attribute:

  • The id attribute is used to give each one a unique ID used by the designer and will appear in the project's SyntaxFilters property if selected.
  • The optional sortOrder attribute is used to define the order in which they are added to the BuildAssembler configuration file. This affects the order in which they appear in the rendered API topics. Filters without a sort order will appear after all other elements with a sort order sorted alphabetically.
  • The optional alternateNames attribute can be used to provide a comma-separated list of alternate language names that will be translated by the designer to the associated syntax filter ID.

generator

This element defines the syntax generator class and has two required attributes:

  • The type attribute provides the fully qualified type name of the syntax filter generator component.
  • The assembly attribute provides the location of the assembly that contains the indicated type. Normally, you will use the {@ComponentsFolder} replacement tag to represent the path to the .\Components and Plug-Ins folder. However, the assembly can be located in any other location. Just be sure that the path is correct.

The generator element will be copied into the BuildAssembler configuration file along with any nested child elements that it contains.

language

This element defines the properties used by the script in the API topic filter dropdown used to show and hide the syntax sections and has three required attributes:

  • The label and name attributes are used as prefixes for resource items used during transformation. Typically, each is set to the same value.
  • The style attribute is used as a parameter in the script in each API topic and defines the language style to show in the content for such things as member link text and language keywords when the associated language is show by itself. It should be set to one of the following values: cs, cpp, or vb.

See Also