The Mathematica Journal
Volume 9, Issue 2

Search

In This Issue
Articles
Tricks of the Trade
In and Out
Trott's Corner
New Products
New Publications
Calendar
News Bulletins
New Resources
Classifieds

Download This Issue 

About the Journal
Editorial Policy
Staff
Submissions
Subscriptions
Advertising
Back Issues
Contact Information

Customizing the Help Browser
Pavi Sandhu

Setting Up New Browser Categories

Introduction

The four columns in the Help Browser display the categories into which the reference material is organized. These categories are arranged in a hierarchy with the first column showing the top-level categories. Clicking a topic either opens more subtopics in the next column or causes reference material about that topic to be displayed in the Browser window.

To make your own material accessible from the Help Browser, you need to define a set of topics that will be displayed in the Help Browser's columns. To do this, you must edit one of the BrowserCategories.m files contained in the Documentation directory of your Mathematica layout.

The BrowserCategory Command

The following example shows the contents of a simple BrowserCategories.m file.

The contents of a simple BrowserCategories.m file.

To investigate the effect of this file, copy it into the Documentation/English/AddOns directory of your Mathematica layout. You should first save a copy of the existing BrowserCategories.m file in the same location under a different name so that you can revert to it later. If you then rebuild the Help Browser (using the Rebuild Help Index command under the Help menu), the categories defined by the new BrowserCategories.m file will appear in the Browser window.

Every BrowserCategories.m file consists of a single BrowserCategory command of the form: BrowserCategory["category name", name, list].

The arguments in a BrowserCategory command are as follows:

1. "category name"--This is a string that specifies the category name to be displayed in the Help Browser column.

2. name--If set to None, this option indicates that the source files are located in the same directory as the BrowserCategory.m file being edited. Alternatively, the source files can be kept in a subdirectory one level below the current directory. In this case "name" is set to the name of the subdirectory.

3. list--This is a list whose elements can be commands of the following types:

Item["subcategory name", "file name", options]--This command specifies the name of a terminal subcategory in the Help Browser. Clicking the subcategory name causes information about it to be displayed in the Help Browser.

Item[Delimiter]--This command inserts a horizontal line in the column where the subcategories are listed. It is useful for separating subcategories.

HelpDirectoryListing["directory", arg2, arg3]--This command creates categories in the Help Browser's columns taken from a different BrowserCategories.m file. The location of the file to be used is specified by the three arguments.

BrowserCategory[]--This command is of exactly the same form as the top-level BrowserCategory command, except that it is nested one level deeper in the hierarchy, so that its category name will be displayed one column to the right.

Note: Since there are only four columns in the Help Browser, a BrowserCategory command can be nested at most four levels deep.

The HelpDirectoryListing Command

The HelpDirectoryListing command is used to create categories in the Help Browser's columns based on a BrowserCategories.m file at a different location. It has the form: HelpDirectoryListing[directory, arg2, arg3].

