1 Adding Material to the Help Browser

1.1 Introduction

Mathematica’s online help contains detailed information about all of its features and functions. You can also add your own reference material to the existing help files so that the material is viewable from the Help Browser window. This document describes the organization of the online help and the steps needed to modify it.

All material that can be viewed from within the Help Browser is stored in the form of Mathematica notebooks inside the Documentation/English directory. This directory is located in the top-level Mathematica directory, and it contains five subdirectories, one for each radio button in the Browser window.

In addition to the notebooks containing the help material, each of these directories must contain its own copy of the following two files:

To add new reference material to the Help Browser:

Further details about these steps are presented in the following sections.

Note: Each time you modify any of the help files, you should click the Help ⊳ Rebuild Help Index menu command for your changes to take effect.

1.2 Setting Up New Browser Categories

The four columns in the Help Browser, just below the radio buttons, 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 any of the topics in the last column 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 categories to be displayed in the Help Browser’s columns. To do this, you must edit the BrowserCategories.m file contained in the User Documents directory. This requires a knowledge of the syntax for a BrowserCategory command.

BrowserCategory Commands

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

BrowserCategory["User Document", None, 
	{BrowserCategory["Complex Analysis", None,
	 {Item["Analytic Functions", "MyHelp.nb"],
 	  Item["Cauchy's Theorem", "MyHelp.nb"]}]}]

The contents of a simple BrowserCategories.m file.

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

As shown in this example, every BrowserCategories.m file consists of a single BrowserCategory command written in a specific syntax. This command has the form BrowserCategory["category name", name,list].

The arguments in a BrowserCategory command are as follows:

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

HelpDirectoryListing Commands

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 path name of the directory must be given. Otherwise, the path name 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, then the BrowserCategories.m file is taken to be in the 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 radio buttons that appear in the Help Browser window. The contents of this file are shown below.

BrowserCategory["Help Browser", None, {
    HelpDirectoryListing[{"GettingStarted"}, False],
    HelpDirectoryListing[{"UserGuide"}, False],
    HelpDirectoryListing[{"Reference"}, False],
    HelpDirectoryListing[{"Samples"}, False],
    HelpDirectoryListing[{"UserDocs"}, False],
    BrowserCategory["Master Index", None, {HelpMasterIndex[]}]
}]

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

Example 2

Here is another simple example of a BrowserCategory.m file that uses HelpDirectoryListing commands. Here it is assumed that each of the directories UserDocs/Chapter 3 and UserDocs/Chapter 4 contains a separate BrowserCategories.m file.

BrowserCategory["UserDocs", None,
{   BrowserCategory["Chapter 1", None,
     {Item["Section 1.1", "MyHelp.nb"],
      Item["Section 1.2", "MyHelp.nb"]}],
      Item[Delimiter],
      HelpDirectoryListing[{FrontEnd`FileName[{"UserDocs",   
      "Chapter 3"}]}, False],
      HelpDirectoryListing[{FrontEnd`FileName[{"UserDocs",  
      "Chapter 4"}]}, False]
}]

Item Commands

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

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

The 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:

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 which 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.

BrowserCategory["User Document", None, 
	{Item["Numbers","MyHelp.nb",IndexTag -> "Chapter 1"],
	 BrowserCategory["Calculus",None,
		{BrowserCategory["Differentiation", None,
		 {Item["Definition", "MyHelp.nb",
		  IndexTag -> "Subsection 2.1.1"],
		  Item["Differentiating a product","MyHelp.nb", 	
		  IndexTag -> "Subsection 2.1.2"],
		  Item["Partial Differentiation","MyHelp.nb",
		  IndexTag -> "Subsection 2.1.3"]}],
    	  Item["Integration","MyHelp.nb", IndexTag -> "Section 2.2"]}],
    	  Item["Trigonometry","MyHelp.nb",IndexTag -> "Chapter 3"],
          Item["Linear Algebra","MyHelp.nb",IndexTag -> "Chapter 4"],
          Item["Graph Theory","MyHelp.nb",IndexTag -> "Chapter 5"]}]

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.

BrowserCategory["User Document", None, 
{BrowserCategory["Complext Analysis", None,
{Item["Analytic Functions", "MyHelp.nb", CopyTag->"SubItem1"],
 Item["Cauchy's Theorem", "MyHelp.nb", CopyTag->"SubItem2"]}]}]

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

You are now ready to view your help information.

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.

1.3 Creating Hyperlinks to the Help Browser

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 this 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 which contains the corresponding IndexTag. The cells associated with that Item command 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. (Click here for more information on how to do this.) The expression for each hyperlink consists of a ButtonBox command with the following syntax:

ButtonBox["Button text", ButtonData :> "IndexTag", ButtonStyle -> "UserDocsLink"]

A ButtonBox command can have three arguments:

This ButtonData option can be set in three different ways:

An Example

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

Item["Option Inspector","FormatMenu.nb",CopyTag -> "OptionsDialog", IndexTag -> "Option Inspector"]

Hence the expression for the ButtonBox command will be:

ButtonBox["Option Inspector", ButtonData :> "Option Inspector", ButtonStyle -> "ReferenceLink"]

Note:

Here are the steps involved in creating such a hyperlink:

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.

1.4 Adding New Topics to the Master Index

Once you have defined browser categories for your reference material, you might want to incorporate key words from it into the Master Index. The Master Index provides an alphabetical listing of all key words, allowing users to quickly locate information on a specific topic.

To add new key words to the Master Index:

The BrowserIndex.nb file

The BrowserIndex.nb file is a Mathematica notebook that contains the list of terms that appear in the Master Index, as well as links to information about each item. This file must use the “HelpBrowser.nb” style sheet, which contains definitions for all the special styles needed. Here is an example of a simple BrowserIndex.nb file:

The contents of a simple BrowserIndex.nb file

Every BrowserIndex.nb file consists of a header followed by a list of entries. The first cell in the file is called the header.

The header must have the following properties:

This is what the expression for the header in the sample BrowserIndex.nb file looks like. You can see that it satisfies both the properties listed above.

Cell["My Help Documentation", "IndexSection", CellTags -> "MasterIndexHeading"]

The header cell is followed by a series of entries. Each entry corresponds to a single topic in the Master Index.

A Master Index entry has the following properties:

Here is the cell expression for the first entry in the sample BrowserIndex.nb file. You can see that it has all the three properties listed above.

Cell[TextData[{"My first entry, ", ButtonBox["1", ButtonData :> "Chapter 1", ButtonStyle -> "UserDocsLink"]}], "Index", CellTags -> "My first entry"]