Re: books on writing packages
- To: mathgroup at smc.vnet.net
- Subject: [mg56659] Re: [mg56626] books on writing packages
- From: "David Park" <djmp at earthlink.net>
- Date: Mon, 2 May 2005 01:32:41 -0400 (EDT)
- Sender: owner-wri-mathgroup at wolfram.com
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 package. 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 $BaseDirectory/Applications/Algebra/ ToyPackage.nb 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 Needs["Algebra`ToyPackage"] or <<Algebra`ToyPackage` 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. $BaseDirectory/Applications/Subject/ YourPackage.nb YourPackage.m Documentation/English/ BrowserCategories.m BrowserIndex.m Individual Help notebooks for each command FrontEnd/ 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 earthlink.net http://home.earthlink.net/~djmp/ From: marlinswin at gmail.com [mailto:marlinswin at gmail.com] To: mathgroup at smc.vnet.net 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 authoring? Thanks. **************************************************************************** Notebook[{ Cell[CellGroupData[{ Cell["A Toy Package", "Title"], Cell[BoxData[ \(BeginPackage["\<Algebra`ToyPackage`\>"]\)], "Input", InitializationCell->True], Cell[BoxData[ \(\(Algebra`ToyPackage::usage = "\<This is a usage mesage for the \ entire package.\>";\)\)], "Input", InitializationCell->True], Cell[BoxData[ \(\(SquareTheQuantity::usage = "\<SquareTheQuantity[x] will take \ the square of x.\>";\)\)], "Input", InitializationCell->True], Cell[BoxData[ \(Begin["\<`Private`\>"]\)], "Input", InitializationCell->True], Cell[BoxData[ \(SquareTheQuantity[x_] := x\^2\)], "Input", InitializationCell->True], Cell[BoxData[ \(End[]\)], "Input", InitializationCell->True], Cell[BoxData[ \(\(Protect[Evaluate[$Context <> "\<*\>"]];\)\)], "Input", InitializationCell->True], Cell[BoxData[ \(EndPackage[]\)], "Input", InitializationCell->True] }, Open ]] }, FrontEndVersion->"5.0 for Microsoft Windows", ScreenRectangle->{{0, 1280}, {0, 941}}, AutoGeneratedPackage->Automatic, WindowSize->{494, 740}, WindowMargins->{{1, Automatic}, {Automatic, 1}} ]
- Follow-Ups:
- Problems with eps format
- From: Ted Sariyski <tsariysk@craft-tech.com>
- Problems with eps format