What are A-Links and A-Keywords???

By Tim Green
April 7, 2006

Original article link

 

Introduction:

A lot of people find A-links and A-keywords very daunting because at first it's quite difficult to understand what they are and what they can be used for. I had the same experience -- for quite a while when I was first learning to use A-links I felt as though my brain was being twisted every time I tried to think about them.

Actually, however, A-links are quite simple once you have grasped the basic concepts. One of the main problems is the use of the word "keywords" for the jump targets used by A-links -- this is rather confusing because they are really not keywords at all in the normal sense.

This guide is based on a discussion about A-links on the forum and is an attempt to make the basic principles behind A-links comprehensible, which should make it easier to use them if you have to.

Understanding A-links:

The "A" in A-links and A-keywords stands for "associative". This is because A-link keywords are actually not keywords at all. They are more like link or jump targets (known as anchors in H&M). They are never visible to the user like index keywords. They are known as "associative" because they are not absolute targets.

Normal links are programmed in advance and point to a specific address that must be there (otherwise the link will be dead). A-links are different. They are not created until the help is displayed -- instead of programming a hard link you insert a little program that looks for one or more A-link keywords in all available topics. If they are found a matching link is displayed, and if more than one matching topic is found clicking on the link displays a list of topics to choose from rather like an index entry.

This may already be confusing but don't worry about that now, just remember the word "associative" -- it will become clearer in a moment.

A-keywords and "See also" lists:

The best-known use of A-links and A-keywords is for generating "See also:" lists. Instead of inserting a list of links manually what you do is insert a little piece of code in your topic (a mini-program) that says to the help viewer, "Look for all the topics that contain this A-keyword and display a link." When the user displays the help topic the A-link code makes the viewer scan all the topics in the entire help and then it displays links to the ones for which you have entered the A-keyword in question (the keyword also needs to be specified in the code for generating the links).

What makes this useful, theoretically at least, is that you don't need to worry about updating your link lists. If you create a new topic that is relevant for the "See also:" list you just need to include the correct A-keyword, and it will be included in the list. You can also include any number of A-keywords, so that the topic can be included in different lists.

A-keywords and links between help modules:

That's basically the entire mechanism of A-keywords and A-links. That's why they're called "associative" -- because they allow you to generate links "by association". This ability also makes it possible to do other things with them. The most common additional use is for making links between modules in modular projects when you are not sure whether the target of your link is going to be there when the user clicks on it.

This needs a little additional explanation: In HTML Help and WinHelp you can create help systems that are made up of multiple help files. The contents of these additional files are displayed in the TOC only if the file is present in the same directory when the user opens the help. If it is not present it is not part of the help. This makes it very easy to distribute different versions of your help -- you just include or exclude modules.

The problem comes when you have hyperlinks between modules. If you use a normal "hard-coded" link and a module is not there when the user clicks on the link the user will just get an error message. A-links get around this problem: In addition to generating a link to a topic if it contains a specified A-keyword, the A-link code can also display an alternative link if the A-keyword is not found.

What happens is actually exactly the same as with the "See also:" list. When the user displays the topic the help viewer scans all the available topics in all the help files in the current directory for the specified A-keyword. If the keyword is found a hyperlink to the topic is displayed (it needs to be the only topic containing this A-keyword, of course). If the keyword is not found the A-link code automatically displays an alternative link, which will usually be to a topic in the main help file (which is always there by definition). For example, you could direct the user to a topic that displays information about an attractive upgrade she or he could purchase to get additional functionality.

The limitations of A-links:

So why aren't A-links and A-keywords used more often? The first problem is their complexity and the fact that it's rather difficult to explain how to use them, which puts most users off before they have even got started (even though they are quite easy to use once you get it). In WinHelp they are relatively simple but in HTML Help the mechanism is much more complicated and the code involved looks very daunting to beginners. H&M gets around this by allowing you to use the WinHelp method in HTML Help as well -- when you compile it translates it into the HTML Help version automatically (this is explained in the help).

When it comes to "See also:" lists, however, there's also another reason not to use A-keywords -- although they are an impressive, geeky, gee-whizz technology, the sad fact is that they just don't make very good lists. A-links aren't "intelligent", they're dumb. They will doggedly include all the topics containing the A-keyword, no matter whether they are really relevant in the current case or not. A reference that may be very useful in one case may be a complete waste of the user's time in another, and there's no way you can include this decision in the A-link code (you can see this happening all the time in Microsoft's help, which naturally makes extensive use of A-links because they invented the technology).

If you want to make A-links generate really relevant "See also:" lists you have to maintain an extremely large and complex list of different A-keywords for all possible relevancy eventualities, and keep tabs on them in your own mind (or set up a special reference database for it) which will be a nightmare in anything but the smallest projects. It is really much easier to create your "See also:" lists manually by entering the links in the normal way, and you will get much more relevant lists this way.

There is no free lunch:

It's like indexes: There is no way to automate the generation of a good keyword index. There is simply no replacement for the hard work of deciding which keywords are relevant in every single topic. Automated keyword indexes are either unusable because they include everything or useless because they include almost nothing. It's the same with "See also:" lists -- a human being who knows what she or he is doing really needs to decide which links are relevant and which aren't.

Tim Green is an experienced help author and translator. He wrote the online help of Help & Manual and is the site admin of the H&M user forum. You can reach him through his private web site http://www.it-authoring.com