H2 Attributes & Filters

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.

1. Defining Attributes

Attributes are associated with topic files. To create attributes in a help project, we simply add them as name-value pairs to the head section of our topic files (topic file meta data). Example:

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:

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.

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:

1. Title-level .HxA files - these are compiled into the .HxS help (title) file.
2. 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.

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

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.