Tuesday, 23 February 2010

Documentation Formats

NAG documentation is available in several formats. For the Fortran Library, the following formats are available:

  • XHTML XHTML + MathML files, one per routine, with XHTML tables of contents.
  • PDF Individual PDF files, for each document, with additional HTML navigation pages.
  • Single File PDF A single PDF file essentially being a repackaging of the individual PDF files.
  • Windows Help File Windows HTML help is essentially a compressed archive of HTML+MathML files derived from the XHTML+MathML documentation, together with additional index and navigation controls.

The C Library documentation, which is largely derived from the same source, is available in similar formats.

In addition, documentation for other interfaces are available, also usually generated from the same (XML) source. For example, the NAG Toolbox for MATLAB documentation is available as a MATLAB help file (essentially a jar archive of customised HTML files) and as a collection of PDF files with HTML tables of contents for ease of navigation. The NAG Library for .NET, currently in beta test, provides the documentation in two forms, a “classic” Windows HTML help file and also a MSHelp2 file, which integrates as a help collection into Visual Studio when the product is installed.

Historically the documentation has been provided in other formats, for example Dynatext, and looking forward we hope to make the documentation available using whatever technology provides the right level of stability and typesetting quality for the devices in use. For the future we hope that (especially) the ability to generate richly structured (X)HTML will provide the necessary flexibility. Many of the currently available formats, such as Windows help and formats for e-books are essentially packaged, compressed, HTML files. Using an HTML base rather than say, PDF, one is forced to sacrifice some typesetting quality, but gain a lot of flexibility enabling the documents to be read in novel ways. An iphone being used to browse the (XHTML) NAG documentation for example.

Even without changing the format used, there are issues in keeping up with technology. Currently, for example we generate PDF versions of our documents using a relatively old version of Acrobat Distiller. More recent versions of Acrobat use some new language features to make much smaller PDF files, at the price of loss of compatibility with older readers. It is hard to know if support for older PDF readers matters or not (does it?), but the bandwidth savings, and space on restricted media such as CD, probably mean that we will switch at some point. Another potential change is the upcoming HTML5 revision of HTML. Currently, in order to get the best possible mathematical rendering, we use MathML in our documentation, but this currently necessitates the use of XHTML rather than HTML, which unfortunately makes things slightly harder to set up in the browser. HTML5 promises to specify the parsing of MathML within HTML documents, so hopefully in future this complication will be gone, and also, the prominence given to MathML by its reference from HTML5 may encourage more browser makes to add native MathML support.

So …

  • Do you prefer the single file versions (single file PDF, Windows help) or the multiple file versions (individual PDF or HTML files?
  • At what point is it acceptable to move to newer PDF or HTML standards?
  • How important is it that documentation for alternative interfaces take on the style of the documentation in the host environment? (For example, NAG Toolbox for MATLAB documentation using a similar style to MATLAB, or the NAG Library for .NET documentation using a .NET/MSDN style.)
  • What other features would you like in the product documentation?

3 comments:

  1. NAG's documentation is among the best in the business IMHO and the fact that it is available in so many formats is a big bonus.

    For environments such as MATLAB, I think that it is vital that the NAG documentation takes the form of the host environment otherwise it will not appear as well integrated.

    Why worry about restricted media such as CDs? Everyone (everyone I know at least) uses DVDs these days.

    ReplyDelete
  2. I use either the XHTML or the single file PDFs. Happy with newer PDF, don't know about HTML5.

    Call me old-fashioned, but I would also like to have unix man pages. These would be particularly useful for when one just needs to quickly check the argument list for a routine.

    Finally, an illuminated manuscript version for special occasions :-)

    ReplyDelete
  3. Ed,

    A very simple man page along the lines of the NAG Toolbox for MATLAB ASCII help comments would be possible, with just the one line short routine description and the syntax declaration. Including more text would cause complications with the (lack of) math typesetting support in the classic nroff man macros.

    On your last point, this fragment turned up recently, perhaps the rest of the document can be found…

    ReplyDelete

NAG moderates all replies and reserves the right to not publish posts that are deemed inappropriate.