Creating a Syntax Filter Generator Component

Syntax generators are used to add language and usage syntax sections to each API topic for a programming language. They are executed in BuildAssembler as part of the SyntaxComponent. Several language and usage syntax generators are supplied with Sandcastle by default. This topic will walk you through the creation of a syntax generator project used to add a new language or usage syntax section.

• Defining the Syntax Generator Configuration
• Creating the Project
• The Export Attribute Metadata
  • Id
  • Language Element Name
  • Keyword Style Parameter
  • Version
  • Copyright
  • Description
  • SortOrder
  • AlternateIds
  • IsConfigurable
  • DefaultConfiguration
• The Factory Class
• The Syntax Generator Template Class

The first step is to determine what items will appear in the syntax generator configuration. The configuration is stored as an XML fragment in the help file builder project file. The root node is always generator. Define your own elements to contain the syntax generator configuration that will be nested within the root element. It is possible that a syntax generator will have no configurable elements. In that case, there is nothing to add to the default configuration. Below is an example of a configuration that is passed to a syntax generator.

<generator id="VisualBasic">
  <includeLineContinuation value="false" />
</generator>

This section describes how to create and configure the syntax generator project. It will describe the process for a C# project but the steps should be fairly similar for a VB.NET project with a few differences in the configuration option titles.

Create the Syntax Generator Project

You are now ready to edit the syntax generator class itself. See the comments in the template class for information on how to get started. Some general information is given below. Note that multiple build components can reside within the same assembly. Add new class files to the project and implement the necessary methods as described below and as shown in the template class.

The syntax generator can be derived from either Sandcastle.Core.BuildAssembler.SyntaxGenerator.SyntaxGeneratorCore which is a simpler base class suitable for usage syntax generators or from Sandcastle.Core.BuildAssembler.SyntaxGenerator.SyntaxGeneratorTemplate which is more suited for language syntax as it contains more methods related to language-specific elements. A nested Managed Extensibility Framework (MEF) factory class that describes the component, creates instances, and allows interaction with the design tools and build engine must also be implemented. These are described below. Review the code for "TODO:" comments to find sections that need attention such as setting the syntax generator's ID, language name, the default configuration, etc. If you followed the steps in the Creating the Project section, you can run the project and debug it by setting breakpoints in the syntax generator's code. As noted above, set the test project's Component Path property to the folder containing the syntax generator assembly first. If necessary, close and reopen the test project so that it can discover the syntax generator.

The nested factory class is a MEF component. The SyntaxGeneratorExportAttribute is used to define the necessary metadata that enables the help file builder to load and use the component.

Id

The Id parameter is required and is used to uniquely identify the syntax generator. Typically, the ID is the language name.

Language Element Name

The Language Element Name parameter is required and is used to uniquely identify the syntax language element generated in each topic by the component. This value should be valid as an XML element name.

Keyword Style Parameter

The Keyword Style Parameter parameter is required and is used to get the keyword style parameter value used by the client side script in the topics for language specific keyword/separator text. This will typically be one of the following: cs (C# or equivalent), vb (VB.NET or equivalent), cpp (C++ or equivalent), fs (F# or equivalent). The value cs is typically used as a default.

Version

The Version property is optional and allows you to define the build component version displayed in the help file builder property page when the syntax generator is selected.

Copyright

The Copyright property is optional and allows you to define the syntax generator copyright displayed in the help file builder property page when the syntax generator is selected.

Description

The Description property is optional and allows you to define the syntax generator description displayed in the help file builder property page when the syntax generator is selected.

SortOrder

The SortOrder property is optional and allows you to define the sort order of the presentation style when used in conjunction with other syntax generators. The syntax build component will use this sort order to define the order in which the syntax sections are emitted to the topic.

AlternateIds

The AlternateIds property is optional and allows you to define a comma-separated list of other language names that can be mapped to this generator.

IsConfigurable

The IsConfigurable property is optional and allows you to define whether or not the syntax generator supports interactive editing of its configuration. If false, the default, the syntax generator will not be configurable. If true, the SyntaxComponent's configuration editor will allow modifications to the syntax generator configuration. The SyntaxComponent must be added to the help file builder project in order to edit the configuration settings.

DefaultConfiguration

The DefaultConfiguration property is optional and is used to specify the default configuration for a custom syntax generator. This information is used when the component is selected for use and the SyntaxComponent does not contain an alternate configuration for it. You can use the various replacement tags as attribute values. These will be replaced at build time with the appropriate project values. The default if not overridden is an empty string.

The factory class for a syntax generator is quite simple. It is derived from Sandcastle.Core.BuildAssembler.SyntaxGenerator.ISyntaxGeneratorFactory and contains the following abstract members that must be implemented:

• ResourceItemFileLocation - This property is used to return the location of the language's resource item file. This file contains the localized string resources used for labels, messages, etc. and allows syntax generators to be developed and deployed without having to make changes to the presentation styles. By default, the project contains a SyntaxContent\ folder with a single XML file named after the language. These are the default resources if no language-specific resources are defined. To create language-specific versions of the resource files (i.e. French, German, Chinese), create sub-folders named after the language ID (i.e. fr-FR, de-DE, ch-CN) and place a copy of the file in each language sub-folder containing the translated resource items.

    Important

  If you change the language name, rename the matching language resource item file in the SyntaxContent\ folder to the same name and update the IDs of the content items in it with the new name. This is required to ensure that the file and its content items are matched correctly to the syntax sections in the generated topics.

• Create - This is used to create an instance of the syntax generator and return it.

Syntax generators are more complex than a standard build component and contain several abstract methods that must be overridden. They also rely heavily on the reflection information present in each document to produce the correct syntax. It is recommended that you take a look at the existing syntax components to see how they are implemented. If one represents a language close to the one you are implementing, you can use it as a starting point. More information on creating syntax generators will be added at a later date.

Other Resources