WARNING: I recently learned that building the index for new documentation can have undesired effects in a windows machine. Please read Alexey's comments for more details. As far as I can tell, everything is working fine in Mac OS X. I'll give an update once I determine what the source of the problem is.
Here I present a function to allow any notebook to become part of the documentation center in Mathematica 8. You can start by letting Mathematica evaluate the following:
Clear[FormatDoc, AddDocs];
FormatDoc[dir_, last_, num_, appName_, pacFile_, index_] :=
Module[{dirs, nbs, nb, str, comma = ",", title, tags},
nbs = FileNames[dir <> "/*.nb"];
dirs = FileNames[dir <> "/*"];
Do[If[last && i == Length@nbs, comma = ""];
str = FileNameDrop[nbs[[i]], {1, num}];
title = StringDrop[FileNameTake[nbs[[i]]], -3];
Print[Row[{Style["Adding: ", "MSG", Black],
Style[str, "MSG", Blue]}]];
str = StringDrop[str, -3];
WriteString[pacFile,
"\t\t\t\t\"" <> str <> "\"" <> comma <> "\n"];
nb = NotebookOpen[nbs[[i]]];
tags =
DeleteDuplicates@
Flatten@Map[#[[2]] &,
Cases[NotebookGet[
nb], (_Dummy | (CellTags -> _)), \[Infinity]]];
SetOptions[nb,
DockedCells ->
FEPrivate`FrontEndResource["FEExpressions", "HelpViewerToolbar"],
Saveable -> False,
WindowTitle ->
"Mathematica 5.2 | " <> FileNameDrop[str] <> " | " <> title,
TaggingRules -> {"ModificationHighlight" -> False,
"Metadata" -> {"context" -> appName <> "`", "keywords" -> tags,
"index" -> True,
"label" -> "Mathematica 5.2 | " <> FileNameDrop[str],
"language" -> "en", "paclet" -> appName, "status" -> "",
"summary" -> ToString@tags, "synonyms" -> {},
"title" -> title, "windowtitle" -> title, "type" -> "Doc",
"uri" ->
StringReplace[FileNameJoin[{appName, str}], "\\" -> "/"]},
"SearchTextTranslated" -> "", "LinkTrails" -> ""}];
NotebookSave[nb];
NotebookClose[nb];
DocumentationSearch`AddDocumentationNotebook[index, nbs[[i]]];, {i,
Length@nbs}];
Do[If[DirectoryQ[dirs[[i]]], str = FileNameDrop[dirs[[i]], {1, num}];
Print[
Row[{Style["Adding from: ", "MSG", Black],
Style[str, "MSG", Gray]}]];
FormatDoc[dirs[[i]], last, num, appName, pacFile, index];], {i,
Length@dirs}]]
AddDocs[appName_] :=
Module[{appDir, appDocs, dirs, pacFile, index, indexDir, str, num},
appDir = FileNameJoin[{$UserBaseDirectory, "Applications"}];
appDocs =
FileNameJoin[{appDir, appName, "Documentation", "English"}];
indexDir = FileNameJoin[{appDocs, "Index"}];
dirs = FileNames[appDocs <> "/*"];
If[Length@dirs == 0,
Print[Style["There are no documents to add... ", "MSG", Orange]];
Return[]];
Print[Row[{Style["Working in: ", "MSG", Black],
Style[appDocs, "MSG", Red]}]];
num = Length@FileNameSplit[appDocs];
index =
DocumentationSearch`NewDocumentationNotebookIndexer[indexDir];
pacFile = OpenWrite[FileNameJoin[{appDir, appName, "PacletInfo.m"}]];
WriteString[pacFile, "Paclet[
Name -> \"" <> appName <> "\",
Version -> \"5.2.0\",
MathematicaVersion -> \"7+\",
Extensions -> {
{
\"Kernel\",
\"Context\" -> {
}
},
{
\"Documentation\",
Language -> \"English\",
LinkBase -> \"" <> appName <> "\",
Resources -> {\n"];
Do[If[DirectoryQ[dirs[[i]]], str = FileNameDrop[dirs[[i]], {1, num}];
Print[
Row[{Style["Adding from: ", "MSG", Black],
Style[str, "MSG", Gray]}]];
FormatDoc[dirs[[i]], i == Length@dirs, num, appName, pacFile,
index];], {i, Length@dirs}];
WriteString[pacFile, "\t\t\t}
}
}
]\n"];
Close[pacFile];
DocumentationSearch`CloseDocumentationNotebookIndexer[index];
PacletManager`RestartPacletManager[];]
How to use it:
In a new document or the same one where you evaluated the functions start by finding out what this variable is:
$UserBaseDirectory
In my case, since I'm using Mac OS X I get:
/Users/jmlopez/Library/Mathematica
Find out what yours is. In this directory you should see the folder Applications. Inside Applications create the folder where you will be placing the MMA5 documentation. I named my folder MMA5 because it is short but you can give it any name you want, in the case of Alexey we can call it LegacyDocumentation. Inside this folder transfer a copy of the folder named Documentation found in the installation directory for MMA5.
We are almost done. Now call the function AddDocs. This function takes only one argument: The name of the application whose documentation we wish to add. In my case, since I named the folder MMA5 I will call it as follows:
AddDocs["MMA5"]
The next thing you should see is a sequence of notebooks appearing and disappearing as well as a sequence of messages being printed. Here is part of that sequence of messages:
![Output]()
Since the documentation of MMA5 is quite extensive this process will take a while. I did a timing on this function and it said it took about 40 seconds (It seemed a lot longer to me).
You are done. The documentation of MMA5 should now be available in the documentation center.
Test Drive
Say you wish to look up some information on DSolve. If you search for DSolve you see the following:
![DSolve MM8]()
To look up for the MMA5 documentation we need to click on the link for DSolve located in "Search for all pages containing DSolve". Now we obtain something like this:
![DSolve MM5]()
In the above screenshot I have marked in red the entries that give us access to the Mathematica 5 documentation. I have no way of writing a nice summary for each of the files in the documentation so I just made Mathematica write the CellTags located in the notebooks. This is why you see a list of strings.
If you click on the first red entry this is what we obtain
![Jackpot]()
So there you have it, a working copy of legacy documentation working on the new version of Mathematica. I have not tested this in MMA7 but I have a feeling it would work. If someone tries this please let me know.
NOTES
If you want to apply this to other documents in a different application. You need to pay attention to this:
WindowTitle ->
"Mathematica 5.2 | " <> FileNameDrop[str] <> " | " <> title,
TaggingRules -> {
"ModificationHighlight" -> False,
"Metadata" -> {
"context" -> appName <> "`",
"keywords" -> tags,
"index" -> True,
"label" -> "Mathematica 5.2 | " <> FileNameDrop[str],
"language" -> "en",
"paclet" -> appName,
"status" -> "",
"summary" -> ToString@tags,
"synonyms" -> {},
"title" -> title,
"windowtitle" -> title,
"type" -> "Doc",
"uri" ->
StringReplace[FileNameJoin[{appName, str}], "\\" -> "/"]
},
Notice that I have hardcoded "Mathematica 5.2" in the label. You may even want to change this to "LegacyDocumentation" if you want. This is just a label. Another important point is
the keywords. I have set keywords to the variable tags. Every cell in a notebook has the option to add CellTags. If you are going to write some documentation you should use them. I have taken advantage of this to let the documentation center know how to search for the documents. This is something I have just recently learned and I will definitely implement in a package.
If you ever feel like writing a complete application with its documentation I suggest you take a look at my post integrating notebooks to MMA doc center. Here you will find more information that will let you figure out how the functions I have provided here work.
As a final note I'd like to add that I have also tested this in windows machine and it worked fine, that's the reason behind this line of code:
StringReplace[FileNameJoin[{appName, str}], "\\" -> "/"]
EDIT:
I changed the function so that it can correctly work in MMA7. Turns out that the pacletInfo.m file needs to have the line MathematicaVersion -> 7+ so that it can work in MMA7 and MMA8.
EDIT 2:
I made a mistake while copying and pasting the function. It should be fixed now. If you have both MMA7 and MMA8, I suggest running it only once in MMA7. That way the documentation will be available to both MMA7 and MMA8.
