Documentation Template

Overview

Editing a Documentation Template

Opening a Documentation Template

Saving a Documentation Template

Interpreting a Documentation Template

Overview

A documentation template is a document which represents a template for the generation of one or more documents using DG. A documentation template, therefore, consists of two types of content:

A script which describes how to create certain content elements in the generated document, and

Other content which is inserted into the generated document unaltered.

The template is saved in the file in Rich Text Format (RTF).

The script is written in a specially developed language, DGML, so it will be called DGML script from here on. DGML scripts not only allow full control over the generation of content, but they also allow content to be generated on the basis of DA-C project data. DGML script is separated from the rest of the content by #{ labels and }# labels, for the beginning and end of the script, respectively.

DG offers a tool by means of which you can write even very complicated documentation templates without being familiar with DGML. DGML script modifications in the template can be performed manually, using DTE.

If documentation template cannot be created and/or opened, possible causes could be:
- Folder or file is protected - Folder or filename contains characters that cannot be correctly read in DA-C (not part of the standard ASCII code) - If using Word 2010 or newer, RTF files could be blocked in Options -> Trust Center -> File Block Settings ...

Editing a Documentation Template

A documentation template is created using the Documentation/New Template menu command. In the dialog this command brings up, you need to specify the name of the DT and the location where it is to be saved. Created DTs can be added to the active project via the Add New Documentation Template to Project option in the configuration dialog (General tab).

You can base your documentation on any one of the supported standards, which you can specify in this dialog.

About creating/editing Template files you may read here.

Opening a Documentation Template

There are several ways to open a DT:

Via the Documentation/Open Template command. This command opens the standard Open dialog for selecting a DT. On opening, the Open dialog displays the content of the default documentation directory, which can be set in the configuration (Directories tab).

From the Recently Used list (the Documentation menu). Recently used DTs are found on this list.

From the Default(types)/Document Files/Templates logical group in Logical view. If you are adding your DTs to the project, you can open all the DTs in one move from this logical group.

Saving a Documentation Template

A document is saved from DTE. A saved DT must be in Rich Text Format.

Interpreting a Documentation Template

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 DA-C 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

DA-C 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 DA-C 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 DA-C 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 gray scale 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-2022, RistanCASE PR