Developing Packages and 
Notebooks in Version 3.0

Speaker

Richard Mercer
Wright State University

rmercer@wright.edu
http://seuss.math.wright.edu/Richard/

Packages

What is calcE?

Define[f[x]=Sin[x]]PlotE[Sin[x],{0,2 π},{-1,1},Tangents[{0,1,2,3,4,5,6},Dots,Length[1]]];

PlotE[{-1,1},Square,
	Disk[0.7,Lavender],
	Axes[Blue,Ticks[Major,Above,Right]],
	Axes[{-0.5,-0.5},{Red,Arrow,Right,Up}]
];

PlotE[{-3,4},Square,
	Lattice[{1,2},{-1,1},Red,Lines,Dots,Triangular]
];

PlotE[x^2,{-2,2},
Texts[{hi,-1},{ho,0},{he,1},Bold,Italic,24 Point,Red]];

The Development Environment

Develop your package in notebook form, with all the code in initialization cells.

Develop your package in the Global context; don't establish a separate context until you are ready to freeze your code. This allows you to edit a piece of code, and immediately execute and test it.

You only need two debugging tools -- Print[] and Abort[]

A good programmer is a tool builder! Try to develop low-level commands that make your life easier.

Example: ListMe

ListMe[item__]:= 
	If[ListQ[item],
		item,
		{item}
	];

Option Settings for development notebook

AutoGeneratedPackage->Automatic,
InitializationCellLoading->False,
TabSpacings->2,
CommonDefaultFormatTypes->{"Input"->InputForm}

Notes: 
AutoGeneratedPackage->Automatic will result in your package being automatically saved as a .m file as well as a .nb file each time you save.
InitializationCellLoading->False will prevent Mathematica from trying to execute ALL the initialization cells in your notebook the first time you execute one of them!
Formatting your code works best in InputForm; then the tabs work as expected. This is the purpose of the last two options.

Creating buttons and palettes: successes and failures

Here is a button that will select the cell group following it and begin animation. Select the cell containing the button and use Format/Show Expression to see how this button works. Note that this is the way to edit a ButtonFunction. (NEVER use the Edit Button... menu item!)

Animate

Where do you find front end tokens for use in buttons like this?! (e.g. "SelectionAnimate"). Until such things are documented, look in the following files:

SystemFiles/FrontEnd/TextResources/KeyEventTranslations.tr

SystemFiles/FrontEnd/TextResources/Macintosh/MenuSetup.tr

The Options Browser: Learn to Love It!

The Options browser is often the most practical way (available) to customize.

Stupid Options Browser Tricks

Turn off the startup sound!

GlobalOptions/SystemConfiguration/StartupSound->False

Remember those rectangles that showed the size of a cell group? Now you can have them back again!

CellOptions/DisplayOptions/ShowClosedCellArea->True

In version 3.0 the Options Browser is the only practical way to set page breaks.

How can I permanently turn off the In/Out labels, instead of having to turn them off in each notebook?

CellOptions/CellLabels/ShowCellLabel->False

How can I get Mathematica to show the timing of each executed input cell?

NotebookOptions/EvaluationOptions/EvaluationCompletionAction->"ShowTiming"

Change Palette Features

The options browser is the easiest way to format your palettes.

Notebooks

The following suggestions apply to notebooks you are preparing for distribution, commercial or otherwise. It is assumed you will want the notebooks to look good in both onscreen and printed form.

What NOT to do when writing notebooks.

Do NOT specify fonts without a very good reason!

Do NOT specify font sizes, even WITH a very good reason!

Reason: All font sizes will change when printed, EXCEPT for the places where you specified a font size! This will look really bad on the printed page.

MINIMIZE the use of pasted external graphics.

MINIMIZE the use of ad hoc stylistic variations
e.g. underlined, outlined, or shadowed fonts, colored text and background

Do NOT use private style sheets for your notebooks. 
Use a shared style sheet or sheets.

