Disable templates for user defined functions with usages

Question

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:

Answer 1

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] &;

Answer 2

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:

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

Answer 3

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

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.