8
$\begingroup$

I am exploring the Workbench documentation tools for the first time and one of the difficulties I encountered was that when documentation pages are generated, a CamelCase package name is changed into "CAMEL CASE" with a space inbetween. How can I prevent this?

Take a look at the top left:

enter image description here

It says,

MA TE X SYMBOL

I want it to say "MATEX SYMBOL", with no spaces. What setting should I change?

My PacletInfo.m is as follows:

Paclet[
    Name -> "MaTeX",
    Version -> "1.6.1",
    MathematicaVersion -> "10+",
    Extensions -> 
        {
            {"Documentation", Resources -> 
                {"Guides/MaTeX"}
            , Language -> "English"}
        }
]

I believe this should be possible, as I see that e.g. TetGenLink isn't broken up to TET GEN LINK in the official documentation.


Update and possible solution:

The function that adds the spaces is AddSpaceToCamelCase in Utils.m in the DocumentationBuild package that ships with Workbench. This function has an explicit, hard-coded list of names, such as NETLink, GPUTools, FEM, TetGenLink, etc. which it will not break up.

A very hackish but simple solution was to edit Utils.m and add "MaTeX" to this hard-coded list of exceptions.

$\endgroup$
  • $\begingroup$ Link to W Community version: community.wolfram.com/groups/-/m/t/956614 $\endgroup$ – Szabolcs Nov 6 '16 at 11:34
  • 2
    $\begingroup$ I am running additional script to fix all problems like that, I decided that writing such will be faster than finding documented anwers. $\endgroup$ – Kuba Nov 6 '16 at 12:22
5
$\begingroup$

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.

$\endgroup$
  • $\begingroup$ Do you know how to invoke the documentation build from within Mathematica? Have you ever tried to do this? Then we could do a live, in-memory patch of the doc tools instead of having to edit them. $\endgroup$ – Szabolcs Nov 15 '16 at 15:57
  • $\begingroup$ This is much better than post-processing because post-processing would corrupt the file outline cache. $\endgroup$ – Szabolcs Nov 15 '16 at 15:59
  • $\begingroup$ @Szabolcs I was planning, but never found time*motivation. But it is still on my todo list. $\endgroup$ – Kuba Nov 15 '16 at 16:01
  • 1
    $\begingroup$ @Szabolcs p.s. If you import and export notebook as "NB" the outline cache will adjust. $\endgroup$ – Kuba Nov 16 '16 at 7:42
  • 1
    $\begingroup$ @Szabolcs Documentation build would be a nice application for new NotebookTemplates but index and friends creation are still black magic for me so I didn't even try. $\endgroup$ – Kuba Nov 17 '16 at 9:52
4
$\begingroup$

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.

$\endgroup$

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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