Context tracking annotations are used to identify regions of interest in your document.
Syntax #
set-context-before(class;label;depth)
set-context-after(class;label;depth)
class
arbitrary class name used to distinguish different contexts tracked
label
a label to apply to the new entry of a context
depth
the depth of the new entry of a context
Purpose #
Context tracking annotations are used to track regions of interest in your document. Migrate is often used to convert visually-rich documents into semantically-rich XML documents. The meaning of these visual cues, however, can be context dependent. The same formatting may have different meanings in different places in your document. There are many examples of this:
- a list item in a task is actually a step in a procedure rather than a plain list item,
- a list item in a questionnaire is in fact a possible answer for a multiple choice question,
- a bold tag in a step command should be mapped to a user interface control,
- a table with headers step and action in in reality a procedure, and should not retain its table nature, and
- a list in a glossary or references section of a document is not a plain list.
Description #
The Migrate conversion does not use context directly; rather, it is a mechanism that you use to help ensure that you correctly set other annotations that will guide the conversion. You can set the context, and you can check the context in other rules—you control the logic. This topic discusses how to set the context you would like to track. Testing the current context is discussed elsewhere.
Documents have an inherent hierarchical structure—books have parts, which contain chapters, which contain sections containing subsections. Migrate’s context tracking supports this with its depth argument. Context tracking items can pile up one on top of the other, and then unwind. For example, when a section ends, we may still be in the same chapter. The depth argument is optional, but when specified, it must be a number greater than zero; a value less than or equal to zero is equivalent to omitting the depth entirely. If the depth argument is omitted, the context item with the greatest depth has its label replaced with the new label. If it is provided, the new context entry will be created at the specified depth, and all context entries having a greater depth will be removed. So, for example, after having set a context with depth 4 for a subsection, setting a depth of 3 for a section will cause the item at depth 4 to be removed and the item at depth 3 to be updated.
Migrate allows different contexts to be tracked simultaneously by providing different values for the class argument. This is not to be confused with the ability to track hierarchical structure using the depth argument. You would only need separate classes to track parallel hierarchical structure in your document. This is not very common, so setting class to something like location all of the time works very well. The class argument is mandatory. It can be the empty string, and cannot contain a semi-colon character, or parentheses characters.
The label argument is used to provide a meaningful label to each item of context you choose to track. For example, if you chose to use location for the class argument, you might choose labels such as: in-task, in-concept, in-reference, or in-glossary. The label argument is mandatory, but it can be the empty string, and cannot contain a semi-colon character, or parentheses characters. Labels do not need to be unique.
Before, After, and Lifetime
The difference between set-context-before and set-context-after is in where each takes effect.
For example, if you write a paragraph rule and set the context before, then other rules which test the context will see the newly set context on the very same paragraph. With after context, the new context will only be applied on content elements following the current paragraph; specifically, this does not include content elements within the paragraph (such as span). The same principles apply to other content elements: if you set context before a table, the context is visible on that table and inside of it, whereas if you set the context after, the new context is only set after the entire table has been processed.
Regardless of whether before or after context is used, the context will continue to be applied to the following content element. This will only stop when
- a rule changes the context, or
- the containing content element on which the context setting was made is finished.
So if you set context on a span content element, that context will be available for all subsequent span in that paragraph, but will be automatically removed when that paragraph ends. Likewise, if context is set on a table row, that context will be automatically removed when the table ends. If you set the context on the table itself, it will be available to subsequent paragraphs and tables, as these are all at the same level.
Do not confuse the logical hierarchical structure of your document with the nesting of content elements: content elements are quite flat. For example, headings of various importance are all just paragraph content elements with different properties.
Tips #
Because context is used to identify regions in your document, you have to be careful to identify the end of a region, not just its start. If you set some context at the right point in your document, you must ensure that the context gets unset when the region logically ends; otherwise, your rules will likely behave in unexpected ways.
