Atomik Roundtrip 2.1: Tutorials << >>

Chapter 6 Tutorial 3 : Roundtrip rulesets

In this tutorial you will learn about creating and using Atomik Roundtrip rulesets, for formatting many different kinds of text in QuarkXPress.

A ruleset maps QuarkXPress styling elements to XML elements, so that when those elements are imported into QuarkXPress, they are automatically formatted. You are not required to use rulesets with Atomik Roundtrip, and if you don’t use a ruleset, the imported text will be given the styling of the text already in the box to which it was dragged.

The key stages in this tutorial are:

  1. Creating a new ruleset document
  2. Mapping QuarkXPress styles to DTD elements
  3. Adding prepended and appended characters automatically to XML


The objective of this tutorial is to provide an overview of how rulesets can be used to apply styling in QuarkXPress.

  1. Click the ‘Open Document’ button (
  1. ) on the Roundtrip Control palette. In the resulting dialog, navigate to the file ‘RT_Tutorial3.qxp’ in the ‘Tutorials’ folder.
  2. Select ‘Show Style Sheets’ from the ‘View’ or the ‘Window’ menu in QuarkXPress. Note: if the menu item reads ‘Hide Style Sheets’, then the style sheets palette is already showing.

Note that the document is set up with many QuarkXPress styles already.

  1. Click on the ‘Create Ruleset’ button (
  1. ) in the ‘XML palette’.

You will be presented with a dialog asking you to first select a DTD, and to provide a name for the ruleset. if you do not have any items listed in the DTD pop-up menu in this dialog, re-visit Tutorial 1, with regard to getting your Roundtrip Folder preferences set up again.

A DTD is a ‘Document Type Definition’, which is a description of the format of an XML file. Most XML files are written to conform to a DTD, and that DTD defines the structural rules which an XML file must obey. An XML file whose structure conforms to that defined in a DTD is known as valid XML, whereas XML which does not conform to a DTD structure (or is simply not associated with a DTD), but does have a correct arrangement of tags, is known as well formed XML. Atomik Import can read either valid or well formed XML (but only valid XML can have a ruleset applied to it).

  1. Select the “Easy_Magazine.dtd” DTD file from the list, and enter a name for the ruleset - Tutorial3.rls, would be suitable.

5. You will then be asked to select an XML file to import with that ruleset, choose the file ‘RT_Tutorial3.xml’ from your Tutorials folder and click Import. Note; Cancel can be selected if you do not want to associate an XML file with the document at this stage.

Your new empty ruleset palette will be automatically displayed on screen, close the ruleset palette for now by clicking in the top corner. The Focus tab of the Roundtrip XML palette will display the DTD that the ruleset is referring to, the ruleset name and the XML file that has just been imported into the document.

  1. Click on the ‘DTD’ tab of the XML palette. Holding down the ‘alt’ or ‘option’ key on your keyboard, click the disclosure triangle. All of the element definitions which are included in the ‘Easy_Magazine.dtd’ DTD file are listed, along with some information about the structure of those elements.

