__Update 4:__ The code in this answer has been incorporated into @jkuczm's [WWBCommon package](https://github.com/jkuczm/WWBCommon). 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](http://mathematica.stackexchange.com/a/28505/8253)), along with Teake's techniques of [generating the index in *Mathematica* 9](http://mathematica.stackexchange.com/a/28321/8253) and [writing a cross-version `PacletInfo.m`](http://mathematica.stackexchange.com/a/28349/8253), seems to completely solve the cross-version documentation problem.
##Background:##
I was inspired by Teake's [comment](http://mathematica.stackexchange.com/questions/28316/creating-cross-version-compatible-documentation-with-workbench/28505#comment88377_28321) 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](http://reference.wolfram.com/mathematica/tutorial/WorkingWithStylesheets.html) (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](http://mathematica.stackexchange.com/questions/28316/creating-cross-version-compatible-documentation-with-workbench/28592#comment89356_28592). 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.