Convenient way to add inline formatting to usage Messages

Question

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.

Answer 1

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:

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:
   

2. Select the output, and go to menu item Cell > Convert to > InputForm. Result:
   

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

Answer 2

I think the easiest way is to just use the Front End to format your string. If you are writing a package, you can use "auto-save packages" (i.e. when the contents of the initialization cells of a notebook become the package). If you use a text editor to write the package then it might just be too much trouble to use formatting ...

Answer 3

This answer is an addition to Sjoerd's answer.

First of all, we do not have to use the FrontEnd command Cell > Convert to > InputForm to get the linear form of boxes. We can get it just by applying InputForm to the output of MakeBoxes:

In[1]:= InputForm@MakeBoxes[Subscript[x, 1,2]==(-b\[PlusMinus]Sqrt[b^2-4 a c])/(2 a)]
Out[1]//InputForm=
\(x\_\(1, 2\) == \(\(-b\) \[PlusMinus] \@\(b\^2 - \(4\ a\ c\)\)\)\/\(2\ a\)\)

Secondly, we can export the final typesetting in-line string representation of boxes by the following two ways with equivalent result (the only difference is that Put wraps the text):

OutputForm@
  StringInsert[
   ToString[
    InputForm@
     MakeBoxes[
      Subscript[x, 1, 2] == (-b \[PlusMinus] Sqrt[b^2 - 4 a c])/(
       2 a)], OutputForm], "\\!", 1] >> "C:\\input.txt"

Export["C:\\input.txt", 
 StringInsert[
  ToString[InputForm@
    MakeBoxes[
     Subscript[x, 1, 2] == (-b \[PlusMinus] Sqrt[b^2 - 4 a c])/(2 a)],
    OutputForm], "\\!", 1], "String"]

In both cases we get a file with one line: \!\(x\_\(1, 2\) == \(\(-b\) ± \@\(b\^2 - \(4\ a\ c\)\)\)\/\(2\ a\)\).

Inserting this line in a Notebook in the FrontEnd gives the original expression (try it by yourself!):