Usage Messages in Mathematica
- To: mathgroup at smc.vnet.net
- Subject: [mg129252] Usage Messages in Mathematica
- From: "djmpark" <djmpark at comcast.net>
- Date: Thu, 27 Dec 2012 05:04:47 -0500 (EST)
- Delivered-to: l-mathgroup@mail-archive0.wolfram.com
- Delivered-to: l-mathgroup@wolfram.com
- Delivered-to: mathgroup-newout@smc.vnet.net
- Delivered-to: mathgroup-newsend@smc.vnet.net
An extremely weak features of Mathematica is the design of Usage messages,
which seems to be stuck at Version 1, although the technology has moved far
beyond that.
The present design is not up to the task and full of gotchas. For example,
how does one include a box structure, for example a subscripted symbol,
within a usage message? If one just enters a subscript then the first time
the message is displayed there are quotes around it and the second time the
quotes go away. If one starts an InlineCell within the string and enters the
expression then that problem goes away. If one then moves the usage
definition to a package and Runs the package it works OK. But if one saves
and closes the package, quits the kernel and then reinitializes, loading the
package, the usage message is defective giving the InputForm of the box
expression. Mathematica parses and changes the usage messages when the file
is read.
The String form is just not adequate for usage messages. Nor is it adequate
to contain information on overloading functions. Usage definitions should be
expressions. Something like the following:
Usage[FunctionName] = {{template, usageExpression}..}
(The usageExpression might be a Row containing Strings and mathematical
expressions.)
Then Workbench would have all the information for constructing the Usage
cell at the top of Function pages and the Build process should have the
information to incorporate the command completion features - now lacking for
developers in Version 9.
Another present inadequacy is the use of SubValues, such as f[p][x,y] where
p might be a parameter and x,y are variables. This construction is extremely
useful. Alfred Gray used SubValues copiously in his Modern Differential
Geometry book. Workbench now truncates at the first pair of square brackets
on command completion. The specification of explicit templates might solve
that problem.
The potential to use Mathematica as a development, preservation,
documentation and communication medium is one of its greatest features, but
WRI has badly neglected this possibility and, as a result, discouraged such
use. Workbench is dormant and fraught with problems, for example not being
platform independent and not incorporating command completion features.
David Park
djmpark at comcast.net
http://home.comcast.net/~djmpark/index.html
- Follow-Ups:
- Re: Usage Messages in Mathematica
- From: Bob Hanlon <hanlonr357@gmail.com>
- Re: Usage Messages in Mathematica
- From: Murray Eisenberg <murray@math.umass.edu>
- Re: Usage Messages in Mathematica