Model Templates : Properties : Properties Segment Section : Using Keywords to Write Portions of the Long Description

Using Keywords to Write Portions of the Long Description

In the last part of each property entry, you want to include information from the data-item’s long description. This information consists of free text that is attached to the element’s form. The long description can be divided into portions through the use of keywords. For example, you can set off those portions of the text that deal with data-item purpose by enclosing the text within the keywords !PURPOSE and !END PURPOSE. You can extract this information using a database extraction function that searches for keywords in the text and returns (to a file) all the text contained between these words. You can then use an INCLUDE statement to cause the file containing the text to appear in the document.

For each section of text that you want to appear, you begin by assigning a value to the string variable di_desc_file, which represents the name of the file with the desired text. Note that the fourth argument of the database extraction function is an empty string. This argument is reserved for the name of the file in which the desired text is returned. If you want the information in a specific file, you can specify a name for this argument. If you specify an empty string, as shown in the template, the Documentor writes the text in a temporary file. In either case, the function returns the name of the file in which the text is written. For example, in the first section, di_desc_file represents the temporary file that contains all the text between the keywords !PURPOSE and !END PURPOSE.

The assignment for di_desc_file is followed by an IF/THEN/ELSE statement that either includes the text or prints a “not available” message if the starting keyword is not found. This is done by means of the status parameter st, which appears in the keyword’s extraction function. If the value of st is equal to stm_success, the text is included in the document. If the value of st is equal to stm_starting_keyword_not_found, the message “not available” is written. Any other status values will leave the paragraph empty.

The rest of the template extracts long description information in the same manner. The template execution then loops back to the beginning, repeating the instructions for each data-item in the list.

The final output is shown in the following section.