SPFE Documentation | Collections > Essays on SPFE > Declarative markup

Declarative markup

By Mark Baker


SPFE is intended to support a declarative approach to markup -- one in which authors use markup to declare what something is, rather than the give and instruction about how something is to be handled. Some other systems rely on imperative markup (which gives instructions). SPFE will allow for imperative markup, but is generally intended to avoid the need for it.

In structured writing, markup is a means of inserting metadata into content so that the content can be identified or manipulated by algorithms, and it ensure that the content meets a set of required constraints. This metadata can be divided into two broad categories, declarative and imperative.

  1. Declarative markup - Declares what a piece of content is, either its role in a document (such as paragraph or list item) or what subject matter it refers to (such a an ingredient in a recipe or a parameter in a API routine).

  2. Imperative markup - Gives an instruction about how to handle the content under certain conditions. For instance, a conditional statement that includes certain content when a condition is true, or an instructions to reuse a piece of content by inserting it at a particular point in a text. Links are also a form of imperative markup as they tell the algorithm where to link to.

The main reason for using imperative markup is to make it easy for writers to specify certain behaviors in the content without the need to create specific markup or specialized algorithms to support them. The inclusion of a standard set of imperative markup in a markup language, along with a corresponding set of algorithms to process the imperative markup, can allow an organization to manipulate content in useful ways without the need for additional structures or coding. DITA, in particular, makes extensive use of imperative markup, largely as a means to do content reuse.

However, there are several downsides to the use of imperative markup:

Many (not all) of the effects that can be achieved using imperative markup can also be achieved using declarative markup. Where imperative markup puts the instruction in the content, declarative markup puts information needed to make a decision into the content, but places the instructions itself in an algorithm. For example:

The SPFE architecture is designed to facilitate the use of declarative markup as much as possible. Imperative markup can still be use (and if used is resolved in the resolve step of the synthesis stage), but the use of declarative markup is encouraged by the following features: