Creating SDKs: Creating HxS s
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="© 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.