9
$\begingroup$

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?

Improve this question
$\endgroup$
1
  • $\begingroup$ 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). $\endgroup$
    – Szabolcs
    Commented Nov 15, 2016 at 19:20

3 Answers 3

Reset to default
8
$\begingroup$

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. >> *)
Improve this answer
$\endgroup$
8
  • $\begingroup$ 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? $\endgroup$
    – Szabolcs
    Commented Nov 15, 2016 at 19:18
  • $\begingroup$ 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. $\endgroup$
    – Szabolcs
    Commented Nov 15, 2016 at 19:34
  • $\begingroup$ @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? $\endgroup$
    – jkuczm
    Commented Nov 16, 2016 at 12:04
  • 1
    $\begingroup$ @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. $\endgroup$
    – jkuczm
    Commented Nov 16, 2016 at 12:06
  • $\begingroup$ 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? $\endgroup$
    – QuantumDot
    Commented Aug 28, 2017 at 3:06
1
$\begingroup$

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.

Improve this answer
$\endgroup$
0
$\begingroup$

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]]
Improve this answer
$\endgroup$
2

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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