A Guide to Sandcastle - Part 3 - Customizing the build process [Help File]

Now that the basic elements related to the project are ready, it is time to customize the help file itself. To do this, there are a couple of dedicated options in the Help File section (in the property grid) in SHFB. This is the section that basically defines the appearance of all linked documents that constitute the help content.

The first block of properties is pretty self-explanatory:

This all relates to the content position and complimentary elements (like the copyright text and link). Next, there is a set of properties that might be a bit confusing first:

IndentHtml

This particular property doesn't affect the way the end-user is going to receive the help content. It is designed for those who plan on editing the automatically generated HTML content - if the property is set to True, the HTML content will be correctly indented in the pre-compiled file set.

For a quick comparison:

Indented

Non-indented

You can easily see this if you have the CleanIntermediates property set to False, therefore being able to access the autogenerated content.

Language

No, this will not automatically translate the help content to another language. Some basic elements will be translated, but the major content (XML documentation) is still in your hands.

Basically, this property allows you to tell SHFB that you are using a non-standard language and that proper encoding should be used.

NamingMethod

Defines the way intermediary files are named. Ultimately those are compiled in a single file, but you can see how those are named through the Working folder in your project folder.

The default method is set to Guid, so if you take a look at the current file set (once again, you need the CleanIntermediates property set to False so that the cache isn't destroyed) you should see something similar to this:

Not exactly helpful, so why not change Guid to MemberName, since each page represents a separate member anyway? Here is the updated list:

Much better, but there is one more option - HashedMemberName:

Either of these options is only useful for debugging and customization purposes - ultimately, your end-user won't see any significant benefits from you using one naming convention over another.

PresentationStyle

Defines the appearance of the help document. There are three options available by default:

• VS2005 - as it says, represents the layout used in the default MSHelp2 system.
• Prototype - resembles the documentation style for Visual Studio 2002/2003.
• Hana - a conceptual design currently not used by Microsoft.

Additional styles can be added manually if you have time and willingness to create your own appearance descriptors.

Here is how each of these styles looks like (tested in the context of a HtmlHelp1 project).

VS2005:

Prototype:

Hana:

RootNamespaceContainer

If you referenced more than one assembly, probably there are more than one namespaces available that need to be documented. Setting this property to True will list all namespaces as child nodes relative to the main content node in the help tree. For example:

SyntaxFilters

If you decided that you don't want to provide VB.NET and C++ cases for general class declarations and method invokes, this is the place to disable them. If you take a look at the image above (applied to the VS2005 presentation style), you will notice that the class implementation is presented in multiple programming languages. Not only can you remove existing entries but also create new ones for other .NET-supported languages, like F#, J# and even (where applied) implementations for ASP.NET and XAML.