[[TracNav(TracNav/SigMmt)]]

= Drawing ISO 15926 diagrams using macros =

This page describes how content in ISO 15926 format can be represented in diagrams, using [http://www.tug.org/ LaTeX], the [http://www.tug.org/applications/Xy-pic/ xy-pic] extension, and macros defined in the [source:SIG/MMT/work/tools/templatediagram.sty templatediagram.sty] style.

[[PageOutline(2-4,Contents,inline)]]


The diagrams described here use the ''graph'' feature of xy-pic (see the [http://tug.org/applications/Xy-pic/soft/xyrefer.ps 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 [source:SIG/MMT/work/tools/templatediagram.sty 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.

{{{
#!html
<pre class="wiki">
{{{
#!LatexEquation
\TemplateDiagram{

         The diagram goes here!  

 }
}}}
</pre>
}}}

=== 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 [http://www.tc184-sc4.org/wg3ndocs/wg3n1328/lifecycle_integration_schema/lifecycle_integration_schema.html 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:
{{{
#!html
<pre class="wiki">
{{{
#!LatexEquation
\TemplateDiagram{
  !c{person}{Person}{Class of Individual}
 }
}}}
</pre>
}}}
This input produces the following graph.
{{{
#!LatexEquation
\TemplateDiagram{
  !c{person}{Person}{Class of Individual}
 }
}}}

=== 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.
{{{
#!html
<pre class="wiki">
{{{
#!LatexEquation
\TemplateDiagram{
  !c{person}{Person}{Class of Individual}
  [rr]
  !c{child}{Child}{Class of Individual}
 }
}}}
</pre>
}}}
We now have the following graph.
{{{
#!LatexEquation
\TemplateDiagram{
  !c{person}{Person}{Class of Individual}
  [rr]
  !c{child}{Child}{Class of Individual}
 }
}}}

=== 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 ''[http://www.tc184-sc4.org/wg3ndocs/wg3n1328/lifecycle_integration_schema/lexical/specialization.html 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,
{{{
#!html
<pre class="wiki">
{{{
#!LatexEquation
\TemplateDiagram{
  !c{person}{Person}{Class of Individual}
  [rr]
  !c{child}{Child}{Class of Individual}
  [l]
  !r{spec_person_child}{Specialization}
 }
}}}
</pre>
}}}
and the resulting graph like this.
{{{
#!LatexEquation
\TemplateDiagram{
  !c{person}{Person}{Class of Individual}
  [rr]
  !c{child}{Child}{Class of Individual}
  [l]
  !r{spec_person_child}{Specialization}
 }
}}}

=== 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"
 2. The name of the role on the left side of the relation
 2. The identifier of "end 2" of the relation, its "right side"
 2. 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 [http://www.tc184-sc4.org/wg3ndocs/wg3n1328/lifecycle_integration_schema/lexical/specialization.html 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,
{{{
#!html
<pre class="wiki">
{{{
#!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})
 }
}}}
</pre>
}}}
producing this drawing:
{{{
#!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})
 }
}}}

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.