Making a working copy of the legacy documentation for version 5 inside new versions of Mathematica

Question

In new versions of Mathematica we have fully functional old-fashioned Mathematica Help Browser. But the legacy documentation of version 5 is not included in new versions of Mathematica. This legacy documentation takes only 209 МB of disk space and it would be useful to have it accessible from within the new versions of Mathematica.

Having Mathematica 5.2 and Mathematica 7 or 8 installed on the same machine, how can one make the legacy documentation accessible from within a new version through the old-fashioned Help Browser?

I tried to copy the Documentation folder from

C:\Program Files\Wolfram Research\Mathematica\5.2\Documentation

to

C:\Documents and Settings\All Users\Application Data\Mathematica\Application\LegacyDocumenation

and inside of the legacy Help Browser now appear "Help Browser" as an AddOn. But it does not work properly.

Some useful information on tuning the appearance of the Help Browser in Mathematica 5 can be found here. But I do not know how to apply this to new versions of Mathematica.

Answer 1

The solution

Incidentally I have found the way to add all Mathematica 5.2 documentation to the legacy Help Browser in new versions of Mathematica.

The key is the "HelpBrowserSetup.tr" file located in the directory (under Windows)

C:\Program Files\Wolfram Research\Mathematica\7.0\SystemFiles\FrontEnd\TextResources

One should replace its contents with:

@@resource HelpBrowserSetup
BrowserCategory["Help Browser", None, {
    HelpDirectoryListing[{"RefGuide"}, False],
    HelpDirectoryListing[{"AddOns"}, False],
    HelpDirectoryListing[{"MainBook"}, False],
    HelpDirectoryListing[{"OtherInformation"}, False],
    HelpDirectoryListing[{"GettingStarted"}, False],
    HelpDirectoryListing[{"Tour"}, False],
    HelpDirectoryListing[{"Demos"}, False],
    BrowserCategory["Master Index", None, {HelpMasterIndex[]}]
}]

Then, the "Documentation" folder from the $InstallationDirectory of Mathematica 5.2 should be copied to the $InstallationDirectory of new version of Mathematica with replacement (one unimportant file will be replaced). Another possibility is to copy it to directory (under Windows)

C:\Documents and Settings\All Users\Application Data\Mathematica

(probably the $UserBaseDirectory is also appropriate).

Now start Mathematica and evaluate

FrontEndTokenExecute["HelpDialog"]

The legacy Help Browser will open and will contain all the documentation from the version 5.2!

Edit

I just have found even simpler solution. One may modify the "HelpBrowserSetup.tr" file as follows:

@@resource HelpBrowserSetup
HelpDirectoryListing[SystemHelpPath, False, True, True]

(or simply copy with replacement this file from the version 5.2 installation to the new version's folder).

Addition for those who have Mathematica 5.2 installed

You need not to copy the Documentation. You have two possibilities:

1.) Copy only the "HelpBrowserSetup.tr" file from the version 5.2 installation to new version's folder. Then evaluate something like

SetOptions[$FrontEnd, 
 SystemHelpPath -> 
  Union[SystemHelpPath /. 
    Options[$FrontEnd, 
     SystemHelpPath], {"C:/Program Files/Wolfram \
Research/Mathematica/5.2/"}]]

(where "C:/Program Files/Wolfram Research/Mathematica/5.2/" is the $InstallationDirectory of Mathematica 5.2).

2.) Just modify the "HelpBrowserSetup.tr" file as follows (but in this case all installed pre-version 6 Add-Ons will not appear in the legacy Help Browser):

@@resource HelpBrowserSetup
HelpDirectoryListing[{"C:/Program Files/Wolfram Research/Mathematica/5.2/"}, False, True, True]

and then evaluate

FrontEndTokenExecute["RebuildHelpIndex"]
FrontEndTokenExecute["HelpDialog"]

P.S. Adding Help Browser item to the Help menu

For this we just need to add row MenuItem["Help Browser...", "HelpDialog"], in appropriate place in MenuSetup.tr:

HelpMenu["&Help", 
{
    MenuItem["Documentation &Center", "OpenHelpLink"],
    MenuItem["Help Browser...", "HelpDialog"],

Answer 2

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:

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:

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:

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

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.