This property allows you to define where the additional and/or conceptual content items appear in the table of contents. By default, they will appear above the namespaces. By setting this property to BelowNamespaces, you can make the items appear below the namespace entries in the table of contents.

This property's setting will be ignored if the table of contents is split via a custom tag in one of the additional content files, a site map is defined that specifies a split table of contents, or conceptual content is defined with an entry marked as the split location. In such cases, items prior to the entry with the "split" option will appear before the API content. The item with the "split" option and all items after it will appear below the API content.

These two properties can be used individually or in combination. If only CopyrightHref is specified, a link will appear in the footer of each page for the specified URL. If only the CopyrightText property is specified, that message appears in the footer of each page. If both are specified, a link appears in the footer of each page using the text from the CopyrightText property and the target of the link is set to the URL specified in the CopyrightHref property. The value of the CopyrightText property is treated as plain text. It will be HTML encoded where necessary to resolve issues related to the ampersand character and the XML parser. In addition, you can encode special characters such as the copyright symbol using an escaped hex value (i.e. © = \xA9).

If an e-mail address is specified in the FeedbackEMailAddress property, an extra message is included in the footer of each page with a message saying "Send comments on this topic to" plus the specified e-mail address or link text. If a FeedbackEMailLinkText value is specified along with a feedback e-mail address, that text will be displayed as the link text rather than the e-mail address. If left blank, the e-mail address will be used. The e-mail address is rendered as a clickable mailto: link and the subject of the e-mail will be set to the title of the help file plus the title of the page in which the link appears.

This property can be used to insert an extra message in the footer of each page. By default, it is blank. HTML tags are supported within the text.

This property can be used to insert an extra message in the header of each page. By default, it is blank. HTML tags are supported within the text. See the Preliminary property for a way to mark all topics as preliminary.

This property is used to set the title for the help file. This text will appear as the title of the help file's window.

This property is used to specify the name of the HTML help file. This name is used during the build process for a couple of other files so be sure that you do not specify a path or an extension on this value. It should only specify the name part of the file. The extension will always be .chm (HTML Help 1), .HxS (MS Help 2), or .mshc (MS Help Viewer) and the path is controlled via the OutputPath property.

Note
For MS Help 2 builds, this name is used as the collection namespace name. In such cases, spaces in the name are not allowed and, if any are found in the name, the build will fail.

This property allows you to specify the language to use for the compiled help file. The default is to use the English language resource files. A shared content file is supplied that contains various item overrides related to the help file builder's project properties. Currently, shared content files for the help file builder are available for several languages. If you specify a language for which a file does not exist, the help file will build but you will see a warning in the build output that the selected language resources could not be found and that it is defaulting to the US English (en-US) language files. For more information on creating additional language resource files, see the Localizing Language Resource Files help topic.

This property allows you to specify how the help topic filenames will be generated. There are three options:

• Guid will generate an MD5 hash of the topic ID and format it as a GUID value. The topic ID is the member name from the XML comments file for the item and includes all parameter values for methods. This is the default value and is suitable for most help files. While this guarantees unique topic filenames, it does make it cumbersome to link to help topics from external sources such as application code or web pages that are not part of the help file's additional content as the names are rather long and non-intuitive.
• MemberName will name each help topic after the member that it represents. To avoid problems with invalid filename characters, " " (space), ":", ".", "`" (0x60), "#", "*", and "?" characters are replaced with an underscore in the member names. Overloaded methods will generate duplicate names. To avoid this problem, all subsequent duplicate names will have a counter added to the end of their name separated by an underscore (i.e. M_Type_Method, M_Type_Method_1, M_Type_Method_2, etc). When this occurs, a message is recorded in the log file. Also note that this may generate extremely long filenames when the full path is included. This may cause the build to fail. If so, try using the next option.
• HashedMemberName will name each topic using the hash value of the member name in hex format. This results in a much shorter filename, even shorter than the GUID names, but it can still be easily reproduced by an application or ASP.NET web page in order to link to the help topic. The actual member name is used without any of the character replacements noted for the MemberName option. As with the MemberName option, overloaded methods will generate duplicate names. To avoid this problem, all subsequent duplicate names will have a counter added to the end of their name separated by an underscore (i.e. M:Type.Method, M:Type.Method_1, M:Type.Method_2, etc.). When this occurs, a message is recorded in the log file.

Note that each help topic ID will have a prefix denoting what it represents:

• R: represents the root namespace page. There will always be a single entry named R:Project.
• N: represents a namespace help topic that lists all of the members of the given namespace.
• T: represents a type help topic that lists all of the members of the given type.
• Overload: represents a help topic that lists all of the overloads for a particular class member.
• F: represents a field member.
• E: represents an event member.
• P: represents a property.
• M: represents a method.

Below are some examples of the member names and their equivalent filenames. The values in the first column would be used for the HashedMemberName option to create the hash value. The second column would be used for the MemberName option. For GUID filenames, the method names in the first column would include parameter information rather than a numeric suffix.

To map a member name to its equivalent filename, you can use code similar to the following. As noted in the code, the HTML files will reside in an html\ folder and will have a .htm extension so be sure to add them to the resulting topic filename.

CopyC# - GUID

// Compute the MD5 hash of the member name.  Assume
// memberName contains the member name of the topic
// to show.
HashAlgorithm md5 = HashAlgorithm.Create("MD5");

