OwS Style Sheet Directive: obligation

The #obligation directive triggers the execution of a set of OwS statements whenever the OwS tokenizer discovers a paragraph of a certain style.

Syntax

ObligationDirective	:=	#obligation PrePostQualifier? StyleName => ExecutableCode
	|	#obligation PrePostQualifier? StyleName		de-registers all obligations for the given style and mode (pre/post)
PrePostQualifier	:=	<		Obligation is executed before a line of text with the given style is processed
	|	>		Obligation is executed after a line of text with the given style is processed. This is the default behavior.
ExecutableCode	:=	PackageName
	|	Text

---

Description

The #obligation directive is a simplified variant of the #pattern directive. In contrast to the #pattern directive, #obligation can be used in conjunction with other directives.

Like the #pattern directive, an obligation links a sequence of OwS statements to a defined MS Word style sheet:

argument	description
PrePostQualifier	This optional argument denotes, if the obligation shall be executed before ("<") or after (">") the execution of any other directive linked with a given style sheet.
StyleName	The style sheet that shall be linked with the obligation.
ExecutableCode	Either a sequence of OwS statements or the name of a #package that shall be executed whenever the given style is detected within the MS Word document.

StyleName and ExecutableCode must be separated by "=>". This allows for style sheet names consisting of multiple words (e.g. Überschrift 1) to be used with this directive.

Postprocessing using Obligations

The most common scenario where #obligation is used, is the postprocessing of object definitions that had been triggered by the #heading directive. A typical example is given below

Style Sheet		Text		Comment
OwS		#heading 2 concept .Name ( .Designation[Language=de] )		headlines of level 2 contain the name and German designation of a concept that is to be defined.
OwS		#obligation Überschrift 2 => set me.Display = me.Name		After processing a paragraph of style sheet "Überschrift 2" the Display property of the currently defined object shall be set to the object's name.
Standard		…
Überschrift 2		Mammals (Säugetiere)		When teh OwS tokenizer discovers this paragraph, first the #heading directive is processed (because this is a level-2 headline) and then the defined obligation is executed (because this paragraph is formatted as "Überschrift 2")
OwS.Definition		Mammals are characterized by the possession of a neocortex (a region of the brain), hair, three middle ear bones and mammary glands.		setting the definition of the newly defined concept

By default an obligation is executed after the processing of any other directives linked to the named style sheet. Therefore the example above translates to:

define concept (Mammals) {
    set me.Designation[Language=de] = (Säugetiere)
    set me.Display = (Mammals)
    set me.Definition = ($ Mammals are characterized by the possession of a neocortex (a region of the brain), hair, three middle ear bones and mammary glands.
}

As one can see the Designation property is set first because it is part of the processing of the #heading directive. After that directive has been processed, the obligation is executes which sets the value of the Display property. After that normal processing proceeds (in this case by setting the Definition property of the concept.

Defining Multiple Obligations for a Style Sheet

When an obligation is defined for a style sheet that is already linked with an obligation, the newly defined obligation is appended to the defined obligation(s). As well one may define preprocessed and postprocessed obligations for a single style sheet. E.g. if in the example above two obligations had been defined:

#obligation Überschrift 2 => set me.Display = me.Name
#obligation Überschrift 2 => set me.Definion = (Definition:)

the concept's display name was set to the concept's name and the text "Definition:" be set as the first paragraph of the defining text.

Deactivating Obligations

When placing OwS directives and statements into MS Word documents there may be situations where paragraphs of a specific style sheets shall be parsed in on chapter but be left as-is within other chapters. For this one can disable the OwS processing of obligations by using the #obligation directive with just the style sheet name to be disabled as an argument. E.g. the directive

#obligation Überschrift 2

deletes all obligations defined for the style sheet "Überschrift 2". By giving ">" before the style sheet name, only postprocessing obligations are deleted.