Click or drag to resize
Sandcastle Help File BuilderCreating 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

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.

Example Syntax Generator Configuration
Copy
<generator id="VisualBasic">
  <includeLineContinuation value="false" />
</generator>
Creating the Project

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

  1. In Visual Studio, select the New Project option. In the New Project dialog box, select the C# or VB.NET language, and then select the Documentation subcategory. Select the BuildAssembler Syntax Generator template, give it a name and click OK to create it. Once it has been created, right click on the project and select Properties.

  2. In the Application tab, set the assembly name and default namespace as you see fit.

  3. On the Debug tab, do the following:

    • Set the Start Action to "Start external program" and enter the path to the BuildAssembler.exe program. If you installed the help file builder in the default location, this will be %ProgramFiles(x86)%\EWSoftware\Sandcastle Help File Builder\. If not, substitute your path as appropriate.

    • Set the Command line arguments property to /config:sandcastle.config manifest.xml.

    • Set the working directory to the working folder of a project that contains the build component. Note that you will need to perform one build of the project with the Clean intermediate files option turned off so that you can test the build component using the temporary build files.

    Tip Tip

    Using the BuildAssembler tool as the host is easier than using Visual Studio as the package locks the assemblies once the help file builder project has loaded them for use and you will not be able to rebuild them. Shutting down BuildAssembler frees the assemblies so that you can rebuild them and start a new debugging session.

    In the help file builder project that you use to test your build component, set the project's Component Path property to the folder containing your build component's assembly. If you have opened the project's Components property page before setting the component path, you may need to close and reopen the project in order for it to discover your build component assembly.

  4. Optionally, select the Signing tab and check the "Sign the assembly" checkbox. Select "<New...>" from the "Choose a strong name key file" dropdown, enter a filename, and click OK to create the key file. You can protect the key file with a password if you like or uncheck the option to create one without a password.

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 Export Attribute Metadata

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.

Important note 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.

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

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 note 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.

The Syntax Generator Template Class

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.

See Also