22
$\begingroup$

Why are the messages almost always defined like this (at least in packages):

If[Not@ValueQ[function::usage], function::usage = "Usage message"]

and not just like this?

function::usage = "Usage message";

Is this some sort of safety measure in case of double loading of the package?
I also notice that error messages, coming after usage messages, are usually defined the second way.
I cannot imagine a reason why I would do that.
Are there situations when someone would like to import a package, redefine some usage messages and be sure they are not reset in case of reloading of the package?

Improve this question
$\endgroup$
  • $\begingroup$ You do not need to do this when writing your own packages. It is a hack to have formatted (and I suppose localised) messages for standard packages. $\endgroup$ – Szabolcs Mar 22 '13 at 14:57
  • $\begingroup$ I use Mathematica 10.3 and I need to do If[Not@ValueQ[function::usage] construct, otherwise I get error messages. $\endgroup$ – Bob Ueland Apr 25 '19 at 7:16
28
$\begingroup$

If you look carefully, you'll notice that the usage messages of package functions are nicely formatted.

Mathematica graphics

Notice the nice italicised and subscripted $x_1$. If you actually look in the package, you'll find a usage message that doesn't have any formatting at all, and even differs from the version ?DelaunayTriangulation gives us.

If[Not@ValueQ[DelaunayTriangulation::usage],DelaunayTriangulation::usage =
"DelaunayTriangulation[{{x1,y1},{x2,y2},...,{xn,yn}}] yields the (planar) \
Delaunay triangulation of the points. The triangulation is represented as a \
vertex adjacency list, one entry for each unique point in the original \
coordinate list indicating the adjacent vertices in counterclockwise order."];

So where did the formatting come from? It turns out that Mathematica includes an alternate set of usage messages defined elsewhere. These are nicely formatted. The Not@ValueQ[...] is there to prevent the nicely formatted messages from being overwritten by the package.

The file that contains the formatted messages is located at 

$InstallationDirectory/SystemFiles/Kernel/TextResources/English/Usage.m

Use

FileNameJoin[{$InstallationDirectory,
  "SystemFiles", "Kernel", "TextResources", "English", "Usage.m"}]

to get an absolute path from Mathematica.

Regrettably, it seems some errors have slipped in and sometimes the formatted messages contain less information than the original ones... just like in the example above.

Improve this answer
$\endgroup$
  • $\begingroup$ I didn't know about that, +1! I only used the ValueQ method to inject new info to existing messages, for example when using built-in symbols for option names in own package. $\endgroup$ – István Zachar Mar 22 '13 at 15:17
  • $\begingroup$ I wonder why there is an unformatted form of the usage string stored in the package. In wich case will Mathematica use them? I recognized that in documentation center the unformatted usages are displayed, but i wonder where they come from. The question seems to be what is loaded first, the formatted usage or the unformatted one? $\endgroup$ – sacratus Apr 8 '15 at 17:56
  • $\begingroup$ @sacratus I don't know. My arbitrary guess is that when the package is being developed, they just use the usual way to do it. When Mathematica is ready for polishing and release, someone else than the developer goes through the messages and creates formatted versions. And maybe translations for other language versions. $\endgroup$ – Szabolcs Apr 8 '15 at 18:01
  • $\begingroup$ that might be a good explanation. I found out, that the summary that can be seen on a reference page of a symbol with CurrentValue[ EvaluationNotebook[], {TaggingRules, "Metadata", "summary"}] is an unformatted form of the formated usage string. Its actually not the original usagestring stored in the package. Its seems they are never used again after developing. $\endgroup$ – sacratus Apr 8 '15 at 18:10

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.