MathGroup Archive 2005

[Date Index] [Thread Index] [Author Index]

Search the Archive

Re: books on writing packages

  • To: mathgroup at
  • Subject: [mg56659] Re: [mg56626] books on writing packages
  • From: "David Park" <djmp at>
  • Date: Mon, 2 May 2005 01:32:41 -0400 (EDT)
  • Sender: owner-wri-mathgroup at

Packages are pretty easy to write in Mathematica but there are several ways
of doing it.

I don't think there is one perfect book for learning to write packages but
the best book is probably 'Programming in Mathematica: Second Edition' by
Roman Maeder. The book is good on details, but is a bit old and doesn't
actually show the easy way to write a package.

The easiest way to write a package is to write an ordinary Mathematica
notebook with the package statements, BeginPackage etc., make the cells
Initialization cells (Select the whole notebook and use Ctrl C R I) and then
save the notebook. When you first save the notebook, Mathematica will ask if
you want to create an AutoSave Package. Answer yes. Then not only will the
notebook be saved, but the .m package notebook will also be created and
saved. From then on, every time you update and save the notebook the package
file will also be updated.

At the end of this email I have pasted a notebook expression for a toy
package. Copy the expression and paste it into an new empty notebook. Save
the resulting notebook into an appropriate folder and you will have the

The next question, often confusing to package writers, is where to put the
notebook and package. This also relates to how the BeginPackage statement is
written. There are a number of places it could be put, but the best place is
to evaluate:

$BaseDirectory or $UserBaseDirectory in Mathematica 5.0 or later.
($AddOnsDirectory in Version 4). The advantage of using this is that if you
update Mathematica, the update won't interfere with these folders so
everything gets carried over.

This will give you a folder and if you look in that folder you should find
an Applications folder. For our ToyPackage, you will then want to create an
Algebra folder in the Applications folder. And you want to put the package
in that Algebra folder. So you will have

	ToyPackage.m  (after you open and save ToyPackage.nb)

(The other places you could put packages are in the Wolfram files
ExtraPackages or Applications.)

Mathematica automatically looks in $BaseDirectory/Applications (and a few
other places also) when asked to load a package.

Notice that the package started with BeginPackage["Algebra`ToyPackage`"] and
the 'Algebra' in the statement corresponds to the Algebra folder that you
created. Obviously you could change both of these to any other name.

The package can then be loaded with




So that should get you started. Just substitute your own usage messages in
the outer part of the package, and write your own routine definitions in the
Private part of the package.

Now for advanced package engineering - documentation! The simplest method is
to write a tutorial notebook that could also be stored in the Algebra
folder. Many packages are poorly documented. Most of the standard packages
have only a single notebook in the Help Browser. If you have a really nifty
package, then it is worthwhile having nice documentation for it. The
documentation is as important as the package code. It is not at all
difficult to produce documentation for the Help Browser that will have Help
pages and examples for every command defined in the package. (If you're
clever you can also make examples in the Help notebook for each command that
test the principal uses of the command and thus this will also act as a
permanant test file.)

What you have to do is write notebooks in the HelpBrowser style for each
command. (The easiest way to do this is to take an existing Help notebook
and modify it.) Then you have to write a BrowserCategories.m file that will
tell Mathematica how to place your documentation files into the Help
browser. You can also write a BrowserIndex.nb notebook that contains the
command names for your package. This will place them in the MasterIndex
listing. Maybe your package also has a style sheet and palettes. All of
these can be incorporated in a folder structure as follows.

	  Individual Help notebooks for each command
	  Palettes/ any palatte notebooks you have
	  StyleSheets/ any style sheet notebooks you have

Once you have this you can just drag the Subject folder into a new zip file,
and send it to a user. They can just unzip the file into the Applications
folder, rebuild the Help Index and voila! they have your whole package
installed. The Help categories will be in the Help browser, the individual
Help pages will all be there, the palettes will appear in the Palettes
listing under File, and the style sheets will appear in the Style Sheet
listing under Format.

The ConicSections package at my web site below is a fairly small package.
You could download it and look at the folder structure, and modify the
BrowserCategories.m file to build your own browser categories. I don't know
if there is any description of the syntax of the BrowserCategories file but
it is fairly obvious by looking at one.

David Park
djmp at

From: marlinswin at [mailto:marlinswin at]
To: mathgroup at

I'd like to learn to write my own packages for both research and
teaching purposes. Is there any good books or references on package



Cell["A Toy Package", "Title"],

    \(BeginPackage["\<Algebra`ToyPackage`\>"]\)], "Input",

    \(\(Algebra`ToyPackage::usage = "\<This is a usage mesage for the \
entire package.\>";\)\)], "Input",

    \(\(SquareTheQuantity::usage = "\<SquareTheQuantity[x] will take \
the square of x.\>";\)\)], "Input",

    \(Begin["\<`Private`\>"]\)], "Input",

    \(SquareTheQuantity[x_] := x\^2\)], "Input",

    \(End[]\)], "Input",

    \(\(Protect[Evaluate[$Context <> "\<*\>"]];\)\)], "Input",

    \(EndPackage[]\)], "Input",
}, Open  ]]
FrontEndVersion->"5.0 for Microsoft Windows",
ScreenRectangle->{{0, 1280}, {0, 941}},
WindowSize->{494, 740},
WindowMargins->{{1, Automatic}, {Automatic, 1}}

  • Prev by Date: Re: [Newbie] Interpreting output
  • Next by Date: Re: ndsolve error message
  • Previous by thread: Re: Plot3D attempt.
  • Next by thread: Problems with eps format