User-defined usage message template; removing repeated text

Question

In Mathematica 9.0.1, I want to write a user-defined template for a function that I wrote: myfunc

Remove[myfunc]
myfunc::usage = "myfunc[x,y,z] is a function.
                 myfunc[x,y,z,w] is another function."

with the result:

As you can see, within the description myfunc is (in my opinion) unnecessarily repeated. In fact, templates for built-in functions do not behave that way. For example, look at the template for the Integrate function:

The function name Integrate is not repeated in the description. How do I tell Mathematica not to repeat the name of the function inside the description?

Answer 1

The built-in function templates displayed by the Input Assistant when Shift+Ctrl+K-ing the symbol name are NOT drawn from either

• the package file that holds the symbol. Check and edit e.g. Calendar`DaysPlus in $InstallationDirectory\AddOns\Packages\Calendar\Calendar.m. It has one simple usage though the Input Assistant shows two.
• the usage file: $InstallationDirectory\SystemFiles\Kernel\TextResources\English\Usage.m. It does contain the multiple usage messages for e.g. Calendar`DaysPlus or Integrate, but editing them will only change ?f and Message[f::usage] prints, but not the Input Assistant templates.

The usage messages in Usage.m are probably programmatically created from the same source during initialization that is used to format the templates. This source is in v9 (before, it was FunctionInformation.m):

file = ToFileName[{$InstallationDirectory, "SystemFiles", "Kernel", "TextResources", 
            CurrentValue["Language"]}, "FunctionInformation2.m"]

The file is read when the FrontEnd initializes (at line 376 in GetFEKernelInit.tr):

ToFileName[{$InstallationDirectory, "SystemFiles", "FrontEnd", "TextResources"},
            "GetFEKernelInit.tr"]

While "FunctionInformation2.m" is compressed, it is easy to create a wrapper that makes it readable. Here I only print the information on System` symbols (and omit package symbols that form the first part of data). Warning: the list is huge, 2871 symbols are printed.

format[list_List] := OpenerView[{list[[1]], Column@{
      "ArgumentsPattern" -> list[[2]],
      "Help" -> If[list[[3]] =!= None, Panel@Column[
          MapThread[Row[{##}, " "] &, {DisplayForm /@ list[[3]], 
            DisplayForm /@ list[[4]]}], Alignment -> Left]],
      "Options" -> If[Length@list > 4, list[[5]], ""],
      "LocalVariables" -> If[Length@list > 5, list[[6]], ""]
      }}];

data = Uncompress@Get@file;
format /@ Last@Last@data // Column

The structure is: first symbols without options, then symbols with options, then symbols with options and available "LocalVariables" specification. What you are looking for is the list[[4]] part, that lists the textual part of each line of help (while list[[3]] lists the formula part for each line).

Unfortunately, I don't see any easy ways to add custom syntax information/template to "FunctionInformation2.m" in the way you would like it to be. It's a pity WRI does not allow users to manipulate the Input Assistant in a more usable fashion.

Answer 2

The short answer is: there isn't currently a way to do so.

As @istvan has correctly guessed, both the usage messages and the templates come from a common source, which is in fact the source notebooks used to generate the documentation. For those familiar with the DocumentationTools included with Wolfram Workbench, these are very similar. These source notebooks have a fair amount of markup that the build systems--for usages, templates, and documentation center--can use to precisely separate out which pieces go where, and produce these nicely formatted templates.

Of course, we still have the fall-back system of automatically generating templates from usage messages. It doesn't allow for the same level of control. This isn't because we don't care, but because its a very hard problem. Without the extra tagging, it's not obvious which part of the usage message to put in the template and which to be in the description. In fact, the InputForm of a formatted is string sufficiently complicated that just reliably picking it apart and splitting it into different pieces without causes pink boxes to appear is not trivial. For that reason, it is unlikely for the automatic usage message -> template system to be upgraded to support the nice templates of V9 and later.

Note: since version 11, the FunctionInformation2.m file is in fact no longer used for templates of system functions. We are working on making the new system user extendible, but as with all features under development, we cannot promise when it might be released.