Documentation Generator - Basic Principles

Documentation generation is founded on documentation templates (DTs). A set of documentation templates describes how the software documentation will look when completed. Software documentation is created by the process of generating documentation on the basis of documentation templates.

That is, each documentation template is an RTF document which contains clearly delineated parts - scripts. On the basis of each documentation template, DG generates one or more documents. The generated documents consist of content which also exists in the documentation template, with the difference that instead of script the generated documents contain content generated on the basis of the script.

Documentation generation

Script is written in a macro language specially developed for this purpose, DGML. DGML is a language for "programming" documentation. It encompasses a range of directives meant to ensure full control over the document generation process. DGML also, through predefined functions and data types, allows access to the large number of data contained in the DAC project. In this way it is possible to:

Display various kinds of reports: Browser reports, VCS reports, graphics reports.
All graphics reports are in WMF (Windows Meta File) format.
Display project data: data on the project itself, data on project objects, and data on messages.

Generating documentation is accompanied by checking the documentation template which results in an error report. Checking the documentation template identifies both syntactic and semantic errors and makes it possible to assess the serviceability and consistency of the generated documentation. Taking into account the potentially long time needed to generate documentation (for a large data set), checking documentation (as the more rapid process) can be performed independently of the documentation generation process.

DG also offers support for creating documentation templates. Creating and updating documentation templates is organized on the basis of cooperation between DAC and the external text-processor (DTE).

DG ensures interactive and intuitive forming of DGML scripts by means of the Wizard. You begin the operation by choosing a documentation object by activating or selecting it - the documentation object can be any content you want to document. You then access the Wizard. It allows you to document the documentation object by a simple choice of property's. Based on the property's selected, the Wizard create a complete set of DGML scripts and inserts it directly into the active documentation template or onto the Clipboard.

DG supports basic operations for manipulating documentation templates (opening existing ones, creating new templates). DG is also equipped with a range of standard documentation templates created in accordance with documentation templates.


Copyright 1993-2017, RistanCASE GmbH