Compiling Help Files from XML Using Sandcastle - Creating the Help File (
Page 3 of 4 )
Creating the Help File
It’s time to create the help file. You have everything in place, including the Sandcastle Help File Builder properties. Before you can generate a help file, though, you must provide the location of the project’s XML file by clicking Add. Use the Select the File(s) to Document dialog box to locate the XML ProjectAndNamespace.XML file you created earlier. Double click this file and you see it added to the Assemblies to Document. Notice that Sandcastle Help File Builder tells you that this file contains comments only.
ADVERTISEMENT
You still need to add the application file, the file that contains the output that Visual Studio provided, ApplicationComments.XML in the case of the example application. Double clicking this file automatically adds the executable to the list. If you have multiple assemblies that you want to document in a single help file, simply add them to the list using the same technique.
After you add all of the assemblies that you want to work with to the list, click Save the Current Project on the toolbar (the disk icon). Save the project file. At this point, you can click Build the Help File on the toolbar (the icon looks the same as the build icon in Visual Studio). The help building process takes a while, even for a small project, so you can get a cup of coffee. When the process is done, the GUI automatically launches the new help file for you. Figure 4 shows typical CHM file output.
Figure 4: Typical help file output from Sandcastle.
This help file contains a number of very helpful features. For example, you can switch from the default C# declaration syntax to Visual Basic or C++. The switching mechanism really works—I must admit that I was surprised. Clicking any link takes you to that place in the help file. The site map at the top of the file lets you move between locations. Various options let you filter the content with a click of a button. In short, the output file works provides significant functionality and helps you work with any code documentation quite easily. If you set the Include Favorites property to True, the resulting help file even includes a Favorites tab that you can use to save favorite locations.
