Documentation Template Macro Language

Documentation Generator Macro Language

Documentation Generator Macro Language (DGML) is a documentation template script language. In documentation templates, scripts begin with the #{ symbol and end with either the }# or }#\ symbol. If the script ends with the }#\ symbol, all whitespace which follow a script in DT (space characters, tab-stops, new paragraph shifts) are ignored. When defining DGML directives, the symbol }# will always be used as a script end marker in order to ensure greater clarity. This does not detract from the importance of the }#\ symbol. On the contrary, when creating DTs you should always consider carefully which symbol to use at the end of the script to ensure that unwanted "white" symbols do not appear in the generated document.

Data Types

The following data types are defined in DGML:

Simple (non-composite):

integer or int: same meaning as "int" in C

float: same meaning as "float" in C

string: same meaning as "char *" in C

date: variable of this type stores date (e.g. file creation date).

image: variable of this type stores graphical reports.

Composite types:

TCollection<Type>: data collection of type Type

struct: same meaning as "struct" in C (see another composite types)

Lexical Elements (tokens)

Tokens are the basic language elements recognized by the interpreter. The following tokens are defined in DGML:

keywords

identifiers

constants

operators

special characters

Keywords

begin_image

else

else_if

end_image

end_for

end_if

for_each

end_target_document

if

in

include

target_document

Identifiers

Identifiers are names for variables, constants and functions and must be distinguished from DGML keywords. A DGML identifier is defined like an ANSI-C identifier (a string of letters, numerals or "_" characters in which the first character cannot be a numeral).

An identifier can be:

A standard identifier (names of standard constants and functions)

A user-defined identifier (names of variables)

Variables

Variable type is not explicitly defined in the documentation template but is determined on the basis of the value assigned to it. Variable value is defined if it is located on the left side of a command of assignment or as the output parameter of one of the standard functions. The DGML variable is valid from the point in DT where its value was first defined to the end of the DT in which it is defined.

Constants

A "constant" is a number, character, or character string that can be used as a value in a program. Use constants to represent values that cannot be modified.

integer: unmarked string of decimal numerals (e.g. 123)

real: unmarked string of decimal numerals containing a decimal point (e.g. 123.45)

string: character string surrounded by quotation marks (e.g. "abide")

date: three constants of the integer type separated by the slash character "/" (e.g. 20/03/2000)

TCollection: a string of constants of the corresponding simple type (except the image type) enclosed in the '{' and '}' characters (e.g. {"A", "B", "C"})

NULL: a constant of the non-defined (arbitrary) type - it marks non-defined values

Operators

The following table displays DGML operators sorted according to priority (from highest to lowest).

Table 11: DGML operators

Character

Operator name

.

Selection operator

+

Binding operator

< <= > >= == !=

Relational operators

!

Logical NOT operator

&&

Logical AND operator

||

Logical OR operator

,

Separation operator

( )

Function call operator

=

Assigning operator

Special Characters

Special characters are used to define DGML script structure. The following characters fall into this category:

#{ }# ( ) \

The special characters ” ( “ and ” ) “ are also found on the operator list. The DGML interpreter determines the function of these characters on the basis of the context in which they are used.

Comments

Comments are a parts of DGML scripts or separate DGML scripts that are not analyzed by the DGML interpreter. Their function is to clarify the action of a DGML script or parts of the template. A comment is surrounded by the characters /* and */ .

Example 1:

#{ include( "\FP Documentation\Templates\FnArgsTemplate.rtf" ) /* FnArgsTemplate.rtf documents function arguments in greater detail */ }#

Example 2:

#{ /* This is an example of a comment which is the only script element */ }#

Expressions

The following expressions are present in DGML:

selector expressions

character expressions

relational expressions

logical expressions

addition expressions

function calls

assignments

Syntax:

Expr
: Selection
| StrExpr
| RelExpr
| LogicalExpr
| AdditionExpr
| FunctionCall
| Assignment

Selector Expressions

A selector expression selects a structure member. Expression value and type correspond to the selected structure member.

Syntax:
Selection
: StructName.ID
StructName
: Selection
| ID

Character Expressions

In DGML, character expressions bind string-type data.

Syntax:
StrExpr
: StrExpr + PrimaryExpr
| PrimaryExpr
PrimaryExpr
: Constant
| Identifier
| Selection

Relational Expressions

Relational expressions are used to compare two operands of the same simple type. The result is of the int type and assumes its value from the set {0, 1} (1 if relation is satisfied, 0 if not).

Syntax:
RelExpr
: Expr RelOper Expr
RelOp
: one of < <= > >= == !=

Logical Expressions

Logical expressions in DGML are strings of relational expressions bound by the logical operators AND (&&), (||) and NOT (!). The result of logical expressions is of the int type and assumes its value from the set {0,1}.

Syntax:
LogicalExpr
: LogicalExpr || LogicalExprP
| LogicalExprP
LogicalExprP
: LogicalExprP && LogicalExprR
| LogicalExprR
LogicalExprR
: LogicalExprV
| ! LogicalExprV
LogicalExprV
: ( LogicalExpr )
| RelExpr

Addition Expressions

Addition expressions in DGML are constants and/or identifiers of same type (int or float) bound by the operator PLUS (+). The result of addition expressions is of the int or float type.

Syntax:
IntExpr
: IntExpr + PrimaryExpr
| PrimaryExpr
PrimaryExpr
: IntConstant
| IntIdentifier
FloatExpr
: FloatExpr + PrimaryExpr
| PrimaryExpr
PrimaryExpr
: FloatConstant
| FloatIdentifier

Function Calls

A function call is an operator which transfers control and parameters (if any) to the function. In DGML, there is no possibility of defining functions so only standard functions can be called.

