Microsoft Windows SDK Blog : Docs

How it works: Windows SDK Documentation Part 2

wsdkblog@microsoft.com — Tue, 02 Sep 2008 20:39:00 GMT

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.

TOC Manipulation
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
MS.LHSMSSDK.1033	MSSDK.HXT
MS.LHSNETFX30SDK.1033	NETFX30SDK.HXT
MS.LHSWINSDK.1033	WINSDK.HXT

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:

[Other TOC info…]

</HelpTOCNode>

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.

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:

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.

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"?>
<!DOCTYPE HelpTOC>
<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>
       <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>
    </HelpTOCNode>
    <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.

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

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

How it works: Windows SDK Documentation (Part 1)

wsdkblog@microsoft.com — Wed, 27 Aug 2008 23:03:00 GMT

Introduction

Many Windows SDK users have questions about the system behind the documentation provided with the SDK. Here is the first in a series of posts explaining how this system works and how to customize it. This post provides an overview of the basic structure behind the Windows SDK help system. It also looks at how ms-help:// URLs can be used to learn about the organization of the documentation “behind the scenes.” Look for part 2, which will explain the mechanism behind the table of contents (TOC), and show you how to customize it.

Explanation of Help Services and the Viewer

There are two major pieces to the documentation that ships with the Windows SDK. The first is a set of help services (called Help 2.0). These services allow us to create namespaces for holding sets of documentation, register documentation files (.HXS files) to those namespaces, and provide that content to the customer by servicing requests from URLs in the form ms-help://

The second big piece is the viewer. The viewer that ships with the Windows SDK currently is DExplorer 9.0. DExplorer has been around for quite a long time. It is the application that launches when you click the icon for Windows SDK documentation in the start menu.

These two pieces, the help services and the DExplorer viewer, make up the primary offline help experience for Microsoft. It is used by many teams across the company, including MSDN, SQL Server, and of course the Windows SDK.

Windows SDK Namespaces

Different product units use different schemes for their documentation. For the Windows Server 2008 SDK, we chose to organize our documentation into three namespaces. The first, MS.LHSMSSDK.1033, is our root “parent” namespace. It is mostly empty, containing only introductory topics about the SDK and some API catalog information. The second, MS.LHSNETFX30SDK.1033, contains our “managed” content, topics aimed toward the .NET developer. The third, MS.LHSWINSDK.1033, contains the “native” content, topics aimed toward the Win32 and COM developer. This is how we allow the user to only install the Win32 and COM documentation, .NET Framework documentation, or both. At installation time, we always install the parent node, and then install and plug-in the appropriate children depending on the user’s selections.

Deciphering ms-help URLs

When paying attention to the URL box toward the top the documentation in DExplorer, the user can learn more about where topics live in the documentation system. From the URL users can determine not only which HXS file contains each topic, but which namespace the HXS file is registered to. This will help later in figuring out how to customize the TOC.

URLs for the SDK are almost always in the form:

ms-help://MS.LHSMSSDK.1033/<hxsname>/…
Or
ms-help://MS.LHSMSSDK.1033/<child namespace>/<hxsname>/…

For instance, open the SDK documentation, expand the Win32 and COM node, expand the Administration and Management node, expand the Application Installation and Servicing node, then click on the Application Recovery and Restart node.

Observe that the URL is:

ms-help://MS.LHSMSSDK.1033/MS.LHSWinSDK.1033/recovery/recovery/portal.htm

This URL tells us the topic lives in recovery.hxs, which belongs to the MS.LHSWINSDK.1033 namespace, which is a child of the master MS.LHSMSSDK.1033 namespace as outlined earlier.

Conclusion

Hopefully this basic overview of what is going on “behind the scenes” with the Windows SDK documentation is helpful. A basic understanding that the help system is made up of a set of services and a viewer to those services can help troubleshoot problems with the documentation. Being able to look at a help URL and understand something about the way files and topics are organized can help users better see the structure.

In a future post, we’ll take this basic information and use it to make TOC customizations. With some additional information, reorganizing the table of contents is easy and can help users quickly get to the content they use most often.

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

Speech Content in the Windows SDK

wsdkblog@microsoft.com — Wed, 27 Feb 2008 21:23:00 GMT

Charles Oppermann on the Speech team wrote a post on the new Speech-related content that ships in the recently released Windows SDK for Windows Server 2008 and .NET Framework 3.5. The content in this new Windows SDK completely replaces the older SAPI 5.1 SDK and supports development on Windows XP, Windows Server 2003, Windows Vista, and Windows Server 2008.

How-to: Find API References Alphabetically

