ColdFrame: Documentation

Introduction

ColdFrame can generate HTML-formatted documentation from your model.

At first sight this may seem unnecessary. However, there are at least three reasons why it may be helpful:

• It shows what is actually present in the model. It's very easy to omit things from a diagram in the CASE tool, giving a misleading impression: for example, a forgotten transition on a state diagram.
• It is in a more amenable format for comparison than typical model files. You can generate documentation for the model as it was and as it is now, and use Microsoft Word (or possibly Libre Office) to compare the two documents for review.
• It is hyperlinked.

Installation

No special installation is needed, but diagram generation depends on Graphviz.

Normally you should have Graphviz's binary directory on your PATH: if not, set the environment variables DOT and CIRCO to the locations of dot and circo respectively.

Use

Assuming you have set up your Makefile using the supplied Makefile.inc, simply say

make Domain.html

or, if you don't want diagrams (easier to do comparisons, perhaps; or maybe you can't install Graphviz),

make Domain.html GENERATE_DIAGRAMS=no

Images will be created in the subdirectory Domain.images/, which needs to be copied with Domain.html.

Notes

ColdFrame normalizes names to match the conventions of the target language, currently Ada. This means that a model name such as air traffic controller will appear in generated documentation as Air_Traffic_Controller.