9
$\begingroup$

It appears that fixing the template system is low on Wolfram Research's priority list. For my package, I have defined Usage info for my functions involving lots of formatting, which causes the template system to run amuck. Since this looks very unprofessional, I want to prevent the front-end from trying to render templates for these functions. How do I disable the templates only for the functions in the package I am writing (in v9 and v10)?


Here is an example (version 9.0.1):

function::usage = "function[\!\(\*StyleBox[\"x\", \"TI\"]\)] carries out some complicated algorithm.

Possible options: AlgorithmComplexity, SimplifiedOutput"

and here is what the template looks like:

enter image description here

$\endgroup$
  • 1
    $\begingroup$ It would be extremely helpful if you could give a fake function definition which shows what you mean by causes the template system to run amok. $\endgroup$ – halirutan Oct 5 '14 at 0:50
  • $\begingroup$ @halirutan I have added an example. $\endgroup$ – QuantumDot Oct 6 '14 at 11:42
  • $\begingroup$ Have you seen and tested my answer? $\endgroup$ – halirutan Oct 9 '14 at 8:36
2
$\begingroup$

I think the problem (bug?) has been fixed in version 10.0.2. For example:

thisismytestfunction::usage =
        Row[{
                    Style[thisismytestfunction, Red, Bold][Style[x, Italic]],
                    "carries out some complicated algorithm.\n",
                    Style["Possible options:", Bold, 16],
                    "AlgorithmComplexity, SimplifiedOutput"
                    }, " "] // ToString[#, StandardForm] &;

fancy styled usage information

$\endgroup$
9
$\begingroup$

This doesn't really answer your question, but it is worth noting that the internal Macros package does make it easier to define nicely-formatting usage messages:

Needs["Macros`"];
SetUsage[mymap, 
    "mymap[f$, {e$1,e$2,$$}] yields {f$[e$1],f$[e$2],$$}.",
"mymap[f$, list$, n$] maps f$ over list$ at level n$."
];

Which gives a usage that looks like this:

enter image description here

Unfortunately this still doesn't render nicely in the popup usage thing. I may fix that for 10.0.2.

$\endgroup$
  • 2
    $\begingroup$ Is Macros' a version 10 feature? I can't seem to load it with my v9.0.1 copy. $\endgroup$ – QuantumDot Oct 8 '14 at 13:44
  • $\begingroup$ I got an email from Wolfram saying that 10.0.2 is out; so, is it fixed now? $\endgroup$ – QuantumDot Dec 12 '14 at 22:42
  • $\begingroup$ What would be the way to fix rendering in popups? Does it require changes in the popup rendering code (which users cannot do) or does it just require the usage message to be written in a certain way? Related. Is there documentation on how usage messages should be written to play nicely with auto-completion? $\endgroup$ – Szabolcs Oct 6 '15 at 10:53
  • $\begingroup$ This appears to still fail for the pop-up as of v10.3.1. $\endgroup$ – Emilio Pisanty May 4 '16 at 21:43
5
+50
$\begingroup$

Unfortunately, this will not help you because although it fixes the issue for your usage messages, I would not recommend to include this hack in your package. I found out about all this when I was investigating in usage messages for the IntelliJ Plugin.

Very interesting is the file

FileNames["FEKernelInit.tr", {$InstallationDirectory}, Infinity]

because it shows some routines how usage templates are automatically extracted from (user defined) usage messages. Following these lines, you see that there are functions like getTemplateFromUsage which calls things like makePlainText etc.

You can try these things for your own function:

function::usage = "function[\!\(\*StyleBox[\"x\", \"TI\"]\)] carries out some complicated...";
FE`getTemplateFromUsage[function::usage, "function"]

and you see that the StyleBox is stripped from your usage exactly as it is in the screenshot of your question. Going a bit further in this file, you will find a function named FE`FTU and this looks like it is providing the information for what is shown in the template tooltip you see. The last line of this function is

MathLink`CallFrontEnd@
 FrontEnd`TemplateTooltipPacket[FrontEnd`InputNotebook[], sn, name, template, usageStrings]

When you debug this function by unprotecting it and looking at the values of the parameters, you see that in usageStrings all formatting is preserved. Since this seems to be the problem, you could simply redefine this function and make your usage messages plain text for the tooltip.

Unprotect[FE`FTU];
FE`FTU[sn_, name_] := 
 Block[{usage, usageStrings, template}, 
  usage = ToExpression[name <> "::usage"];
  If[! StringQ[usage], Return[]];
  usageStrings = StringSplit[usage, Except["\*" | ","] ~~ "\n"];
  template = FE`getTemplateFromUsage[#, name] & /@ usageStrings;
  template = 
   If[template === $Failed, Return[], 
    FE`makePlainText[#] & /@ template];
  template = 
   If[template === $Failed, Return[], 
    FE`reparseBoxStructure[#, name] & /@ template];
  template = GridBox /@ List /@ List /@ template;
  Global`tmp = {sn, name, template, usageStrings}; 
  MathLink`CallFrontEnd@
   FrontEnd`TemplateTooltipPacket[FrontEnd`InputNotebook[], sn, name, 
    template, FE`makePlainText /@ usageStrings]]
Protect[FE`FTU]

After this, the tooltip looks fine

enter image description here

Please note, that you have to do this after you Quit[] the kernel, since those template tooltips seem to be cached. Therefore, (1) quit your kernel, (2) redefine FE`FTU, (3) define and try you function.

$\endgroup$
  • $\begingroup$ I am new to templates, what does "\!(*" accomplish before StyleBox, and where is this usage documented? $\endgroup$ – John McGee Nov 20 '15 at 19:49

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.