Introduction to re:ality XML

This section outlines the basics principles of creating a re:ality XML file. The topics covered are:

  • The Structure of re:ality XML Document
  • XML Declaration
  • Document Type Declaration (DTD)
  • Namespace
  • Document Validation
  • Metadata
  • Output specifications
  • Color Scheme
  • Styles
  • Master Pages
  • Content

The Structure of a re:ality XML file

Re:ality XML starts like all valid XML documents with an XML declaration, following this there is a root element, with a namespace binding; followed by a document element. There are six main children of the document element that can be thought of in two sections system set-up data and render-able data.

Document Structer

In the system set-up data section there are five main areas metadata, outputs, colors, styles and masterpages (the order of elements is strictly checked). The render-able data section contains the data that is needed for rendering to an output format and is named content.

NOTE Although described here as system set-up data and render-able data these two sections do not exist inside the re:ality XML file format, they are used here primarily for visualisation/understanding of the file structure.

The re:ality XML file that follows shows the above diagram as XML: 

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE re:root
       SYSTEM 'http://reality.dataactive.com/DTDs/reality-1.0.dtd'>
 
<re:root xmlns:re='http://reality.dataactive.com'>
 
       <re:document
               version='1.0'
               language-code='ENG'
               country-code='GBA' 
               category-code='examples'
               uid='1234' 
               display-name='Example'>
 
               <re:metadata>
                      <re:meta name='author' value='DataActive' />
               </re:metadata>
 
               <re:outputs collate='false' 
                      compression='9' 
                      manifest='false'>
                      <re:output name='Kwik PDF' 
                             file-name='1234_example.pdf' 
                             type='reality.pdf.kwik'
                             options='page-crop-marks:false' />
               </re:outputs>
 
               <re:colors>
                      <re:color name='red' type='CMYK' value='0,1.0,1.0,0' />
               </re:colors>
 
               <re:styles>
                      <re:style name='exampleStyle' parent='' >
                             <re:styleattribute name='font-size' value='9' />
                      </re:style>
               </re:styles>
 
               <re:masterpages>
                      <re:masterpage id='Master-A' >
                      </re:masterpage>
               </re:masterpages>
 
               <re:content>
                      <re:page>
                      </re:page>
               </re:content>
 
       </re:document>
 
</re:root>

The following outlines each section of this example XML and what each section is responsible for.

XML Declaration

At the start of all XML there is a XML declaration the purpose of witch is to alert the parser (of this file) that the document has certain properties. The options that are available for the XML declaration are beyond the scope of this document, however it is mandatory to specify the version number (1.0) and although not mandatory its common practice to include the document encoding. 

<?xml version='1.0' encoding='utf-8'?>

For more information on document declaration's see:

Official XML specification Overview http://www.w3.org/XML/

Official XML specification (Second addition version 1.0) http://www.w3.org/TR/2000/REC-xml-20001006

XML FAQ http://www.ucc.ie/xml/

Document Type Declaration (DTD)

The document type declaration (DTD) is where parameters are parsed to the document for validation and entity escapes. All re:ality XML files are validated against the DTD. This means that the structure of the document must match the patterns laid out in the DTD. By validating the document the structure can be said to obey the re:ality XML specification, however this does not mean that the desired results will be achieved from the output just that the document has the correct syntax.

For more information on document declaration's see:

Official XML specification Overview http://www.w3.org/XML/

Official XML specification (Second addition version 1.0) http://www.w3.org/TR/2000/REC-xml-20001006

W3 School - DTD Tutorial http://www.w3schools.com/dtd/default.asp

re:root

The document element (here re:root) is the very first (and essentially a virtual) element of the XML tree. Document element is the formal name for the start element and is a type of XML node; it's more commonly known as the 'root element' or 'root node'.

The root element can have other XML node types besides the document element, e.g. comments and processing instructions.

re:document

The re:document element is primarily a secondary root tag, this is because the XML specification considers each XML file to contain one document, whatever the structure and type of that information. To prevent the confusion that could arise from this situation the re:document element, contains all the data necessary to output a single deliverable output. In the future this could allow the re:ality XML file format to contain information for more than one document without infringement of the XML specification.

re:outputs

The re:outputs element groups re:output information.

re:colors

The re:colors element groups re:color information.

re:styles

A re:style is a collection of commonly used attributes that can be used in association with structural mark-up to apply visual formatting to a document. This means that the content of a document, or a collection of documents, can be separated from the presentation. This has a number of advantages:

The author does not have to repeat similar presentational information for every instance of a given feature, such as a heading, in every document.

The document could be output in a different format or re-styled altogether.

Re:ality XML supports both stand-alone styles and inheritable styles. Stand-alone styles define every thing that will be used in one style sheet; where as inherited style references another style sheet for their information. Style sheet inheritance is singular, with each style sheet having the ability to use the inherited values or to specify new values for the inherited values (over ride).

The re:styles element groups re:style information.

re:masterpages

The re:masterpages element groups re:masterpage's information.

re:content

The re:content element groups all render-able elements. This element must contain at least one re:page, but can contain more pages of varying size for outputting. The content sections children will usually reference data from re:colors, re:styles and re:masterpages.