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.

Related http://www.mathematicahelp.info/minor-progress-with-6-0-documentation — Dr. belisarius, Jun 21 '11 at 05:19
I am not posting this as an answer because you explicitly disregarded the WorkBench. But I think you are after something like this palette http://reference.wolfram.com/workbench/index.jsp?topic=/com.wolfram.eclipse.help/html/reference/DocumentationTools/tutorial/AuthoringSymbolPagesUsingDocumentationTools.html — Dr. belisarius, Jun 21 '11 at 10:26

score 1 · Answer 1 · answered Jun 21 '11 at 08:17

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

score 1 · Accepted Answer · answered Jun 21 '11 at 12:38

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.

Generate boxes from your formatted expression:
Select the output, and go to menu item Cell > Convert to > InputForm. Result:
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

+1. I was unaware that `InputForm` of boxes is linear form. See my answer for additional observations. — Alexey Popkov, Jun 21 '11 at 14:23

Alexey Popkov · Answer 3 · 2011-06-21T22:28:17.127

1

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

screenshot

edited Jun 21 '11 at 22:28

answered Jun 21 '11 at 14:39

Alexey Popkov

9,355
4
42
93

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](http://www.dbaileyconsultancy.co.uk/m_documentation/m_documentation.html). – jmlopez Jul 04 '11 at 08:09
1

@jmlopez Select your text, then press Alt+0 and enter `"TI"` in the dialog box. Alternatively, use `Format > Style > Other...` menu item. – Alexey Popkov Jul 04 '11 at 09:09
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`? – jmlopez Jul 04 '11 at 09:34
@jmlopez 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. – Alexey Popkov Jul 05 '11 at 02:10
I don't know if you have checked my most recent [question](http://stackoverflow.com/questions/6574710/integrating-notebooks-to-mathematicas-documentation-center). If you find out how to do it please share it. :) – jmlopez Jul 05 '11 at 05:30

Convenient way to add inline formatting to usage Messages

3 Answers3

Linked