Fixing links to symbol pages with special characters made with Workbench

Question

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]:

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.

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:

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.

Answer 1

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.