Atomik Roundtrip 2.1: Tutorials << >>

Chapter 9 Tutorial 6 : Advanced Rulesets

In this tutorial, you will learn how to create some more complex rulesets, allowing for rules to be applied only under certain conditions.

In the ruleset which you created in Tutorial 3 you applied rules globally to all elements with a particular name. However, your XML may be structured in such a way that you have identically named elements in different contexts : which you may want to present differently. For example, you may have XML that contains article elements, each of which has a ‘Title’ element and multiple book references, each of which also contains a ‘Title’ element. The difference between these elements is that one is the title of the article, the other is the title of a reference work referred to in the article. Under most circumstances, the styling of these would be very different.

You may also find that the meaning of your XML is differentiated by the contents of an attribute specified on the XML, rather than the element name. This tutorial will enable you to create rulesets which cater for both of these circumstances. It will also introduce you to Roundtrip’s Unicode and character entity support.

The key stages in this tutorial are:

  1. Creating a ruleset with contextual styling
  2. Creating a ruleset with attribute driven styling
  3. Using Unicode characters and XML entities in QuarkXPress with Roundtrip


The objective of this tutorial is to show how Roundtrip’s rulesets can be made more flexible, allowing for a wider range of XML formats to be imported into QuarkXPress and styled appropriately.

Note: The tutorials we’ve looked at so far use XML which is fairly simple in its structure. The XML which we are going to look at in this tutorial is a bit more complex; and consequently this tutorial requires a basic understanding of XML hierarchies. If you are new to XML, you may want to take a look at ‘A brief guide to XML’ later in this manual before proceeding with this tutorial.

The XML which you shall be using in this tutorial is different, and more complex, from that used in the previous articles. This XML is for a scientific journal publication. In the magazine XML from tutorials 1 through 4, each element type was unique - a ‘GameTitle’ was always the title of a review, and would always be styled in the same way in QuarkXPress.

  1. Start by taking a look at the XML which we are going to use in this tutorial - Tutorial6.xml.

You can look at the XML file using any application which can read text files; such as Simple Text, BBEdit, Notepad, Microsoft Word, TextPad etc. However, you should take care not to save the XML file once you’ve taken a look at it, as some of these applications will save the file in their own format, not as a text file : and an XML file needs to be saved as a text file for Atomik Roundtrip (or indeed any other XML-aware application) to be able to read it.

  1. Locate the first ‘Abstract’ element (near the top of the document).
<P>Umpteen XMLs lamely arose from two well-styled <Emphasis Style="Bold">Imports</Emphasis>, although multitudinous very stupendous XMLs slightly quickly bought Captain Reeder, but a very well-styled Klingon fell over two stupendous DTDS, then one hatstand mostly annoyingly bought umpteen Jabberwockies. Multitudinous hatstands towed one lampstand, even though Ermintrude slightly cleverly tickled multitudinous Imports. Umpteen Rulesets comfortably marries one XML, yet two easy-to-use Imports ran away, and umpteen structures cleverly tickled Santa Claus.</P>

The element which is particularly interesting here is the ‘Emphasis’ element. This is an element which contains an attribute ‘Style’, which has a value of ‘Bold’. If you look further through the XML, you’ll see other instances of the Emphasis element, with different values for their Style attributes (‘Italic’, for example).

<!-- XML note -->
Attributes are a special type of content within an XML file, known as ‘metadata’. Essentially this is information about the content, rather than actual content.
Attributes appear inside the tag of an element, for example:
<emph type=”bold”>This text is emboldened</emph>
It’s possible to have multiple attributes applied to the same element:
<Article section=”News” pub=”Easy_Journal” issue=”67”> ...</Article>

  1. The first thing we’re going to do with this ruleset is to create some rules allowing ‘Emphasis’ elements to be styled differently according to the value of the attribute in the text.
  2. Open the tutorial document ‘RT_Tutorial6.qxp’ from the Roundtrip Tutorials folder.
  3. Import the XML file ‘RT_Tutorial6.xml’ from the same folder, making sure that the ruleset ‘Tutorial6.rls’ is selected in the ‘Ruleset’ pop-up menu.
  4. Open the Roundtrip Ruleset palette (Window->Show Roundtrip Ruleset).
  5. Click on ‘Abstract’ in the list of elements on the right-hand side of the ruleset palette. The controls in the ruleset palette will change to show the settings for the ‘Abstract’ element’s rule.

