Last update: 19-Mar-2003 This document discusses the pros and cons of using collection-level and title-level .HxA files. Thanks to Michael Waltuch and Microsoft for assistance in writing this document.
|
<HEAD> ... <xml> <MSHelp:Attr Name="Product" Value="VB" /> <MSHelp:Attr Name="Product" Value="VC" /> <MSHelp:Attr Name="Product" Value="VS" /> <MSHelp:Attr Name="Product" Value="MSHWkShop"/> <MSHelp:Attr Name="Information Type" Value="Orientation" /> <MSHelp:Attr Name="Information Type" Value="Reference" /> <MSHelp:Attr Name="TopicType" Value="kbRef" /> <MSHelp:Attr Name="TargetOSVers" Value="kbWinOS" /> <MSHelp:Attr Name="TargetOS" Value="Windows" /> <MSHelp:Attr Name="Locale" Value="kbEnglish" /> <MSHelp:Attr Name="Locale" Value="en-us" /> <MSHelp:Attr Name="DocSet" Value="Visual Basic" /> <MSHelp:Attr Name="DocSet" Value="Visual Studio" /> <MSHelp:Attr Name="DocSet" Value="C#" /> ... </xml> ... </HEAD> |
Later we use these attributes to create filters that can reduce the scope of TOC, Index and Search results. Here's an example of a VS filter:
Filter name: Visual Basic
Filter definition: ("DocSet" = "Visual Basic")
OR ("DocSet" = "MSDN" AND "ProductVers" = "kbVBp700")
|
But this is all rudimentary (see other references if it's not). Things get more interesting when we start to look at the .HxA attribute definition files.
14-June-2006:
Your TOC not appearing in the main VS TOC? We used these attributes to make our docs show correctly in VS 2005.
<xml> <MSHelp:TOCTitle Title="My Title"/> <MSHelp:RLTitle Title="My Title"/> <MSHelp:Attr Name="Information Type" Value="Orientation"/> <MSHelp:Attr Name="Information Type" Value="Reference"/> <MSHelp:Attr Name="DocSet" Value="Visual Basic"/> <MSHelp:Attr Name="DocSet" Value="Visual Studio"/> <MSHelp:Attr Name="TargetOS" Value="Windows"/> <MSHelp:Attr Name="Locale" Value="kbEnglish"/> <MSHelp:Attr Name="LinkGroup" Value="GettingStarted"/> </xml> |
28-June-2006
What about VS 2005/2008 Express? See H2 FAQ.
2. Attribute Definition (.HxA) Files
Attributes can be optionally re-declared in an .HxA file:
- to make them display or be hidden in the Filter Editor dialog list box.
- to give a friendly name to both the attribute name and value.
- to mask out certain attributes.
The format of .HxA files are defined in your MS.VSHIK online documentation:
ms-help://ms.vshik/mshlpwrk/html/hxgrfattributedefinitionfilehxa.htm
There are two types of .HxA files:
- Title-level .HxA files - these are compiled into the .HxS help (title) file.
- Collection-level .HxA files - these are shipped as is, uncompressed.
The Golden Rule is Collection-level files must not contain a DTD reference.
DTD files are installed by VSHIK and are required only for compiling .HxS help files. Your customers won't have the DTD files, so any use of DTD in collection-level Hx? files will cause registering and viewing problems.
Title-level .HxA file:
<?xml version="1.0"?> <!DOCTYPE HelpAttributes SYSTEM "ms-help://hx/resources/HelpAttributes.DTD"> <HelpAttributes DTDVersion="1.0"> <AttName Id="1" Name="helpware" Display="Yes" UIString="Helpware" AttType="Enum"> <AttVal Id="1_1" Name="h2reg" Display="Yes" UIString="h2reg" /> </AttName> ... Collection-level .HxA file: <?xml version="1.0"?> <!DOCTYPE HelpAttributes> <HelpAttributes DTDVersion="1.0"> <AttName Id="1" Name="helpware" Display="Yes" UIString="Helpware" AttType="Enum"> <AttVal Id="1_1" Name="h2reg" Display="Yes" UIString="h2reg" /> </AttName> ... |
If you are interested, the DTD files can be accessed by decompiling the help file
Resources.HxS (which is part of the "Hx" collection) at this location:
c:\Program Files\Microsoft Help 2.0 SDK\Resources.HxS
3. Title-level .HxA file
| From Visual Studio .NET Help Integration doc:
Attributes can be defined in an attribute definition (.HxA) file and then assigned to topics. This allows you to control what attributes and values are included in the compiled Help title. Attributes that are assigned to topics but not defined in the .HxA file are not included at compile time. Alternatively, you can choose not to add an .HxA file to your Help project. In this case, all attributes and values assigned to topics will be included at compile time. The Visual Studio .NET attribute schema is extensive and useable by most documentation sets. To augment the Visual Studio attribute schema, you can define additional attribute/value pairs or add values to existing attributes. If you choose to augment the Visual Studio schema, do not include an .HxA file in your Help project. |
Q. What if I don't use a compiled .HxA file at all?
A. This is recommended. Excluding the compiled .HxA file causes *all* attributes
and values specified in the topics to be included at compile time.
Q. If I compile an .HxA file into my .HxS file, then *only* the attributes
and values defined in that .HxA file are included when the title is compiled?
A. Correct. Topic attributes not declared in that .HxA are masked out of existence.
Q. Should my compiled .HxA file contain any VS attributes I have used in my topics?
A. Yes. If you compile in an .HxA file you will need to declare any VS attributes used.
Products that integrate with VSCC typically use some attributes from the VS
attribute schema (Locale, DocSet, etc.) for their topics. If you compile an .HxA file
you must redefine all the VS attributes and values that your content uses. Again
you will have less to debug if you simply exclude the compiled .HxA all together.
Q. What do MS recommend?
A. MS now recommend that in your current and future VS integration releases you move
away from using a compiled .HxA file. It will make debugging problems easier. It also
makes less work for your doc team because you do not have to track which VS attributes
you use in your content.
This is a tedious and error prone process. If you miss even one that is used for filters or
Dynamic Help, then your content will not work the way you expect, because it will be as
if your topics do not even have that attribute/value. Unnecessarily compiling an .HxA file
makes debugging filter and Dynamic Help bugs much more difficult. You can see the attribute
markup in the topics (view source), but until you decompile the title and compare the
attributes/values in the .HxA with the ones in the markup you don't know what was really
included at compile time.
4. Collection-level .HxA file
| Attributes declared in a collection-level .HxA file will show up in the Filter Edit dialog attribute list. By excluding .HxA attributes or the entire .HxA file, you are only hiding those attributes from the Filter edit dialog attribute list. IE. if you *know* what your values are you can still create valid filters using the excluded attributes. |
Q. What if I don't use a collection-level .HxA at all?
A. Your attributes will still work in collection filters. They just won't be visible
in the Filter Edit dialog attribute list or when the H2 API returns a list of attributes.
Q. So collection-level .HxA files expose (make visible) attributes at the collection level?
A. Yes in your collection, and in any collections you plug into. And any collection those
collections plug into, etc.
Q. I'm doing VS integration. Do I need to declare the VS attributes I used in this .HxA file?
A. No since the VS collection you are plugging into already exposes the VS attributes.
If your topics use only existing VS attributes, you can safely remove this .HxA entirely.
Q. Is it possible to add my own values for standard VS attributes so they appear in the section
of the Filter Dialog users expect?
A. Yes, simply assign the appropriate AttName and AttVal in your .HxA.
Q. Why would you exclude attributes from the .HxA file, or even exclude the entire .HxA file?
A. Maybe to create filters with attributes hidden from easy view.
Q. So I don't really need any .HxA files at all to use attributes?
A. Correct. However without a collection-level .HxA your own unique attributes won't be exposed to the user.
Q. How does this all effect LinkGroups and VS dynamic help?
A. I found by removing the collection-level .HxA file completely my LinkGroup disappeared.
So make sure your LinkGroup attribute is declared in the collection-level .HxA file.
Here's my collection-level .HxA file from my H2Reg collection...
<?xml version="1.0"?> <!DOCTYPE HelpAttributes> <HelpAttributes DTDVersion="1.0"> <AttName Id="1" Name="helpware" Display="Yes" UIString="Helpware" AttType="Enum"> <AttVal Id="1_1" Name="h2reg" Display="Yes" UIString="h2reg" /> </AttName> <AttName Id="8" Name="LinkGroup" Display="No" UIString="LinkGroup" AttType="Enum"> <AttVal Id="8_1" Name="HelpWareHelp" Display="No" UIString="HelpWareHelp" /> </AttName> </HelpAttributes> |
Other References:
Q. I need more basic information. Where do I go?
A. See the VSHIK white papers and our tutorial MS H2 Collection.
Q. Which attributes should I declare if I'm integrating into Visual Studio?
A. See the VSHIK white papers and our tutorial MS help 2 Dynamic Help.