The documentation for the NAG Toolbox for MATLAB aims to integrate as far as possible with the host MATAB environment and provide the same integrated documentation experience as found with built in MATLAB functions.

MATLAB is itself in continuous development with a 6-month release cycle. New features appear in the MATLAB GUI, and as far as possible we try to use these features if it is possible to keep the documentation working on all the versions of MATLAB that we support.

THE FUNCTION BROWSER

One relatively new feature, added at MATLAB release 2008b is the function browser. This is available in the help menu, or by pressing Shift-F1 (or equivalent keyboard shortcut, depending on platform and local customisation). It is essentially a modified table of contents to (just) the function reference pages, with built in search box and popup windows showing abbreviated summary documentation.

Currently the functions of the NAG Toolbox do not show up in this function browser, however this has now been enabled in the development builds and should, subject to final testing, be appearing in newer releases of the toolbox scheduled for later in the year. the following screenshot shows how it should look:

The screenshot shows the drop down function menu showing the hierarchical table of contents for the NAG Toolbox functions, and a popup help box showing a summary for c05aj that appears if the mouse hovers over that entry. These tooltips may be “torn off” the function browser in which case they stay in the GUI and can be positioned as desired, this is shown by the summary for c05ad that is still visible.

In order to make this work the function browser (apparently) looks for certain named sections on the function's reference page, and so I have had to change the section titles from being numbered to unnumbered, Purpose, Syntax, Description rather than 1 Purpose, 2 Syntax, 3 Description as in the current documentation. The tooltip essentially shows the Description section. I should also note that while versions of the function browser appeared in MATLAB 2008b, the internal details were apparently different and at the time of writing, with the development build, the NAG functions appear in Function Browsers in MATLAB versions starting from 2009b. (The screenshot is of MATLAB 2010a).

Improving the doc function

One way of accessing the function reference page (html documentation) is to open the help browser and then navigate the table of contents or search to obtain the documentation for the function required. This of course works for the NAG Toolbox as well as for built in MATLAB functions. However when working on a function in the command window, an alternative method of accessing documentation is to use the doc function. Unfortunately (for several MATLAB releases) doc is now documented as only working for MATLAB functions built into MATLAB, or supplied in MathWorks Toolboxes. A command such as doc s18ad does not bring up the full html reference page, but opens the help browser with a summary information derived from the ASCII comments in the s18ad.m file, which is the information produced by the command help s18ad. Fortunately the docsearch function does work, and one useful by-product of NAG's function naming scheme is that searching for the function name reliably returns the reference page as the most relevant result, and the reference page is displayed in the help browser. To make the doc and help information more useful, an HTML link invoking MATLAB's docsearch function has been placed into the comments and so, as shown in the following screenshot, in future, while doc s18ad does not bring up the full reference page, there is a hypertext link on the summary page that is displayed that will invoke docsearch s18ad and so the full reference page will be accessible with a single click.

Note that the phrase “NAG Toolbox Help Files” is now a hyperlink, with the status bar showing that clicking on it will activate the MATLAB command docsearch.

FUTURE IMPROVEMENTS

If you have any further ideas for improving the documentation or integrating with currently unused features in the MATLAB GUI, please do let us know!