Click or drag to resize
Sandcastle Help File BuilderImporting and Colorizing Code from Source Files

The help file builder allows you to import source code into an additional content HTML page and colorize it using the <code> tag. It supports the same colorizer options as the <pre> tag and the CodeBlockComponent. The main difference is that you specify a required source attribute to specify the source code file and an optional region attribute to limit the code to a defined region of the source file. The tag should be self-closing or should contain no content. The lang attribute must also appear in order to specify the language to use for colorizing the code. All other colorizer attributes are optional. The path specified can be relative. If so, it is always assumed to be relative to the project file's folder. See the Code Block Component help topic for option details. Below are several examples of its use.

Caution note Caution

Deprecated

The additional content model of adding extra content to a help file has been deprecated. While it will continue to be supported and will not be removed, it will not receive any more features or updates. Going forward, conceptual content is the preferred method of adding non-reference content to the help file. The additional content feature can still be used to override stock content and add supporting files to the help file.

Copy
<!-- Import an entire file -->
<code language="xml" source="..\Test.xml" numberLines="true" title=" "/>

<!-- Import a defined region -->
<code language="vbnet" source="..\Class1.vb" region="Test Region"
    title="Test region from class" /></code>

<!-- A few more examples -->
<code language="vbnet" source="..\Class1.vb" region="Embedded snippet"
    title="Test region from method" numberLines="true" />

<code language="cs" source="..\TestClass.cs" region="Methods"
    numberLines="true" outlining="true" />

<code language="cs" source="..\GenericClass.cs" > </code>

You can also import multiple code snippets into one common colorized code block by nesting them within a pre tag and including the nested="true" attribute. Nested code tags should be flush left or the leading spaces before the tag will be included before the first line of the imported code block. Only the source and region attributes will be utilized. All other attributes that control colorization of the merged code block will be retrieved from the parent pre tag.

Copy
<pre title="Nested code block example" language="VB.NET">
<code source="..\Class1.vb" region="Snippet #1" nested="true" />
<code source="..\Class1.vb" region="Snippet #2" nested="true" />
</pre>

Literal code can also be mixed in between the nested code tags.

Copy
<pre title="Nested code block example" lang="VB.NET">
<code source="..\Class1.vb" region="Snippet #1" nested="true" />

' ... Some stuff happens here ...

<code source="..\Class1.vb" region="Snippet #2" nested="true" />
</pre>
See Also