I am writing documentation for a package using Workbench v2.0 and Mathematica v9.0.1, and certain Symbols defined by my package have special (Greek) characters characters e.g. Unitλ.

As I am building the documentation, I am running into problems when trying to get links to these Symbol pages. Firstly, Workbench fails to properly recognize the symbol name from the .m file, and recommends that I create two distinct symbols--one for Unit and another for \[Lambda]:

enter image description here

Neither is acceptable, so I created a Symbol Page called "Unit[Lambda]". In the Guide page I use the B button in the Documentation Tools palette to browse for the specific symbol page it is supposed to link to.


Issue 1: After Building the documentation, and Previewing the guide page, the link is simply not working. I have checked the URI and they match.

enter image description here

Solution: Apparently, this is solved by modifying the file docbuild.xml according to Simon Rochester's answer to the question: Creating cross-version compatible documentation with Workbench.


Issue 2: Furthermore, for these symbols with special characters, upon calling the usage via ? Unit\[Lambda], I am not getting the relevant >> link to the documentation center:

enter image description here

Is there a solution the problem of the missing >> link in the usage box? I am basically looking for almost any solution: playing around with files after "Build"ing documentation is acceptable, as long as after it is deployed to other machines, everything works as normal.

up vote 4 down vote accepted
+100

Issue 1

If you want your documentation notebook to work, without problems, in different operating systems, you should avoid special characters in file names. I'd call your documentation notebook UnitLambda.nb

Last element of URI should match documentation notebook file name (without .nb). In specific case from question URI should be RapidSolver/ref/UnitLambda.

Make sure that all links in source documentation notebooks point to correct URI.

You can change URI cell from UnitLambda.nb and all links from other source notebooks using Eclipse search/replace functionality.

Issue 2

Add Resources to "Documentation" Extensions of your Paclet, that will point to appropriate documentation notebook:

Paclet[
    (*...,*)
    Extensions -> 
        {
            {"Documentation",
                (*...,*)
                Resources -> {
                    {
                        "ReferencePages/Symbols/Unit\[Lambda]",
                        "ReferencePages/Symbols/UnitLambda.nb"
                    }
                }
            }, 
            (*...*)
        }
]

This method works in Mathematica version 9.0 and above (at time of writing tested up to version 11.0), but does not work in version 8 and earlier. If support for version 8 is needed, "hacky" solution, presented below, could be used.

Issue 2 (Old hacky version)

Add a small hack to your package:

Unprotect[Documentation`CreateMessageLink];
Documentation`CreateMessageLink["RapidSolver`", "Unit\[Lambda]", "usage", "English"] = 
    Documentation`CreateMessageLink["RapidSolver`", "UnitLambda", "usage", "English"]
Protect[Documentation`CreateMessageLink];

CreateMessageLink is a function used by Information to, as its name suggests, create a link at the and of a message. This hack will tell Mathematica that, when documentation page of RapidSolver`Unit\[Lambda] symbol is needed, it should really search for a page with URI ending with UnitLambda.

Your package will change definition of symbol from another package, which in general is a bad idea, but in this case redefinition affects only situations in which CreateMessageLink is called with context of your package as first argument, so it should be harmless.

You can put this code anywhere inside package file. Only relevant thing is that it gets executed when package is loaded.

Tested on Linux with Mathematica versions 8.0.0, 9.0.1 and 10.0.0.

  • This worked perfectly on my machine (Mac OSX, Mathematica v9.0.1). But for some reason, the hack doesn't work another test machine which runs Windows Server. I have already made sure none of my file names contain special characters. I will need to test on other machines and see if I can pin-point the problem... – QuantumDot Dec 5 '14 at 17:27
  • @QuantumDot Currently I don't have access to MMA on Windows, so I'm not sure I can help with this. But just to clarify the problem: Which MMA version is on your Windows Server? What precisely doesn't work? Link in usage message doesn't show up? Do links from other pages pointing to Unitλ page work? Can you access Unitλ page by pressing F1 with cursor on Unitλ symbol? – jkuczm Dec 6 '14 at 10:32
  • I have tried MMA v9.0.1 and v10.0.1 on Windows Server. Link in usage message of Unitλ doesn't show up. But links within other symbol/guide pages pointing to Unitλ all work fine (corrected by Issue1). Pressing F1 has never gone directly to the relevant page (neither on MacOS or Windows) for any of my symbols; it has always gone to the Search results page which displays the relevant page as one of the top hits. Interestingly, even after implementing your hack, the link in the Search page pointing to Unitλ does not work (goes to blank page) on both my Mac and Windows machine. – QuantumDot Dec 6 '14 at 12:30
  • @QuantumDot Behavior I'm getting on Linux: in v10 pressing F1 leads directly to symbol page (with additional link on top: Search for all pages containing Unitλ) in v8 and v9 F1 leads to search results page with link to symbol page as first result, clicking on it correctly leads to Unitλ symbol page. – jkuczm Dec 6 '14 at 13:58
  • @QuantumDot Links from other documentation pages have URIs taken from ButtonData option of ButtonBoxes present in source notebooks of those pages. Link on search result page is different, its URI is taken from URI cell from "Categorization" section of Unitλ symbol source notebook, so make sure it's correct. Problem with this cell might be "invisible" i.e. extra space or some formatting box invisible in the notebook. To be absolutely sure it's correct use Cell > Show Expression and check that first element of cell expression is exactly "RapidSolver/ref/UnitLambda" string. – jkuczm Dec 6 '14 at 14:02

Your Answer

 
discard

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.