Documentation Tools: How to prevent breaking up CamelCase package name?

I can understand why MyPackage is changed to MY PACKAGE SYMBOL and unfortunately LaTeX is a special name which suffers from that change.

On the other hand, conversion functions are far from being perfect because if your package is called is e.g. WRI then it will be translated to W R I SYMBOL, which looks strange and I'd call it a minor bug.

I don't know what may go wrong so do this on your own responsibility.

The fix

• Find Utils.m file in:

  eclipse / installation / path / eclipse / jee-neon / eclipse / configuration / org.eclipse.osgi / 971 / 0 / .cp / MathematicaSource / DocumentationBuild

  This path is OS dependent etc so the best way is to run a documentation build and take a look at the first [echo] in console.

• find GetClassificationBoxes["Symbol", paclet_, _, lang_String:"English"] := Localized["PacletSymbolClassification", lang][paclet];

  it will be commented

• change the pattern to GetClassificationBoxes["Symbol", paclet_, _, lang_String:"English", opts___]

• uncomment it

• save Util.m

• run build

I don't know who and why commented that so be careful. Without our modification it wouldn't be caught anyway and land in the last GetClassificationBoxes definition which then uses AddSpaceToCamelCase and other strange things.

---

How did I know?

• I took DocumentationBuild path and searched for "PacletNameCell" which is the problematic cell's style.

   TextSearch[path, "PacletNameCell"]
  

• I've found that it is created in Make.m and the content is:

   pacletNameCell =      CapitalizeString[
      Transmogrify`ConvertToString[
         GetClassificationBoxes[info, lang, "Rebranded"->$Rebranded]
      ]
   ]
  

• run a build with pacletNameCell as a column with all those steps, which showed that the problem is in GetClassificationBoxes[_list]

the rest you know.

Solution 1

One way is to modify the DocumentationBuild package. This, of course, isn't ideal, but it is the quickest workaround so I am sharing it. If you have more time, I recommend solution 2.

1. Find Utils.m with the DocumentationBuild package. Simply open a notebook through the Workbench, then evaluate

   FindFile["DocumentationBuild`Utils`"]
   

   to find its location.

2. Search for the AddSpaceToCamelCase function. At the beginning there is a list of strings, such as "GUIKit", "JLink", etc., which will not be broken up. Simply add anything you don't want broken up to this list.

Solution 2

Patch the AddSpaceToCamelCase function in-memory after the DocumentationBuild package is loaded. This answer is modelled directly on this answer by @jkuczm.

In docbuild.xml, add the following code right before the <ant antfile="${appPath}/DocumentationBuild/SystemFiles/ant/Build/notebook.xml" line:

<mathematica exe="${mathExe}">
<![CDATA[
  If[Not@MemberQ[$Path, #], PrependTo[$Path, #]]&@AntProperty["appPath"]
  Needs["DocumentationBuild`"]
  DownValues[AddSpaceToCamelCase] = 
    DownValues[AddSpaceToCamelCase] /. HoldPattern[Alternatives][s__String] :> 
                                           Alternatives[s, "MaTeX"]
]]> 
</mathematica>

Instead of "MaTeX", use a list of strings you wish to preserve.

The problem with simply trying to post-process the generated notebook is that broken up words also en up in the index. If we prevent breaking them up in the first place, we don't have to think about where else they might show up.