SandcastleBuilder.Components This is a JavaScript declaration syntax generator that is used to add a JavaScript Syntax section to each generated API topic. This version differs from the ScriptSharpDeclarationSyntaxGenerator in that it looks for a <scriptSharp /> element in the <api> node and, if found, only then will it apply the casing rules to the member name. If not present, no casing rules are applied to the member names thus it is suitable for use with regular JavaScript such as that used in AjaxDoc projects. In order to use this script generator, you should modify the Sandcastle transformation file FixScriptSharp.xsl by adding the following template as the second one in the file. The help file builder uses a modified version of the transformation so that you do not need to apply the change when using it. ]]> Check to see if the given attribute exists on the entry The reflection information The attribute for which to search True if found or false if not found Check to see if the element is unsupported The reflection information The writer to which the "unsupported" message is written. True if unsupported or false if it is supported Convert the identifier's first letter to lowercase The identifier to modify The identifier with the first letter converted to lowercase Read the containing type name from the entry The reflection information The containing type name if found or null if not found Read the full containing type name from the entry The reflection information The full containing type name prefixed with its namespace or null if not found Read the full type name from the entry The reflection information The full type name prefixed with its namespace or null if not found Read the member name from the entry The reflection information The member name If a <scriptSharp /> element exists in the entry, the casing rule is applied to the member name. If not present, it is returned as-is. The casing rule will convert the first letter of the name to lowercase unless the member is marked with System.PreserveCaseAttribute. Read the namespace name from the entry The reflection information The namespace name Read the type name from the entry The reflection information The type name Write an indented new line The syntax writer to which it is written Write out a normal type reference The API name The syntax writer to which it is written Write out a parameter The parameter information The syntax writer to which it is written Write out a parameter list The reflection information The syntax writer to which it is written Write out the record constructor syntax The reflection information The syntax writer to which it is written Write out the record syntax The reflection information The syntax writer to which it is written Write out the type reference The reference information The syntax writer to which it is written Constructor The syntax generator configuration Not used by this syntax generator The reflection information The syntax writer to which it is written Write out attached property syntax The reflection information The syntax writer to which it is written Write out class syntax The reflection information The syntax writer to which it is written Write out constructor syntax The reflection information The syntax writer to which it is written Write out delegate syntax The reflection information The syntax writer to which it is written Write out enumeration syntax The reflection information The syntax writer to which it is written Write out event syntax The reflection information The syntax writer to which it is written Write out field syntax The reflection information The syntax writer to which it is written Write out interface syntax The reflection information The syntax writer to which it is written Write out namespace syntax The reflection information The syntax writer to which it is written Write out normal method syntax The reflection information The syntax writer to which it is written Operator syntax is unsupported The reflection information The syntax writer to which it is written Write out property syntax if supported The reflection information The syntax writer to which it is written Structure syntax is unsupported The reflection information The syntax writer to which it is written This is a reimplementation of the TargetInfo class used by . Constructor The target URL The target's link text The type of link This is thrown if the target URL or text is null. This read-only property is used to get the text This read-only property is used to get the link type This read-only property is used to get the URL This build component is used to add additional HTML Help 2.x attributes to the XML data island in each generated API topic. <!-- HTML Help 2 attribute configuration. This must appear after the TransformComponent. --> <component type="SandcastleBuilder.Components.MSHelpAttrComponent" assembly="C:\SandcastleBuilder\SandcastleBuilder.Components.dll"> <!-- Additional attributes (required) --> <attributes> <!-- At least one attribute element must be defined. The "name" attribute is required. The "value" attribute is optional. --> <attribute name="DocSet" value="NETFramework" / > <attribute name="DocSet" value="ProjectNamespace" / > <attribute name="TargetOS" value="Windows" / > </attributes> </component> Constructor A reference to the build assembler. The configuration information See the class topic for an example of the configuration This is thrown if an error is detected in the configuration. This is implemented to add the attributes to the XML data island. The XML document with which to work. The key (member name) of the item being documented. This is a derived ResolveReferenceLinksComponent2 class that loads cached MSDN URLs from a serialized binary file rather than letting the base component invoke the web service to look them up. This can significantly decrease the amount of time needed to perform a build. The cache is built cumulatively over time rather than having all 170,000+ resolved entries loaded, most of which would never be used. If new URLs are added to the cache during a build, the cache is saved during disposal so that the new entries are used on subsequent builds. <!-- Cached MSDN URL references component. This should replace the standard ResolveReferenceLinksComponent2 build component. --> <component type="SandcastleBuilder.Components.CachedResolveReferenceLinksComponent" assembly="C:\SandcastleBuilder\SandcastleBuilder.Components.dll" locale="en-us" linkTarget="_blank"> <cache filename="C:\SandcastleBuilder\Cache\MsdnUrl.cache" /> <targets base="C:\Program Files\Sandcastle\Data\Reflection" recurse="true" files="*.xml" type="MSDN" /> <targets files="reflection.xml" type="Local" /> </component> Constructor A reference to the build assembler. The configuration information This is thrown if an error is detected in the configuration. This is overriden to save the updated cache when disposed This build component is used to obtain version information for each topic so that it can be placed in the footer by the . The adds the version information to the topic after it has been transformed into HTML. We need to get the version information here though as the reference information is lost once it has been transformed. <!-- Version information component configuration. This must appear before the TransformComponent. See also: PostTransformComponent --> <component type="SandcastleBuilder.Components.VersionInfoComponent" assembly="C:\SandcastleBuilder\SandcastleBuilder.Components.dll"> <!-- Reflection information file for version info (required) --> <reflectionFile filename="reflection.xml" /> </component> Constructor A reference to the build assembler. The configuration information See the class topic for an example of the configuration This is thrown if an error is detected in the configuration. This is implemented to set the version information ready for use by the . The XML document with which to work. The key (member name) of the item being documented. This is used by the to get the assembly versions for the current topic. This form is used to configure the settings for the . Constructor The current XML configuration XML fragment Close without saving The sender of the event The event arguments Go to the CodePlex home page of the Sandcastle Help File Builder project. The sender of the event The event arguments Validate the configuration and save it The sender of the event The event arguments Select the base source folder The sender of the event The event arguments Required designer variable. Clean up any resources being used. true if managed resources should be disposed; otherwise, false. Required method for Designer support - do not modify the contents of this method with the code editor. This is used to return the configuration information This is a reimplementation of the ConceptualLinkInfo class used by . Private constructor This is used to create a conceptual link based on the information in the supplied XPath navigator. The XPath navigator node from which to load the link settings. A conceptual link info object This is thrown if the node parameters is null. The target of the link The optional anchor name within the target The text to show for the link This form is used to configure the settings for the . Constructor The current XML configuration XML fragment Close without saving The sender of the event The event arguments Go to the CodePlex home page of the Sandcastle Help File Builder project. The sender of the event The event arguments Validate the configuration and save it The sender of the event The event arguments Select the base source folder The sender of the event The event arguments Select the syntax for style file The sender of the event The event arguments Required designer variable. Clean up any resources being used. true if managed resources should be disposed; otherwise, false. Required method for Designer support - do not modify the contents of this method with the code editor. This is used to return the configuration information This form is used to configure the settings for the . Constructor The current XML configuration XML fragment Close without saving The sender of the event The event arguments Go to the CodePlex home page of the Sandcastle Help File Builder project. The sender of the event The event arguments Validate the configuration and save it The sender of the event The event arguments Select the base source folder The sender of the event The event arguments Select the syntax or style file The sender of the event The event arguments Select the logo or "Copy" image file The sender of the event The event arguments Update the image information if it changed The sender of the event The event arguments Draw the image on the panel using the width and height settings to give an idea of how big it will be. The sender of the event The event arguments Redraw the image when the width or height changes The sender of the event The event arguments Disable alignment unless "Above" is selected for placement The sender of the event The event arguments Required designer variable. Clean up any resources being used. true if managed resources should be disposed; otherwise, false. Required method for Designer support - do not modify the contents of this method with the code editor. This is used to return the configuration information This is a derived CopyFromIndexComponent class that loads the index document cache from a serialized binary file rather than loading it from the XML reflection data files. This can significantly decrease the amount of time needed to instantiate the component. <!-- Cached Reflection Index Data component. This should replace the first instance of the CopyFromIndexComponent. --> <component id="Cached Reflection Index Data" type="SandcastleBuilder.Components.CachedCopyFromIndexComponent" assembly="C:\SandcastleBuilder\SandcastleBuilder.Components.dll"> <index name="reflection" value="/reflection/apis/api" key="@id" cache="10"> <cache base="C:\Program Files\Sandcastle\Data\Reflection" recurse="true" files="*.xml" cacheFile="C:\SandcastleBuilder\Cache\Reflection.cache"/> <data files="reflection.xml" /> </index> <copy name="reflection" source="*" target="/document/reference" /> </component> <!-- Cached Framework Comments Index Data component. This should replace the third instance of the CopyFromIndexComponent. --> <component id="Cached Framework Comments Index Data" type="SandcastleBuilder.Components.CachedCopyFromIndexComponent" assembly="C:\SandcastleBuilder\SandcastleBuilder.Components.dll"> <index name="comments" value="/doc/members/member" key="@name" cache="100"> <cache files="%SystemRoot%\Microsoft.NET\Framework\v2.0.50727\en\*.xml" cacheFile="C:\SandcastleBuilder\Cache\en_2.0.50727.cache" /> <data files="ExtraComments.xml" /> <data files="TestDoc.xml" /> <data files="_InheritedDocs_.xml" /> </index> <copy name="comments" source="*" target="/document/comments" /> </component> Constructor A reference to the build assembler. The configuration information This is thrown if an error is detected in the configuration. Load a cached index The parent index node The name of the index The cache settings This is used in the debug build to get an idea of how many files were kept loaded in the cache. This is a reimplementation of the TargetDirectoryCollection class used by . Add a new target directory to the collection The target directory to add Find the target info for the specified file The file for which to find target info A object if found or null if not found. This read-only property returns the number of items in the collection. This contains a reimplementation of ResolveConceptualLinksComponent that allows the use of inner text from the <link> tag, allows the use of anchor references (#anchorName) in the link target, and allows the use of an optional linkText element in the companion file to specify the link text. This version contains the following improvements and fixes: Broken links use the None style rather than the Index style so that it is apparant that they do not work. The inner text from the conceptual link is used if specified. On broken links, when the showBrokenLinkText option is true and there is no inner text, the target value is displayed. Conceptual link targets can include an optional anchor name from within the target such as "#Name" (see examples below). Unnecessary whitespace is removed from the link text. If the companion file contains a <linkText> element and no inner text is specified, its value will be used for the link text rather than the title. This allows for a shorter title or description to use as the default link text. On links without inner text, if the companion file contains a linkText element, that text will be used. If not, the title is used. Click Here PropertyA]]> <!-- Resolve conceptual links --> <component type="SandcastleBuilder.Components.ResolveConceptualLinksComponent" assembly="C:\SandcastleBuilder\SandcastleBuilder.Components.dll" showBrokenLinkText="true"> <targets base="xmlComp" type="local" /> </component> Constructor A reference to the build assembler. The configuration information This is implemented to resolve the conceptual links The XML document with which to work. The key (member name) of the item being documented. Determine what to display for broken links The target key The link text The text to display for the broken link Compile an XPath expression and report an error if it fails The XPath expression to compile. The compiled XPath expression. Get target info The target for which to get info The target info object if found or null if not found This build component is used to generate IntelliSense files based on the documented APIs. Only the basic set of tags needed for IntelliSense are exported and only for documented API members. This is based on the Microsoft IntelliSense build component. That version only works with Microsoft-specific XML comments files and does not work with general XML comments files created by the compilers. <!-- IntelliSense component configuration. This must appear before the TransformComponent. --> <component type="SandcastleBuilder.Components.IntelliSenseComponent" assembly="C:\SandcastleBuilder\SandcastleBuilder.Components.dll"> <!-- Output options (optional) Attributes: Include Namespaces (false by default) Namespaces filename ("Namespaces" if not specified or empty) Directory (current folder if not specified or empty) --> <output includeNamespaces="false" namespacesFile="Namespaces" folder="C:\ProjectDocs\" /> </component> Constructor. A reference to the build assembler. The configuration information This is implemented to extract the IntelliSense comments. The XML document with which to work. The key (member name) of the item being documented. Write the comments to the assembly's XML comments file The key (member name) of the item being documented. The assembly filename The comments XPath navigator Write out closing tags and close all open XML writers when disposed. This static method is used by the Sandcastle Help File Builder to let the component perform its own configuration. The current configuration XML fragment A string containing the new configuration XML fragment This public enumerated type defines the link types No links Local links Index links This is a reimplementation of the TargetDirectory class used by . Constructor The target directory The URL expression The text (title) expression The alternate link text expression The link type This is thrown if the directory, URL expression, or either text expression is null. Get target info for the specified file The file for which to get target info A object if found or null if not found. This build component is used to add "missing" notes for missing summary, parameter, returns, value, and remarks tags. It can also add default summary documentation for constructors. <!-- Show missing documentation component configuration. This must appear before the TransformComponent. --> <component type="SandcastleBuilder.Components.ShowMissingComponent" assembly="C:\SandcastleBuilder\SandcastleBuilder.Components.dll"> <!-- All elements are optional. --> <!-- Auto-document constructors (true by default) --> <AutoDocumentConstructors value="true" /> <!-- Show missing param tags (true by default) --> <ShowMissingParams value="true" /> <!-- Show missing typeparam tags (true by default) --> <ShowMissingTypeParams value="true" /> <!-- Show missing remarks tags (false by default) --> <ShowMissingRemarks value="false" /> <!-- Show missing returns tags (true by default) --> <ShowMissingReturns value="true" /> <!-- Show missing summary tags (true by default) --> <ShowMissingSummaries value="true" /> <!-- Show missing value tags (false by default) --> <ShowMissingValues value="false" /> <!-- Show missing namespace comments (true by default) --> <ShowMissingNamespaces value="true" /> <!-- Show missing include target docs (false by default) --> <ShowMissingIncludeTargets value="false" /> <!-- Shared content file containing the localized messages (optional) --> <contentFile filename="C:\Working\SharedContent.xml" /> </component> Constructor A reference to the build assembler. The configuration information See the class topic for an example of the configuration This is thrown if an error is detected in the configuration. This is implemented to add the missing documentation tags The XML document with which to work. The key (member name) of the item being documented. Check for missing text in the specified documentation tag and, if it doesn't exist or the text is blank, add a "missing" message as the documentation tag's text. The comments node to check. The key (name) for the current item The tag type for which to check. Check for missing text in the specified <param> or <typeparam> tag and, if it doesn't exist or the text is blank, add a "missing" message as the tag's text. The comments node to check. The key (name) for the current item The parameter name for which to check. The tag type for which to check. Check for bad include elements and, if any are found, add a "missing" message to the summary tag's text. The comments node to check. The key (name) for the current item This build component is used to search for <code> XML comment tags and colorize the code within them. It can also include code from an external file or a region within the file. Note that this component must be paired with the . <!-- Code block component configuration. This must appear before the TransformComponent. See also: PostTransformComponent. --> <component type="SandcastleBuilder.Components.CodeBlockComponent" assembly="C:\SandcastleBuilder\SandcastleBuilder.Components.dll"> <!-- Base path for relative filenames in source attributes (optional). --> <basePath value="..\SandcastleComponents" /> <!-- Connect to language filter (optional). If omitted, language filtering is enabled by default. --> <languageFilter value="true" /> <!-- Allow missing source files (Optional). If omitted, it will generate errors if referenced source files are missing. --> <allowMissingSource value="false" /> <!-- Remove region markers from imported code blocks. If omitted, region markers in imported code blocks are left alone. --> <removeRegionMarkers value="false" /> <!-- Code colorizer options (required). Attributes: Language syntax configuration file (required) XSLT style file (required) "Copy" image file URL (required) Default language (optional) Enable line numbering (optional) Enable outlining (optional) Keep XML comment "see" tags within the code (optional) Tab size for unknown languages (optional, 0 = use default) Use language name as default title (optional) --> <colorizer syntaxFile="highlight.xml" styleFile="highlight.xsl" copyImageUrl="CopyCode.gif" language="cs" numberLines="false" outlining="false" keepSeeTags="false" tabSize="0" defaultTitle="true" /> </component> <example> A basic code block that uses the configuration defaults: <code> /// Code to colorize </code> Override options with block-specific options: <code lang="xml" numberLines="true" outlining="false" tabSize="8" > &lt;XmlTags/&gt; </code> An entire external file or a delimited region from it can be included. This allows you to compile your example code externally to ensure that it is still valid and saves you from maintaining it in two places. Retrieve all code from an external file. Use VB.NET syntax. <code source="..\Examples\WholeDemo.vb" lang="vbnet"/> Retrieve a specific #region from an external file. <code source="..\Examples\SeveralExamples.vb" region="Example 1" lang="vbnet"/> Keep <see> tags within comments so that they are converted to links to the help topics. <code keepSeeTags="true"> int x = this.<see cref="CountStuff">CountStuff</see>(true); string value = this.<see cref="System.Object.ToString"> <code> <example> Constructor A reference to the build assembler. The configuration information NOTE: This component must be paired with the . See the class topic for an example of the configuration and usage. This is thrown if an error is detected in the configuration. This is implemented to perform the code colorization. The XML document with which to work. The key (member name) of the item being documented. This is used to load a set of nested code blocks from external files. The node in which to replace the nested code blocks The XPath expression used to locate the nested code blocks. The HTML encoded blocks extracted from the files as a single code block. Only source and region attributes are used. All other attributes are obtained from the parent code block. Text nodes are created to replace the nested code tags so that any additional text in the parent code block is also retained. This is used to load a code block from an external file. The node containing the attributes The HTML encoded block extracted from the file. This is used to add language filter IDs for the Prototype, VS2005, and Hana styles so that the code block is shown or hidden based on the language filter selection. The title node if used The code node The language to use as the filter A unique ID number for the code block The span node containing the title and code nodes The adds the script necessary to register the code blocks and set their initial visible state in the Prototype and Hana styles. This static method is used by the Sandcastle Help File Builder to let the component perform its own configuration. The current configuration XML fragment A string containing the new configuration XML fragment This is used by the to insert the colorized code blocks. The colorized code blocks contain HTML which isn't supported by conceptual topics pre-transformation. As such, we hold onto them here and use a placeholder ID. The post-transform component will replace the placeholder ID with the actual colorized code block. This is used by the to get the destination location and filename of the "Copy" image. This is used by the to get the "Copy" text so that it can be replaced with an include item. We can't do it here as the TransformComponent strips the <include> tag as it isn't one it recognizes. This build component is is a companion to the . It is used to add the stylesheet and JavaScript links to the rendered HTML if the topic contains colorized code. In addition, it can insert a logo image at the top of each help topic and, for the Prototype presentation style, hide the language combo box if only one language appears in the Syntax section. With a modification to the Sandcastle reference content files, it will also add version information to each topic. The colorizer files are only copied once and only if code is actually colorized. If the files already exist (i.e. additional content has replaced them), they are not copied either. That way, you can customize the color stylesheet as you see fit without modifying the default stylesheet.

By adding "Version: {2}" to the locationInformation entry and the assemblyNameAndModule entry in the reference_content.xml file in the Prototype, VS2005, and Hana style content files, you can add version information to each topic. The help file builder uses a composite file with this fix already in place. <!-- Post-transform component configuration. This must appear after the TransformComponent. See also: CodeBlockComponent. --> <component type="SandcastleBuilder.Components.PostTransformComponent" assembly="C:\SandcastleComponents\SandcastleBuilder.Components.dll" > <!-- Code colorizer files (required). Attributes: Stylesheet file (required) Script file (required) "Copy" image file (required) --> <colorizer stylesheet="highlight.css" scriptFile="highlight.js" copyImage="CopyCode.gif" /> <!-- Base output path for the files (required). This should match the parent folder of the output path of the HTML files (see SaveComponent). --> <outputPath value="Output" /> <!-- Logo image file (optional). Filename is required. The height, width, altText, placement, and alignment attributes are optional. --> <logoFile filename="Logo.jpg" height="64" width="64" altText="Test Logo" placement="left" alignment="left" /> </component>

Constructor A reference to the build assembler. The configuration information This is thrown if an error is detected in the configuration. This is implemented to perform the post-transformation tasks. The XML document with which to work. The key (member name) of the item being documented. This is used to add version information to the topic The document to modify This requires a modification to the Sandcastle presentation style file reference_content.xml (all styles). The help file builder uses a composite file for them and it includes the fix. This can go away once version information is supported by Sandcastle itself. The request has been made. This is called to add the logo to the page header area The document to which the logo is added. This static method is used by the Sandcastle Help File Builder to let the component perform its own configuration. The current configuration XML fragment A string containing the new configuration XML fragment This enumeration defines the logo placement options Place the logo to the left of the header text (the default). Place the logo to the right of the header text. Place the logo above the header text. This enumeration defines the logo alignment options when placement is set to Above. Left-align the logo (the default). Right-align the logo. Center the logo.