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.
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.
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.
In the Application tab, set the assembly name and default namespace as you see
fit.
In the Package tab, set the NuGet package properties.
By default, the Debug project properties are set to use the standalone GUI for debugging
which will help you see if the component can be located, that the configuration form is working if you
created one for the component, and that it is working within the build as expected. See the
Debugging Components and Plug-Ins for some special requirements when debugging
components and plug-ins.
Using the standalone GUI 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 the standalone GUI 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.
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 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.
The Id parameter is required and is used to uniquely identify the
syntax generator. Typically, the ID is the language 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
