Thursday, 27 May 2010

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 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!

Tuesday, 18 May 2010

Reflecting on 40 years of software development

As regular readers of this blog will know, NAG celebrated its fortieth anniversary on May 13th with a series of informal talks during the day and a dinner party in the evening. Over 200 people - members, collaborators, current and ex-staff - took part in what was a thoroughly enjoyable day. Katie, our Marketing Communications Manager and Queen of the Blogosphere, put together an amazing scrapbook with photographs going back to the early days. Somebody commented to me that a healthy proportion of the pictures involve food and drink - I guess thats just the sort of Company that we are ☺.

Talking to some of the older participants it was clear that - while computing has changed completely in the last four decades - many of the issues which faced the early NAG pioneers are still with us today. Portability remains a key concern, particularly since after a long period of relative stability we are seeing a great divergence in hardware and a smorgasbord of proprietary, non-standard mechanisms for parallel computing. How to satisfy users of different language has always been another issue. Its a little-known fact that the original aim of the NAG project was to produce an Algol 60 library and that the Fortran library that persists to this day was a secondary activity. Over the years we've produced libraries in Ada, Pascal, Fortran 90 and C, with only the latter still under active development. Alongside that work we've produced many bindings for other languages - the first work that I did for NAG was to produce C header files for the Fortran Library while a PhD student at the University of Bath.

Another area where NAG has always been at the forefront is computer-generated documentation. When I first visited NAG more than twenty years ago most of the routine documents were produced on a golfball typewriter, although there were computer-readable versions maintained by Mike O'Donohoe at Cambridge University. His ingenuity at laying out complex mathematical formulae using only ASCII characters was quite astonishing! From there we adopted TSSD (a UK-developed contemporary of TeX), LaTeX, SGML and now XML from which we produce both pdf and HTML variants.

I have a sneaking suspicion that when NAG hosts its fiftieth birthday in ten years time, some of these issues will still be causing us headaches. For every problem that is solved, another will arise. Last Thursday we reminisced about the days when RAM was measured in kilobytes and IEEE arithmetic had yet to be invented. In ten years we might find the idea of having only a single CPU on a computer quite quaint, and a new generation of functional programmers will struggle to understand what object-oriented languages are all about. Its hard to predict the future but, whatever the issues, I'm sure that NAG will be working hard to address them and to continue to deliver high-quality software to our customers.

Thursday, 13 May 2010

NAG's 40th Anniversary

NAG might be 40 years old today but the office feels like we are having a 21st birthday party with a real buzz about the place. Absolutely amazed that Jack Dongarra is in the building and about to give a seminar on the Impact of Architecture and Technology for Extreme Scale on Software and Algorithm Design having travelled from the States just to attend our Anniversary celebrations. Hopefully the weather will hold till later when we have afternoon tea and Pimms after hearing from our founding Directors Brian Ford and Steve Hague on how they created NAG and made it the success it is today.

Jack Dongarra Presenting at NAG's 40th Anniversary Open Day

Monday, 3 May 2010

Congratulations NAG Prize 2010 Winners!

Last week some of my colleagues attended the first Manchester SIAM Student Chapter conference at the University of Manchester. Going by the feedback it was a really good day with some great presentations by Professor Sven Hammarling (NAG), Professor Bill Lionheart and Dr Oliver Dorn (both of the School of Mathematics, University of Manchester) as well as many student presentations - so well done to those who organised the event.

John Holden (centre) and Craig Lucas (right) chat to an attendee of at the Manchester SIAM Student Conference

The NAG Student Prize was established in 2006 to recognise the long standing relationship NAG has with Manchester and reward the highest achieving students in maths and computation related courses. Mike Dewar, NAG Chief Technology Officer awarded this years prizes at a ceremony later in the day.We’re delighted that this years prizes go to Xiaolu Han and Michael Crabb for their outstanding work in the Mathematical Finance and Mathematics and Computational Science MSc courses respectively.

NAG Prize 2010 Winners Xiaolu Han and Michael Crabb with Mike Dewar, NAG Cheif Technical Officer (centre)

Congratulations and well done to both Xiaolu and Michael.