Drawing ISO 15926 diagrams using macros

This page describes how content in ISO 15926 format can be represented in diagrams, using LaTeX, the xy-pic extension, and macros defined in the templatediagram.sty style.

Contents

  1. Getting started
  2. Creating diagrams on Trac pages
    1. 1. The diagram container
    2. 2. Adding a class: the class macro !c
    3. 3. Adding a second class: diagram hops with [r], [l], [d], and [u]
    4. 4. Connecting the classes: The relation macro !r
    5. 5. Adding roles to relations: The macro [!s]

The diagrams described here use the graph feature of xy-pic (see the xy-pic reference manual, section 26). The full xy-pic language is very expressive, and not exactly easy to understand for people with only finite time on their hands. However, to get started with ISO 15926 diagrams all that is needed is a tiny number of commands. This page will teach you how to draw diagrams with very little effort.

This method for producing diagrams is being developed as part of the SigMmt activity.

Getting started

There are two main options.

  1. Enter diagrams into a page in this Trac, as described below. For experimentation, consider the SandBox.
  2. For adding diagrams to your own LaTeX documents, download templatediagram.sty. (If you are just starting out with LaTeX, see http://www.tug.org/begin.html for some useful pointers to software and documentation.)

Creating diagrams on Trac pages

1. The diagram container

The first thing you need to do is to add a section to your Trac page that looks as follows.

{{{
#!LatexEquation
\TemplateDiagram{

         The diagram goes here!  

 }
}}}

2. Adding a class: the class macro !c

Classes are inserted into a diagram using the macro !c, which must be followed by three arguments, all enclosed in curly braces. A diagram of ISO 15926 content should always show the entity type of each element. This means the macro for adding a class has one argument for the element name, and one for the type name. In addition, we usually need to assign a name to each element in the diagram, so that we can refer to them later.

!c{ diagram identifier }{ class name }{ entity type name }

To enter a Class of Individual named Person, add "!c{person}{Person}{Class of Individual}" to the digram container:

{{{
#!LatexEquation
\TemplateDiagram{
  !c{person}{Person}{Class of Individual}
 }
}}}

This input produces the following graph.

3. Adding a second class: diagram hops with [r], [l], [d], and [u]

For example, let's say we wish our diagram to express that the class Child is a subclass of Person. We will need to place a Child class box in the diagram at a suitable distance from the Person box.

For moving around in the diagram, we use the common xy-pic statements.

  • [r] right, [l] left, [d] down, [u] up.

These can be combined quite flexibly for hopping around on the canvas, for instance:

  • [rr] two right hops, [ddr] two hops down, then one to the right

In order to leave room for a relationship symbol, we will move two hops to the right before drawing the Child class box.

{{{
#!LatexEquation
\TemplateDiagram{
  !c{person}{Person}{Class of Individual}
  [rr]
  !c{child}{Child}{Class of Individual}
 }
}}}

We now have the following graph.

4. Connecting the classes: The relation macro !r

We wish to relate the classes with a subclass expression, to represent the statement "every Child is a Person". the ISO 15926 entity type for this kind of relation, between pairs of classes, is Specialization.

The macro for creating relation symbols is !r. This adds a relation symbol to the graph, and annotates it with its entity type.

!r{ diagram identifier }{ entity type name }

Here, we first add [l] to ensure a hop one step to the left, i.e., to halfway between the two classes. Then we insert !r{spec_person_child}{Specialization} to add the symbol to the graph. The diagram identifier spec_person_child is only introduced so that we have a way to refer to the relation symbol within the context of the diagram. Our code section now looks like this,

{{{
#!LatexEquation
\TemplateDiagram{
  !c{person}{Person}{Class of Individual}
  [rr]
  !c{child}{Child}{Class of Individual}
  [l]
  !r{spec_person_child}{Specialization}
 }
}}}

and the resulting graph like this.

5. Adding roles to relations: The macro [!s]

The specialization relation in the diagram needs to be tied to the classes it relates. This is done using the !s macro, which takes five arguments:

  1. The identifier of the relation to be given some roles
  2. The identifier of "end 1" of the relation, its "left side"
  3. The name of the role on the left side of the relation
  4. The identifier of "end 2" of the relation, its "right side"
  5. The name of the role on the right side of the relation

!s{ relation identifier }{ end 1 identifier }{ end 1 role name }{ end 2 identifier }{ end 2 role name }

We can refer to the documentation for Specialization to find that the role of subclass appears first, i.e., as end 1, and that the role of superclass appears second, i.e., as end 2. The identifiers we have used for, respectively, the Person class, the Child class, and the Specialization relation between them are "person", "child", and "spec_person_child". This means we should add the roles by filling in the macro as follows.

!s{spec_person_child}{child}{subclass}{person}{superclass}

NB.

  • this macro depends on the participants having been defined earlier in the graph, or else the references to identifiers will not be understood by the processor
  • this macro doesn't require any hops. In order to avoid any disruption, place the macro in parentheses, as follows (refer to the xy-pic documentation for details).

(!s{spec_person_child}{child}{subclass}{person}{superclass})

Our diagram now has the following encoding,

{{{
#!LatexEquation
\TemplateDiagram{
  !c{person}{Person}{Class of Individual}
  [rr]
  !c{child}{Child}{Class of Individual}
  [l]
  !r{spec_person_child}{Specialization}
  (!s{spec_person_child}{child}{subclass}{person}{superclass})
 }
}}}

producing this drawing:

This completes the introduction. The three macros !c, !r, and !s, and hops [r], [l], [u], and [d] is all you need to get started drawing diagrams. If you wish to add more sophisticated elements to your drawings, check out the documentation for LaTeX in general, or xy-pic in particular.

Home
About PCA
Reference Data Services
Projects
Workgroups