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

Glossary

The post General Annotations Summary appeared first on Stilo.

concatenate(label;separator)

label

Label for the XML element that you want to join.

separator (optional)

Optional separator for use with concatenate.

Purpose

The concatenate annotation is used to join elements of the same type in order to make a larger element. This is often used to join spans, especially in titles. A title that is not in one paragraph can cause conversion problems, especially if it’s the document’s title.

There is an optional separator that can be specified, so that the units joined are still obviously distinct from each other. A common use for this is when joining block-level elements such as paragraphs. The default separator, if none is specified, is a newline; this is stripped when published to HTML, so a Unicode newline is sometimes specified (U+2028) to force the published content to appear the same as the input source.

Example: Concatenate a divided title

This shows a short document with a divided title.

The following shows you what the output may look like before this annotation is applied. You will see that the title has been broken into two topics, which is not what is desired here.

<task>
  <title>Testing italic and bold text -</title>
</task>

<concept>
  <title>How concatenate is sometimes used</title>
  <conbody>

Let’s apply the concatenate() annotation now to clean this up. This is what your rule may look like.

The following shows you what the output may look like after this annotation is applied. The title segments have been joined and are in the same topic.

<task>
  <title>Testing italic and bold text - How concatenate is sometimes used</title>
  <taskbody>

The post concatenate appeared first on Stilo.

Syntax

element-identifier(IDENTIFIER)
element-identifier-lowercase(IDENTIFIER)
element-identifier-lowercase-alphanumeric(IDENTIFIER)
element-identifier-alphanumeric(IDENTIFIER)
remove-attribute(ATTRIBUTE-NAME)
set-attribute(ATTRIBUTE-NAME=ATTRIBUTE-VALUE)
set-attribute-on(ELEMENT-NAME;ATTRIBUTE-NAME=ATTRIBUTE-VALUE)

IDENTIFIER

The value which the ID attribute will be set to.

ATTRIBUTE-NAME

The name of an attribute whose value will be set.

ATTRIBUTE-VALUE

The value to which an attribute will be set.

ELEMENT-NAME

The name of the element on which the attribute will be set.

Description

The element-identifier annotation is used to set the ID attribute of the element to which it is applied. The value to which the ID attribute should be set must be provided as an argument to the annotation. Even though the set-attribute can be used for this purpose in certain contexts, it is preferable to use the element-identifier annotation since this annotation is capable of formating values to conform to the required format of the ID attribute.

The remove-attribute annotation is used to remove attributes from the element to which it is applied. The name of the attribute which should be removed from the element must be provided as an argument to the annotation.

The set-attribute annotation is used to set the ID attribute of the element to which it is applied. The name of the attribute which should be set as well as the value to which it should be set must be provided as arguments to the annotation.

The elements which are visible in the Rules Editor are converted by Migrate into valid XML elements. However in order to generate valid XML, Migrate must also create other elements. The set-attribute-on annotation is used to set attributes on those elements which are created implicitly by Migrate. An example of this is the p.title.concept annotation. The paragraph to which this annotation is applied is converted into the title of a concept and the concept element is created by Migrate. The set-attribute-on annotation can be used to set an attribute on the concept element.

The post element-identifier appeared first on Stilo.

Syntax

element-identifier(IDENTIFIER)
element-identifier-lowercase(IDENTIFIER)
element-identifier-lowercase-alphanumeric(IDENTIFIER)
element-identifier-alphanumeric(IDENTIFIER)
remove-attribute(ATTRIBUTE-NAME)
set-attribute(ATTRIBUTE-NAME=ATTRIBUTE-VALUE)
set-attribute-on(ELEMENT-NAME;ATTRIBUTE-NAME=ATTRIBUTE-VALUE)

IDENTIFIER

The value which the ID attribute will be set to.

ATTRIBUTE-NAME

The name of an attribute whose value will be set.

ATTRIBUTE-VALUE

The value to which an attribute will be set.

ELEMENT-NAME

The name of the element on which the attribute will be set.

Description

