The intermediary document : Boxes structure (first example)

The main thing the intermediary document is intended for is specifying the position of the graphical elements without the use of any coordinates. To achieve this, the principle of LaTeX is taken over.

Objetcs are placed inside boxes. Some boxes can contain other boxes and every can be separated from others by springs.

1. Our first example

The best way to start is to have the famous etablished following example : let's display Hello world !. To be able to run this example, you first need to download and install TAXI which contains the necessary executable code (click here to jump to that page).

Save the following code under editor/XML/Examples/example1.grp (create Examples directory, editor is the directory you installed XML editor in) :

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <!DOCTYPE grp SYSTEM "../grp.dtd">
    <grp>
      <hbox>
        <tbox fontSize="30" fontStyle="italic">Hello world !</tbox>
      </hbox>
    </grp>

Save the following Definitions Document under editor/XML/Examples/examples.def :

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <!DOCTYPE definitions SYSTEM "../definitions.dtd">
    <definitions>
    </definitions>

Open a console, change to directory editor/XML/Examples, and then type (to know more about how to apply transformation, you can read From XML to GRP : How to from a console):

    java -cp ../../lib/taxi.jar fr.loria.taxi.transformer.TransformerGRPToSVG -grp_in example1.grp -defs examples.def -svg_dtd ../svg.dtd

You should see the following output :

    Parsing file examples.def
    Parsing file example1.grp
    Creating SVG document
    Generating SVG file example1.svg

The document example1.svg in the directory editor/XML/Examples has been generated. You can open the document in your browser if a SVG plugin is installed or you can use Batik (display is not always correct), for instance.

It looks like that with the Adobe plugin :

The SVG document is always generated in the same directory than the GRP document (the intermediary document).

2. Our first example explained

We already have a lot to explain through this simple example. Let's begin with the command line.

2.1. The command line

We called Java and instanciated the class transformer.TransformerGRPToSVG that performs the transformation of a GRP document to a SVG document with :

    java -cp ../../lib/taxi.jar fr.loria.taxi.transformer.TransformerGRPToSVG

We passed 3 parameters to the class transformer.TransformerGRPToSVG :

-grp_in,
-defs,
-svg_dtd.

Each parameter in followed by its value. -grp_in indicates the name of the intermediary document, in this case example1.grp. -defs indicates the definitions document, examples.def. And -svg_dtd indicates where to find the DTD of SVG, ../svg.dtd (the file svg.dtd contained by the parent directory). For these 3 parameters, we used relative paths but absolute paths can be used.

2.2. The definitions document

Actually, we passed an empty definitions document. We will detail later its role and its use.

2.3. The intermediary document

The GRP document (the intermediary document) is ruled by the DTD grp.dtd located in /editor/XML. It is not compulsory to use this DTD when you write your own GRP documents but it is more than highly recommended as this DTD will ensure the validity of these intermediary documents. You must keep in mind that the high level program will parse your GRP document and trust the result of that parsing. If you don't use the DTD provided your document might be invalid but the XML parser won't tell it and the high level program will consider it as valid. The outcome of the transformation then cannot be guaranteed. Thus, always use the DTD grp.dtd when writing your own GRP documents.

You discovered 3 tags :

grp : this is the root tag,
hbox : an horizontal box that contains another box,
tbox : a box that contains some text.

The width and height of the box tbox are computed respectively according to the width and height of the text that it contains.

The width and height of the box hbox depend on the width and height of the boxes it contains. In this case, our hbox contains only one box, so its width and height are equal to the width and height of our tbox.

We will explain later how widths and heights are computed. Now, let's have a closer look to the box called tbox.