Progress
Help Development
Guide


Adding KLinks and ALinks

KLinks and ALinks are hypertext links from words, phrases, or graphics in help topics that direct the help engine to run a macro that searches for other help topics based on specified keywords. With KLinks and ALinks, you do not need to specify any destination topic IDs.

KLinks and ALinks work exactly the same way, except for the types of keywords they use to identify matching topics, and the help macros they use to find sets of matching topics. KLinks use the KLink macro to search for topics associated with a K-keyword, while ALinks use the ALink macro to search for topics associated with an A-keyword.

An advantage of using KLinks and ALinks is that you can create them and compile the help file that contains them without knowing exactly what topics will serve as their targets. Also, because KLinks and ALinks use keywords instead of topic IDs, they can identify more than one topic as a target. When multiple topics are found, their titles are displayed in a Topics Found dialog box.

A disadvantage of using KLinks and ALinks as opposed to jumps, is that it is possible to create a KLink or an ALink that does not find any topic. When this happens, the help engine either displays a default topic (which you specify) or displays a message box with the text “No additional information is available.”

The difference between KLinks and ALinks lies in the way their corresponding keyword types are meant to be used in help systems.

KLinks

A KLink works by finding a set of topics, each of which is associated with one or more specified index keywords. Each index K-keyword is stored in the K footnote of a topic and it says something about that topic. For example, a help topic about the File menu might have as an index keyword, “saving files,” because the task of saving files is something you can do from the File menu.

Index keywords (K-keywords) are the keywords that appear on the Index tab of the Help Topics dialog box, and they are intended to function in exactly the same way as the keywords that appear in the index in the back of a printed book. In fact, the results of a KLink topic search for any keyword will be exactly the same as when the user double-clicks on that keyword in the Index Tab.

ALinks

An ALink works by finding a set of topics, each of which is associated with one or more specified A-keywords. Each A-keyword is stored in the A footnote of a topic and it says something about another topic that this topic is related to. For example, in a command reference help file, if Command-1 is related to Command-2, then the topic explaining Command-1 might have an A-keyword, “Command-2.” The topic on Command-2 would then have a Related Topics button or text hotspot designed to find all other topics that reference Command-2 in their A footnotes.

An ALink is often associated with a graphical hotspot that looks like a button, and is labeled Related Topics. (Note that a Related Topics “button” is not the kind of button you create with a CreateButton macro in the [CONFIG] section of the help project file; it is a bitmap that you turn into a graphical hotspot using the Hotspot Editor. (See the "Adding Hotspots to Graphics" section.)

An advantage of ALinks, is that when you add a new topic to an existing help file, you can identify it as related to an existing topic without editing that topic. Instead of adding a hard-coded “See also” jump to the old topic that refers back to the new topic, you add an A-keyword to the new topic, indicating that it is related to the old one.

Creating KLinks and ALinks

Follow these steps to create a KLink or an ALink:

  1. Decide which word, phrase, or graphic reference will serve as the link text (the visual cue that identifies the jump to the user).
  2. Format the text or graphic reference as double underline (or strikethrough) text.
  3. Enter the KLink or ALink macro as hidden text immediately following the link text.

In the example shown below, the phrase “KLink” (formatted as double underline text) is the KLink link text. The text string “!KLink(keyword)” (formatted as hidden text) is the KLink macro that performs the search for all topics that reference the keyword in their K footnotes:

In the example shown below, the phrase “ALink” (formatted as double underline text) is the ALink link text. The text string “!ALink(keyword)” (formatted as hidden text) is the ALink macro that performs the search for all topics that reference the keyword in their A footnotes:

For more detailed information on the KLink and ALink macros, see the Help Author’s Guide (hcw.hlp), the help file for Help Workshop.


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095