5
$\begingroup$

This probably has an easy answer but I can't work it out. In Mathematica's documentation, the ::usage message has some text formatting for expr. In the documentation this formatting is ommitted. I am looking to understand if this is something that can be done manually or only through package development via the Workbench?

enter image description here

$\endgroup$

2 Answers 2

4
$\begingroup$

The SetUsage function is what you need. Give it a plain text string and it will create the usage message containing the various italics and other formatting niceties:

GeneralUtilities`SetUsage["MyFunction[m$] does interesting things with the input m$.
MyFunction[m$,{s$1,s$2,$$}] does even more interesting things with m$ and all of the \
various s$i."];

enter image description here

There is plenty of documentation for this function, just ask for it with

?GeneralUtilities`SetUsage
$\endgroup$
6
  • $\begingroup$ Hi, thanks for the answer. I probably need to edit the question to make it clearer but I don't mean "what's the documentation for Head but rather, how can I get the documentation of my own package function through its ::usage definition, to show the argument in italics without having a bunch of TextBoxes and StyleBoxes $\endgroup$
    – gpap
    Apr 3 at 20:26
  • 3
    $\begingroup$ @gpap - I am giving you the (humorous) one-raised-eyebrow squint because I think you missed the point. I will use a different example. $\endgroup$
    – Jason B.
    Apr 3 at 20:30
  • $\begingroup$ Ach, I see, I did totally miss the point (+1 btw) - earned the raised eyebrow! But now I am even more puzzled. How can I use this in my package if this just sets the usage message until the package is reloaded? Like how can I access the "source" code for the usage message? $\endgroup$
    – gpap
    Apr 3 at 21:03
  • $\begingroup$ @gpap - the way I see this function being used in packages is that instead of writing MyFunction::usage = .... in your package file, you put the GeneralUtilities`SetUsage["... command in its place. This introduces a loadtime dependency on the general utilities package for what its worth. $\endgroup$
    – Jason B.
    Apr 3 at 21:37
  • $\begingroup$ this is a good solution then! It maintains human-readability and renders the pretty documentation (I am not bothered about the loadtime dependency that much but the human-readable aspect of the package is important). I will give it a few more hours before accepting. Thanks for the help and sorry for being dim $\endgroup$
    – gpap
    Apr 3 at 21:47
4
$\begingroup$

My solution is to write my package in an .nb file, putting everything in Code-style cells. Here it is easy to format text using command-0 to style italicized text as style TI: enter image description here

enter image description here

Set up the notebook with the AutoGeneratedPackage option as described here. After that, every time you save your .nb, it will automatically generate the .m version along side.

This is what is saved in the .m file:

Test::usage="Test[\!\(\*
StyleBox[\"args\", \"TI\"]\)] is a test function.";

Who'd want to figure that out manually?!

Maybe there's an easier way, but this is actually quite usable because you only have to set up the AutoGeneratedPackage option once.

$\endgroup$
2
  • $\begingroup$ Thanks (+1), this makes sense but I was hoping that there was an easy way for mathematica to render the expression like in the built-ins (like enclose the argument in special brackets or something) but still maintain human readability of the package which wouldn't be the case with the \!\(\* StyleBox[\"args\", \"TI\"]\) part $\endgroup$
    – gpap
    Apr 3 at 21:12
  • 1
    $\begingroup$ @gpap Just never look at the resulting .m file, only work on the .nb $\endgroup$
    – Chris K
    Apr 3 at 23:10

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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