NAG Toolbox for MATLAB Documentation: Features in Development
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
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
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.
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!