Debugging document templates

There are several reasons for errors when specifying document templates. This chapter explains typical error cases and different ways to solve the problem.

Since Document templates are converted first to OSI templates, which, again, are translated to OSI functions, error lines reported while running the template refer to OSI function lines rather than to document template lines. This may cause additional problems when trying to locate errors.

In order to avoid this problem, it is suggested to implement larger OSI functions in the resource database. The OSI functions may be checked before running, which reduces the risk of errors. This, however, is not possible for document templates of any kind. Hence one should try to reduce the code lines in document templates in order to keep templates transparent.

When defining document templates as external resources, naming conflicts may easily happen, when calling the document template not via external program call but via internal function call. In order to optimize OSI function loading, OSI functions will be cached by the dictionary when being loaded. This will improve the performance, when calling document templates several times.

When the application generates different documents referring to global or class templates with the same name, loading the second document template will fail, since an OSI expression with the same name has already been loaded.

In order to reuse OSI functions, which are referenced in several templates, OSI functions might be implemented in the resource database. One cannot, however, store document templates in the resource database. Hence, document template names should be prefixed in order to obtain unique template names.

Syntax errors are detected while converting the document template into an OSI template, while translating OSI templates into OSI functions and while loading OSI functions to the dictionary. In order to detect errors, it is suggested running CreateDocument.exe. When a syntax error has been detected, the console output will list the OSI function or template expression, which has been failed. Below the error message, the converted OSI template or function is listed, which usually allows to locate the problem (see example below).

Referring to unresolved operation names is a typical error, which is rather easy to locate. Error template name, class and line causing the problem are listed in the console output (see below).

In order to locate malfunctions, one may run document generation in OSI debug mode. In order to activate the debug mode, OSI_DEBUG=YES has to be added to the [CreateDocument] section in the ini-file before calling CreateDocument.

In order to break at certain positions, one may insert break points in the document template in two different ways. In order to set a break point within a code line (with paragraph style OSICode) one may simply insert an # character at first position of the code line. In order to set a break point within fixed text references, a statement has to be inserted, since break points can be set for statements, only. Usually, one simply inserts a dummy statement as ${# 1;}$, which contains a break point and debugging will stop at the marked text position.

Sometimes, the document may contain invalid characters or unbalanced XML tags. When loading the document fails, LibreOffice write line number and position, where the error occurred. In order to locate the invalid text, one may change the extension for the document to .zip and browse the zip file content.

In the zip-file directory, the is the content.xml file, which contains the invalid line. Just open the content.xml file with a text editor supporting line numbers and locate the reported position. Usually, content errors are obvious when editing the content file.