Return to Answer

Using this technique when generating documentation in Mathematica 6 (with the method described in my other answer), along with Teake's techniques of generating the index in Mathematica 9 and writing a cross-version PacletInfo.m, seems to completely solve the cross-version documentation problem.

I was inspired by Teake's comment that he'd like to do something like If[$Version < 9., "More Information", "Details and options"] if it were possible. It turns out that it's not possible to include functions in cell contents, but functions can be included in cell options, as mentioned in the documentation here (bottom of the page).

• I couldn't call the "crossVersionReplacements" target from the "main" target, because the "docbuild" target has already loaded the J/Link library, and Ant doesn't want to load it a second time. Probably there's some other way around this, but I just called "crossVersionReplacements" from inside "docbuild", to piggyback on the already-loaded library.

• The "Details and Options" section heading should just read "Details" if there are no options for the function listed. To accomplish that, I search for the substring "option" or "Option" in the Details section, and replace the heading if no instances are found (other than in the heading itself).

• WRI added spacer cells at the beginning and ends of sections in the version 9 documentation, to obtain spacing that disappears when the sections are closed. To get a cross-version version of this, I added spacer cells in the appropriate places that display as very thin cells in pre-version 9 Front Ends.

• The Guide pages have been totally redesigned in version 9, so there's no way to match them exactly. In particular, the Tutorials heading and links have been completely restyled. I tried to give things a consistent look by undoing these changes, to match the Tutorials style with the style of the other sections. Update: I realized I could do this a little more simply by swapping out the cell style in the Tutorials heading for another section heading style.

• I encountered a rendering bug on the pre-version 9 Guide pages, affecting the layout on the whole page, which I found was triggered by the use of a non-integer value for a frame specification in the Abstract text. I adjusted the value to avoid the bug.

• To get the total number of examples on a symbol page, I added together the existing example counts for all of the example subsections.

• I learned some interesting things along the way, such as that the box representation of a Spacer is given by

    ToBoxes@Spacer[24]
  

     InterpretationBox[StyleBox[GraphicsBox[{}, ImageSize -> {24, 0},   
         BaselinePosition -> Baseline], "CacheGraphics" -> False], Spacer[24]]
  

• Update 3: In testing on Windows, I found that when a magnification level of less than 100% is chosen for the documentation notebook, the cell frame label is reduced by a different amount than the enclosing cell, causing layout errors. These are the same glitches as Teake reported seeing in OS X. There isn't much we can do about the different magnification factors. (Mathematica's magnification functionality has always been a bit of a crapshoot.) However, a workaround is to increase the width of the frame label cell, so as to run the rendering glitch right off of the page. This is implemented in the updated code. Please let me know if you encounter any other issues.

Using this technique when generating documentation in Mathematica 6 (with the method described in my other answer), along with Teake's techniques of generating the index in Mathematica 9 and writing a cross-version PacletInfo.m, seems to completely solve the cross-version documentation problem.

I was inspired by Teake's comment that he'd like to do something like If[$Version < 9., "More Information", "Details and options"] if it were possible. It turns out that it's not possible to include functions in cell contents, but functions can be included in cell options, as mentioned in the documentation here (bottom of the page).

• I couldn't call the "crossVersionReplacements" target from the "main" target, because the "docbuild" target has already loaded the J/Link library, and Ant doesn't want to load it a second time. Probably there's some other way around this, but I just called "crossVersionReplacements" from inside "docbuild", to piggyback on the already-loaded library.

• The "Details and Options" section heading should just read "Details" if there are no options for the function listed. To accomplish that, I search for the substring "option" or "Option" in the Details section, and replace the heading if no instances are found (other than in the heading itself).

• WRI added spacer cells at the beginning and ends of sections in the version 9 documentation, to obtain spacing that disappears when the sections are closed. To get a cross-version version of this, I added spacer cells in the appropriate places that display as very thin cells in pre-version 9 Front Ends.

• The Guide pages have been totally redesigned in version 9, so there's no way to match them exactly. In particular, the Tutorials heading and links have been completely restyled. I tried to give things a consistent look by undoing these changes, to match the Tutorials style with the style of the other sections. Update: I realized I could do this a little more simply by swapping out the cell style in the Tutorials heading for another section heading style.

• I encountered a rendering bug on the pre-version 9 Guide pages, affecting the layout on the whole page, which I found was triggered by the use of a non-integer value for a frame specification in the Abstract text. I adjusted the value to avoid the bug.

• To get the total number of examples on a symbol page, I added together the existing example counts for all of the example subsections.

• I learned some interesting things along the way, such as that the box representation of a Spacer is given by

    ToBoxes@Spacer[24]
  

     InterpretationBox[StyleBox[GraphicsBox[{}, ImageSize -> {24, 0},   
         BaselinePosition -> Baseline], "CacheGraphics" -> False], Spacer[24]]
  

• Update 3: In testing on Windows, I found that when a magnification level of less than 100% is chosen for the documentation notebook, the cell frame label is reduced by a different amount than the enclosing cell, causing layout errors. These are the same glitches as Teake reported seeing in OS X. There isn't much we can do about the different magnification factors. (Mathematica's magnification functionality has always been a bit of a crapshoot.) However, a workaround is to increase the width of the frame label cell, so as to run the rendering glitch right off of the page. This is implemented in the updated code. Please let me know if you encounter any other issues.

