Skip to main content

Creating cross-version compatible documentation with Workbench


Wolfram Workbench allows you to create documentation for your own packages that is similar to the build-in documentation center. Integrating this type of documentation with the documentation center is possible starting from Mathematica 6, and hence I would like to create packages whose documentation nicely integrates with Mathematica 6, 7, 8, and 9.



However, Workbench doesn't support this out of the box. Its documentation tools seem to be a spin-off from WRI own tools to create version-specific documentation, so it is no wonder creating cross-version compatible docs in Workbench is nearly impossible.


So far, I've identified the following obstacles to creating cross-version compatible docs:



  1. Documentation indices built with Mathematica <= 8 are not compatible with Mathematica 9, so docs built with <= 8 are not searchable in 9. See this workaround.

  2. Documentation pages built with a given version of Mathematica always give the "This notebook was created in a more recent version of Mathematica" dialog warning in older versions. See this workaround.

  3. The PacletInfo.m syntax has changed with Mathematica 9; it now requires a "Kernel" extension. This chokes the Mathematica 6 PacletManager, ruling out docs simultaneously compatible with 6 and 9. See this workaround.

  4. Workbench 2 can only properly build docs with Mathematica 7 or 8. Mathematica 6 returns malformed notebooks (see this workaround by Simon Rochester), and 9 freezes halfway the build process for large packages.

  5. Docs build with lower version look pretty bad on Mathematica 9. See this partial workaround.


Points 2 and 5 are by no means deal-breakers, but 1 in combination with 4 certainly is. I've managed to find work-arounds for most of these issues, which I've posted below.



If someone has identified similar issues or has better workarounds, I'm all ears!




Comments

Post a Comment

Popular posts from this blog

front end - keyboard shortcut to invoke Insert new matrix

I frequently need to type in some matrices, and the menu command Insert > Table/Matrix > New... allows matrices with lines drawn between columns and rows, which is very helpful. I would like to make a keyboard shortcut for it, but cannot find the relevant frontend token command (4209405) for it. Since the FullForm[] and InputForm[] of matrices with lines drawn between rows and columns is the same as those without lines, it's hard to do this via 3rd party system-wide text expanders (e.g. autohotkey or atext on mac). How does one assign a keyboard shortcut for the menu item Insert > Table/Matrix > New... , preferably using only mathematica? Thanks! Answer In the MenuSetup.tr (for linux located in the $InstallationDirectory/SystemFiles/FrontEnd/TextResources/X/ directory), I changed the line MenuItem["&New...", "CreateGridBoxDialog"] to read MenuItem["&New...", "CreateGridBoxDialog", MenuKey["m", Modifiers-...
Post a Comment
Read more

How to thread a list

I have data in format data = {{a1, a2}, {b1, b2}, {c1, c2}, {d1, d2}} Tableform: I want to thread it to : tdata = {{{a1, b1}, {a2, b2}}, {{a1, c1}, {a2, c2}}, {{a1, d1}, {a2, d2}}} Tableform: And I would like to do better then pseudofunction[n_] := Transpose[{data2[[1]], data2[[n]]}]; SetAttributes[pseudofunction, Listable]; Range[2, 4] // pseudofunction Here is my benchmark data, where data3 is normal sample of real data. data3 = Drop[ExcelWorkBook[[Column1 ;; Column4]], None, 1]; data2 = {a #, b #, c #, d #} & /@ Range[1, 10^5]; data = RandomReal[{0, 1}, {10^6, 4}]; Here is my benchmark code kptnw[list_] := Transpose[{Table[First@#, {Length@# - 1}], Rest@#}, {3, 1, 2}] &@list kptnw2[list_] := Transpose[{ConstantArray[First@#, Length@# - 1], Rest@#}, {3, 1, 2}] &@list OleksandrR[list_] := Flatten[Outer[List, List@First[list], Rest[list], 1], {{2}, {1, 4}}] paradox2[list_] := Partition[Riffle[list[[1]], #], 2] & /@ Drop[list, 1] RM[list_] := FoldList[Transpose[{First@li...
Post a Comment
Read more

dynamic - How can I make a clickable ArrayPlot that returns input?

I would like to create a dynamic ArrayPlot so that the rectangles, when clicked, provide the input. Can I use ArrayPlot for this? Or is there something else I should have to use? Answer ArrayPlot is much more than just a simple array like Grid : it represents a ranged 2D dataset, and its visualization can be finetuned by options like DataReversed and DataRange . These features make it quite complicated to reproduce the same layout and order with Grid . Here I offer AnnotatedArrayPlot which comes in handy when your dataset is more than just a flat 2D array. The dynamic interface allows highlighting individual cells and possibly interacting with them. AnnotatedArrayPlot works the same way as ArrayPlot and accepts the same options plus Enabled , HighlightCoordinates , HighlightStyle and HighlightElementFunction . data = {{Missing["HasSomeMoreData"], GrayLevel[ 1], {RGBColor[0, 1, 1], RGBColor[0, 0, 1], GrayLevel[1]}, RGBColor[0, 1, 0]}, {GrayLevel[0], GrayLevel...
Post a Comment
Read more