22
$\begingroup$

I'm writing an own package with Mathematica, that I would like to make available for others. In order to do that (and for my own usage of the package), I would like to write ::usage-strings for all my public functions.

I would like to use a formated string for ::usage in order to refer to some mathematical background in the explanations, e.g. if one of the inputs is a matrix, the ::usage may contain $\mathbf{M}\in\mathbb Z^{d\times d}$ or something like that.

The way I'm generating these up to now is, to take a cell and change it's style to text, then write the text and copy it into the ::usage="..." cell of the package. On saving the package, that gets transformed into the classic commands, like in the following example:

DirichletKernel::usage = "DirichletKernel[\!\(\*StyleBox[\"mM\",\nFontWeight->\"Bold\"]\)]    
  provides a dirichlet kernel with respect to the regular integral matrix mM
  in Fourier coefficients. The same options as for the function \!\(\*
  StyleBox[\"deLaValleePoussinKernel\", \"Code\"]\)\!\(\*
  StyleBox[\"[\", \"Code\"]\)\!\(\*StyleBox[\"]\", \"Code\"]\) apply.";

Where the last part at least seems a little messed up.

There are two questions arising:

1) Is there an easier way to write such a usage message? because if I want to change something, I usually have to write the whole text again, because the format is quite verbose. What workflow do you use to write ::usage messages?

2) Sometimes the copy&paste stuff generates errors (hmpf, if you want to demonstrate something, of course, it works, I'll edit this, if I can get the actual message), that occur in the message window. Since Mathematica 9 that already happens if the autocomplete-box occurs. So what has to be taken into account copying formated cells (text with math formula and e.g. bold face and code parts) into strings - in order to not get messed up (erroneous) strings?

|improve this question
$\endgroup$
  • 2
    $\begingroup$ not sure, but I think this is at least related: mathematica.stackexchange.com/q/3941/169 $\endgroup$ – Albert Retey Dec 17 '12 at 11:23
  • $\begingroup$ Though I'm not using Workbench, the hint, that nonescaped quotes mess things up, is quite helpful :) $\endgroup$ – Ronny Dec 17 '12 at 11:53
  • $\begingroup$ Oh, thanks for the hint. I think I'll rework some of the naming, because i have several functions starting with Upper case letters. For DirichletKernel[] at least, the reason is, that Dirichlet is a personal name, so i would always tend to write that upper case; where for example for de La Vallée Poussin it's mere chance, that that's not starting upper case...; for my other functions you're right, i should rework some. $\endgroup$ – Ronny Dec 17 '12 at 15:48
  • 1
    $\begingroup$ @Nasser i just checked some other packages (non standard Mathematica but from the Library online) and many delevopers use functions starting with capital letters, e.g. IntegerSmithForm. I don't know, which would be better Mathematica Programming Practice... $\endgroup$ – Ronny Jan 4 '13 at 9:46
  • 1
    $\begingroup$ I still consider the question little unanswered. Would like to get see comments on how to step and format short comments on the available options such that they would look nice when using ? etc. $\endgroup$ – Johu Jun 18 '14 at 13:47
10
$\begingroup$

In Mathematica, usage messages are typically for conveying a short description of how to call the function. Your text that talks about the options would be better placed in package documentation in the Details section. You can use Wolfram Workbench to generate package documentation that shows up in the Documentation Center.

|improve this answer
$\endgroup$
  • $\begingroup$ Workbench includes a set of documentation build tools that compile the source documentation notebooks into something that has the right look and feel for the documentation center, and adds to the help index as well. Not sure how hard it would be to duplicate this functionality a different way. $\endgroup$ – Joel Klein Dec 18 '12 at 0:46
  • $\begingroup$ Of course, writing a complete Documentation would be realy nice. I red some questions here about writing an own Documentation page, and that seemed very complicated (at least prior to Mathematica 9) for me. And I haven't used WB up to now. $\endgroup$ – Ronny Dec 18 '12 at 6:14
  • 1
    $\begingroup$ There are a lot of nice screencasts for Workbench to show you how to do things. This one is for doc builds: wolfram.com/broadcast/screencasts/workbench/documentation $\endgroup$ – Joel Klein Dec 18 '12 at 6:53
  • $\begingroup$ Though both other answers were great, too, I think this one fits best, due to the idea to use Workbench for the documentation and the link to the Screencast in the links. $\endgroup$ – Ronny Dec 21 '12 at 12:24
12
$\begingroup$

First, I want to say that I don't like heavily formatted usages messages. A usage message should be a short description in a form of a simple ascii message, so that it can be viewed even without a front-end.

Nevertheless, let me try to give you a hint here. I would do the following:

  1. write your usage messages in a separate package-notebook in the Mathematica front-end, where you can look at it as formatted text and not as string-expression.
  2. store this notebook as package Usage.m side by side to your implementation package.
  3. load this package in the Kernel/init.m of you package.

1. Package notebook

When you use the Mathematica front-end for editing, you can input any special box form without caring about the underlying, complicated string-expression.

enter image description here

2. Store the package

After you saved the package, it is stored on disk as

(* ::Package:: *)

BeginPackage["YourContext`"];
f::usage="f[x] calculates \!\(\*SubsuperscriptBox[\(\[Integral]\), \(min\),\
  \(max\)]\)f[x]\[DifferentialD]x."
EndPackage[];

but you don't have to care about it, because 1. you never see this in e.g. the Wolfram Workbench because your implementation is in another file and 2. you edit this package always in the front-end.

3. Loading the usages

Just load this in the init.m. It's probably the best, when you look how it is done in the VectorFieldPlots package in the AddOns/Packages path. Their init.m looks like

(* initialization file for the vector field plots package VectorFieldPlots` *)

Get["VectorFieldPlots`Usage`"];
Get["VectorFieldPlots`VectorFieldPlots`"];
Get["VectorFieldPlots`VectorFieldPlots3D`"];

and the file structure is

imagem

|improve this answer
$\endgroup$
  • $\begingroup$ That's a neat idea, because now I'm storing it in the package-m File and it sometimes gets messed up due to missing escaped ". And you're right, of course it should not be overloaded with formated stuff. I was thinking about emphazising (in italics) parameters, bold face matrices and vectors and perhaps very small explaining formulae as the one you used in your example. I'll try your approach these days, but it sounds quite nice. $\endgroup$ – Ronny Dec 18 '12 at 13:19
  • $\begingroup$ Do you know if it is possible to write two separate ::usage messages: one if the front end is present, and another if it is not? $\endgroup$ – QuantumDot Jul 28 '17 at 4:17
  • $\begingroup$ @QuantumDot I'm sure you could do something like testing if e.g. the $FrontEnd variable has a value and then attach the correction version of your usage message, but I never used something like this. $\endgroup$ – halirutan♦ Jul 28 '17 at 5:11
  • $\begingroup$ @QuantumDot I think the classic thing would be to define the alternates in a If[$Notebooks, FE present usages, FE not present usages ] block $\endgroup$ – b3m2a1 Aug 4 '17 at 0:28
  • $\begingroup$ @halirutan, Yes I took your advice and converted my whole package so that it is command-line ready. If it is loaded without an interface, then I have plaintext usages, and otherwise use formatted text. Eventually, I am planning to transition over to the IntelliJ Mathematica environment; have you tried it before? $\endgroup$ – QuantumDot Aug 4 '17 at 0:34
6
$\begingroup$

My advice is to keep things like this as simple as possible. I have found that copying the official documentation is adequate and generates few (... no) error messages.

With v8, there appears to be a newer WRI style. Before this, usages were written

function::usage = "function[arguments, options] does ...";

An example of this form can be found in 

ToFileName[{$AddOnsDirectory, AddOns, ExtraPackages, Utilities}, CleanSlate.m]

From v8 onwards, the style seems to have changed to 

If[!ValueQ[function::usage],
 function::usage = "function[arguments, options] does ..."
];

An example of this form can be found in 

ToFileName[{$AddOnsDirectory, AddOns, Packages, ANOVA}, ANOVA.m]

I have found no practical difference between the two versions, but your kilometerage may vary.

|improve this answer
$\endgroup$
  • $\begingroup$ What's the difference when using the second? Is there an advantage? $\endgroup$ – Ronny Dec 17 '12 at 11:08
  • $\begingroup$ @Ronny, I defer this question to experts. However, I have not noticed any difference between the two versions, either in performance or functionality. $\endgroup$ – dwa Dec 17 '12 at 13:27
  • $\begingroup$ Have you seen this? $\endgroup$ – J. M. is away♦ Apr 15 '13 at 17:32
  • $\begingroup$ @J.M. Interdasting! $\endgroup$ – dwa Apr 16 '13 at 8:11
  • $\begingroup$ I believe it is !ValueQ[function::usage]. Otherwise it does not make sense. $\endgroup$ – JEM_Mosig Aug 3 '17 at 21:16

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.