Usage Messages Have Become a High Tech Kludge
- To: mathgroup at smc.vnet.net
- Subject: [mg103813] Usage Messages Have Become a High Tech Kludge
- From: "David Park" <djmpark at comcast.net>
- Date: Wed, 7 Oct 2009 07:02:58 -0400 (EDT)
In my opinion the usage message processing is poorly designed and ever since
Version 6 the problems have increased.
Of course, part of the reason for this is their added functionally with
Workbench/DocuTools. This not only makes a fairly good attempt to set up the
Function page from the usage message and function definitions, but when the
documentation is built it adds the quite useful link to the Function page at
the end of the usage message.
But I think there are serious problems and deficiencies in design.
1) For many of us the font size in usage messages is too small and, worse,
non-adjustable. Most cells can be magnified by using Alt - +. This does not
work for displayed usage messages. I did try changing the FontSize for "MSG"
in my style sheet but that didn't work either. Magnifying the entire
notebook is an option but a local solution would be much better.
2) Usage messages do not allow subvalues in the function definitions.
Subvalues are very useful and some writers use them all the time. For
example, Alfred Gray in "Modern Differential Geometry" made extensive use of
them.
For example:
catenary::usage =
"catenary[a][t] is the curve formed by a perfectly flexible \
inextensible chain of uniform density hanging from two supports.";
catenary[a_][t_] := {a Cosh[t/a], t}
If we use command completion on this, the "[t]" portion is dropped off and
is not part of the template. Similarly, when Workbench/DocuTools generates a
Function page Usage cell it splits off the "[t]" and makes it a part of the
descriptive text. I don't see any good reason why the internal Mathematica
processing couldn't pick off the successive contiguous "[.]" expressions and
process them to make them part of the template. If it can process one it
should be able to process any finite set.
3) Neither does command completion work properly if the function name begins
with a Greek letter (or any other palette character). Example:
\[Alpha]foo::usage = "\[Alpha]foo[x] is a function";
Try command completion.
4) It is not at all clear how to design or input usage messages if they are
very long or if we want them to contain box style Mathematica expressions.
Another example from Alfred Gray:
cissoid::usage =
"cissoid[a][t] is an ivy-shaped curve whose implicit equation is \
x^2 + x y^2 - 2 a y^2 == 0";
cissoid[a_][t_] := 2 a t^2 {1/(1 + t^2), t/(1 + t^2)}
That works passably, but suppose we want the equation in the usage message
to be formatted with superscript powers. Then we might try:
cissoid::usage =
ToString[Row[{"cissoid[a][t]",
" is an ivy-shaped curve whose implicit equation is ",
x^2 + x y^2 - 2 a y^2 == 0}], StandardForm];
cissoid[a_][t_] := 2 a t^2 {1/(1 + t^2), t/(1 + t^2)}
?cissoid
That works well, but now try command completion on cissoid (Ctrl-Shirt-K). I
would hate to see what it might look like on a Function page!
There is also a problem if we copy usage expressions into a package and they
get "\" characters inserted. They must all be taken out else they will make
line returns in the displayed usage message.
5) The main problems with usage messages is that they demand definition as a
String and the template processing is pretty shoddy. The String requirement
must just be a relic from Version 1. Why not redesign usage messages to be
defined as a Row construction? The first argument could, by definition,
define the template. It could either be a String (but one that allowed
subvalues) or, even better, there might be a special form for templates.
(There is an experimental InterpretTemplate function but WRI tells us
nothing about it.)
David Park
djmpark at comcast.net
<http://home.comcast.net/~djmpark> http://home.comcast.net/~djmpark/