This assumes you are distributing several notebooks. If it's just one or two, a private style sheet is OK.

DO create your own custom style sheet(s), and create as many new styles as you need to cover recurring stylistic variations.

Using style sheets and creating your own styles.

It's easy! Just make a copy of the Default style sheet (or other of your choice), give it a new name, open it, and play around with it.

Suggestions for Style Sheets

Most cells should have the options 
PageWidth->WindowWidth
CellHorizontalScrolling->False

Except Printing cells should have 
PageWidth->PaperWidth

In my experience Style Environment Names don't always work. You may want to experiment with this.

The cell margins are VERY generous. You might want to trim them down.

How to "clean up" a notebook.

Notebooks converted from pre-3.0 versions, or otherwise messed up, may look OK onscreen but have many hidden problems you are better off fixing. Here are things you can do to fix some of the problems that can arise. Not all of these suggestions may be useful to you.

General

Use Kernel/Delete All Output menu item.

Use Format/Remove All Options... menu item. Click on OK (NOT on Recursive).

Specific

Select All and use Format/Show Expression menu item to convert the entire notebook into "Boxes" format. Search for the following items

FontSize: remove all or unneeded options of the form FontSize->_

FontColor: remove unneeded options of the form FontColor->_

FontFamily: remove all or unneeded options of the form FontFamily->_

FontVariations: Repair instances of options such as FontVariations->{"CompatibilityType"->"Superscript"} by deleting the old superscript or subscript and creating a proper superscript or subscript using 3.0 features.

FormBox or StyleBox: delete unneeded instances of the FormBox and StyleBox constructions. (This requires some experience and/or experimentation.)

PageWidth->Infinity

"\:" and "\." which mark untranslated special characters.

While in "Show Expression" format, scan for obvious problems and redundancies.

Here is an example of a cell as converted from 2.2 and typed in from scratch in 3.0. Look at both in "Show Expression" format to see the enormous internal differences.

Example: As converted

x = cos(t)     y = sin(t)           x2 + y2 = cos2(t) + sin2(t) = 1

Example: Typed in from scratch in 3.0

x = cos(t)     y = sin(t)          (x^2)+ (y^2) = (cos^2)(t)+(sin^2)(t)=1

Select All and use Format/Show Expression menu item again to return notebook to proper format.

Tips on displaying formulas.

You will find that making formulas look the way you want isn't always easy.

Tip #0: Understand the difference between Inline Formulas and Display Formulas.

Tip #1: When you find something that works, make it into a style (or modify an existing style).

Tip #2: Avoid TraditionalForm

Tip #3: Set Default Format Types BEFORE you start creating formulas.

Tip #4: Styles can be applied to selections within cells as well as to entire cells.

Tip #5: Change the value of the ScriptSizeMultiplier option (0.71) to something larger (like 0.86).

Tip #6: To make limits, sums, etc. have vertical form, use

FormattingOptions/ExpressionFormatting/SpecificBoxOptions/
UnderscriptBoxOptions/LimitsPositioning->False

Here are inline formulas containing a limit (lim_(x->0))((sin(x))/x) and a sum (∑_(i=0)^n)(i^2)

Select the inline cell with the limit, and use this option to place x->0 below "lim".

You can do similarly with the sum by instead using UnderoverscriptBoxOptions

Preparing Notebooks for Printing

Should you use separate notebooks for printing?

Ideally not; and version 3.0 has gone a long way toward making this unnecessary. However I find that I still have to use seperate notebook, for the following reasons:

(1) I want to include output, particularly graphics, in the printed version, but not in the notebooks that are distributed.

It was pointed out at the Developer Conference that one can use stylesheets to suppress the display of any cell style. However that trick is not applicable to this situation. I DO want output and graphics cells displayed in the notebooks I distribute (when the user executes a command), but I don't want any of those cells included in the distributed version.

