I want to create properly linked documentation pages dedicated to specific messages issued by my own functions inside a package, similar to those for messages of built-in functions like Integrate below:

Integrate[x,2]

Integrate::ilim : Invalid integration variable or limit(s) in 2. >>

Here, the ">>" links not to the Integrate help page, but to a page specific to the message Integrate::ilim:

enter image description here

How do I create such a page in Workbench? And how should one properly link the Messages to their appropriate pages?

  • Could you take a look at my comment below the accepted answer? I'm using the new Eclipse plugin ("Workbench plugin version 10.1" according the about box). – Szabolcs Nov 15 '16 at 19:20
up vote 7 down vote accepted

Say you're developing MyPackage` and want to create page for MySymbol::myMessage. Assuming you already have created standard Application project, with documentation support, perform following steps.

  1. Inside MyProject/MyPackage/Documentation/English/ReferencePages create Messages directory with MySymbol sub-directory.

  2. Open PacletInfo editor (double click on PacletInfo.m file). Choose Documentation tab, there should be ExtraReferences/Messages position select it and click on Add Page. Type in myMessage in window that should appear and click OK. MyProject/MyPackage/Documentation/English/ReferencePages/Messages/myMessage.nb file should be created.

  3. Manually move above file to MySymbol sub-directory. Its path should now be:

    MyProject/MyPackage/Documentation/English/ReferencePages/Messages/MySymbol/myMessage.nb
    
  4. Open myMessage.nb file. In Categorization section, change Entity Type to Message and URI to MyPackage/ref/message/MySymbol/myMessage.

    Manually tweak contents as you like. E.g. change title from myMessage to MySymbol::myMessage, remove usage cells etc.

  5. Make sure PacletInfo.m has proper "Documentation" and "Kernel" Extensions.

After standard building and deploying everything should work automatically.

Assuming that in your package there is something like:

MySymbol::myMessage = "This is my message."

then printing MySymbol::myMessage should give message text together with proper documentation link:

Needs["MyPackage`"]

Message[MySymbol::myMessage]
(* MySymbol::myMessage: This is my message. >> *)
  • I did step 1 but in step 2 I do not see ExtraReferences/Messages. I have three categories: Symbols, Guides, Tutorials. Did I misunderstand something? – Szabolcs Nov 15 '16 at 19:18
  • OK, I figured it out: it seems to be necessary to run a documentation build after creating the folder in step 1. Only then will ExtraReferences/Messages appear. – Szabolcs Nov 15 '16 at 19:34
  • @Szabolcs I just tested it on fresh project. I had PacletInfo.m open on Documentation tab while manually creating directories, and ExtraReferences/Messages popped up instantly after creating Messages directory. I'm using Eclipse Mars.2 (4.5.2) with Wolfram Workbench 10.1.757 on Linux. Maybe it's some refreshing issue in specific Eclipse version. Maybe something like right-click on project, in Navigator, and choosing Refresh, or closing/reopening PacletInfo.m would be enough? – jkuczm Nov 16 '16 at 12:04
  • 1
    @Szabolcs In fact, clicking on Add Page with ExtraReferences/Messages selected creates a "Symbol" documentation page, so it has same effect as clicking on Add Page with Symbols selected, you'll just need move notebook file from different directory. – jkuczm Nov 16 '16 at 12:06
  • Do you know how to make messages for several symbols point to the same page? Like how error messages FullSimplify::time and Simplify::time work? – QuantumDot Aug 28 '17 at 3:06

Nice question! I do not have MMA with me now, but I think you could do as follows: 1- Create a doc page titled with the name of the message. 2 create a message text which includes a link to the above mentioned page.

If you have any doubts as to how to make the link, examine the inner "guts" of the Integrate::illim cell, using ctrl-shift-E and try to reproduce the same pattern in your own message text.

Here's what you need it's an example. You need to style the output cell!

CellPrint[
 Cell["abc", 18 , Background -> LightYellow, 
  CellFrame -> {{2, 0}, {0, 0}}, CellFrameColor -> Yellow]]

Your Answer

By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.

Not the answer you're looking for? Browse other questions tagged or ask your own question.