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.

Amaryl

Related mathematicahelp.info/minor-progress-with-6-0-documentation – Phosphide

I am not posting this as an answer because you explicitly disregarded the WorkBench. But I think you are after something like this palette reference.wolfram.com/workbench/index.jsp?topic=/… – Phosphide

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

Wainscot

+1. I was unaware that InputForm of boxes is linear form. See my answer for additional observations. – Amaryl

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 ...

Karmakarmadharaya

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!):

Amaryl

would you happen to know how to quickly format a letter using Times New Roman Italic ("TI")? What I do is type the letter then go to fonts and switch it. But when I look at the full form I get something like StyleBox[\"L\",FontFamily->\"Times\",FontSize->11,FontWeight->\"Plain\",FontSlant->\"Italic\"] instead of the shorted version StyleBox[\"L\", \"TI\"]. I've also been having problems with this when I try to create an index as it is described here. – Duckweed

@Duckweed Select your text, then press Alt+0 and enter "TI" in the dialog box. Alternatively, use Format > Style > Other... menu item. – Amaryl

thanks, this simplifies the formatting process. Going back to your original example: ActionMenu::usage. If you look at ?ActionMenu on a notebook you will see a formatted message. Now, if you look for ActionMenu start:1 in the doc center you will see the same message without the italic times new roman. Is this not the same ActionMenu::usage message? I've been trying to build my index by setting the summary of a function to functionName::usage but I always end up with StyleBoxes all of the place. Is there a way to remove the formatting from ActionMenu::usage? – Duckweed

@Duckweed Yes, what you see in the Documentation Center is of course completely independent on the ::usage messages. As I understand, the contents of the page ActionMenu start:1 is generated on the fly by some Java code which removes formatting. It seemingly has some special rules on converting two-dimensional elements like SubscriptBox to one-dimensional form. I do not know how to do this in Mathematica. Probably it is worth to create separate question on it. – Amaryl

I don't know if you have checked my most recent question. If you find out how to do it please share it. :) – Duckweed