Creating Hyperlinks to the Help Browser

Creating a Button Box

The CopyTag option to the Item command allows you to specify which material should show up in the Help Browser when you click on a topic displayed in one of the columns. However, the Item command can also take a second type of option called IndexTag. Using the latter option, you can construct special hyperlinks in a notebook that point to reference material in the Help Browser.

When one of these hyperlinks is clicked, the Help Browser searches for the Item command in the BrowserCategories.m file that contains the corresponding IndexTag. The cells associated with that item are then displayed in the Help Browser.

To construct a hyperlink that uses an index tag, you should know how to unformat a cell and edit the expression representing the cell directly. To see the expression for a cell, select the cell and choose Format Show Expression. The expression for each hyperlink consists of a ButtonBox command with the following syntax:

A ButtonBox command can have three arguments:

1. "Button text"--This is the text that forms the hyperlink. It usually appears underlined and in a different color.

2. "ButtonData"--This is an option that is used to specify the material referred to by the hyperlink. It is usually set to the IndexTag associated with the cell or group of cells that must be displayed in the Help Browser. If this option is omitted, then it assumes a default value given by "Button text".

3. "ButtonStyle"--This option specifies the directory in which the target material of the hyperlink is stored. It can take any of five values, each named after one of the button categories, that is, GettingStartedLink, MainBookLink, OtherInformationLink, RefGuideLink, or AddOnsLink.

This ButtonData option can be set in three different ways:

i. If ButtonData "tag", then the Browser searches the BrowserCategories.m file for an item with that IndexTag. The cells associated with that item (i.e., whose cell tags match the CopyTag or IndexTag for the corresponding Item command) are then displayed in the Browser window.

ii. If ButtonData {"tag1","tag2"}, then the Browser searches the BrowserCategories.m file for an item with an IndexTag of "tag1". All cells associated with that item are then displayed in the Browser window. However, the window scrolls down to the first cell with the additional cell tag of "tag2".

iii. If you do not set the ButtonData option explicitly, it assumes a default value given by the "subcategory name" specified in the first argument of the Item command.

An Example

Suppose you want to construct a hyperlink that points to information about the Option Inspector menu command under the Format menu. The cells with this information are located in the a notebook called "FormatMenu.nb" and have the cell tag "OptionsDialog". This notebook is in the OtherInformation directory of the Documentation/English directory. Here is the item in the BrowserCategories.m file that refers to this topic.

Hence the expression for the ButtonBox command will be the following.

Note

1. The first argument of the ButtonBox command contains the text that will represent the hyperlink.

2. The setting for the ButtonData option matches the IndexTag for this item.

3. The setting for the ButtonStyle option is OtherInformationLink because the target material is located in the OtherInformation subdirectory.

Here are the steps involved in creating such a hyperlink:

1. Select the cell in which you want to place the hyperlink, for example, a blank text cell.

2. Unformat the expression for the cell by typing E. (For Macintosh, type E.)

3. Insert the previous ButtonBox expression into the cell.

4. Wrap the command TextData[ ] around the ButtonBox expression inside the cell.

5. The cell expression now looks like this.

Cell[TextData[ButtonBox["Option Inspector", ButtonData "Option Inspector", ButtonStyle "Hyperlink"]], "Text"]

6. Format the cell expression by typing E again.

This completes the construction of the hyperlink. The text "Option Inspector" now appears underlined and colored. Clicking the link will cause the Help Browser to open and display information about this menu command. A similar procedure can be followed for constructing a hyperlink to any other item in the Help Browser.