About A-Keywords

<< Click to Display Table of Contents >>

Navigation:  Reference > Project Structure & Templates > Topic IDs, Context Numbers and Keywords >

About A-Keywords

A-keywords, which are also referred to as "associative keywords" (that's what the A stands for) or "A-link keywords", are quite a mystery to many help authors. They are actually not as complicated as many people believe, but they tend to get neglected because most people believe they are too difficult to understand or use.

A-keywords are available in HTML Help CHM files only

A-keywords are a proprietary Microsoft technology that is only supported in the Microsoft HTML Help CHM format. They used to be supported in the Winhelp HLP format as well, but that is now obsolete and no longer used. You cannot use A-keywords in any other format.

Introduction to A-keywords

The following brief list describes the main features and capabilities of A-keywords. First and foremost it is important to understand that A-keywords are a Microsoft help technology that is only available in HTML Help. Their functionality is not available in any other output format.

A-keywords are invisible

A-keywords are similar to ordinary index keywords ("K-keywords" or "K-link keywords") but they are never seen by the user. This might seem strange at first – what good is a keyword that nobody can see? That brings us to the purpose of A-keywords:

A-keywords are used for "associative" linking

A-keywords are not used for indexes, they are used for creating "associative" links. When an A-keyword is accessed it returns a list of links to all the topics in the help that contain that keyword. We say that the topics are "associated" with the keyword.

These links are not pre-defined by the help author, they are generated actively when the user views the help. When the user clicks on a special hyperlink that access an A-keyword the help viewer searches all the topics in the help to see whether they contain the keyword, including all topics in external help files in modular help systems.

This makes it possible to use them to generate lists of links to "relevant" topics. To add a topic to the list you just need to include the relevant A-keyword in its Topic Options, in the A-Keywords section.

A-keywords are "soft" and "conditional"

This means that you don't have to "hard code" links to specific topic addresses. Only links to topics containing the A-keyword (or keywords) at runtime are displayed. This means you can create links to topics that may or may not be present when the user views the help, which usually only happens in modular help systems.

A-keywords have their limitations

All this being said, A-keywords do have their drawbacks. They are extremely useful for creating links to external help files in modular projects. However, as you will discover yourself when you try, it is a lot of work to use them to create genuinely meaningful "See also" lists.

The problem is that the inclusion of a simple keyword is too mechanical to be able to provide a real basis for relevance in all but the most simple and technical texts. Also, managing your A-keywords and their relevance is actually much more difficult than simply deciding yourself which topics are really relevant to the current topic. You will either end up overwhelming the user with too many links that are not really relevant, or you will miss the relevant links.

More information about A-keywords

If you are interested in more background information about the technology and uses of A-keywords the best place to start is the website weblink http://www.helpware.net. Be warned, however, that the information provided there will be easiest to understand if you have experience with developing HTML Help and Winhelp Note that Windows Vista does not support Winhelp. If you want to be compatible with Vista you must transition to a different help format. files manually with Microsoft's Help Workshop and HTML Help Workshop!

The main uses of A-keywords

There quite a few technical uses for A-keywords but the main purposes in normal help files are for automated generation of "See also" lists and for links between separate help files in modular help systems.

"See also" lists:

You can use A-keywords to create "See Also" links that automatically display link lists of related topics when the user clicks on them. The list includes all topics found containing the A-keywords specified in the A-link macro definition. These links work in both individual help files and modular help systems consisting of multiple help files.

One of the most interesting features of this function is that you don't have to specify which help files you want to look in. The help viewer will automatically search all available help files that are part of the modular help system for the A-keyword. This means that it will automatically include topics from modules that are available from the list and exclude topics from modules that are not available.

See Using A-Keywords for details on how to make your own "See also" lists.

Links between help modules:

You can also A-keywords to create links between modular help files. The advantage of this method is that if the target file is not available at runtime the link is not dead. Instead, the user sees an alternative topic from the current help file. If the target file is available the user sees a dialog in which he or she can choose the topic from the target file or the alternative topic.

See Using A-keywords for details on how to make associative links between help modules.

See also:

Keywords and Indexes

Using A-keywords