Search code examples
wolfram-mathematicamathematica-frontend

Convenient way to add inline formatting to usage Messages

Usage Messages of built-in functions have embedded in-line formatting. For example:

In[1]:= ActionMenu::usage // FullForm

Out[1]//FullForm= 
"\!\(\*RowBox[{\"ActionMenu\", \"[\", RowBox[{StyleBox[\"name\", \"TI\
\"], \",\", RowBox[{\"{\", \
RowBox[{RowBox[{SubscriptBox[StyleBox[\"lbl\", \"TI\"], \
StyleBox[\"1\", \"TR\"]], \":>\", SubscriptBox[StyleBox[\"act\", \"TI\
\"], StyleBox[\"1\", \"TR\"]]}], \",\", \
RowBox[{SubscriptBox[StyleBox[\"lbl\", \"TI\"], StyleBox[\"2\", \
\"TR\"]], \":>\", SubscriptBox[StyleBox[\"act\", \"TI\"], \
StyleBox[\"2\", \"TR\"]]}], \",\", StyleBox[\"\[Ellipsis]\", \
\"TR\"]}], \"}\"}]}], \"]\"}]\) represents an action menu with label \
\!\(\*StyleBox[\"name\", \"TI\"]\), and with items labeled \
\!\(\*SubscriptBox[StyleBox[\"lbl\", \"TI\"], StyleBox[\"i\", \
\"TI\"]]\), that evaluates the expression \
\!\(\*SubscriptBox[StyleBox[\"act\", \"TI\"], StyleBox[\"i\", \
\"TI\"]]\) if the corresponding item is chosen."

One can see that this in-line formatting is based on the set of styles defined in "Styles for Inline Formatting" section of the Core.nb stylesheet. But I have not found any documentation for these styles as well as any description of the convenient algorithm of adding formatting to usage Messages.

What is the convenient way to add in-line formatting to user-defined usage Messages in Mathematica? What are the usage rules of default styles for in-line formatting defined in the Core.nb stylesheet? I would like to add in-line formatting to the usage Messages in my package just with Mathematica, without installing additional components like Workbench etc.

P.S. The syntax of the embedded in-line formatting in Strings is partially documented on the tutorial page "String Representation of Boxes." Related question in the official newsgroup on this syntax: "(any documentation for) linear syntax?" Displaying of such strings in the FrontEnd is controlled by the option ShowStringCharacters->False of Cell.

Solution

  • One of the problems of handling strings like that is that most operations with strings in Mathematica automatically replace the backslash (\) with the escaped backslash (\\).

    If you try this:

    enter image description here

    you may think you have the string you're looking for (minus the \! to make it an expression), but in fact it is: "\\(x\\_\\(1, 2\\) \[Equal] \\(\\(-b\\) \[PlusMinus] \\@\\(b\\^2 -\\(4\\ a\\ c\\)\\)\\)\\/\\(2\\ a\\)\\)"

    My solution is far from elegant, but it works.

    1. Generate boxes from your formatted expression: enter image description here
    2. Select the output, and go to menu item Cell > Convert to > InputForm. Result: enter image description here
    3. You can now edit the string, putting \! in front of it and quotes around it: "\!\(x \_ \(1, 2\) == \(\(-b\) \[PlusMinus] \@\(b \^2 - \(4\ a\ c\)\)\) \/ \(2\ a\)\)"

    If you perform step 3 in an external editor, leave away the quotes and just have \! in front and paste back the result in MMA it is directly converted to the formatted expression