Re: Best practice for Mathematica package development
- To: mathgroup at smc.vnet.net
- Subject: [mg77403] Re: Best practice for Mathematica package development
- From: Andrew Moylan <andrew.j.moylan at gmail.com>
- Date: Thu, 7 Jun 2007 06:32:08 -0400 (EDT)
- References: <f43e7d$mv$1@smc.vnet.net><f463fn$p7k$1@smc.vnet.net>
* The usage strings for built-in functions for Plot use boxes and look
nice (see the copy-and-paste of Plot::usage, below). By contrast,
custom packages that I have seen use plain-text usage strings. What's
an easy way to create and maintain nice-looking usage strings (that
use boxes)?
Plot::"usage" // InputForm
"\!\(\*RowBox[{\"Plot\", \"[\", \
RowBox[{StyleBox[\"f\", \"TI\"], \",\", \
RowBox[{\"{\", RowBox[{StyleBox[\"x\", \"TI\"], \
\",\", SubscriptBox[StyleBox[\"x\", \"TI\"], \
StyleBox[\"min\", \"TI\"]], \",\", \
SubscriptBox[StyleBox[\"x\", \"TI\"], \
StyleBox[\"max\", \"TI\"]]}], \"}\"}]}], \"]\"}]\) \
generates a plot of \!\(\*StyleBox[\"f\", \"TI\"]\) \
as a function of \!\(\*StyleBox[\"x\", \"TI\"]\) \
from \!\(\*SubscriptBox[StyleBox[\"x\", \"TI\"], \
StyleBox[\"min\", \"TI\"]]\) to \
\!\(\*SubscriptBox[StyleBox[\"x\", \"TI\"], \
StyleBox[\"max\", \"TI\"]]\). \
\n\!\(\*RowBox[{\"Plot\", \"[\", \
RowBox[{RowBox[{\"{\", \
RowBox[{SubscriptBox[StyleBox[\"f\", \"TI\"], \
StyleBox[\"1\", \"TR\"]], \",\", \
SubscriptBox[StyleBox[\"f\", \"TI\"], \
StyleBox[\"2\", \"TR\"]], \",\", StyleBox[\"\[Ellipsis]\", \
\"TR\"]}], \"}\"}], \",\", RowBox[{\"{\", \
RowBox[{StyleBox[\"x\", \"TI\"], \",\", \
SubscriptBox[StyleBox[\"x\", \"TI\"], \
StyleBox[\"min\", \"TI\"]], \",\", \
SubscriptBox[StyleBox[\"x\", \"TI\"], \
StyleBox[\"max\", \"TI\"]]}], \"}\"}]}], \"]\"}]\) \
plots several functions \
\!\(\*SubscriptBox[StyleBox[\"f\", \"TI\"], \
StyleBox[\"i\", \"TI\"]]\). "
On Jun 6, 8:49 pm, Andrew Moylan <andrew.j.moy... at gmail.com> wrote:
> To elaborate a little more, some of the other particular topics (aside
> from those mentioned in my original post) for which I am interested in
> best practises are:
>
> * layout of .m files in package directories, and why;
>
> * testing (use Eclipse's built-in testing stuff? a separate
> Mathematica notebook? why?);
>
> * uniqueness of exported symbol names (i.e., has this old question
> been resolved satisfactorily yet:http://groups.google.com/group/comp.soft-sys.math.mathematica/browse_...
>
> * long function definitions with (*comments*) inside them versus many
> smaller function definitions with (*comments*) between them; and
>
> * standards for features new to Mathematica 6, like syntax colouring.
>
> On Jun 5, 8:34 pm, Andrew Moylan <andrew.j.moy... at gmail.com> wrote:
>
> > What are the best standards and practices to follow when developing
> > serious Mathematica packages that are intended for many people to use?
> > Is there a handy guide, and/or template .m files, that can be used by
> > prospective package developers?
>
> > In the past I have made packages by allowing Mathematica to
> > automatically generate .m files from a notebook containing the
> > relevant definitions in initialization cells. With the advent of
> > Workbench, I assume this is no longer the best method.
>
> > I am interested in best practices related to managing options,
> > contexts, warnings and errors, interfaces in general, etc. Is there a
> > list of standards adhered to when WRI designs packages?
>
> > Of course I can often see how others have designed packages by reading
> > the .m files in their packages. Are all well-known packages as well-
> > designed as each another? Can anyone recommend a particular package as
> > a good example of how to write packages well?