Research Description Language

Introduction to REd's Open Architecture

The Research Editor (REd) has an open architecture, which means that it can be extended by others to suit their specific needs. This open architecture is based on the "openness" of the Research Description Language (RDL): there is no RDL DTD or Schema. In fact, the core of RDL consists of only a few explicitly defined elements, like include and experiment. Other elements can be added by anyone using element definitions.

top

Adding elements using element definitions

An element definition, as its name implies, defines a new element for use in an RDL document. This definition takes the form of a small XML document that links a visual style to the element for use in REd and tells REd how to translate the element to LaTeX. An example is show below:

<?xml version="1.0"?>
<elements>
  <element name="em" caption="Emphasize" style="font-style: italic">
    <latex>\em{@text}</latex>
  </element>
</elements>

After reading in the definition above, REd will understand em elements in an RDL document. The way this element is shown in REd, is determined by the style attribute: this can be anything that is valid in CSS. REd's user interface will show a command Emphasize to let the user apply this definition to the current selection, or to start marking up text like this. The latex element within a element element defines how the element is to be translated to LaTeX. In this definition, @text denotes the text between the start and end tags. A somewhat more complicated example is shown below:

<?xml version="1.0"?>
<elements>
  <element name="section" caption="Section">
    <counter style="list-style: decimal"/>
    <element name="title" style="font-weight: bold; font-size: x-large">
      <latex>\section{@text}</latex>
    </element>
  </element>
</elements>

This example introduces two important new mechanism: counters and subelements. Subelements are just elements defined within other elements. Since the subelement itself is also an element, it can get its own latex definition. In the example above, this is all that's needed to typeset the section element, so the outer element does not get a latex part.

Counters are used to number parts of a text, in this case section headings. The style attribute defines how the numbering is shown. The default is decimal, which shows Arabic numbers, so it could have been left out of this example. Note that for other styles, the latex definition whould need to \renewcommand LaTeX's \section command to get the desired effect. This can be achieved using a preamble element within a latex element. Anything in such an element goes into the preamble of the generated LaTeX document. Counters can be relative to other counters, e.g. the counter for figures could be relative to the counter for sections. In that case, the second figure of the third section would be numbered Figure 3.2 instead of Figure 2. This is achieved using the relative attribute of the counter element, e.g. <counter relative="section"/>.

Any element that uses a counter, can automatically be referred to. But sometimes we need to refer to non-counted elements as well. This is achieved by adding refer="on" to the element's definition. In that case REd will recognize an id attribute for the element, and use that when adding references. For example, when enabling references for the em element defined above, the following becomes valid RDL: <em id="ex1">example</em>. The example text can then be referred to using RDL like As is show in the <refer id="ex1">example</refer> above.

Note that the counter in the example above is specified on the top level element, section. Since a subelement is just an element, it can get its own counter, as the following example shows:

<?xml version="1.0"?>
<elements>
  <element name="listing" caption="Listing" style="font-family: Courier">
    <counter relative="section"/>
    <latex>\begin{enumerate}@text\end{enumerate}</latex>    
    <element name="line" caption="Line">
      <counter relative="listing" caption="refer"/>
      <latex>\item{@text}</latex>
    </element>
  </element>
</elements>

The caption attribute of the counter determines when the caption of the element will be shown. The default is all, which means both at the place where the element is used, and at the place where the element is referred. Other possible values are refer and use. Using refer allows referring to individual lines in a listing as Line 5.2.11 for the eleventh line of the second listing of section 5, whereas the Line caption is not shown before each line in the listing.

The example above also shows how to typeset an element and its subelements. In this case, both get a latex definition, where the @text of the element consists of everything in it, including its subelements.

top

The experiment element

Adding new elements is not the only way to extend the functionality of RDL and REd: one can also extend the experiment element. In fact, this is the most important aspect of using REd, since it allows for automization of many standard tasks.

The experiment element is used to include markup based on experiments described in an Experiment Description Language (EDL) document. The basic usage of this element is as follows: <experiment src="example.edl" dest="table"/>. The src element defines where the experiment is described, but the more interesting atribute is the dest attribute. It can take on any value, provided REd can find the conversion program that goes with it. When dest is table, as in the example, then REd searches for a conversion program called edl2rdl-table, when it is figure REd looks for edl2rdl-figure, etc.

REd comes with some conversion programs installed, but one can also write one's own. A conversion program is a command line program that must accept as its single parameter the name of the EDL document. It must then process this document, and produce an RDL document with the same name as the EDL document, but with the .rdl extension. REd will automatically include the resulting RDL document.

top

Adding export formats

REd is capable of converting RDL documents to LaTeX documents. To facilitate publishing in other kinds of formats, REd uses an export file. This XML file describes file types and conversions between them. An example is shown below:

<?xml version="1.0"?>
<export>
  <format name="DeVice Independent"       ext="dvi" view="windvi,xdvi" />
  <format name="PostScript"               ext="ps"  view="gsview,ghostview" />
  <format name="Portable Document Format" ext="pdf" view="acrord32" />

  <convert from="tex" to="dvi" using="latex"  at="http://tug.org/texlive/" />
  <convert from="dvi" to="ps"  using="dvips"  at="http://tug.org/texlive/" />
  <convert from="tex" to="pdf" using="pdftex" at="http://tug.org/texlive/" />
</export>

An export file contains two types of information: formats and conversions between them.

A format element describes a publishing format. The ext attribute gives the extension for files in this format. This information is used for determining which conversion program to call (there may be more than one conversion between formats). The view attribute contains a comma separated list of programs that can be used to view files of this type.

The convert element describes a conversion between formats. The from attribute indicates the extension of the source format, and the to attribute the extension of the destination format. The using attribute defines the command to run. Note that if a full path is omitted, as in the example above, the command needs to be on the path to be executed successfully. The at attribute indicates where the conversion program can be obtained.

REd comes with a set of predefined export conversions in the REd.exp file. You may add your own formats, viewers, and conversions to this file as appropriate. REd will load this file at startup.

You may select any defined format when publishing a file. When the required conversion program cannot be run, REd allows you to download and install the software, using the URL in the at attribute. After the conversion, you may select to view the destination file, using one of the viewers in the format's view attribute.

REd will also automatically chain conversion programs. In the example above, the Publish dialog will present you with the Postscript format. Selecting it will cause REd to execute two conversions, first from tex to dvi, and then from dvi to ps.