wsdkblog@microsoft.com — Thu, 21 Feb 2008 10:03:00 GMT

Did you know that you can search for APIs alphabetically in the Windows SDK Documentation? You can search the online SDK Documents on MSDN.

The alphabetical API listing is named “Platform Information” topic. It’s a handy way to find that API reference if you can remember the API name, or close to it. Search by ‘Managed’, ‘Win32 and Com’ or ‘All’.

Windows Sidebar Documentation Refresh

wsdkblog@microsoft.com — Fri, 17 Aug 2007 03:43:00 GMT

My name is Karl Bridge and I’m the Programming Writer responsible for the Windows Sidebar documentation on MSDN and the Windows SDK.

Based on comments and criticisms of the Sidebar developer documentation released with Windows Vista, I set out to review the existing documentation and backfill and revise as necessary. As it turned out, backfilling became a bit of an understatement and I wound up reorganizing and rewriting the entire document set. I believe gadget developers will find the new Sidebar documentation to be significantly more comprehensive, informative, and helpful.

The results of this rewrite will be released to the Web via MSDN in mid-August as well as in the next release of the Windows SDK.

Along with new Overviews and completely revised Reference documentation, a significant addition to the Sidebar documentation is the comprehensive code snippet coverage throughout. These code snippets demonstrate each of the scripting elements available to create gadgets for the Sidebar. The majority of snippets are derived from fully-functional sample gadgets being released in coordination with the documentation refresh. The gadget samples can be downloaded from the Microsoft Download Center or, if you installed the Windows SDK and did not modify the standard install location, you can find them at: %user%\Program Files\Microsoft SDKs\Windows\[version number]\Samples\WinUI\Sidebar.

Here’s a rundown and brief description of each of the gadget samples:

Hello World

Demonstrates a simple 'Hello World' gadget.

Gadget Flyout

Demonstrates gadget Flyout functionality.

Gadget Settings

Demonstrates gadget Settings functionality.

Gadget Docking

Demonstrates the gadget docking functionality.

Environment Variables

Demonstrates how to get the value of an environment variable.

Sidebar State

Demonstrates how to get the Sidebar dock state.

Machine Details

Demonstrates how to get details about the user's machine.

System Diagnostics

Demonstrates how to write an Application event log entry.

Gadget Debugging

Demonstrates gadget debugging functionality.

Text and Graphics

Demonstrates the g:background, g:image, g:text elements and the gimage protocol of the Windows Vista Sidebar.

Time and Sound

Demonstrates how to expose system sounds and time settings.

System Shell

Demonstrates how to expose system shell information.

Windows Contacts

Demonstrates how to access the Windows Contacts store.

Windows Mail

Demonstrates how to access the Windows Mail message store.

Please continue to provide feedback on the Sidebar documentation through the MSDN forums, the Community Content tab now available on each respective page, the MSDN page rating tool, and the Windows SDK feedback channels. We value your feedback immensely and look forward to your comments on our efforts to provide you with the best developer documentation possible.

Karl Bridge

Programming Writer – Windows Sidebar

Send the Windows SDK Team Your Thoughts

wsdkblog@microsoft.com — Thu, 26 Jul 2007 20:35:00 GMT

Do you have feedback for the Windows SDK? We want to hear from you. Email your feedback to us. The Windows SDK provides all of the necessary headers, libraries, and tools needed to build Windows applications that make use of the Win32 API set and the .NET Framework, and includes samples to illustrate the technologies for those platforms. What do you like? What do you dislike? What should we change next time?

Finding WPF Samples in the SDK Docs

wsdkblog@microsoft.com — Tue, 23 Jan 2007 01:04:00 GMT

When you click on a link to download one of the Windows Presentation Foundation Samples in the Windows SDK, you go to the Windows SDK .NET Framework 3.0 Samples page, where you can download all the .NET samples in bulk.

This can be convenient, except that when you are looking at an individual sample topic, there's no way for you to know where each sample is in the download you just installed. The WPF team is working on a way for users to download individual samples from their respective topics, which will allow you to determine the location of the sample yourself. Until the fix is implemented, the WPF folks have posted a handy file listing all the WPF samples and their locations.

Ever wonder why managed samples are included in the documents of the Windows SDK but unmanaged samples are installed to your hard drive as loose files in the file system? Find out in Why are Windows SDK samples installed differently?

Karin Meier

Samples PM, Windows SDK Team

IntelliSense in the Windows SDK

wsdkblog@microsoft.com — Thu, 11 Jan 2007 02:13:00 GMT