byte[] input = Encoding.UTF8.GetBytes(memberName);
byte[] output = md5.ComputeHash(input);

// Format it as a GUID value
Guid pageId = new Guid(output);

// Show the topic in the help file.  Remember to add
// the "html\" folder name and the ".htm" extension.
Help.ShowHelp(parentForm, helpFilePath,
    HelpNavigator.Topic, @"html\" + pageId.ToString() + ".htm");

CopyVB.NET - GUID

' Compute the MD5 hash of the member name.  Assume
' memberName contains the member name of the topic
' to show.
Dim md5 As New HashAlgorithm.Create("MD5")

Dim inputArray() As Byte() = Encoding.UTF8.GetBytes(memberName)
Dim outputArray() As Byte() = md5.ComputeHash(inputArray)

' Format it as a GUID value
Dim pageId As New Guid(outputArray)

' Show the topic in the help file.  Remember to add
' the "html\" folder name and the ".htm" extension.
Help.ShowHelp(parentForm, helpFilePath, _
    HelpNavigator.Topic, "html\" & pageId.ToString() & ".htm")

CopyC# - MemberName

Regex reInvalidChars = new Regex("[ :.`#<>*?]");

// Assume memberName contains the member name of the
// topic to show.
string pageName = reInvalidChars.Replace(
    memberName, "_");

// Show the topic in the help file.  Remember to add
// the "html\" folder name and the ".htm" extension.
Help.ShowHelp(parentForm, helpFilePath,
    HelpNavigator.Topic, @"html\" + pageName + ".htm");

CopyVB.NET - MemberName

Dim reInvalidChars As New Regex("[ :.`#<>*?]")

' Assume memberName contains the member name of the
' topic to show.
Dim pageName As String = reInvalidChars.Replace( _
    memberName, "_")

' Show the topic in the help file.  Remember to add
' the "html\" folder name and the ".htm" extension.
Help.ShowHelp(parentForm, helpFilePath, _
    HelpNavigator.Topic, "html\" & pageName & ".htm")

CopyC# - HashedMemberName

// Assume memberName contains the member name of the
// topic to show.
string pageName = String.Format("{0:X}",
    memberName.GetHashCode());

// Show the topic in the help file.  Remember to add
// the "html\" folder name and the ".htm" extension.
Help.ShowHelp(parentForm, helpFilePath,
    HelpNavigator.Topic, @"html\" + pageName + ".htm");

CopyVB.NET - HashedMemberName

' Assume memberName contains the member name of the
' topic to show.
Dim pageName As String = String.Format("{0:X}", _
    memberName.GetHashCode())

' Show the topic in the help file.  Remember to add
' the "html\" folder name and the ".htm" extension.
Help.ShowHelp(parentForm, helpFilePath, _
    HelpNavigator.Topic, "html\" & pageName & ".htm")

The naming rules are the same for pages generated for the website output. One way to get the URL to use for a page in the website output is to bring up the Index page for the generated website (Index.html or Index.aspx), you can right click on the links in the navigation pane and select Copy Shortcut. Paste that into your web page that you want to link to the selected topic and modify the link by inserting "Index.html?topic=" or "Index.aspx?topic=" immediately in front of the "html/" part of the link. That will bring up the index page and show the selected topic as the default page in the right-hand pane. For example:

Copy 

http://www.ewoodruff.us/shfbdocs/Index.aspx?topic=html/1aea789d-b226-4b39-b534-4c97c256fac8.htm

Tip
Conceptual content topic files are always named using their GUID as the filename with a ".htm" extension and they are always placed in the html/ folder.

When this property is set to True, it will mark all topics in the help file with a large, red message "[This is preliminary documentation and is subject to change.]". This is a quick and easy way to mark documentation for beta software as preliminary and subject to change.

This property is used to choose the presentation style that determines the layout and appearance of the help topics. Sandcastle comes with three styles: VS2005 (the default), Prototype, and Hana. The files for each style are located in the .\Presentation folder under the main Sandcastle installation folder.

Tip

If you create your own styles, place the folders in the same location and the help file builder will detect them automatically and let you select them in the project. Be sure to include one of the default style names in your folder name as certain build steps are performed differently based on the selected style and this will be the hint that the help file builder uses to determine what action to take.

The RootNamespaceContainer property is used to specify whether or not a root namespace entry is added to the table of contents to act as a container for the namespaces from the documented assemblies. If set to True, a root Namespaces table of contents entry will be created as the container of the namespaces in the documented assemblies. If set to False, the default, the namespaces are listed in the table of contents as root entries. To change the name of the root container from "Namespaces", enter the new name in the RootNamespaceTitle property.

When an SDK link type property is set to MSDN, the SdkLinkTarget property is used to define where the MSDN links will open in the browser. This property has no effect if the SDK link type property for a particular help file format is set to any other value. The default value is Blank to open MSDN links in a new window. It can also be set to Self, Parent, or Top which have the same effect of replacing the current window's content with the content of the MSDN topic. The last two are useful when producing web output as they will cause the MSDN links to replace the frameset with the MSDN topic page.

This property lets you specify which languages appear in the Syntax section of the help topics and the languages that will appear in the language filter dropdown. It can be set to one language, a combination of languages, All to include them all, Standard (the default) for C#, VB.NET, and C++ only, or None to remove the Syntax section entirely.

Other Resources