Layout of model documents

The set of layout suggestions below can be supported and easily maintained up to a certain level through the use of word processor options and functions in Microsoft Word (styles, indentation and hanging indentation). These layout suggestions are specifically designed to work together with the predefined ITP styles.

Layout suggestions

• Start each ITP instruction on a new line.
• Put each group-start keyword (DO, REPEAT, THEN, ELSE) on a new line.
• Put each group-end keyword (OD, UNTIL , ELIF, FI) on a new line.
• If a group only contains a single instructions the group-start keyword, the instruction and the group-end keyword can be put on the same line.
• The instructions between a group-start and group-end keyword are indented one tab; suggested to be the width of three characters in a non proportional font.
  • If an instruction does not fit on a single line it can be continued on the next line indented with two tabs.
• A single space is used:
  • after opening-brackets "("
  • before close-brackets ")"
  • after semi-colons ";"
  • before function names
  • before and after operators ( :=, +:=, -:= , +, -, %, etc.).
• In INTERACTs the QUESTIONS and ANSWERS are indented the same amount as the line containing the keyword INTERACT. The optional keywords between a QUESTION and ANSWER are indented one tab more. Put each keyword belonging to an INTERACT is on a new line.
• If WITH/FORALL instructions have a WHERE-part, put each PAR on a new line indented with two tabs.
• Add empty lines before WITH/FORALL and FUNC/PROC, and after the subsequent OD.
• Additional empty lines can be added wherever you see fit. The same goes for splitting long lines. A few suggestions:
  • break assignments after the :=
  • put each parameter on a single line in long procedure and function applications.
  • Comments should only be used when they add information. Comments are mostly descriptive in nature and consist of one or more longer sentences. These should therefore be placed on their own lines. If a comment cannot be placed on a single line you can create a comment block by placing the opening "(*" on its own line followed by the comment, indented by a tab, and the closing "*)" on its own line.

Word processor options

To enhance readability font colors can be added to a model document. A (non-official) standard is to use blue text for the ITP Code, red text for Comments and purple/pink text for include statements.

Because we are working in a word processor character properties such as size, boldface and italics can be used. We advise you to use the following conventions in order to maintain a readable document:

Boldface and a few points larger than other code:

• WITH/FORALL instructions, including PAR keywords.
• procedure and function declarations e.g., PROC/FUNC instructions, including parameter definitions.
• INTERACT keywords, including the parameter.

Italics:

• INTERACT statements, the INTERACT keyword and all QUESTIONS belonging to that statement.

These word processor options are reflected in the ITP styles, except for the INTERACTS style.

Example

#
BEGIN
(* This is an example comment. *)
FUNC TEXT ex_func( 
      CONST NUMBER a; 
      CONST TEXT b )
DO
   IF a < 19000000
   THEN
      BOOL continue
      INTERACT "Error"
      TEXTBLOCK "Date before 1900"
      QUESTION "Do you want to continue?"
        DFT(FALSE)
      ANSWER continue
      IF NOT continue 
      THEN STOP FI
   	ELSE 
      ASSIGN ex_func := date( a ) + text_fragment( b; 3; 5 )
   FI
OD
NUMBER test
(*
   What we see here is an example of a comment that does not fit a single line and is therefore split over more than one line.
*)
FORALL X0 IN EXP.Example
DO
   ASSIGN test := X0.Field
   IF X0.Other_field <> "" THEN ASSIGN test +:= other_field FI
OD
#
@( number( test; 2) )
@( ex_func( test; "hello" ) )
#
END
#