Share via

Creating SDKs: Creating HxS s

  • Article

On Friday I talked a bit about how teams work together to create SDK collections. Today I'm going to drill in more detail into the process of creating HxSs, the base files used for documentation in the Libraries. The same disclaimer applies as on Friday: I'm talking mainly about the MSDN Quarterly Library here, since I was part of that team for around six years. The Longhorn SDKs are somewhat different, but still follow common protocols and concepts.

The big difference between an SDK and a shipping piece of software, from a production standpoint, is that an SDK is essentially nothing more than a collection of disparate files pulled together by several different wrappers. Docs are all delivered in an HxS format, sometimes accompanied by an HxI. HxSs are XML-based versions of what used to be called CHM files. You're almost certainly familiar with CHMs if you ever click Help in any application. Your local computer probably has dozens of CHMs on it, and many teams still ship CHMs as part of their process. HxSs are the next generation version of CHMs. They're XML-based, so they're much more easily edited, and they also integrate more smoothly with each other in a collection.

An HxS consists of HTML files, associated art, any CSS or JS files, and several meta-files. HTML can come from literally any source, whether XML transformed through use of XSLTs, raw HTML authored by hand, or HTML that comes from a user database. Art is the material associated with the HTML pages, such as example gifs or product logos. CSS and JS files are used to create specific functionality. The meta-files are usually pretty standard. No HxS can be compiled without an HxT, an XML TOC file. Here's an example of an HxT:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE HelpTOC SYSTEM "MS-Help://Hx/Resources/HelpTOC.DTD">
<HelpTOC DTDVersion="1.0">
<HelpTOCNode Url="/html/odc_AcSecurity.htm"/>
<HelpTOCNode Url="/html/odc_acXMLLnk.htm"/>
<HelpTOCNode Url="/html/odc_conformat.htm"/>
<HelpTOCNode Url="/html/odc_accessowc.htm"/>
<HelpTOCNode Url="/html/odc_acautocrct.htm"/>
<HelpTOCNode Url="/html/odc_websvsvb6.htm"/>
<HelpTOCNode Url="/html/odc_webvsnet.htm"/>
<HelpTOCNode Url="/html/odc_accessxml.htm" Title="Importing From and Exporting to XML"/>
<HelpTOCNode Url="/html/odc_acdates.htm"/>
</HelpTOC>

As you can see, an HxT is nothing but a series of references to other files, some of which can have titles. The other necessary file is an HxC, which is essentially a manifest for the HxS. It contains all the meta-information about an HxS:

<?xml version="1.0"?>
<!DOCTYPE HelpCollection SYSTEM "MS-Help://Hx/Resources/HelpCollection.dtd">
<HelpCollection DTDVersion="1.0" LangId="1033" Title="Microsoft Access 2002 Technical Articles" Copyright="&#x00A9; 2005 Microsoft Corporation. All rights reserved." FileVersion="7.1.41028.1452">
<CompilerOptions OutputFile="dnacc2k2.HxS" CreateFullTextIndex="Yes" CompileResult="HxiHxs" StopWordFile="Scripts\msdnFTSstop_Unicode.stp" SampleStagingDir="samples">
<IncludeFile File="Scripts\includes.HxF"/>
</CompilerOptions>
<SampleDef File="SamplesOut.hxe"/>
<TOCDef File="dnacc2k2.HxT"/>
<KeywordIndexDef File="Scripts\Alinks.HxK"/>
<KeywordIndexDef File="Scripts\Klinks.HxK"/>
<KeywordIndexDef File="Scripts\Flinks.HxK"/>
<ItemMoniker Name="!SampleInfo" ProgId="HxDs.HxSampleCollection" InitData="S"/>
<ItemMoniker Name="!DefaultTOC" ProgId="HxDs.HxHierarchy" InitData="AnyString"/>
<ItemMoniker Name="!DefaultFullTextSearch" ProgId="HxDs.HxFullTextSearch" InitData="AnyString"/>
<ItemMoniker Name="!DefaultKeywordIndex" ProgId="HxDs.HxIndex" InitData="K"/>
<ItemMoniker Name="!DefaultAssociativeIndex" ProgId="HxDs.HxIndex" InitData="A"/>
<ItemMoniker Name="!DefaultContextWindowIndex" ProgId="HxDs.HxIndex" InitData="F"/>
</HelpCollection>