The Windows SDK includes almost everything a professional developer would need to program for Windows, such as headers, tools, docs, and samples.

As a part of this, we shipped IntelliSense XML files for .NET Framework 3.0 in the Windows SDK for Vista and we create the IntelliSense Xml files for the .NET Framework 3.5 for all Visual Studio editions including Visual Studio Express.

IntelliSense is especially useful when exploring a new technology. There is information about IntelliSense here: http://msdn2.microsoft.com/en-us/library/hcw1s69b(VS.80).aspx. IntelliSense presents text to the VS user. Some, perhaps all, of that text can be found in an XML file that corresponds to an assembly of a similar name.

One example of this text follows:

<?xml version="1.0" encoding="utf-8"?>

<doc>

<name>System.Data.ObjectSpaces</name>

</assembly>

<summary>Generates identity keys for entities.</summary>

</member>

I am trying to understand the ratio of people that use the IntelliSense XML files through Visual Studio versus how many use the IntelliSense XML files directly from the Windows SDK. My guess is that most folks that use IntelliSense XML files use it in Visual Studio, but I’d like to hear from the community on this one.

Sean Grimaldi

Documentation PM

Windows Vista SDK Online Documentation

wsdkblog@microsoft.com — Fri, 10 Nov 2006 04:19:00 GMT

In case you’re wondering where the Windows Vista SDK online docs went to on http://windowssdk.msdn.microsoft.com ….well, Vista has RTM’d so we’ve integrated the Windows SDK docs into the “official” MSDN Library for release content.

We plan to keep http://windowssdk.msdn.microsoft.com live going forward to be a home for beta (pre-release) “Longhorn” Server and VS “Orcas” SDK content.

Keith Swem

Production Manager, Windows SDK Team

Broken links in the SDK

wsdkblog@microsoft.com — Tue, 18 Apr 2006 19:59:00 GMT

Hi Everyone, I'm Ken Milne, the Documentation PM for the Windows SDK. My work touches all aspects of aggregating documentation content and documentation-related features into the Windows SDK.

As we rapidly approach the date when the Windows SDK will ship for Windows Vista Beta 2, we are closing down on numerous issues in the docs and striving to improve the overall documentation quality in many areas. There are ton of issues in documentation that drive me nuts, but the one that’s driving me crazy today is broken links. There are few things more annoying than knowing I’m hot on the trail of exactly the right piece of information I need to do my job when I get

Sorry, no topics were found for the selected link.

Keywords = "3fc0e979-dad6-4f28-81ec-8707c0f0efdc"

IndexMoniker =

SourceURL =

… and I’m stopped dead in my tracks. Blecchh! I’m frustrated, I feel like I’ve wasted time, and my search for that elusive piece of information I need in order to move forward takes me back to where I began. It’s not only a colossal drag, it’s the kind of thing that I want to see us completely eliminate from the Windows SDK by the time we ship the RTM version of the Windows Vista OS.

The good news is, we’re making progress. There are still far too many broken links in the Windows SDK, but we are well on our way to driving that number down. Here are some facts:

The Windows SDK documentation includes 2.37 million hyperlinks. As Microsoft continues to document new WinFX features and the 7000 new unmanaged APIs that ship in Windows Vista, that number grows every day.

We currently have 24,000 broken links in the Windows SDK. This means that around 1% of all our links don’t work in our current builds.

24,000 broken links is 24,000 too many. That said, we had 37,000 broken links in the documentation a few weeks ago. Thanks to great work by our documentation build and production team, we’ve made up a lot of ground by eliminating a lot of broken links in our managed reference documentation. The User Education (UE) teams who contribute the documentation that we ship in the Windows SDK team have also done an admirable job of fixing broken links in the content that they own and deliver.

Since the SDK contains hundreds of thousands of Help topics, you may wonder how we find all of these broken links in the first place. We use an internally developed tool called HavMatLite to seek out these pesky links. HavMatLite checks how links in the HTML Help 2.x (a.k.a. Havana) system resolve. HavMatLite generates a broken link report for each .HxS file we ship, and then we pass those reports along to the UE team that owns the file. It’s that team’s job to investigate and fix broken links, and include those fixes in future content drops to the SDK. Progress is iterative, and we run the HavMatLite tests frequently to see how we’re doing overall. The SDK team itself owns several of these files and we make it a priority to fix broken links in all of the conceptual, samples, how to, and reference content we own and build.

Is there anything that drives you crazy about the Windows SDK documentation? Let us know! It’s my hope that you find the Windows SDK documentation useful and informative, so any comments you have on how we can improve doc quality overall is greatly appreciated.

Ken