How to Create a Mathematica 6.0 Add-On with Documentation in the "Documentation Center" (Help Menu) and Palette in the "Palettes" Menu

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

Contents

Create a package that can be loaded with Needs[ ]

Create package's documentation in Mathematica's "Documentation Center" (Help Menu)

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

Distribute your Add-on to other Mathematica users

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 $UserBaseDirectory in your Mathematica session, the actual result in your computer will be different from the one shown:

$UserBaseDirectory

The new Mathematica Add-on will be placed inside the "Applications" subdirectory (folder) in the $UserBaseDirectory (remember that in your computer it will be a different directory, the one that you obtain from evaluating $UserBaseDirectory in your computer):

Write a Mathematica package. You can do that in Mathematica ("File" Menu, "New" option, "Package" option):

Here is the sample package that will be used in the rest of this document:

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

BeginPackage["Plots`TwoD`"]

PlotColor::usage=
"PlotColor has the same sintaxis as Plot"<>
" and you can change the color in real time";

Begin["`Private`"]

PlotColor[f_, {x_,x1_,x2_}, opts___Rule]:=
 Manipulate[
 	Plot[f,{x,x1,x2},PlotStyle->Hue[c],opts],
 {{c,0.8,"Color"},0,1}];
 
End[]
EndPackage[]

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

Create the subdirectory Plots inside Applications and save there the package with the filename TwoD and the extension .m. Remember that Mathematica is case sensitive:

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

Needs["Plots`TwoD`"];
Names["Plots`TwoD`*"]

? PlotColor

PlotColor[Sin[x],{x,0,6}]

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 "Documentation Center" (Help Menu).

Contents

Create package's documentation in Mathematica's "Documentation Center" (Help Menu).

Now we will create documentation for the package we just created, and we will include that documentation in Mathematica's "Documentation Center" (Help Menu). In a new Mathematica file (notebook) 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":

Below the title cell write other cells with 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. Inside that directory create another directory with name Guides. Finally inside that inner directory save the Mathematica file with the name PlotsDocumentation.nb. Remember that all this directory structure is inside the Applications subdirectory of the $UserBaseDirectory, as you can see in this image:

Create another file with the format of a package ("File" Menu, "New" option, "Package" option):

Write the following text inside that new file the following text:

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

(* Paclet Info File *)
Paclet[
     Name -> "Plots",
     Version -> "1.0.0",
     MathematicaVersion -> "",
     Description -> "",
     Extensions -> 
          {
               {"Documentation", Language -> "English", 
    					LinkBase -> "PlotsDocumentation",
                		Resources -> {"Guides/PlotsDocumentation"}                
    			}
           }
 ]

Now save the new file with the name PacletInfo.m in the main (outer) directory of the package, the directory Plots:

Close the files PlotsDocumentation.nb and PacletInfo.m
If everything is alright, then your documentation must be already accesible from the "Documentation Center" (Help menu).
Open Mathematica's "Documentation Center" in the Help menu:

Go to the lower-right corner of the "Documentation Center" main page (you might have to scroll-down with the mouse) and select the option Installed Add-ons:

The link to your documentation must be appear in the next "Documentation Center" page:

Click in the link and your documentation must open inside the "Documentation Center":

Now our package can be loaded with the Needs[ ] command and it has its documentation in the Documentation Center, 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" 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:

The following commands create a palette for this package. 
Remember that Mathematica is very strict with sintaxis, for example you cannot replace the backquote ` with the quote  '
The selection place holder □ can be entered by pressing the keys [ESC]pl[ESC]
For the moment, the palette is stored in the variable mypalette:

mypalette=
CreatePalette[
{Button["Needs[\"Plots`TwoD`\"]",NotebookWrite[InputNotebook[],"Needs[\"Plots`TwoD`\"]"],Appearance->"Palette"],
Button["Names[\"Plots`TwoD`*\"]",NotebookWrite[InputNotebook[],"Names[\"Plots`TwoD`*\"]"],Appearance->"Palette"],
Button["PlotColor[Sin[x],{x,0,2Pi}]",NotebookWrite[InputNotebook[],"PlotColor[Sin[x],{x,0,2Pi}]"],Appearance->"Palette"],
Button["PlotColor[\[Placeholder],{\[Placeholder],\[Placeholder],\[Placeholder]}]",NotebookWrite[InputNotebook[],"PlotColor[\[Placeholder],{\[Placeholder],\[Placeholder],\[Placeholder]}]"],Appearance->"Palette"]
},  WindowTitle-> "Plots Palette", WindowMargins->Automatic,Magnification->1.5]

The palette looks like this:

Next we save the palette in the proper directory:

NotebookSave[mypalette,ToFileName[{$UserBaseDirectory,"Applications","Plots","FrontEnd","Palettes"},"PlotsPalette.nb"]]

Verify that the palette was saved in the correct place:

Close the palette:

Exit Mathematica in order to have the Palettes menu updated:

Enter Mathematica again. The palette will be listed in the Palettes menu. Click to open it:

The palette opens:

You can use the palette now. REMEMBER THAT THE PACKAGE MUST BE LOADED (Needs) BEFORE ANY OF ITS COMMANDS (PlotColor) IS USED, otherwise a new variable PlotColor will be created that will create conflicts (shadowing) with the PlotColor from the package

Needs["Plots`TwoD`"]

Names["Plots`TwoD`*"]

?PlotColor

PlotColor[Sin[x],{x,0,2Pi}]

Now your package can be loaded with the Needs[] command, it has its documentation in the Documentation Center, 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 Documentation Center, 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. See for example the instalation instrucctions of this package for doing Quantum Mechanics calculations in Dirac notation in Mathematica:  http://homepage.cem.itesm.mx/lgomez/quantum/

Contents

Author

José Luis Gómez-Muñoz

jose.luis.gomez@itesm.mx

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

Contents