You can make a new rule based on an existing rule simply by selecting the existing rule, and then selecting the element to which you wish to apply the new rule in the ‘Element’ pop-up menu.

  1. Select ‘Emphasis’ from the ‘Element’ pop-up menu.
  1. You’ll notice when you do this that the ‘With Attribute’ checkbox becomes enabled. This checkbox is only enabled when the element selected in the ‘Element’ pop-up menu has an attribute list defined in the DTD.
<!ELEMENT Emphasis (#PCDATA | Emphasis | Email | URL | List | FigRef | Ref)*>
  1. Select the ‘With Attribute’ checkbox in the ruleset window, and then select the ‘Style’ attribute from the adjacent pop-up control.
  2. Also check the ‘Value’ checkbox immediately below, and enter the text ‘Bold’ into the adjacent text field.

The rule which we’re defining will apply to any ‘Emphasis’ elements which have an attribute of ‘Style’ with a value of ‘Bold’.

    Now we’ve defined when the rule is going to be applied, we also need to add some styling information to make this rule actually do something.

    1. Check the ‘Use Character Attributes’ checkbox, then check the ‘Type Style’ checkbox.
    2. From the list of styling attributes (which looks like QuarkXPress’s measurements palette), select the ‘Bold’ icon.

      Ensure that the ‘Merge’ radio button is selected. This means that this rule will add ‘Bold’ styling to the current paragraph or character style, whatever that might be.

      If, for example, the current paragraph style defined the text as being underlined, having this rule defined as ‘Merge’ would mean that any Emphasis elements inserted would have both underlined (inherited from the underlying paragraph style sheet) and bold (applied by this rule) styling set.

      If instead you set the radio button to ‘Set’, this will apply only bold styling, and will cancel out any existing styling which had been set by the underlying paragraph (or indeed character) style sheet.

      1. The rule is now almost ready. Any ‘Emphasis’ elements with a ‘Style’ attribute which has the value ‘Bold’ will be displayed in emboldened text. Before you finish, make sure you set the ‘Paragraph Style’ and ‘Character Style’ pop-up menus to ‘Not Set’.
      1. Now just click the ‘Add’ button (in the top right-hand corner of the ruleset palette). This will save your new rule to the ruleset. You’ve just made your first attribute dependent rule.
      2. Repeat the steps described above to make further rules for ‘Emphasis’ elements with the attribute values ‘Italic’ and ‘Underline’ (which make the text italic and underlined - but you probably guessed that..)

      If you take another look at the XML we’re using in this tutorial, you’ll see that there are several different elements called ‘Title’.

      The first of these is the title of the article. The next instance of a ‘Title’ element is within a ‘Section’ - which is a child element of the article. In this case, the ‘Title’ element is the title of this section, and will need to be styled differently in QuarkXPress - otherwise it would look like the start of a new article, rather than a subheading of a section within the current article.

      The final appearance highlighted in the palette is from the references section of the article. Here the ‘Title’ element is the title of a reference work which is referred to within the article, and again this must be styled differently to the other instances.

      If you take a look at the image on the next page, this shows the same XML laid out on the QuarkXPress page, with the same elements circled - you can see here that the styling on all of these ‘Title’ elements needs to be different. This is what we’re going to do next.

      1. Try drag & dropping the ‘Head’ parent element to the top box on the page - you should find it looks very much like the picture on the previous page. Note also that you’ll see the result of your recently added ‘Emphasis’ element - the text within the Emphasis tag appears in bold on the page.

        18. Now try dragging the ‘Body’ element to the large 2 column text box at the bottom of the page. If you scroll down to the second page of the article, you’ll see that things are not looking so good here.

        19. Now drag & drop the ‘References’ element into the blank space at the end of the article. This will look incorrect - the titles of the books referred to in the references are styled using the same style sheet which has been applied to the title of the article - certainly not how you’d want your references section to be styled.

        You can see how the document should be styled by taking a look at the document ‘Easy_Journal_Finished.qxp’ inside the Tutorials folder.

        1. Open the Import ruleset palette (by selecting ‘Show Roundtrip Ruleset’ from the ‘Roundtrip’ menu).

        1. In the ruleset palette, select ‘Title’ in the list of rules on the left-hand side of the ruleset palette.

        You can see from looking at the ruleset palette that the ruleset is instructing Atomik Roundtrip to style all instances of the ‘Title’ element as if they were the title of an article. However as we’ve already seen that for this XML file this is not appropriate as the ‘Title’ element needs to be styled differently when it appears in different contexts within the XML hierarchy.

        When a ‘Title’ appears in the ‘Head’ section of the XML, it is the title of the article, but when a ‘Title’ appears as part of a section, it is a section subheading. Similarly, when a ‘Title’ appears in the references section, it is as the title of a reference publication. These all need quite different styling in QuarkXPress.

        In previous tutorials, when we’ve created different rules for styling text differently, the XML element to which we’ve applied those rules has always been different, but in this case the name of the XML element is the same. There is a special type of rule within Roundtrip rulesets to account for this eventuality - a ‘contextual’ rule.

        1. Click in the ‘Descendent of’ check box - you’ll notice that the pop-up menu next to the check box has become active. From this pop-up menu, select ‘Head’.
        2. Click the ‘Add’ button in the top right-hand corner of the palette. This adds a new rule to the ruleset palette called ‘Title1’.

        Now, this rule will only be applied to ‘Title’ elements which are a child of the ‘Head’ element: this means that only ‘Title’ elements which are in the heading of the article will be styled up as article titles.

        With only this rule defined, other ‘Title’ elements in the XML, which were not child elements of a ‘Head’ element would simply inherit styling from their parent element.

        You now have two rules, one which applies to all ‘Title’ elements, and one which applies only to ‘Title’ elements which are a child of ‘Head’.

        1. Select the ‘Title’ rule in the list on the left hand side - notice that the palette updates to show the settings for the original rule. Click the ‘Delete’ button in the top right-hand corner of the palette.

        Now you have a single rule - this will style the ‘Titles’ elements which are article titles correctly, and will not style other instances of the ‘Title’ element.

        25. Look at the XML tab of the Atomik Roundtrip XML palette.

        Control + click or

        right click inside the palette and select ‘View as Matching Rule Names’. You will see that the ‘Title’ element which appears under ‘Head’ has been renamed - ‘Title1’ and the ‘Authors’ element beneath that has been renamed ‘Authors<Head’.

        When importing XML with a ruleset, Import can be set to refer to elements by the name of the rule which they match, rather than the original element name in the Atomik Roundtrip XML palette. This means that if you have XML which has element names which are not user-friendly, these elements can be given a more approachable name which you will see in the interface (although the actual name of the elements within the XML file is not changed, so the validity and integrity of the XML is not compromised).

        A rule can be given any name you like, really (so long as it doesn’t contain space characters). Roundtrip will suggest that all rules are named with the name of the element or elements to which they apply, but you can override this default setting by entering a different name in the ‘Rule Name’ box within the ruleset palette.

        1. In the ruleset palette, you are now going to make a new rule for the titles which appear in the ‘References’ section of the XML.
        1. Select the ‘Title1’ rule which you have just made in the list on the left hand side of the ruleset palette.
        2. Change the ‘Descendent of’ pop-up entry to ‘References’. This rule will now only apply to ‘Title’ elements which are descended from a ‘References’ element.

        Note that the ‘descended from’ pop-up doesn’t necessarily refer to the immediate parent of the element. To match a ‘descended from’ rule, the element simply needs to be descended from the specified element at some point in the XML hierarchy.

        1. Now set the paragraph style to ‘Not Set’ (as the whole references section is covered by a paragraph style, which is inherited from the ‘Reference’ element).
        2. Set the character style to ‘a. Ref Title’
        3. If it is checked, uncheck ‘Is a paragraph’ (as this element will appear within a paragraph, rather than being a paragraph in its own right).
        4. Click ‘Add’ to add your new rule.

        Roundtrip will automatically have chosen the name ‘Title’ for this rule (as the previous ‘Title’ rule has now been deleted). This default name can be changed by entering a new name (ie. Title<References) in the ‘Rule Name’ box. Click ‘Save’ to save your changes. It’s a good idea to name your rules so that it is easier to identify which rule applies to which elements when you look at the ruleset palette in the future.

        The ruleset can now handle the article title and titles of references, and import them onto the QuarkXPress page with different styling. You’ve just created a context sensitive rule - a rule which styles an element depending on it’s position in the XML hierarchy.

        1. Remove the XML from the document by selecting ‘Remove XML from document’ on the Import menu. All the content which you’ve dragged on to the page previously is removed.
        2. Import the same XML file back into your QuarkXPress document, making sure that you choose the ‘Easy_Journal_tut6.rls’ ruleset.
        3. Now drag & drop the Head, Body and References elements onto the page (as you did previously in steps 17-19). You’ll see that the heading looks just like it did previously, but now the references section appears correctly.

        Now two of the different types of ‘Title’ element are correctly styled. However, you’ll notice that the two ‘Section’ elements now have no particular styling to pick them out - they are styled the same way as the surrounding text. So we now need to make rules for these elements.

        If you take a look at the finished text, you’ll note that the two section titles are styled differently.

        If you take a look at the XML, you will see that rather than being sibling elements, the two sections are nested one inside of the other. The important thing which helps to differentiate these sections is that both the ‘Section’ elements have an attribute set, and this attribute defines the level of the section.

        <Section level=’1’>

        <Title>A paragraph marries two XMLS</Title>

        The extract from the XML above shows this attribute, (“Level=’1’”).

        This makes it possible to distinguish between the different section levels, and apply different styling to titles contained within them, based on the value of this level attribute.

        If the attribute were specified on the ‘Title’ element, which contains the text which needs to be differently styled, then you could simply make an attribute dependant rule for the ‘Title’ element, as we did earlier for the ‘Emphasis’ element. But this is not the case - in this circumstance, it is the ‘Title’ element’s parent, ‘Section’ to which the attribute is applied. This makes a lot more sense from an XML perspective, as it’s the whole of the section to which this attribute applies, rather than to one particular element, so it is quite logical that it should be applied to the ‘Section’ element.

        What we need to do, therefore is to make a rule which is applied to any ‘Title’ elements which have a parent element of ‘Section’, and that ‘Section’ element has an attribute value of ‘Level=”1”’.

        36. In the Ruleset palette, select the ‘Section’ element in the ‘Element’ pop-up menu. The first thing we want to do is to turn off all the styling controls, because we’re about to make a rule which, odd as this may seem, doesn’t actually do anything! Make sure that the pop-ups for ‘Paragraph Style’ and ‘Character Style’ are both set to ‘Not Set’, ‘Use Character Attributes’ and ‘Element is an Image’ are unchecked, and that the ‘Pre’ and ‘Post’ generated text fields are empty. Also ensure that ‘Is a Paragraph’ is unchecked.

        1. Now check the ‘With Attribute’ checkbox, and select the ‘Level’ attribute from the list (it will probably be selected automatically).
        2. This is the only attribute defined for the ‘Section’ element in the DTD used for this tutorial.
        3. Also check the ‘Value’ checkbox below, and enter the value ‘1’. Change the name of the rule from the default ‘Section’ to ‘SectionLevel1’ by changing the ‘Rule Name’ text field. Now click the ‘Add’ button.
        1. Now change the text in the ‘Value’ edit field to ‘2’.
        2. You’ll notice that the ‘Add’ button (as opposed to the ‘Save’ button) is activated. This is because by changing the attribute value to which this rule responds, you’re changing the type of element to which this rule will apply - so, effectively, this is a new rule. Change the rule name to ‘SectionLevel2’, and then click ‘Add’ again.

        You now have two rules added to the ruleset, one which will apply to any ‘Section’ elements which have a ‘Level’ attribute defined with a value of ‘1’ - and one which will apply to any ‘Section’ elements which have a ‘Level’ attribute defined with a value of ‘2’. But neither of these rules make any changes to the styling of the text.

        1. Now click on the ‘Title’ rule in the list of rules on the left-hand side of the ruleset palette. This will show the rule which currently applies to your ‘Title’ elements. (This is the one listed as ‘Title’, not ‘Title1’ or ‘Title<Reference’.)

        1. In the ‘Rule’ pop-up menu, select the ‘SectionLevel1’ rule which you made earlier, then select ‘06. Section Title 1’

        In doing this, we’re saying that this rule will only apply to ‘Title’ elements which are descendents of elements which match the ‘Section Level 1’ rule - which means ‘Section’ elements with an attribute of ‘Level’ that has a value of ‘1’. This means that this rule will only be applied to ‘Title’ elements which are descended from a ‘Section’ element with an attribute of ‘Level=”1” ‘, so a title in a level 1 section will have the ‘06. Section Title 1’ stylesheet applied to it.

        1. Now just name the rule ‘Title Level 1’, and click ‘Add’.
        2. Repeat the process above to make a rule which applies the ‘07. Section Title 2’ style to any title elements in a level 2 Section.
        3. Select XML & press ‘Remove XML’ button in Roundtrip XML palette.
        4. Import the same XML again, using the Easy_Journal_tut6.rls ruleset. Drag & drop the Head, Body and References elements to the appropriate places on the QuarkXPress page. The elements should now all be styled appropriately.


        In this tutorial you have:

        1. Created Attribute dependent rules
        2. Created Contextual rules
        3. Created Contextual rules based on a parent’s attribute value.