The element-identifier annotation is used to set the ID attribute of the element to which it is applied. The value to which the ID attribute should be set must be provided as an argument to the annotation. Even though the set-attribute can be used for this purpose in certain contexts, it is preferable to use the element-identifier annotation since this annotation is capable of formating values to conform to the required format of the ID attribute.

The remove-attribute annotation is used to remove attributes from the element to which it is applied. The name of the attribute which should be removed from the element must be provided as an argument to the annotation.

The set-attribute annotation is used to set the ID attribute of the element to which it is applied. The name of the attribute which should be set as well as the value to which it should be set must be provided as arguments to the annotation.

The elements which are visible in the Rules Editor are converted by Migrate into valid XML elements. However in order to generate valid XML, Migrate must also create other elements. The set-attribute-on annotation is used to set attributes on those elements which are created implicitly by Migrate. An example of this is the p.title.concept annotation. The paragraph to which this annotation is applied is converted into the title of a concept and the concept element is created by Migrate. The set-attribute-on annotation can be used to set an attribute on the concept element.

The post element-identifier-lowercase appeared first on Stilo.

The empty annotation is used to remove content. One common use for this is to remove the text from a link, leaving the xref intact but not printing the text portion. Some publishing software automatically creates the link text on publishing, so having the text already there is not useful in such cases.

Example: Deleting content from links

This screenshot shows how you would remove the text from both internal and external links in your document.

This next screenshot shows you what the output may look like after this annotation is applied.

<xref href="Typographical_conventions_.dita#ID-1797-00000171/ID-1797-000001a8"/>

The post empty appeared first on Stilo.

extract-before-paragraph
extract-after-paragraph

Purpose

The annotations extract-before-paragraph and extract-after-paragraph are used to pull out an element from another element and place it in a new paragraph either directly before or after the location from which it was extracted. This is often used to remove things like images and tables from headings, due to the insertion point occurring within a sentence or heading rather than just before or just after it. Many software programs render these items as we expect to see them, so it isn’t always known that an insertion point is in the middle of a title, for example. One method of handling this type of issue is in pre-conversion cleanup, making sure that insertion points don’t break up other content. These annotations are used for cases where pre-conversion cleanup wasn’t possible or simply missed an example or two. It is important to note that these annotations work on spans, so you may need to use the on feature to accurately identify the element you want to extract. For more information on how to use the on feature, please see the on page.

Example:

Here we see the heading and image appear fine in the source document. This is because the insertion point is not always visible and because source formats can often present the image in a paragraph after the heading instead of in the middle of it or at the beginning of it.

Here we see the image in the Rules Editor appearing at the start of the heading. The Rules Editor is placing the image exactly at its insertion point.

Let’s apply the extract-after-paragraph annotation now to clean this up. This is what your rule may look like.

extract after paragraph rule

The following shows you what the output may look like after this annotation is applied. The image has been removed from the heading and appears after it in a new paragraph.

<concept>
  <title>Issue 7: Insertion points for images appearing in headings</title>
  <conbody>
  <p><image href="image1.jpg" width="15.024cm" height="11.27cm"/></p>
  <p>
  Sometimes insertion points for images end up in headings or other text that you don’t
  want to contain an image. There are ways to work around this in Migrate, using some
  of the content manipulation annotations.
  </p>
  </conbody>
</concept>

Let’s apply the extract-before-paragraph annotation now. This is what your rule may look like.

The following shows you what the output may look like after this annotation is applied. The image has been removed from the heading and appears in a new paragraph at the end of the previous topic in the document.

  <p>
  Other issues with tables occur where they are not really tables but just used for
  visual representation.
  </p>
  <p>
    <image href="image1.jpg" width="15.024cm" height="11.27cm"/>
  </p>
  </conbody>
</concept>

The post extract-after-paragraph appeared first on Stilo.

extract-before-paragraph
extract-after-paragraph

Purpose

