Rules are the mechanism for guiding Migrate conversions. They are the key to obtaining the target output that you desire.
Overview #
Rules are the to Migrate guide. A rule set is a collection of such rules, and it are associated to documents using the dashboard. Rules consist of two main parts: annotations and a condition. The annotations are instructions to Migrate as to how different portions of your document should be treated during conversion. For example, this content is the title of a task topic, or the term of a definition list entry. The condition is used to determine when a rule matches, that is on what pieces of your document the rule’s annotations should be applied. Conditions can potentially be quite complex.
Anatomy of a rule #
Consider the following rule which tells Migrate that any content styled as ListParagraph, having a list-style property of decimal, and a margin-left property of 720twips, should be considered an ordered list item with a nesting level of 1 (i.e. an outermost list entry).
| 1 | applicability | The rule will only be tried on elements of the indicated type. This helps improve Migrate’s performance. |
| 2 | name | A descriptive name for the rule chosen by you. |
| 3 | condition | Conditions test the properties of content to see if the rule matches, and hence whether or not the rule’s annotation should be applied to that unit of content. |
| 4 | annotations | Annotations indicate how a chunk of input text should be converted. |
Rule condition #
A rule condition can be simple or complex. A simple condition may consist of a single test, such as a style test. This is actually quite common. On the other hand, a condition may be composed of several tests, carefully combined together to capture your specific intent.
A variety of tests types are available so as to enable you to accurately identify the exact portions of your content that require special treatment, thus allowing you to carefully place annotations where they belong. The available test types are summarized in the following table.
Rule test types
| Test | Description |
|---|---|
| style | test the styling applied to the content by the authoring tool |
| property | test some property associated with the content (e.g. the size of the left margin, font size, or the column header if in a table) |
| content | test the content (e.g. see if it starts with some specific initial characters, or if it matches a provided regular expression) |
| condition | test if a particular condition was applied to the content |
| logical combination of tests | test if all of, some of, none of, or not all of the following conditions are true |
| contains element | test if the current element contains a nested element with specific properties |
| context | test the current user managed context |
| id | test the unique identifier of the element |
