This is an advanced feature allowing the user to modify topics in a pretty much any way they want after the topics are created by Doc-to-Help in the help target. An example of a possible use of this feature can be adding some markup to all topics, for example, adding a footer using an HTML table (that may be to ensure that the footer is always at the bottom of the browser window), or replacing some text (tag)

with variable text depending on a parameter specified in that tag.

These are just two examples of adding things to topics or transforming them in a way that can't be done by other means in Doc-to-Help, such as themes and others. This feature makes Doc-to-Help help target creation flexible, allowing for post-build modification in virtually any imaginable custom way.

There are two limitations in this functionality:

1.   XML transforms can be used only with HTML-based targets, that is, they are not used (ignored) in building WinHelp and Manual targets.

2.   XML transforms are applied only if the GenerateXHTML property is set to True. Otherwise, they are ignored.

There are two kinds of XML transforms:

•      Programmatic transforms — These are programs written in any .NET language, such as C# or VB.NET.

•      XSLT transforms — These are XSLT transformations.

To create a custom transformation, follow the instructions below, and you may want to look at the two examples provided with Doc-To-Help:

The expanding sections functionality (see Expanding/Collapsing sections) is implemented as an XML transform (a programmatic one). Its full source code can be found in DocToHelp\Transforms\BuiltIn\Source\XMLInternal.

An XSLT transform example can be found in DocToHelp\Transforms\Examples (to see how it works in Doc-To-Help, replace the standard config file DocToHelp\Transforms\Transforms.config with DocToHelp\Transforms\Examples\Transforms.config).

To create a transform, the user needs to write a program (.NET assembly) or an XSLT file and add it to the configuration file in the Doc-To-Help directory (we show the default path below):

Program Files\ComponentOne\DocToHelp\Transforms\Transforms.config

Transforms registered in the configuration file are applied to every topic in the order of their appearance in the configuration file.

The configuration file is an XML where every transform is registered with a <transform> element with the following elements inside:

<description> — Arbitrary string describing the transform, for explanatory purpose only.

<assembly> — File name of the transform assembly (including the .dll extension) relative to the DocToHelp\Transform directory. For an XSLT transform that element should always be as follows: <assembly>BuiltIn\C1D2HXMLInternal.dll</assembly>

<type> — Full class name in the assembly that implements the IXMLTransform interface. That is the class whose methods are called to perform the transformation. For an XSLT transform that element should always be as follows: <type>C1.D2H.XMLTransform.XSLTTransform</type>

<params> — This element contains whatever elements the transform may need as its parameters. Its contents are passed as they are to the transform method when it is executed. For programmatic transforms, their interpretation is entirely dependent on the code implementing the transform methods. XSLT transforms always have two parameters: <xsl-file> and <copy-files>. The <xsl-file> element contains the name of the XSLT file (with the .xsl extension) relative to the DocToHelp\Transforms directory. The <copy-files> element contains any number (or none) of <copy-file> elements containing file names (relative to the DocToHelp\Transforms directory) that need to be copied to the help target directory to support this transform's functionality (these are usually resource files, such as graphics, scripts, style sheets, etc).

A programmatic transform assembly contains a class implementing the interface C1.D2H.XMLTransform.IXMLTransform. That interface is defined in the C1XHTML.dll assembly residing in the DocToHelp directory. It contains three methods (note that you do not need to implement this interface if you are creating an XSLT transform; creating XSLT transforms requires programming only in XSLT, no .NET programming is required):

void IXMLTransform.ReadParams(XmlNode node)

This method is called before executing the transform, to initialize the transform class with parameter values specified in the <params> tag in the configuration file. This method is called once in Doc-To-Help build, before this transform is applied to any topics. The 'node' parameter passed to this method contains the XmlDocument whose root element is the <params> element of the configuration file.

void IXMLTransform.Execute(XmlDocument doc)

This method executes the transform, applies it to a topic. The 'doc' parameter is the topic XML before applying the transform (all transforms preceding thistransform in the configuration file have already been applied to it. This method implementation modifies the XmlDocument passed to it.

void IXMLTransform.CopyRequiredFiles(string targetPath)

This method is used to copy any files that may be needed in the help target to support this transform's functionality (these are usually resource files, such as graphics, scripts, style sheets, etc). If you don't need any files, leave this method empty. The 'targetPath' parameter contains the path to the TransformFiles subdirectory of the help target directory (for example, MyProject\MyHTMLHelpTarget\TransformFiles). This method implementation copies required files (if any) to that subdirectory (possibly creating subdirectories inside it, if needed).

For an example of an XML transform, see Expanding/Collapsing sections.