The annotations extract-before-paragraph and extract-after-paragraph are used to pull out an element from another element and place it in a new paragraph either directly before or after the location from which it was extracted. This is often used to remove things like images and tables from headings, due to the insertion point occurring within a sentence or heading rather than just before or just after it. Many software programs render these items as we expect to see them, so it isn’t always known that an insertion point is in the middle of a title, for example. One method of handling this type of issue is in pre-conversion cleanup, making sure that insertion points don’t break up other content. These annotations are used for cases where pre-conversion cleanup wasn’t possible or simply missed an example or two. It is important to note that these annotations work on spans, so you may need to use the on feature to accurately identify the element you want to extract. For more information on how to use the on feature, please see the on page.

Example:

Here we see the heading and image appear fine in the source document. This is because the insertion point is not always visible and because source formats can often present the image in a paragraph after the heading instead of in the middle of it or at the beginning of it.

Here we see the image in the Rules Editor appearing at the start of the heading. The Rules Editor is placing the image exactly at its insertion point.

Let’s apply the extract-after-paragraph annotation now to clean this up. This is what your rule may look like.

extract after paragraph rule

The following shows you what the output may look like after this annotation is applied. The image has been removed from the heading and appears after it in a new paragraph.

<concept>
  <title>Issue 7: Insertion points for images appearing in headings</title>
  <conbody>
  <p><image href="image1.jpg" width="15.024cm" height="11.27cm"/></p>
  <p>
  Sometimes insertion points for images end up in headings or other text that you don’t
  want to contain an image. There are ways to work around this in Migrate, using some
  of the content manipulation annotations.
  </p>
  </conbody>
</concept>

Let’s apply the extract-before-paragraph annotation now. This is what your rule may look like.

The following shows you what the output may look like after this annotation is applied. The image has been removed from the heading and appears in a new paragraph at the end of the previous topic in the document.

  <p>
  Other issues with tables occur where they are not really tables but just used for
  visual representation.
  </p>
  <p>
    <image href="image1.jpg" width="15.024cm" height="11.27cm"/>
  </p>
  </conbody>
</concept>

The post extract-before-paragraph appeared first on Stilo.

log(message)

message

user log message

Purpose

The auxiliary annotation is used cause a user-level message to be emitted to the conversion report. The Migrate conversion ignores this annotation, it is only there for your own benefit.

An example of its use is to set a log message when a certain condition applies to indicate that manual clean up is required.

The post log appeared first on Stilo.

outside(element)

element

any XML element you want to close

Purpose

Migrate prefers to leave elements open as long as possible. The outside() annotation is used to force Migrate to close an element where it should end.

Below is some sample text.

You can specify the key to be used for access to encrypted ACE instances. If you specify password protection for an ACE master and want to be able to reset the password for a deployed ACE instance from that master, you must specify a recovery key before you create the package that includes the virtual machine.

1. Click Set recovery key. The Recovery Key dialog box appears.
2. In the Recovery Key dialog box, select Use recovery key to configure a recovery key.
3. To use an existing PEM format key pair, click Browse for Existing Key to navigate to the public key of the pair you want to use. To create a new…

Example Ends Here

Migrate will place the paragraph Example Ends Here inside the step list if not told to do otherwise. To use outside() to close the step list, your rule may look like this:

The post outside appeared first on Stilo.

proceed-with(element)

element

The XML element that you want to use.

Purpose

This annotation is used when you require a specific element in a given place, but there is no other way to open the element. If the element is open already, proceed-with() will keep this element open until required to close it. If the element specified in the argument is not open at this point, it will be opened. This cannot be used to begin a new topic, but can be used with non-topic elements so long as they are not nested.

Example:

This is an example of how you would use the proceed-with() annotation. This document has an image with a title that is in a step.

This is an example of what your proceed-with() rule may look like.

This is an example of how your output could look like after conversion.

<step>
  <cmd outputclass="ID-000003d7">
  To use an existing PEM format key pair, click Browse for Existing Key to navigate
  to the public key of the pair you want to use. To create a new…
  </cmd>
  <info>
  <p><image href="image1.png" width="1.773cm" height="1.798cm"/> Figure 1Browse button</p>
  </info>
</step>

The post proceed-with appeared first on Stilo.