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.
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.
experiment
elementAdding 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.
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
.