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 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.
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.
Background:
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).
To control the display of content in a cell using options, we can use the option CellFrameLabels to effectively embed another cell into first cell. For example, to emulate a text cell with cell expression
Cell["hello world", "Text"]
we can create a cell that has cell expression
Cell["", "Text", CellFrameLabels->{{Cell["hello world","Text"],None},{None,None}}]
(To edit the cell expression for a cell, put the cursor in the cell and choose "Show Expression" from the Cell menu. Then edit, and choose "Show Expression" again to toggle back to the display form.)
Functions used in the cell expression are evaluated in the Front End. That means, unless we use Dynamic (not recommended for evaluation overhead reasons), we are limited to Front End functions defined in the context FEPrivate`. To get a (partial) list of these functions, we can evaluate Names["FEPrivate`*"]. Some of the functions apparently don't show up in the list until after you have already evaluated them, however, adding some mystery to the process of finding these functions.
To see the result of a Front End function call returned directly as output, you can make a call to the Front End from a regular Input cell using wrapper functions, like so:
MathLink`CallFrontEndHeld[FrontEnd`Value[FEPrivate`$ProductVersion]]
"9.0"
As an example of a text cell with conditional text, we can use the Front End functions FEPrivate`Switch and FEPrivate`$ProductVersion to create a text cell that displays the version of Mathematica in which it is viewed:
Cell["", "Text",CellFrameLabels->{{
FEPrivate`Switch[
FEPrivate`$ProductVersion,
"6.0",Cell["6.0","Text"],
"7.0",Cell["7.0","Text"],
"8.0",Cell["8.0","Text"],
"9.0",Cell["9.0","Text"],
True,Cell["Unknown","Text"]
],
None},{None,None}}]
Now we can apply this to fixing the documentation layout problems in version 9. The problems I want to fix are
- Change boxed "MORE INFORMATION" to "Details and Options" or "Details", as appropriate
- Change other section headings from ALL CAPS to Title Case in Symbol, Tutorial, and Guide pages
- Fix spacing before and after section headings
- Style the Tutorial section heading in Guide pages to match other section headings
- Style the tutorial links on Guide pages to match links in other sections
- As a bonus, put the count of the total number of examples in each Symbol page after the Examples section heading, as has been added in version 9
- Update 2: Get proper opener behavior for the section header cells, where clicking anywhere in the cell opens/closes the section
This is accomplished using Mathematica code in the docbuild.xml file to read in each doc nb file (after all doc files have been built), make the necessary replacements, and save it again.
The Code (update 3):
Add somewhere to the docbuild.xml file (for example, near the end, just before the line reading </project>):
<target name="main" depends="clean">
<antcall target="docbuild" />
</target>
<target name="crossVersionReplacements">
<mathematica exe="${mathExe}">
<![CDATA[
(* Start Front End *)
Developer`InstallFrontEnd[];
(* Get all .nb files from build directory *)
outputDir = AntProperty["dist"];
files = FileNames["*.nb", outputDir, Infinity];
AntLog["Running cross-version replacements on "<>ToString@Length@files<>" files in "<>outputDir];
(* Function to discriminate between versions 6--8 and 9 *)
IfPreVer9[pre_, post_] := FEPrivate`If[
FEPrivate`Or[FEPrivate`SameQ[FEPrivate`$ProductVersion, "6.0"],
FEPrivate`SameQ[FEPrivate`$ProductVersion, "7.0"],
FEPrivate`SameQ[FEPrivate`$ProductVersion, "8.0"]],
pre, post];
(* Section spacer that displays as very thin cell in versions 6--8 *)
mySectionSpacer[sty_] = Cell["", sty,
CellSize -> IfPreVer9[{Inherited, 1}, Inherited],
CellElementSpacings -> {CellMinHeight ->
IfPreVer9[1, Inherited]},
CellMargins -> IfPreVer9[0, Inherited],
Editable -> False, Selectable -> False, Deletable -> False,
ShowCellBracket -> False, ShowSelection -> False];
(* List of styles for section headings that we will do replacements on *)
headingStyles = {
"GuideMoreAboutSection",
"GuideTutorialsSection", "MoreAboutSection",
"MoreInformationSection",
"PrimaryExamplesSection", "RelatedDemonstrationsSection",
"RelatedLinksSection", "SeeAlsoSection",
"TutorialsSection",
"RelatedTutorialsSection", "TutorialMoreAboutSection",
"TutorialRelatedLinksSection", "NotesSection",
"GuideRelatedLinksSection"
};
(* Utility functions*)
myspacer = Cell[BoxData[ToBoxes[Spacer[24]]]];
toTitleCase[str_String] :=
StringReplace[ToLowerCase[str],
WordBoundary ~~ x_ :> ToUpperCase[x]];
framelabelopts = {CellSize -> {5000, Inherited}};
cellopts = {"WholeCellGroupOpener" -> True,
CellFrameLabelMargins -> 0,
CellElementSpacings -> {"CellMinHeight" -> 3},
CellSize -> {Inherited, IfPreVer9[11, 14]}};
(* Loop over files *)
Do[
(* Importing nb files containing Manipulate objects can throw a bunch of benign newline interpretation warnings *)
Quiet[expr = Get[file];, Syntax::newl];
(* Convert section headings to Title Case in version 9 *)
expr = expr /. {
(*"MORE INFORMATION" section-- get rid of frame*)
Cell[con_, sty : "NotesSection", o___] :>
Cell["", sty, Sequence @@ cellopts, o, CellFrameLabels -> {{
IfPreVer9[
Cell[con, sty, Sequence @@ framelabelopts],
con /. TextData[Cell[BoxData[box : ButtonBox[__]]]] :> TextData[box] /.
box_FrameBox ->
Cell[TextData[{myspacer, "Details and Options"}],
"NotesSection", Sequence @@ framelabelopts]
], None}, {None, None}}],
(*Guide Tutorials section-- need to mimic standard version 9 section style*)
Cell[con_, sty : "GuideTutorialsSection", o___] :>
Cell["", sty, Sequence @@ cellopts, o,
CellMargins ->
IfPreVer9[Inherited, {{Inherited, Inherited}, {Inherited, 20}}],
CellFrameLabels -> {{
IfPreVer9[
Cell[con, sty, Sequence @@ framelabelopts],
con /. str_String ->
Cell[TextData[{myspacer, toTitleCase[str]}], sty,
Sequence @@ framelabelopts]
], None}, {None, None}}],
(*Examples section-- add placeholder for total example count*)
Cell[con_, sty : "PrimaryExamplesSection", o___] :>
Cell["", sty, o, Sequence @@ cellopts, CellFrameLabels -> {{
IfPreVer9[
Cell[con, sty, Sequence @@ framelabelopts],
con /. (ButtonBox[str_String, bbo___] :>
ButtonBox[
Cell[TextData[{myspacer, toTitleCase[str], " ",
"InsertExampleCount"}], sty,
Sequence @@ framelabelopts], bbo])
], None}, {None, None}}],
(*All other section headings with text only in the title*)
Cell[con_String, sty : Alternatives @@ headingStyles, o___] :>
Cell["", sty, Sequence @@ cellopts, o, CellFrameLabels -> {{
IfPreVer9[
Cell[con, sty, Sequence @@ framelabelopts],
Cell[TextData[{myspacer, toTitleCase[con]}], sty,
Sequence @@ framelabelopts]
], None}, {None, None}}],
(*All other section headings with buttons in the title*)
Cell[con_, sty : Alternatives @@ headingStyles, o___] :>
Cell["", sty, Sequence @@ cellopts, o, CellFrameLabels -> {{
IfPreVer9[
Cell[con, sty, Sequence @@ framelabelopts],
con /. (ButtonBox[str_String, bbo___] :>
ButtonBox[
Cell[TextData[{myspacer, toTitleCase[str]}], sty,
Sequence @@ framelabelopts], bbo])
], None}, {None, None}}]
};
(* Replace "Details and Options" with "Details" if there is no mention of options in the notes section *)
expr = expr /.
notescell : CellGroupData[{Cell["", "NotesSection", ___], ___}, ___] :>
(notescell /. If[
Count[notescell, str_String /; ! StringFreeQ[str, {"option", "Option"}], Infinity] > 1,
{},
"Details and Options" -> "Details"
]);
(* Add total example count to Examples section heading in version 9 *)
expr = expr /. (examplegroup : Cell[CellGroupData[{Cell[_, "PrimaryExamplesSection", ___], ___}, ___], ___]) :>
(examplegroup /. "InsertExampleCount" ->
Cell["(" <>
ToString[Total@Cases[examplegroup, Cell[countstring_, "ExampleCount"] :> ToExpression[countstring], Infinity]] <>
")", "ExampleCount"]
);
(* Add spacers before and after section content in version 9 *)
expr = expr /. {Cell[
CellGroupData[{c1 : Cell[_, "SeeAlsoSection", ___], c2__}, o2___], o3___] :>
Cell[CellGroupData[{c1, c2}, o2], o3],
Cell[CellGroupData[{c1 : Cell[_, "PrimaryExamplesSection", ___], c2__}, o2___], o3___] :>
Cell[CellGroupData[{c1, c2, mySectionSpacer["SectionFooterSpacer"]}, o2], o3],
Cell[CellGroupData[{c1 : Cell[_, Alternatives @@ headingStyles, ___], c2__}, o2___], o3___] :>
Cell[CellGroupData[{c1, mySectionSpacer["SectionHeaderSpacer"], c2, mySectionSpacer["SectionFooterSpacer"]}, o2], o3]};
(*Fix button behavior in Example subsections*)
expr = expr /.
Cell[con__, sty : "ExampleSection" | "ExampleSubsection", o___] :>
Cell[con, sty, "WholeCellGroupOpener" -> True, o];
(*Fix rendering bug pre-version 9 *)
expr = expr /.
Cell[c_, "GuideAbstract", o___] :>
Cell[c, "GuideAbstract", CellFrame -> IfPreVer9[{{0, 0}, {1, 0}}, Inherited], o];
(* Improve font appearance for tutorial links in Guide pages, and mimic section heading style for Guide Tutorial heading *)
expr = expr /. {"GuideTutorial" -> "GuideMoreAbout", "GuideTutorialsSection" -> "GuideMoreAboutSection"};
(* Save notebook using Front End *)
Developer`UseFrontEnd[NotebookSave[NotebookPut[expr], file]],
{file,files}];
]]>
</mathematica>
</target>
Then, at the end of (but inside) the "docbuild" target, just after the line reading
<antcall target="setupPaclet" />
add the line
<antcall target="crossVersionReplacements" />
This will call the replacement routine each time a doc build is done, and produce the cross-version files.
Some Notes:
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.
?symbolcommand resolves the ">>" link to the documentation on M9. But indeed searching M6 generated docs (including the index) seems to work fine on M9. However, I have it straight from the horse's mouth that the Paclet Manager in M9 was completely rewritten (from Java to C++) so docs (and specifically indices) built with earlier version cannot be expected to work reliably on M9. The other way around is guaranteed to work, as the paclet manager is forward compatible. $\endgroup$