Learn more about the rules editor

• guided conversion
• working with the rules editor
  • content panel and content elements
  • elements properties tab
  • rules grid
• rule conditions
• what is a rule
• edit mode

Getting things done with the rules editor

Rules editor reference

The post General Annotations Summary appeared first on Stilo.

The Challenge: Going from Visual to Semantic

Migrate is typically used to convert documentation created in WYSIWIG authoring environments to some semantically rich XML format. The source format is full of visual cues that indicate, to varying degrees, the meaning or purpose of the content. With Migrate, you leverage these visual cues in order to indentify units of text and map them to the target XML format. You create Migrate rules to express this mapping, which we also call a rule set. To successfully create or modify such a rule set it helps to understand:

1. your document’s structure
2. your existing mapping
3. the target format

Facing the Challenge

The starting point, therefore, is understanding your own document. Choose a representative document and open it in the rules editor. Migrate will display a rendition of it in the content panel. You can explore your content and see what properties each piece of content has. These properties are the visual cues that you will base your rules on.

Work with your document to create a rule set that works well. You should then be able to convert similar documents with the same rule set. If you need to make small changes for a particular document to convert propertly, consider creating document specific rules. If these small changes apply to more than one document, you can create a variant of your rule set by cloning it.

The post Guided Conversion appeared first on Stilo.

The post Anatomy of the Rules Editor appeared first on Stilo.

You can clone an existing rule set at any time. Cloning is helpful if you need to start working with a document which is part of a different documentation set. The cloned rule set provides a good starting point for building up the rules for the new documentation type. Cloning a rule set can also be a good idea if you plan to make significant changes to an existing rule set. If you are not happy with the results, you can always delete the cloned rule set. You will still have the original to go back to if necessary. Cloning is therefore a good way to make backups of your rule sets.

Procedure

1. Go to the Rule Sets page.
2. Select the rule set or sets which you would like to clone.
3. Click the Clone button.

Result

Your rule set has been cloned. Apart from having a different name, the new rule set is identical to the one you cloned.

Once you are done

Now is a good time to associate the new rule set to one or more documents. This has to be done before you can edit the rule set.

The post Cloning a Rule Set appeared first on Stilo.

Procedure

1. Go to the Rule Sets page.
2. Select the rule set or sets which you would like to delete.
3. Click the Delete button.

If you try to delete a rule set which happens to be associated with a document, the rule set will be removed. Documents previously associated with the rule set will still be on your portal, but will no longer be associated with any rule set.

Result

The post Deleting a Rule Set appeared first on Stilo.

Overview

When you open the rules editor on a particular document, you are presented with quite a bit of information that is intended to help you when you want to update rules and create new rules. This includes:

• What rules have fired on this element?
• What annotation have been applied to this element?
• Where has this rule fired?
• What are the properties of this element?

To work effectively with the rules editor, you need to know how to get answers to the above questions. This will help you to understand your document’s structure and the existing rule set. You will then be ready to modify rules as needed. Everything you need to know is presented in the:

• content panel,
• element properties tab,
• and rules grid

Content Panel and Content Elements

The Migrate rules editor displays a rendition of your document in the content panel. This is intended to look similar to your source document, but won’t be an exact match as it is an HTML rendition of the document that is specifically suited for Migrate. Sufficient formatting is retained, however, so that the content looks familiar to you. If the document is large, Migrate may actually split the document into chunks. In fact, you can control the chunking behaviour yourself.

If you click around in the content panel, you will see that Migrate provides information associated with text you have selected in the Element Properties tab. The information displayed in the Element Properties tab stays synchronized with the selection in the content panel.

Migrate decomposes your document into content elements. Only the following short list of content element types are available:

• paragraph
• span
• image
• table
• row
• title

Some content elements can be nested inside others. For example, a span is contained in a paragraph. If you click on a nested content element, you will see its properties. To change your selection to the containing content element, simply click on the highlighted selection again. Each click will cause the selection to grow to the containing element. Once the outermost selection is current, the next click will cycle back to the innermost element at the point where you click. For example, if you repeatedly click on a span which is inside a table, the current selection will change from the span, to the containing paragraph, to the containing row, to the containing table. This is how you can select a table to see all of the information Migrate has about it.

The grey bars in the left margin indicate that no rules have been applied to the content element. This is often not a problem, as Migrate will map simple paragraphs to paragraphs, and tables to tables. But if the corresponding element is to have special semantic significance, you will likely need to ensure a rule applies to it.

Element Properties Tab

The Element Properties tab provides the following information on the current content selection in the content panel:

Rules Grid

The rules grid provides a condensed display of your rule set.

As with the Element Properties tab, the rules grid also stays synchronized with the content panel. As you select different rules in the grid, the content element in the content panel for which the rule has has matched will be highlighed with a green border. The Rules Grid provides a toolbar for stepping through these matches. This allows you to quickly see where the in the content the selected rule has applied.

The rules grid is also synchronized with the displayed rules view. As you change your selection in the rules grid, the displayed rules view will automatically scroll to show you the rule’s full definition.

The post Working with the Rules Editor appeared first on Stilo.

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).

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

The post What is a Rule appeared first on Stilo.

Overview

The condition is the most complex part of a rule. The trick to a successful conversion with Migrate is to apply the correct annotations at the right places. Conditions allow you to identify these right places. In the end, a condition will evaluate to either true or false. The rule’s annotations will be applied if, and only if, the condition evaluates to true.

To provide agility and precision, Migrate supports several types of tests which can be used in conditions:

• style test
• property test
• logical group test
• content test
• context test
• contains element test

Migrate also provides mechanisms that allow you to consolidate what might have been several rules into one so that you don’t have to repeat yourself. This also keeps rule sets simpler and easier to understand.

• case construct
• for each construct

Case Construct

For Each Construct

The post Rule Conditions appeared first on Stilo.

Overview

To edit a rule, enter edit mode by double-clicking anywhere on it in the displayed rules view. In edit mode, there are a few extra things that show up all for the purpose of allowing you to make changes to the various parts of the rule.

• a green plus symbol allows you to add a condition
• another green plus allows you to add an annotation
• fields for providing extra details for each annotation
  • specify cases when the annotation applies with when
  • specify to which element the annotation applies with on
  • specify repeated applications of the annotion with for each
• OK and Cancel buttons
• a Delete button to delete the entire rule
• the left margin has been altered further indicate that the rule is in edit mode

In edit mode, you can change a rule’s:

• applicability (i.e. paragraph, span, etc.)
• name
• comment
• condition
• annotations

Simply double-click on whatever you want to change, and options will be displayed. You will notice that anything which you can edit will change to blue when your mouse hovers over it. When you are done, you can press the OK, Cancel to back out of the changes.

Clicking OK only updates the rule in the rules editor. It does not save your changes to the portal.

The post Edit Mode appeared first on Stilo.

Procedure

1. Go to the Documents page.
2. Choose a document that you want to work with, and click on its name in the dashboard.
   1. You have been taken to the document details page for the document you have selected.
3. Select the chunking option that you would like to employ.

Result

The rule editor will display your document’s content one chunk at a time. Use the chunk navigation toolbar at the bottom of the content panel to switch between chunked pages of your content.

The post Controlling Chunking in the Content Panel appeared first on Stilo.