Documentation is of significant importance in any project, particularly with those that are not confined to a finite scope, and the GDMS is one such project. In a time series analysis system, there are an enormous number of possible features, therefore a careful balance must be drawn between the functionality and the documentation. We needed to maximise our coding time whilst still providing sufficient documentation to both meet the requirements and include all of the necessary information that be required by any future developers and users. This led to our decision to use a number of tools to assist with the documentation. Docbook is system for writing documents using SGML or XML. It facilitates structure and is well suited for writing books or papers of this kind. Unlike formal word processors, docbook greatly reduces the time spent on standardising the format of a document by providing a number of features. These include:- Ensuring title fonts are consistent in type and size Tables, equations and figures are listed Table of contents is included Document layout and text justification are automatic. The syntax used for docbook is SGML, which is very similar to HTML. As most of the group members were already familiar with this type of syntax, it greatly reduced the learning curve to use docbook, which might have otherwise rendered the process counter productive. Docbook is easy to automate, which was another determining factor in using this tool. Automation was achieved by using Docbook tools, a suite of programs used to generate the docbook output. The process is similar to compiling source code, utilising a makefile to target the desired files and build them. These files can then be structured in a hierarchical manner to ensure consistent and easy organisation. A typical document might contain a top level file, for example, thesis.sgml, which links the other files, such as timedomain.sgml and theory.sgml. This file also contains the top level information such as whether the document is a book or an article, in which case various pages are generated automatically by docbook accordingly. Thesis.sgml might also contains a preface and glossary and other such general information sections. The target SGML files are linked from the top level file by issuing a command specifying the target file. The following example illustrates a top level file for a simple book: <book> <bookinfo><title>Geodetic Date Modelling System: Thesis</title> <execute><cmd>builddb</cmd><input>authorgroup.sgml</input></execute> <execute><cmd>builddb</cmd><input>abstract.sgml</input></execute> </bookinfo> <chapter id="ch01"><title> Chapter 1 - Introduction and Theory</title> <execute><cmd>builddb</cmd><input>Introduction.sgml</input></execute> <execute><cmd>builddb</cmd><input>Theory.sgml</input></execute> </chapter> <chapter id="ch02"><title> Chapter 2 - Implementation</title> <execute><cmd>builddb</cmd><input>Implementation.sgml</input></execute> <execute><cmd>builddb</cmd><input>Conclusion.sgml</input></execute> </chapter> <chapter id="ch03"><title> Chapter 3 - Conclusion</title> <execute><cmd>builddb</cmd><input>Conclusion.sgml</input></execute> </chapter> </book> The above example describes a simple book with three chapters. Each of the target SGML files would in turn be divided into section within the chapter. This method of documentation has its benefits, some of these being:- Documentation changes need only be made in the one place, in this case a single file. This is advantageous in case where text is repeated, much like the re-use concept in programming. Formatting and layout issues are dealt with by docbook. The layout conforms to a general standard adhered to by a large majority of publishers. Table of Contents and indexing of equations and figures are dealt with automatically by docbook. Our use of docbook, however, was not altogether seamless. We found version inconsistencies in different Linux distributions, and even after updating all of the development machines to use the same version of docbook, we ran into further trouble. It would seem that different distributions are not consistent when it came to building the documentation. An example of this, is that on some of the machines, although the docbook scripts would build the document, it was incomplete. This was due to the fact that SGML syntax errors were not being caught by the scripts and as a result, later in the build process when the build finally broke, it was extremely difficult to determine exactly where the problems originated. The same docbook version used on a different distribution caught the SGML errors allowing us to debug and fix any problems. Furthermore, the templates on the different distributions varied such that page numbering was not always consistent. This was even found to be the case on different versions of the same distribution. To overcome these issues, we simply generated the final submission of the documentation using the most suitable template. Autodocbook is tool employed for the documentation of source code. It is a simple Perl script designed to parse C or C++ source files extracting comment blocks within specific tags and turning them into docbook SGML files. These can then be used to create man pages, info pages and HTML documentation. This again serves to minimise the need to make changes in several places, for example, if comments need to be changed for a specific class or file, it is done in the class file and the Autodocbook script is run again. The second situation is in the creation of the other possible documents, such as man pages, info pages and HTML files. The appropriate conversion script is run on the target files and the task is complete.