Interpreting Documentation Templates

During the documentation generation process, input documentation templates are interpreted. Interpreting a documentation template means copying its content into the generated document until the DGML script is reached. DGML script can be used to control the subsequent interpretation flow or to integrate data or reports on the DAC project into the generated document.

DGML script can be used to define:

1. Adding a document generated on the basis of another documentation template into the generated document

This enables you to generate one document on the basis of several documentation templates. This DGML capability is used to define the documentation model you want from several smaller existing documentation templates. For this purpose library documentation templates which you can add to the documentation templates which you are developing have been developed. In this way, you save time needed to develop documentation templates, and space needed to store them.

2. Saving a part of the generated documentation in a separate file

This allows you to generate multiple output documents on the basis of a single documentation template. When a DGML script which defines the beginning of a block in the documentation template on the basis of which a new output file is being generated is encountered while generating a documentation template, a new file with the assigned name is created. If a file with this name already exists, the index 1 (2,3,...) is added to the name of the file being created. The generated documentation is saved in a new file until the documentation template reaches the DGML script which marks the end of the new document. The saving operation is continued in the previous output file.

3. Multiple interpreting of the same part of the documentation template

This allows you to use a previously defined documentation template block for the documentation of a certain number of documentation objects, to document multiple documentation objects of the same type. In the DGML script, which is located at the beginning of block of the documentation template which is being repeated, the documentation object collection which is to be documented by the included block is entered. The block from the documentation template will be interpreted as many times as there are objects in the collection entered and with every pass through this block, one object from the collection entered will be documented.

4. Conditional interpretation of a part of the documentation template

DGML allows you to define blocks in the documentation template which will be interpreted during the documentation generation phase only if a certain condition has been satisfied. In the headers of such blocks is a DGML script with the condition on the basis of which the decision is made: whether to interpret the next block; or which of the next two blocks is to be interpreted.

5. Separating documentation object data

DAC contains a lot of data in its database. In DGML, all functions which separate documentation object(s) data are defined. Separated data is systematized in the form of previously defined structures. Special data structures are defined to represent data on various documentation objects. By interpreting DGML scripts with a function call for the systematization of data on the assigned documentation object, separated data are saved in the assigned output variables. The call of the function itself has no effect on the generated document. Certain components of separated structures with special scripts are saved in the generated document. In this way project data, browse report data, search report data and message data can be separated.

6. Inserting documentation object data into the generated document

Data separated from the DAC database by an appropriate function can be saved in the generated document. One script saves only one elementary type data in the documentation template.

7. Integrating VCS reports and source code into the generated document

The function call for integrating VCS reports and source code into documentation can be found in the DGML script. When interpreting such scripts, the content of the corresponding report or the specified part of the program source code is copied to the generated document.

8. Defining graphics ODs and their integration into the generated document

Reports generated by DAC in the form of figures can be integrated into the generated document: function flow-charts, call-graphs, type-graphs and metrics reports. For the picture to be integrated into the generated document, the DGML script in which the type of the graphics report to be generated is defined, on which project object it will be generated, how it will be generated must first be found in the documentation template. Then the script with the function call which defines how the generated report will be formatted (as a mosaic or a single figure, as a color or grayscale figure) can be followed, and finally the block which defines the figure is integrated into the documentation. Within this block in the documentation template there is a model figure on which additional figure formatting (frames, etc) can be set. If the figure was formatted as a mosaic, the figure integration block will be interpreted as many times as there are segments in the mosaic.

Comments are a special kind of DGML script. They have no effect on the documentation generation process, but enhance documentation template clarity.

Copyright 1993-2017, RistanCASE GmbH