The three arguments directory, arg2, and arg3 together specify the location of the BrowserCategories.m file to be used. The first argument, directory, specifies a directory location using the FrontEnd`FileName function. The absolute pathname of the directory must be given. Otherwise, the pathname specified is interpreted to be relative to the Documentation/English directory inside the top-level Mathematica directory.

If arg2 is set to False, the Browser searches for a BrowserCategories.m file at the top level of "directory". If it is set to True, the Browser searches all subdirectories located one level below directory.

If arg3 is set to False, the location of the BrowserCategories.m file is completely specified by the first two arguments. If it is set to True, the BrowserCategories.m file is taken to be in a Documentation/English directory located in the directory specified by the first two arguments.

If either of the last two arguments is omitted, they assume their default values. The default value of arg2 is True. The default value of arg3 is the current value of arg2.

These comments are summarized in the following table, which shows the directory that is searched to locate a BrowserCategories.m file for different values of arg1 and arg2.

Note: Here directory / * refers to all subdirectories located one level below directory.

Example 1

The HelpDirectoryListing[] command is used in the top-level BrowserCategories.m file in the Documentation/English directory to define the buttons that appear in the Help Browser window. Here are the contents of this file.

Note that in each HelpDirectoryListing command here, arg2 is omitted. This means it has the same value as arg3 by default.

Example 2

Here is another simple example of a BrowserCategories.m file that uses HelpDirectoryListing commands. Here it is assumed that each directory, Chapter 2, Chapter 3, and so on, contains a separate BrowserCategories.m file.

The Item Command

The Item command has the form: Item[subcategory name, file name, options].

The arguments of the Item command specify the target material that is displayed in the Help Browser when the subcategory name associated with that item is clicked.

1. subcategory name--This is a string that specifies the subcategory name to be displayed in the Help Browser column.

2. file name--This is a string that specifies the name of the notebook from which information pertaining to that subcategory is to be retrieved.

3. options--There can be two types of options: IndexTag and CopyTag:

The IndexTag serves as a tag to identify the item that is the target of a hyperlink in a notebook. A discussion of this option is deferred to the next section.

The CopyTag specifies which cells, from the notebook specified by file name, appear in the Help Browser when the item is clicked.

The value of CopyTag serves as a marker identifying the target cells linked to a specific topic. When an item in the Help Browser is clicked the Browser looks for cells, in the notebook specified by "file name", whose cell tags match the value of the CopyTag for that item. All such cells are then displayed in the Browser window.

The CopyTag option can be specified in four ways:

1. If CopyTag Rule None, the entire notebook specified by file name is displayed in the Browser window.

2. If CopyTag Rule "tag", the Browser looks for all cells in the notebook specified by file name whose cell tag is "tag". Only those cells are then displayed in the Browser window.

3. If the CopyTag is not specified explicitly, it takes the value of the IndexTag option.

4. If both the CopyTag and the IndexTag are omitted, they assume a default value given by the subcategory name specified in the first argument of the Item command.

An Example with Nested Categories

Here is a more complicated example illustrating how to define subcategories at different levels in the hierarchy. It contains multiple BrowserCategory commands, including one that is nested three levels deep. At each level of nesting, the category name associated with the Item command shifts one column to the right in the Browser window.

Note: The CopyTag is not specified explicitly for any of the Item commands in this example. It therefore assumes a default value given by the "subcategory name" for each item.

A sample BrowserCategories.m file showing nested commands.

Here are the categories defined by this file as they appear in the Browser window.

You can use the BrowserCategories.m file shown in this example as a template to construct your own Browser categories by replacing the chapters, sections, and subsections in it with topics and subtopics relevant to your own material. You can add as many extra categories as you wish by adding more BrowserCategory or Item commands to the list at the level required.

Note: Since there are only four columns in the Help Browser, a BrowserCategory command can be nested at most four levels deep.

Adding a Sample Document

Here are the steps involved in setting up the Browser categories shown in the first example above.

1. Go to the Documentation/English directory in the top-level Mathematica directory and open the AddOns directory.

2. Rename the existing BrowserCategories.m file so that you can revert to it later. Then create another file called BrowserCategories.m containing the following text.

BrowserCategory["Add-ons", None,
{BrowserCategory["Complex Analysis", None,
{Item["Analytic Functions", "MyHelp.nb", CopyTagRule "SubItem1"],
Item["Cauchy's Theorem", "MyHelp.nb", CopyTag
Rule "SubItem2"]}]
}]

3. Create a new notebook containing the following text.

Here is some reference material about analytic functions.
Here is some reference material about Cauchy's theorem.

4. Assign the cell tag "Complex Analysis" to the first cell and "Cauchy's theorem" to the second cell. To learn how to add a tag to a cell, see Creating and Using Hyperlinks.

5. Click the File RightTriangle SaveAs menu command to bring up the file dialog box.

6. Save this notebook as "MyHelp.nb" in the Documentation/English/AddOns directory.

7. Go to the Help menu and select Rebuild Help Index. This command updates the Help Browser so that it reflects your latest changes.

Note: You must add cell tags to any target material that is to be displayed when any item in the Browser window is clicked. The cell tags should match the CopyTag for that item, as explained in the discussion of the Item command.

You are now ready to view your help information.

1. Click Help RightTriangle Help Browser.

2. Click the Add-ons & Links button.

3. Click "Complex Analysis" in the leftmost category column and then click "Analytic Function" in the second column.

The first cell of your help notebook is displayed in the Browser window. If you click "Cauchy's theorem", the second cell will be displayed.



     
About Mathematica | Download Mathematica Player
Copyright © Wolfram Media, Inc. All rights reserved.