Syntax:
FunctionCall
: Identifier ( ArgList )ArgList
: ExprList
| eExprList
: ExprList , Expr
| Expr

Assignments

By means of assignment the value of operands to the right of the assignment operator is assigned to the operand on the left.

Syntax:
Assignment
: Identifier = Expr

Directives

DGML directives are used to program the attributes of generated documents. DGML directives can be control or generator. Control DGML directives are used to control flow of interpretation of documentation template . You can define the following by means of control directives: conditional interpretation of certain parts of the documentation template, multiple interpretation of parts of the documentation template, transition to a new output file, transition to the interpretation of another documentation template, and so on. Generator directives provide access to DA-C project data and reports, and integrate them into the generated document.

Syntax:

DTMLDirective : IncludeDirective | TargetDocumentDirective | ExpressionDirective | ForDirective | IfDirective | ImageDirective

The include Directive

By means of the include directive you can include in the generated document a document generated on the basis of some other documentation template.

Syntax:

IncludeDirective : #{ include ( StrExpr ) }#

StrExpr

The name of the documentation template, with the corresponding DA-C path or with an absolute path, on the basis of which the document to be included should be generated. If the relative path is assigned by the expression StrExpr, the documentation template will be first looked for in the directory assigned for documentation templates, after that, in the directory for standard templates, and, finally, in the Project Root directory.

Example:

#{ include( "Documentation\Templates\MyTemplate.rtf" ) }#

The target_document Directive

The target_document directive defines a part of the documentation template on the basis of which documentation written to a separate file is generated.

Syntax:

TargetDocumentDirective : #{ target_document ( StrExpr ) }# Body #{ end_target_document }#

StrExpr

The name of a newly generated document with a DA-C path to the location where it is to be saved.

Note: If the relative path to a file is assigned by the expression StrExpr, the first thing to be checked is whether there is such path in relation to the generated documents directory, and after that it will be checked whether there is such path in the Project root directory. If the path is not found, the target document and the corresponding path will be created in relation to the generated documents directory.

Example:

#{ GetGlobalFunctions ( FunctionsData ) }# #{ for_each ( Fun in FunctionsData ) }# #{ target_document ( "FP Documentation\GeneratedDocuments\ "+Fun.Name+".rtf" ) }# DOCUMENTATION FOR FUNCTION #{Fun.Name}# ... #{ end_target_document }# #{ end_for }#

The expression Directive

The expression directive is used to interpret the expression entered within it. If the expression entered defines a result, this result is transferred to the generated document. Formatting carried out in DTE on such a script will be applied in GD to built-in content. If the expression entered is an assignment or a function call which stores results in output variables, carrying out the expression directive has no effect on the generated document.

Syntax:

ExpressionDirective : #{ Expr }#

Example:

#{ /* example of the Expression directive with the selector expression */ }# #{ GetProject(ProjectData) }# PROJECT DOCUMENTATION FOR #{ ProjectData.Name }#

The for_each Directive

Using the for_each directive you can define a part of the documentation template which will be interpreted multiple times during documentation generation. On each iteration, one object from the object list entered in the directive heading will be documented. The number of passes through the loop is determined by the number of objects on the list whose elements are documented.

Syntax:

ForEachDirective : #{ for_each( Identifier in PrimaryExpr ) }# Body #{ end_for }#

PrimaryExpr collection of objects documented.

Identifier cyclic variable which assumes the value of one of the elements on the PrimaryExp list on each pass through the loop. The identifier variable type corresponds to the type of elements on the PrimaryExp list.

Body Part of the documentation template which is to be interpreted multiple times.

Example :

#{ GetAllFiles( FilesData ) }#

Project files are:

#{ for_each( FileVar in FilesData ) }# #{ FileVar.Name }# #{ end_for }#

The if Directive

The if directive enables you to define parts of the documentation template which will be conditionally interpreted in the documentation generation phase. If the value of the logical expression entered in the directive is 1, the part of the documentation template following the directive header will be interpreted. If the value of the condition entered is 0, expression values in the header of the else_if part (if an else_if part exists) will be examined; otherwise either the part of the documentation template located in the else part (if an else part exists) will be interpreted or the documentation template following the if directive will be interpreted.

Syntax:

IfDirective : #{ if ( LogicalExpr ) }# Body [ElseIfParts] [ElsePart] #{ end_if }#

ElseIfParts : ElseIfParts #{ else_if ( LogicalExpr ) }# Body | #{ else_if ( LogicalExpr ) }# Body ElsePart : #{ else }# Body

Example :

#{ GetAllFiles( FilesData ) }# #{ if (Count(FilesData) < 50 ) }# The project contains the following files: #{ for_each ( FileVar in FilesData ) }# - #{ FileVar.Name }#, #{ end_for }# #{ else }# The project contains #{ Count(FilesData) }# files in all. #{ end_if }#

The image Directive

The image directive defines the integration of a DA-C graphics report into a generated document. The directive body contains an image which will be replaced by a new one, generated on the basis of the current project state, during the documentation generation phase. The image can be accompanied by a caption or any other kind of comment. If the image has mosaic formatting, the body of the image directive will be interpreted as many times as there are segments in the mosaic.

Syntax:
ImageDirective
: #{ begin_image ( Identifier ) }#
Body
  #{ end_image }#
Identifier variable of the Timage type - identifier of the image displayed.

Example:

#{ GetFlowChart( FlowChart, "fri_ops", "", "##kbf33/jw-0hklejh##" ) }# #{ begin_image ( FlowChart ) }#

Flowchart of the function "fri_ops"

#{ end_image }#

Character	Operator name
.	Selection operator
+	Binding operator
< <= > >= == !=	Relational operators
!	Logical NOT operator
&&	Logical AND operator
\|\|	Logical OR operator
,	Separation operator
( )	Function call operator
=	Assigning operator