As you can see, the HxC defines a title for a docset(Microsoft Access 2002 Technical Articles), its name (dnacc2k2.HxS), the fact that it's an HxS/HxI pair (CompileResult="HxiHxs"), what HxT it uses (<TOCDef File="dnacc2k2.HxT"/>) and how its index is created (<KeywordIndexDef File="Scripts\Alinks.HxK"/>, etc.).

This is then all compiled together using the HTMLHelp 2.0 compiler and dropped to a location from which the integrated SDKs can pick it up.

You might be wondering why sometimes we create HxSs only, and sometimes we create HxS/HxI pairs. I'll get into that in more detail when I talk about the role of setup in this process, but essentially HxS only files are easier to manage, while HxS/HxI pairs are more versatile.

As always, please let me know if I missed something important or if you have questions about anything I've talked about.

Comments

  • Anonymous
    July 11, 2005
    Off-Topic? - Maybe. I am a bit confused about the HxS and CHM. As I have seen in VSTS Beta 2, it is now possible to have a Help Project. My evaluation has shown that from that I can produce HxS files. Thats fine! But would it be necessary to produce a CHM file, if I would like to use the help in a Forms application. Is HxS only for VS? Thankx, Cheers

  • Anonymous
    July 12, 2005
    I haven't investigated the VSTS Beta 2 enough to know if there's a viewer shipped that allows for HxS files to be viewed in it. I would assume so, otherwise the technology wouldn't be available. As long as the person viewing the HxS also has the viewer, you can use HxS for help. The big advantage of CHM is that users can double-click a CHM file and the viewer automatically opens up. With HxS, the viewer is seperate from the project.

    Does that help?

  • Anonymous
    July 12, 2005
    Jason, I am not clearly understand, why is there so many HxS, HsK, HxI... files where just single CHM was used?

    Also question. It seems HxS is a kind of resource file but it is XML-based. And it can be viewed outside of VS by browser pluggable protocol. I just copied URL from integrated help, pasted it to Address bar and it just works.

    But is it possible to make it out-of-viewer scenario works with just files on drive and no MSDN Library installation?

  • Anonymous
    July 12, 2005
    The comment has been removed

  • Anonymous
    April 12, 2006
    http://www.yaodownload.com/web-authoring/html-conversion-tools/pocket-chm/

  • Anonymous
    October 28, 2006
    "The biggest limitation of HxS is that it can't work with just files on a drive. It needs to be either plugged into a collection or into a tool that allows you to view it. You can't just double-click an HxS as you can a CHM." Is this still true now, a year later?  This seems like a very big limitation.  e.g. There is no way I'm actually going to all all 12 or so SDK releases for Windows.  But I do have all 12 sitting on a shared network drive, for anyone who needs to refer to them.  Being able to invoke the help/documentation was a very useful part of that. Not being able to easily access a help file must be part of that "too much complexity for very simple things" that seems to pervade products of late.

  • Anonymous
    August 09, 2009
    You (almost) promised a follow-up on this article - but I cannot find it... As far as I can read from Microsoft documentation, creating a single help file install build from several HxS files requires compilation of a single, combined HxI file - but how do you do that? What tool is needed?

  • Anonymous
    August 10, 2009
    Lars, have you checked the Windows SDK Team blog to see if you can find the answer?  Check this article and the linked follow up article: http://blogs.msdn.com/windowssdk/archive/2008/08/27/how-it-works-windows-sdk-documentation-part-1.aspx Karin Meier

  • Anonymous
    October 30, 2012
    I want to integrate a chm file into visual studio 2008 using help integration wizard. But it requires hxs file. So what should I do?