Help File Category Properties

The Help File category properties control the appearance and features of the generated help topics.

• Help title (HelpTitle)
• Help file name (HtmlHelpName)
• Help file version (HelpFileVersion)
• Help file language (Language)
• Topic file naming method (NamingMethod)
• Conceptual content placement (ContentPlacement)
• Include root namespace container/Title (RootNamespaceContainer) and (RootNamespaceTitle)
• Enable namespace grouping if supported (NamespaceGrouping) and Maximum group parts (MaximumGroupParts)
• Include "preliminary documentation" warning (Preliminary)
• Additional header content (HeaderText)
• Additional footer content (FooterText)
• Copyright notice URL/Notice text (CopyrightHref) and (CopyrightText)
• Feedback e-mail address/E-mail link text (FeedbackEMailAddress) and (FeedbackEMailLinkText)
• SDK link target (SdkLinkTarget)

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 resulting 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) or .mshc (MS Help Viewer) and the path is controlled via the Output Path property.

This property is used to specify the version number associated with the help file. You can set it to match the version number of the product to which the help file belongs. The value is a string which allows you to use custom project properties to define the value (i.e. {@Version} or {@Major}.{@Minor}.{@Build}.{@Revision}). The property itself can be used as a substitution tag in other properties such as the header or footer text properties.

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.

• Member Name 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.

• Hashed Member Name 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 Member Name option. As with the Member Name 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_[HtmlHelpName] where "[HtmlHelpName]" is the value of your project's Html Help Name property with spaces replaced by underscores. This suffix is required to keep the root namespace container page ID unique across all help files so that there are no duplicate IDs when generating MS Help Viewer output.

• 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 Hashed Member Name option to create the hash value. The second column would be used for the Member Name 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.

GUID Method

// 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");

' 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")

No code example is currently available or this language may not be supported.

No code example is currently available or this language may not be supported.

Member Name Method

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");

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")

No code example is currently available or this language may not be supported.

No code example is currently available or this language may not be supported.

Hashed Member Name Method

// 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");

' 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")

No code example is currently available or this language may not be supported.

No code example is currently available or this language may not be supported.

The naming rules are the same for pages generated for the website output. If using a newer presentation style such as the Default2022 style, the URLs to the topics are direct. Simply bring up the site and navigate to the page you want to link to. The URL to the page will appear in the browser's address bar. Here is an example:

https://ewsoftware.github.io/SHFB/html/1aea789d-b226-4b39-b534-4c97c256fac8.htm

If using an older presentation style that uses the frame-based index page, the URL must use a query string to specify the topic to display. One way to get the URL to use for a page in the old-style website output is to bring up the Index page for the generated website (Index.html or Index.aspx). You can click on the links in the navigation pane to display the topics and click the Direct Link option at the top of the index pane to show the direct link URL in a message box. Copy and paste that link into your web page. That will bring up the index page and show the selected topic as the default page in the right-hand pane. You can replace Index.aspx with one of the other index pages such as the HTML or PHP version. Here is an example link:

https://ewsoftware.github.io/SHFB/Index.aspx?topic=html/1aea789d-b226-4b39-b534-4c97c256fac8.htm

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 Below namespaces, you can make the items appear below the namespace entries in the table of contents.

This property's setting will be ignored if 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. See the Content Placement Options topic for more information.

The Root Namespace Container 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 Root Namespace Title property.

If enabled, the NamespaceGrouping option will cause namespaces with a common number of root parts (specified by MaximumGroupParts) to be consolidated under a common group topic in the table of contents. Increasing the number of maximum parts to consider will create more subgroups below the main groups as needed. Consider the following namespaces each of which contains at least one type:

• MyCompany.MyProduct

• MyCompany.MyProduct.Web.Controls

• MyCompany.MyProduct.Web.Design

• MyCompany.MyProduct.Windows.Forms

If left at the default maximum group setting of two, a group container for MyCompany.MyProduct would be created with child entries for each of the namespaces including its namesake because it contains types. If the maximum is increased to three, a new subgroup would be created below it for MyCompany.MyProduct.Web to contain the controls and design namespaces beneath it. Since no types appear in the group's namesake a child entry is not added for it.

The group topics are similar in nature to namespace topics in that you can add comments to them using the Namespace Summaries option in the Summaries project property category or use a NamespaceGroupDoc class to manage the comments in the source code.

Be aware that namespaces without any types may not result in a group topic. This is done to prevent group entries that contain a single topic that is itself a group. In the example above, if the MyCompany.MyProduct namespace contained no types, a group would not be created and all topics would be listed at the root level. In such cases, if you still want a root container topic, enable the Root Namespace Container project option and place any comments for the group in the Project Summary project option. In a similar fashion, if the Root Namespace Container option is enabled and a root group is created as in the above example, it is removed and its content is listed in the root namespace container topic to prevent a single group entry from appearing by itself below the root namespace container.

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 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 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.

These two properties can be used individually or in combination. If only Copyright Href is specified, a link will appear in the footer of each page for the specified URL. If only the Copyright Text 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 Copyright Text property and the target of the link is set to the URL specified in the Copyright Href property. The value of the Copyright Text 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 Feedback E-Mail Address 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 Feedback E-Mail Link Text 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.

When an SDK link type property is set to MSDN, the SDK Link Target property is used to define where the external 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 external 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 target topic. The last two are useful when producing web output as they will cause the external links to replace the frame set with the target topic page.

Other Resources