(2) I want to change color text to black for printing.

This would be much easier to fix. What you need is a printing option with two settings, color and monochrome. When set to monochrome, all FontColor options would be ignored.

The following is my list of steps to take. Many of them will not be relevant in your case.

Remove .nb extension from filename (Mac only?)

Set Format/Screen Style Environment menu item to "Printout".

Scan for color text and reset to black.

This is not always so easy. Here are three ways to do it:

Select the cell containing the color text and use the Format/Remove All Options menu item. Click on Recursive. This will (usually) remove color text but may have undesired side effects.

Select the color text, and use the Format/Text Color menu item to select Black. Believe it or not this doesn't always work either. But it works most of the time and is safest.

Select the cell and use the Format/Show Expression menu item. Manually remove all FontColor options. This always works but is labor intensive.

Hide In/Out Names

Execute commands to create output

Resize graphics as needed.

In Printing Settings/Headers and Footers, set the starting page number and left/right printing.

Select Format/Show Page Breaks menu item

Use the options inspector under Cell/Page Breaking to repair poorly placed page breaks.

Scan one last time for visually obvious problems.

Proofread the result before sending it to the printer!

Preparing Notebooks for Distribution

Check CharacterEncoding option; set to Automatic.

I have had  problems with this option being set to "MacintoshAutomaticEncoding", which I believe/guess was a default generated under version 3.0.0. This did not work well under Windows!. This will presumably only be a problem if your notebooks were converted or begun on a Macintosh before version 3.0.1.

Check ScriptSizeMultipliers option.

Set to 0.86 or your preference. Default value does not work well for on-screen display.

Set ShortBoxForm option to False.

This prevents a particularly nasty bug from occuring, which results when the contents of notebook are saved in the "shorthand" form (the one with lots of backslashes). In some isolated cases this shorthand form has ambiguities, and the notebook will change when it is closed and reopened and the shorthand is interpreted.

An example of what could happen.

(∫_( a)^x)f(t)dt

When the notebook is saved and reopened, under some circumstances this will mutate to:

(∫_( a)^xf)(t)dt

I have not duplicated those circumstances in this notebook. If I had, the first integral. would look like the second one!

At the Developers Conference, it was announced that all such occurences should be eliminated by version 3.2. In the meanwhile, set  ShortBoxForm -> False! Not only globally, but at the notebook level in each notebook you distribute, since your users will not have made this global option change.

Set ShowGroupOpenCloseIcon option to True.

Makes the little triangles on the left. A no-brainer -- nothing to lose.

Some Needed Improvements

A few requests for improvements to Mathematica relevant to the subject of this presentation. If you agree with any of these, you may want to let WRI know.

Provide the option to automatically abort after a certain total number of  error messages

When you write a complex package, even the smallest bug in your program tends to produce an infinite cascade of error messages. It would be highly desirable for developers (and users) to be able to automatically terminate execution in this situation.

Allow separate values of ScriptSizeMultipliers for sub-super-scripts and for fractions.

I want to have different behavior for fractions than for subscripts and superscripts. I would like to have a seperate option for each box type.

Give us True Tabs!

The NUMBER ONE obstacle to using Mathematica as a technical word processor is the lack of true tabs, by which I mean left, right, center and decimal tabs (plus margins) which can be dropped at any point, just as with any word processor available today. If these were available (presumably implemented as cell-level options as well as interactively through the toolbar), you could do real word processing, and it would make style sheets even more powerful.

What other features do you think are needed to achieve real mathematical word processing?

Make it easier to align buttons in palettes

As far as I can tell this is a Black Art. If there is some trick to it, I'd like to know. But it shouldn't even be a trick: it should be a simple option.

Make palettes easier to program

The language constructs available for programming palettes are not adequate. Try, for example, to program a palette to modify itself when a button is pushed. I'm sure it can be done, but I'm equally sure it's much harder than it ought to be.

Better Documentation!