Caution

Part of the information on this page comes from my exploration of the new documentation center, and not from official Wolfram documentation. It is up to you to ensure that this information is correct and meets your needs.

The problem

Prior to version 6, built-in Mathematica documentation was organised as a series of tree structures in something called the help browser. Anyone who wrote an add-on package was free to provide documentation which interfaced with this system.

Since version 6, the preferred documentation mechanism became the 'Documentation Center'(DC), although support for the old help browser still exists. If you have a package that uses the old-style documentation installed on your 7.0 system, you can access the help browser by opening the DC at its front page, and clicking on the "Add-Ons and Packages" link near the bottom of the page at the left. You will reach a list of installed packages. Packages with a triangular opener icon at their left use the new documentation, those with a small red square use traditional documentation.

Unfortunately, the only 'official' way to create documentation for the documentation center, is to use the Wolfram Workbench, whereas many, such as myself, prefer to operate directly in the frontend.

Digging deeper

If you look at the built-in GUIKit add-on package, you will see that its documentation is interfaced into the DC. This means, for example, that if you search for CloseGUIObject, the relevant GUIKit documentation will appear. I have followed the directory structure of GUIKit in my (much simpler) DebugTrace package. I suggest you download this free package, and instal it temporarily to see how everything is organised.

As you will see, the main documentation is stored under:

\Documentation/English\Guides\DebugTrace.nb

with additional documentation stored under:

\Documentation\English\References\Symbols\*.nb

There is also another directory containing index files that are created as described below:

\Documentation\English\Index

(I am using the Windows backslash path separator here – adjust as required)

I suspect the additional structure beneath the English directory is arbitrary, but I chose to leave the scheme unchanged except that I did not need a "Widgets" directory. Inside the GUIKit directory, you will also find a file 'PacletInfo.m'. This contains a fairly complicated structure, but again you can find a much simpler version inside my DebugTrace Package:

(* ::Package::*)

(*Paclet Info File*)

(* Created 2009/4/7*)

Paclet[Name -> "DebugTrace",Version -> "0.993",MathematicaVersion -> "",Description -> "",

Extensions->{{"Documentation",Language -> "English",LinkBase -> "DebugTrace",Resources -> {

"Guides/DebugTrace",

"ReferencePages/Symbols/DTDebugExecute",

"ReferencePages/Symbols/DTLocalValue",

"ReferencePages/Symbols/DTRunDebugger"

}}}]

Modify this to suit the name of your package, and the exact locations of your documentation files, starting with your main documentation notebook. Note the forward slashes in this list.

At this stage, you should find that your main page of documentation will show inside the DC, but any other, symbol-specific, pages will not be accessible. It is worth ensuring that this is working before proceeding to the next phase of the process.

Creating an index

At this point, I suggest that you move the working copies of your documentation files outside the file structure described above. The files will be copied back in using the Mathematica program outlined here. This program changes the notebooks in various ways, including setting the notebook option Saveable->False – which is inconvenient in files you are editing. You may want to perform these steps on version 6.0, so that the resultant documentation works with both 6.0 and 7.0 – i.e. avoiding the creation of 7.0 specific notebooks.

Remove any files present inside the Index directory – I suspect that indexing more than once (i.e. on top of an existing index) can cause problems.

Execute a Needs command for the package you are developing.

Copy each file by:

1) Opening it: nb=NotebookOpen[.....

2) Make the notebook non-saveable. This lets users change your documentation on a temporary basis without being prompted to save the result – exactly as happens with the system documentation.

SetOptions[nb,Saveable->False]

3) Set the cell tag of the heading in each of the per-symbol notebooks, to the name of the corresponding symbol. For example, in DebugTrace, the heading in DTRunDebugger.nb has a tag of "DTRunDebugger" (derived not from the name of the file, but from the symbol it is documenting).

4) Set a notebook option called TaggingRules. Here is the one I use in DebugTrace:

SetOptions[nb,TaggingRules->{

"ModificationHighlight" -> False,

"Metadata" -> {

"context" -> "DebugTrace`", "keywords" -> {}, "index" -> True, "label" ->

"DebugTrace Package Paclet Symbol", "language" -> "en", "paclet" ->

"DebugTrace Package", "status" -> "", "summary" ->

fn::usage, "synonyms" -> {}, "title" -> fnname, "type" ->

"Symbol", "uri" -> "DebugTrace/ref/"<>fnname},

"SearchTextTranslated" -> ""}];

Where fn is the symbol corresponding to the name of the notebook, and fnname is the corresponding name. You do not need to change the TaggingRules option for the main page because it does not correspond to a symbol lookup. Note that each documented symbol should have a usage statement, which gets incorporated in the above structure (fn::usage), and appears in summary information inside DC searches.

5) Save the notebook in the appropriate place using NotebookSave. Note that this works even though the option Saveable->False has suppressed the ordinary save mechanism through the menus.

All that remains is to create the index information:

1) Create a document indexer object with a command such as:

ind=DocumentationSearch`NewDocumentationNotebookIndexer["C:\\MathematicaBase\\Applications\\DebugTrace\\Documentation\\English\\Index"];

Note that this is an absolute path name.

2) Add each document to the index (again using absolute paths):

DocumentationSearch`AddDocumentationNotebook[ind,path]

3) Close the document indexer:

DocumentationSearch`CloseDocumentationNotebookIndexer[ind];

Obviously, the above steps will typically be built into a small program that scans the relevant directories for files to copy, etc. Such code would also probably also generate the PacletInfo.m file, since the list of documentation files may not be fixed, and you will want to vary the version number. Code of this sort is in fact embedded in the DebugTrace.m file – accessible via the private function DebugTrace`Private`Create\[Breve]Documentation[].

Needless to say, this code should never run on a user's machine – it is present in DebugTrace purely for my convenience. It also references my directory structure, so you cannot use this code directly – just use it as a guide.

After you are done, close Mathematica completely, and restart – you should find your documentation is fully visible. Zip the complete tree of directories – including the index files, and your users should be able to enjoy the full use of the documentation center.

Note: The index files are clearly binary, and relate to the notebooks at the time of indexing. Although I have not tried this, I imagine that if you change the notebooks after indexing them, you might disrupt a user's frontend – so be sure to index as the final step.

Accessing package documentation from a program

To access the main page of a package, execute for example:

Documentation`HelpLookupPacletURI["DebugTrace"]

To access the documentation for a particular function, execute for example:

Documentation`HelpLookupPacletURI["DebugTrace/ref/DTLocalValue"]

To create a hyperlink, these strings should be prefixed with "paclet:", for example:

Hyperlink["DebugTrace","paclet:DebugTrace"]

and

Hyperlink["DTLocalValue","paclet:DebugTrace/ref/DTLocalValue"]