Many Windows SDK users have questions about the system behind the documentation provided with the SDK. Part 1 of this series explained the basic structure behind the Windows SDK help system. It also looked at how ms-help:// URLs can be used to learn about the organization of the documentation “behind the scenes”. Knowledge of the information in that post is assumed for this post.
In this post, the mechanism behind the table of contents (TOC) will be explained. I will include a couple of easy ways to customize the TOC.
Topics that appear in the documentation all belong to an HXS file. Every HXS file is a compressed collection of topic files gathered together. Each HXS represents one unit of documentation, a collection of topics about the same subject. By default (for English), the Windows Server 2008 SDK installs them to %programfiles%\Microsoft SDKs\Windows\v6.1\Help\1033. Each HXS file contains the .htm files of the pages themselves, as well as a TOC definition file (.hxt) that explains how those topics are organized. Outside of the HXS files, in addition, every namespace has its own TOC definition file, explaining where and how each HXS will appear in the TOC.
Here is a table of the three namespaces created for the SDK and its corresponding TOC file:
|Namespace||TOC Definition File|
Because the .HXT files are simple XML, users have the option to make changes to them and consequently change the appearance of the TOC.
Note: It is highly recommended that you save the original copies of your .HXT files somewhere safe as a backup so that you are able to retrieve them later if you want to restore your TOC to its original state.
Note: Whenever a change is made to the TOC, DExplorer will need to be closed and reopened before those changes will take effect.
Different TOC Node Types
There are several different kinds of tags in the HXT files, each corresponding to a different behavior in how the TOC is displayed to the user in DExplorer.
A “Regular” node is simply a container. It will provide a nest for child nodes. If the tag contains a valid Url= attribute as well, clicking that node in the TOC will also navigate to that topic. In other words:
<HelpTOCNode NodeType=”Regular” Title=”Getting Started” Url=”sdkintro/html/9a2db508-5b77-43f8-afa4-1ca82d24bb83.htm”>
[Other TOC info…]
This will create a TOC node called “Getting Started”, and everything until the closing tag [Other TOC info…] will be nested inside of it. Clicking on that node will also navigate to the indicated page.
Regular nodes don’t have to wrap anything, they can serve almost like bookmarks to topics, with no nested contents underneath of it.
<HelpTOCNode NodeType=”Regular” Title=”Getting Started” Url=”sdkintro/html/9a2db508-5b77-43f8-afa4-1ca82d24bb83.htm”/>
The other most common type of TOC node is the “TOC” type. It passes control of the TOC over to the individual HXS files, plugging them in. It looks something like this:
<HelpTOCNode NodeType=”TOC” Url=”functioncatnat”/>
In this kind of node, the Url must refer to the name of an HXS file that appears in the same namespace. It is possible to turn control over to an HXS file in a different namespace by adding the namespace in question before the name of the file.
<HelpTOCNode NodeType=”TOC” Url=”MS.LHSNETFX30SDK.1033/dv_fxconceptual”/>
So what does this all mean to the user? It is possible to customize the TOC with most commonly used materials gathered in one place.
For instance, a developer that uses the System.Web.Services namespace a great deal and wants to pin it to the top of their TOC, and also wants to keep handy the character class codes for regular expressions, and also wants to keep the cascading style sheet topics toward the top might modify the top of their MSSDK.HXT like this:
<?xml version=”1.0″ encoding=”UTF-8″?>
<HelpTOC DTDVersion=”1.0″ PluginStyle=”Flat”>
<HelpTOCNode NodeType=”Regular” Title=”My Favorites”>
<HelpTOCNode NodeType=”Regular” Title=”System.Web.Services Namespace”>
<HelpTOCNode NodeType=”TOC” Url=”MS.LHSNETFX30SDK.1033/fxref_system.web.services”/>
<HelpTOCNode NodeType=”Regular” Title=”Regex Character Classes” Url=”ms-help://MS.LHSMSSDK.1033/MS.LHSNETFX30SDK.1033/dv_fxfund/html/0f8bffab-ee0d-4e0e-9a96-2b4a252bb7e4.htm”/>
<HelpTOCNode NodeType=”Regular” Title=”Cascading Style Sheets”>
<HelpTOCNode NodeType=”TOC” Url=”MS.LHSWINSDK.1033/css” />
<HelpTOCNode NodeType=”Regular” Title=”Getting Started”…
[the rest of the original file comes after here]
This creates a new top level node called “My Favorites” at the very top of the TOC. Underneath of it is a node called “System.Web.Services Namespace” that contains all of the API reference topics for that namespace. Next is a singleton node called “Regex Character Classes” that points to the specific page that has the character class codes on it. Last is a node called “Cascading Style Sheets” that points to the CSS topics.
In some ways this can be more powerful than simply bookmarking things in your Help Favorites. This is because you can reorganize multiple sets of topics by referring to their HXS file, rather than bookmarking one single topic at a time.
With this basic information it’s easy to manipulate the SDK TOC in ways that make sense to the user. Just be sure to save the originals so you will have a backup. In a later post we’ll discuss how to merge together multiple sets of documentation from different products. For instance, many users are interested in combining their Windows SDK documentation and their Visual Studio documentation in a customized way.
Software Development Engineer in Test
The MSDN Windows SDK Developer Center is the place to find resources and links to Windows SDK products, release notes, technical articles, and more.