The standard view of the DTD in the DTD tab is a hierarchical view of the DTD structure. For someDTDs, this structure could be very complex, which makes navigating the entire DTD tree laborious. Atomik Roundtrip will also allow you to view the DTD as an alphabetical list of elements, which is easier to navigate. Just right click (windows) or control click (mac) on the structure tab of the Roundtrip XML palette, and choose from the pop-up menu whether you wish to view the structture as ‘flat’ or ‘hierarchical’.

  1. Double click/double right click the ‘GameTitle’ element in this DTD. The Ruleset palette will open and the ‘Rule Name’ field for the GameTitle element will be automatically selected.

    The Ruleset palette allows you to define the styling for any XML when placed on the page, depending on what DTD element that piece of XML corresponds to.

    1. In the Ruleset palette, you will notice a pop-up menu labelled ‘Paragraph Style’. This pop-up allows you to select the Paragraph stylesheet from the current (frontmost) QuarkXPress document which you wish to apply to the element. Note; you should always have a QuarkXPress document open when editing rulesets.

    Select ‘03. Header’ from the menu. This style sheet is now associated with XML elements which have the <GameTitle> tag.

    1. Click the ‘Add’ button - this will save your changes to the ruleset, close the ruleset palette by clicking in the top corner.
    2. In the ‘DTD’ tab of the XML palette, select the ‘Review Text’ element and double click/double right click it.
    3. You will observe that the contents of the Ruleset palette will change accordingly to show the settings for the ‘Review Text’ element.
    4. Again, for the ReviewText element set the paragraph stylesheet to ‘06. Text’, and click ‘Add’ again and close the Ruleset palette.
    5. In the DTD tab of the XML palette, double click the ‘Paragraph’ sub-element of ‘Review Text’. In the Ruleset palette, click the ‘Is a paragraph’ check box. This tells Roundtrip to automatically insert a carriage return after every instance of one of these elements. Notice also that we have not set a style sheet for the ‘Paragraph’ element, as the styling from its parent element, ‘Review Text’ will automatically be inherited by ‘Paragraph’.
    1. You will also notice that ‘Paragraph’ has 3 child elements. ‘character data’, ‘Email’ and ‘URL’.

    ‘Characterdata’ isn’t really a child element, it simply refers to the data which belongs to the parent element, but not any of the other child elements. Apply the ‘Email’ and ‘URL’ character style sheets (respectively) from the ‘Character’ pop-up menu, to the ‘Email’ and ‘URL’ child elements of ‘Paragraph’, as you have already done with previous elements.

    1. Double click/double right click on the ‘Score’ element. To this element, set the ‘06.1 Rating’ paragraph style sheet. The score element represents a percentage in the original XML file, but the XML contains only the figure : i.e. 99% is stored simply as ‘99’. In order for this to be correctly brought in to QuarkXPress, you can use Roundtrip’s ‘Generated Text’ functions. Enter a percentage character (‘%’) in the ‘Pre’ text field within the ‘Generated Text’ section of the ruleset palette. Any characters placed in the ‘Pre’ edit field are displayed after the XML when it is imported. Similarly, any characters placed in the ‘Post’ edit field will be displayed before the XML when it is imported.

    Don’t forget to click ‘Add’ (when you create a new rule) or ‘Save’ (when you change an existing rule) to save your changes.

    1. If you now switch to the ‘XML’ tab of the Atomik XML palette, you should be able to drag & drop the ‘GameTitle’, ‘Standfirst’, and ‘ReviewText’ elements on to text boxes on your document, and find that they are styled appropriately.
    2. Position the cursor at the end of the ReviewText which you have dragged, and then drag across the score element. This will also be inserted.

    Now try making some of your own edits to the ruleset, using the principles which have been described in this tutorial. You should avoid playing with the ‘Element is an image’ section of this dialog at this point, as this will be explained in detail in the following tutorial.

    You’ll notice that existing XML that was already on the QuarkXPress page is not changed to the new styling. Try now dragging elements from some of the other ‘Review’ elements in the XML file : these elements will take on the new styling which you have defined.

    Note that when you’re editing rulesets, all you have to do is to double click on the DTD reference (in the ‘DTD’ tab of the XML palette), and the ruleset palette will open up for whatever ruleset was applied to the XML which you have in your document. You don’t need to specially open the ruleset document up in order to access this palette. Once the ruleset palette has opened, rules can be added for more than one DTD element at a time can be added by selecting from the ‘Element’ drop down menu - you will automatically be prompted to save any changes you have made to the rules for the previous element that you may have edited.

    Also note that whenever you import an XML file into Atomik Roundtrip, the last ruleset which you used is automatically selected, unless you choose a different one.


    In this tutorial we have:

    1. Created a new ruleset
    2. Edited ruleset definitions