How to create a Mathematica Add-on with documentation in the "Help Browser" and palette in the "Palettes" submenu

Author: Jose Luis Gomez-Munoz  http://homepage.cem.itesm.mx/lgomez

Contents

1. What are we going to do?

2. Create a package that can be loaded with Needs[]

3. Create package's documentation in Mathematica's Help Browser

4. Update the package's documentation in Mathematica's Help Browser

5. Create a Palette for the package and place it in the Palettes menu

6. Distribute your Add-on to other Mathematica users

What are we going to do?

You will learn how to transform a Mathematica program (package) into an Add-on with the following characteristics:

1. It will be loaded using the Needs[] command, just like the built-in Mathematica Add-ons

2. Its documentation will appear in Mathematica's Help Browser

3. It will have a Palette in the Palettes menu of Mathematica.

Contents

Create a package that can be loaded with Needs[]

Mathematica's Add-ons must be placed in special directories (folders), either the $BaseDirectory or the $UserBaseDirectory. These directories are different in each computer. Evaluate $BaseDirectory in your Mathematica session, the actual result in your computer can be different from the one shown in the figure:

The new Mathematica Add-on will be placed inside the "Applications" subdirectory (folder) in the $BaseDirectory:

Write a Mathematica package in a text editor (Notepad):

Here you have the sample package, so that you can copy-paste to the text editor (Notepad):

BeginPackage["Plots`ThreeD`","Graphics`Graphics3D`"]

Plot3DwithContourPlot::usage=
"Plot3DwithContourPlot has the"<>
" same sintaxis as Plot3D";

Begin["`Private`"]

Plot3DwithContourPlot[f_, {x_,x0_,x1_}, {y_,y0_,y1_}, opts___Rule]:=
  ShadowPlot3D[f, {x,x0,x1}, {y,y0,y1}, opts, 
                  Lighting->False, ColorFunction->GrayLevel, 
                  ShadowMesh->False, SurfaceMesh->False, 
                  PlotPoints->100]
End[]
EndPackage[]

The first argument of the command BeginPackage is called Context, and it specifies the subdirectory and filename that the package must have, separated by a backquote and finishing with another backquote, see the following three figures below:

Create the subdirectory inside "Applications" and save there the package with the filename and the extension ".m". Remember that Mathematica is case sensitive, therefore if the context specified in the BeginPackage command is "Plots`ThreeD`" then the subdirectory must have the name Plots and the filename must be ThreeD.m, as you can see in the figure:

Warning: Be careful that the name does not become ThreeD.m.txt, otherwise it will not work. In order to be sure, set Windows to "show all the file extensions" in the "Folder Options" inside the "Tools" menu of the folder window.

If everything is alright, then you can load the package with the Needs["Plots`ThreeD`"] command, then see the new commands with the Names["Plots`ThreeD`*"] command  and use those new commands (in this example there is only one new command):

Now our package can be loaded with the Needs[] command, in the same way as the standard Mathematica Add-ons. In the following section we will create a help file for our package and we will include it in Mathematica's Help Browser.

Contents

Create package's documentation in Mathematica's Help Browser

Now we will create documentation for the package we just created, and we will include that documentation in Mathematica's help browser. In a new Mathematica file write a title, for example "Basic Example", and select the title cell with the mouse:

With the Cell selected, press the "Format" menu, "Style" submenu and select "Title" (It is important to have at leat one "Title"-style cell so that the documentation is correctly incorporated in Mathematica´s Help Browser):

Below the title cell write the commands for this basic example:

Inside the package directory (Plots) create another directory with name Documentation. Inside that directory create another directory with name English. Finally inside that inner directory save the Mathematica file with the name that you want. Remember that all this directory structure is inside the Applications subdirectory of the $BaseDirectory, as you can see in this image:

Open the "OpenAuthorTools" palette from the Palettes submenu of the File menu of Mathematica:

In the OpenAuthorTools palette select MakeProject. In the "Name of Project" field write Plots Documentation:

Select Pick a file. In the new window that opens find and select the documentation file that you saved. After that select the option Select all .nb files. Your screen must look similar to this figure:

Save the project. Save it in the same directory where you have the documentation and with a name that reminds you what it is. Mathematica will assign an extension ".m" to the project file:

Select "Browser Categories" in the "Project Actions" menu:

A file NewBrowserCategories.m is generated. Close the file:

The NewBrowserCategories.m must be placed in the same directory where you have the documentation. Rename the file to BrowserCategories.m:

There are the files that you must have in the Applications/Plots/Documentation/English path:

Close the two OpenAuthorTools palettes and the folder (exploration) window. Select "Rebuild Help Index" from the "Help" menu of Mathematica:

Our documentation will appear at the bottom of the Add-ons section of the Help Browser after rebuilding the help index:

Our documentation is inside the Add-ons section of Mathematica's Help Browser:

Now our package can be loaded with the Needs[] command and it has its documentation in the Help Browser, in the same way as the standard Mathematica Add-ons. We will also create a Palette for our package, but before that, we will review in the next section how do we have to update the documentation in the Help Browser.

Contents

Update the package's documentation in Mathematica's Help Browser

In order to make a change to the package's documentation, first delete the BrowserCategories.m file:

Open the documentation file, myDocu.nb, and make the changes. For example, add another Title cell and a more elaborated example. Save the modified documentation file:

Open the "OpenAuthorTools" palette from the Palettes submenu of the File menu of Mathematica:

In the OpenAuthorTools palette select MakeProject. In the "Name of Project" field write Plots Documentation:

Select Pick a file. In the new window that opens find and select the documentation file that you saved. After that select the option Select all .nb files. Your screen must look similar to this figure:

Save the project. Save it in the same directory where you have the documentation and with a name that reminds you what it is. Mathematica will assign an extension ".m" to the project file:

Select "Browser Categories" in the "Project Actions" menu:

A file NewBrowserCategories.m is generated. Close the file:

The NewBrowserCategories.m must be placed in the same directory where you have the documentation. Rename the file to BrowserCategories.m:

There are the files that you must have in the Applications/Plots/Documentation/English path:

Close the two OpenAuthorTools palettes and the folder (exploration) window. Select "Rebuild Help Index" from the "Help" menu of Mathematica:

Our updated documentation appears at the bottom of the Add-ons section of Mathematica's Help Browser:

Now our package can be loaded with the Needs[] command and it has its (updated) documentation in the Help Browser, in the same way as the standard Mathematica Add-ons. In the next section we will create a Palette for our package.

Contents

Create a Palette for the package and place it in the Palettes menu

Finally we will create a Palette for our package. In order for the Palette to appear in "Palettes" submenu of the "File" menu in Mathematica, it is necessary to place it in a special directory. Inside the package directory (Plots) create another directory with name FrontEnd (Remember that Mathematica is case-sensitive). Inside that directory create another directory with name Palettes. We will save the Palette inside that inner directory. Remember that all this directory structure is inside the Applications subdirectory of the $BaseDirectory, as you can see in this image:

In order to create the Palette open a new Mathematica notebook:

Select "Create Table/Matrix/Palette" from the "Input" menu:

Set the options for a Palette of 4 rows and 1 column and press OK:

A palette will appear embeded in the notebook. Write inside the palette the commands that you want the final user to be able to perform:

You can add empty spaces that will be filled by the final user if you press the keys [Esc]pl[Esc] and [Esc]spl[Esc]:

Now select the cell that contains the palette. Then select "Generate Palette from Selection" from the "File" menu of Mathematica:

The Palette will appear as a separated window. Try to close that window, Mathematica will ask if you want to save it:

Answer that you want to save the palette:

Save the palette with the name PlotsPalette in the Applications/Plots/FrontEnd/Palettes/ path that we created at the beginning of this section:

Exit Mathematica so that the new Palette is loaded in the "Palettes" submenu of the "File" menu of Mathematica. It is not necessary to save the notebook that has embeded the original version of the Palette:

Restart Mathematica. Now our Palette can be loaded from the "Palettes" submenu of the "File" menu of Mathematica:

Now you can use the Palette as any other built-in Mathematica palette:

Now your package can be loaded with the Needs[] command, it has its documentation in the Help Browser, and it has a Palette in the Palettes menu.

Contents

Distribute your Add-on to other Mathematica users

Now your package can be loaded with the Needs[] command, it has its documentation in the Help Browser, and it has a Palette in the Palettes menu. In order to distribute your package, you can compress the Plots directory and send it to other users with the instructions to uncompress it in the $BaseDirectory or in the $UserBaseDirectory and to "Rebuild the Help Index" after that.

Contents

Author: José Luis Gómez-Muñoz

jose.luis.gomez@itesm.mx

http://homepage.cem.itesm.mx/lgomez/

Contents