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

functions - Get leading series expansion term?

Given a function f[x] , I would like to have a function leadingSeries that returns just the leading term in the series around x=0 . For example: leadingSeries[(1/x + 2)/(4 + 1/x^2 + x)] x and leadingSeries[(1/x + 2 + (1 - 1/x^3)/4)/(4 + x)] -(1/(16 x^3)) Is there such a function in Mathematica? Or maybe one can implement it efficiently? EDIT I finally went with the following implementation, based on Carl Woll 's answer: lds[ex_,x_]:=( (ex/.x->(x+O[x]^2))/.SeriesData[U_,Z_,L_List,Mi_,Ma_,De_]:>SeriesData[U,Z,{L[[1]]},Mi,Mi+1,De]//Quiet//Normal) The advantage is, that this one also properly works with functions whose leading term is a constant: lds[Exp[x],x] 1 Answer Update 1 Updated to eliminate SeriesData and to not return additional terms Perhaps you could use: leadingSeries[expr_, x_] := Normal[expr /. x->(x+O[x]^2) /. a_List :> Take[a, 1]] Then for your examples: leadingSeries[(1/x + 2)/(4 + 1/x^2 + x), x] leadingSeries[Exp[x], x] leadingSeries[(1/x + 2 + (1 - 1/x...
Post a Comment
Read more

mathematical optimization - Minimizing using indices, error: Part::pkspec1: The expression cannot be used as a part specification

I want to use Minimize where the variables to minimize are indices pointing into an array. Here a MWE that hopefully shows what my problem is. vars = u@# & /@ Range[3]; cons = Flatten@ { Table[(u[j] != #) & /@ vars[[j + 1 ;; -1]], {j, 1, 3 - 1}], 1 vec1 = {1, 2, 3}; vec2 = {1, 2, 3}; Minimize[{Total@((vec1[[#]] - vec2[[u[#]]])^2 & /@ Range[1, 3]), cons}, vars, Integers] The error I get: Part::pkspec1: The expression u[1] cannot be used as a part specification. >> Answer Ok, it seems that one can get around Mathematica trying to evaluate vec2[[u[1]]] too early by using the function Indexed[vec2,u[1]] . The working MWE would then look like the following: vars = u@# & /@ Range[3]; cons = Flatten@{ Table[(u[j] != #) & /@ vars[[j + 1 ;; -1]], {j, 1, 3 - 1}], 1 vec1 = {1, 2, 3}; vec2 = {1, 2, 3}; NMinimize[ {Total@((vec1[[#]] - Indexed[vec2, u[#]])^2 & /@ R...
Post a Comment
Read more

plotting - Plot 4D data with color as 4th dimension

I have a list of 4D data (x position, y position, amplitude, wavelength). I want to plot x, y, and amplitude on a 3D plot and have the color of the points correspond to the wavelength. I have seen many examples using functions to define color but my wavelength cannot be expressed by an analytic function. Is there a simple way to do this? Answer Here a another possible way to visualize 4D data: data = Flatten[Table[{x, y, x^2 + y^2, Sin[x - y]}, {x, -Pi, Pi,Pi/10}, {y,-Pi,Pi, Pi/10}], 1]; You can use the function Point along with VertexColors . Now the points are places using the first three elements and the color is determined by the fourth. In this case I used Hue, but you can use whatever you prefer. Graphics3D[ Point[data[[All, 1 ;; 3]], VertexColors -> Hue /@ data[[All, 4]]], Axes -> True, BoxRatios -> {1, 1, 1/GoldenRatio}]
Post a Comment
Read more