This is a workaround for Point 5 in the question, allowing cross-version documentation to be built that fixes the layout and text problems in version 9, while still displaying correctly in versions 6--8.

Update 4: The code in this answer has been incorporated into @jkuczm's WWBCommon package. I encourage everyone creating cross-version documentation in Workbench to use it.

This is a workaround for Point 5 in the question, allowing cross-version documentation to be built that fixes the layout and text problems in version 9 (and 10), while still displaying correctly in versions 6--8.

Update 3: I uncovered a rendering bug on Windows when viewing the doc pages at different magnification settings, which may also be related to the reported rendering glitches on OS X. The new version of the code implements a workaround for the bug on Windows (see the Notes section, below), which should hopefully fix the problems on OS X as well. There still hasn't been any testing on Linux. Feedback is appreciated.

• I couldn't call the "crossVersionReplacements" target from the "main" target, because the "docbuild" target has already loaded the J/Link library, and Ant doesn't want to load it a second time. Probably there's some other way around this, but I just called "crossVersionReplacements" from inside "docbuild", to piggyback on the already-loaded library.

• The "Details and Options" section heading should just read "Details" if there are no options for the function listed. To accomplish that, I search for the substring "option" or "Option" in the Details section, and replace the heading if no instances are found (other than in the heading itself).

• WRI added spacer cells at the beginning and ends of sections in the version 9 documentation, to obtain spacing that disappears when the sections are closed. To get a cross-version version of this, I added spacer cells in the appropriate places that display as very thin cells in pre-version 9 Front Ends.

• The Guide pages have been totally redesigned in version 9, so there's no way to match them exactly. In particular, the Tutorials heading and links have been completely restyled. I tried to give things a consistent look by undoing these changes, to match the Tutorials style with the style of the other sections. Update: I realized I could do this a little more simply by swapping out the cell style in the Tutorials heading for another section heading style.

• I encountered a rendering bug on the pre-version 9 Guide pages, affecting the layout on the whole page, which I found was triggered by the use of a non-integer value for a frame specification in the Abstract text. I adjusted the value to avoid the bug.

• To get the total number of examples on a symbol page, I added together the existing example counts for all of the example subsections.

• I learned some interesting things along the way, such as that the box representation of a Spacer is given by

    ToBoxes@Spacer[24]
  

     InterpretationBox[StyleBox[GraphicsBox[{}, ImageSize -> {24, 0},   
         BaselinePosition -> Baseline], "CacheGraphics" -> False], Spacer[24]]
  

• Update 3: In testing on Windows, I found that when a magnification level of less than 100% is chosen for the documentation notebook, the cell frame label is reduced by a different amount than the enclosing cell, causing layout errors. These are the same glitches as Teake reported seeing in OS X. There isn't much we can do about the different magnification factors. (Mathematica's magnification functionality has always been a bit of a crapshoot.) However, a workaround is to increase the width of the frame label cell, so as to run the rendering glitch right off of the page. This is implemented in the updated code. Please let me know if this fails to solve the problems on Windows or OS X, or you encounter any other issues.

Update 3: I uncovered a rendering bug on Windows when viewing the doc pages at different magnification settings, which was also reported on OS X. The new version of the code implements a workaround for the bug (see the Notes section, below). There still hasn't been any testing on Linux. Feedback is appreciated.

• I couldn't call the "crossVersionReplacements" target from the "main" target, because the "docbuild" target has already loaded the J/Link library, and Ant doesn't want to load it a second time. Probably there's some other way around this, but I just called "crossVersionReplacements" from inside "docbuild", to piggyback on the already-loaded library.

• The "Details and Options" section heading should just read "Details" if there are no options for the function listed. To accomplish that, I search for the substring "option" or "Option" in the Details section, and replace the heading if no instances are found (other than in the heading itself).

• WRI added spacer cells at the beginning and ends of sections in the version 9 documentation, to obtain spacing that disappears when the sections are closed. To get a cross-version version of this, I added spacer cells in the appropriate places that display as very thin cells in pre-version 9 Front Ends.

• The Guide pages have been totally redesigned in version 9, so there's no way to match them exactly. In particular, the Tutorials heading and links have been completely restyled. I tried to give things a consistent look by undoing these changes, to match the Tutorials style with the style of the other sections. Update: I realized I could do this a little more simply by swapping out the cell style in the Tutorials heading for another section heading style.

• I encountered a rendering bug on the pre-version 9 Guide pages, affecting the layout on the whole page, which I found was triggered by the use of a non-integer value for a frame specification in the Abstract text. I adjusted the value to avoid the bug.

• To get the total number of examples on a symbol page, I added together the existing example counts for all of the example subsections.

• I learned some interesting things along the way, such as that the box representation of a Spacer is given by

    ToBoxes@Spacer[24]
  

     InterpretationBox[StyleBox[GraphicsBox[{}, ImageSize -> {24, 0},   
         BaselinePosition -> Baseline], "CacheGraphics" -> False], Spacer[24]]
  

• Update 3: In testing on Windows, I found that when a magnification level of less than 100% is chosen for the documentation notebook, the cell frame label is reduced by a different amount than the enclosing cell, causing layout errors. These are the same glitches as Teake reported seeing in OS X. There isn't much we can do about the different magnification factors. (Mathematica's magnification functionality has always been a bit of a crapshoot.) However, a workaround is to increase the width of the frame label cell, so as to run the rendering glitch right off of the page. This is implemented in the updated code. Please let me know if you encounter any other issues.