Sfairadora

  • Reference Guide

Enkidu Output Templates

The Enkidu language serves to create output text templates. An Enkidu language template can be considered a function returning a formatted text (the type Rich_text). Primarily, Enkidu templates are created in the Output templates document section. It is, however, possible to use the Enkidu language to create any function returning the type Rich_text (see the function editor). The easiest way to create an Enkidu template is to let Sfairadora to generate one automatically by copying an item form the section Data, View or Presentation to the section Output. A template created this way can be then edited as needed.
An Enkidu template is a formatted text that may contain Enkidu language commands. The commands are distinguished from the other text by setting the character attribute hidden. The formatted text editors designed to edit Enkidu templates display the hidden characters like this: Character format, which can be opened from the menu Format. A quick way to switch the hidden attribute is to use the keyboard shortcut Ctrl+H. If it is necessary to remove the hidden attribute, besides other ways, it can be accomplished by pressing Ctrl+space-bar, which removes all the additional formatting. The text not marked as an Enkidu command is simply copied to the resulting text.
In many cases, it is necessary to provide a value as a parameter to an Enkidu command. To specify a value, an Enki language expression is used. However, it is important to distinguish between the Enki language constructs and possible Enkidu construct with the same name. For instance, the both languages contains the if construct, nonetheless, their role is different. While in the Enki language it represents a conditional value computation, in Enkidu it presents a conditional inserting a portion of text to the result, thus this Enkidu construct cannot return any value. Even their syntax differs. The if statement in Enkidu has the form if ... else ... endif. In general, it is necessary to bear in mind that an Enki language expression is used at a defined place of an Enkidu statement and thus it cannot, for instance, contain a portion of text not marked as a command.
In the case of a more complex Enkidu language construct, it is natural to write the commands in separate paragraphs:
 Value x:
 if(x>0)
 positive
 else
 negative or 0
 endif
 End of value x
However, if the template were written this way, empty paragraphs would remain at the places of the commands in the output. For this reason, a paragraph can be marked as a command paragraph with the # mark at the beginning of the paragraph. A command paragraph does not produce a new paragraph in the result; the commands contained in it are executed as if they were attached at the beginning of the next paragraph:
 Value x:
 #if(x>0)
 positive
 #else
 negative or 0
 #endif
 End of value x
Of course, the commands can be written in the middle of a paragraph, as well:
 Value x: if(x>0)positiveelsenegative or 0end if End of value x
It should be noted that the spaces marked as a command (with the hidden attribute) are not copied to the result; they only separate commands. On the other hand, the spaces not marked as a command are part of the resulting text. It is not necessary to separate commands from the proper text with a space.
Other attributes of the commands (except for the hidden attribute) are ignored (with the exception of the < > (Value Insertion) command and special symbols). It is thus possible to use command formatting to make the template more tidy and easy to read by setting, for instance, different font and color to commands.

Error Handling

If an error in an Enki expression occurs during the template processing, the text generation is not interrupted, only a red colored error description is inserted to the resulting text.

Remark

If a template is edited in the document section Output templates and the corresponding output (an Output section item) is displayed in a separate window, the output is re-created only after the template editing is finished and the modified template is stored. Storing the modified template is performed when the editor is left, or it can be forced with the Shift+Enter shortcut.