Flowcharts

Contents
1 Introduction . . . . . . . . . . . . . . . 1 8 Bonus points . . . . . . . . . . . . . . 8
2 The grid . . . . . . . . . . . . . . . . . . 1 9 Clip and focus . . . . . . . . . . . . . 9
3 Shapes . . . . . . . . . . . . . . . . . . . 2 10 Line types . . . . . . . . . . . . . . . . 10
4 Connections . . . . . . . . . . . . . . . 3 11 Overlays . . . . . . . . . . . . . . . . . 12
5 Adding text . . . . . . . . . . . . . . . 5 12 Interaction . . . . . . . . . . . . . . . 13
6 Inheritance . . . . . . . . . . . . . . . . 6 13 Splitting charts . . . . . . . . . . . 14
7 How it works . . . . . . . . . . . . . . 7 14 Other features . . . . . . . . . . . . 17
 1

1 Introduction
This is just another story of TEX meeting MetaPost. This time we will focus on charts,
especially flowcharts. In ConTEXt flowchart support is not part of the core functionality,
but is provided as a module. Therefore, before you can actually define a chart, this
module must be loaded:

\usemodule[chart]

Once loaded, you has access to the functionality described here. Before we go into detail
on the features, we will say some words on history.

When dealing with graphics, it makes sense to use a drawing program. In fact, before
we started using this module, we did use such programs, and they have without doubt
their advantages. As soon as ConTEXt supported interactive documents, there were
means to make graphics interactive, and as long as only a few graphics are involved,
this mechanism works ok.

And then we suddenly had to make a document with thousands of pages and hundreds
of often rather complicated flowcharts. Because these charts were tightly integrated in
the main document, they not only had to be consistent in the use of fonts, but also
had to be interactive and were to be presented both as a whole and in subchart parts.
We wanted fonts, colors and the overall appearance as well as names of people, places,
steps, activities and more to be consistent, especially because these charts are constantly
updated.

I use the term flowchart here because I want to stress that this module typesets charts
which cells are connected by lines (often arrows). Our first application of this module
concerned diagrams that expressed actions and relations between those actions, using
some techniques originating years ago in programming environments: lines were not
to cross, one should read from top to bottom and left to right, etc. However, the module
presented here can be used to draw all kind of charts, and all kind of connections. But
there are limits.

This manual is mostly the one written of end 1998 when the flowchart module showed up in the
distribution. In the meantime the code has been rewritten for MkIV and some functionality is
adapted. But the interface hasn’t changed much.

2 The grid
A flowchart consists of shapes, positioned on a grid, connected by lines. The grid en-
ables the user to anchor the shapes and enables the drawing routines to determine con-
nections. One can either explicitly specify the grid, or let it be calculated automatically.

Normally the grid is not visible, unless one enters test mode. The grid in figure 1 is the
result of the definition:

\setupFLOWcharts
[option=test,
 2

(1,1) (2,1) (3,1) (4,1)

(1,2) (2,2) (3,2) (4,2)

(1,3) (2,3) (3,3) (4,3)

Figure 1 The grid.

nx=4,
ny=3,
dx=\bodyfontsize,
dy=\bodyfontsize,
width=6\bodyfontsize,
height=4\bodyfontsize,
maxwidth=\textwidth]

\startFLOWchart [grid]
\stopFLOWchart

The most straightforward way of calling up this chart is by saying:

\FLOWchart[grid]

In figure 1 we see a grid an dwithin each cell a shape. Normally shapes are smaller
than grid cells. This is necessary because connecting lines need some room. The offset
is important, because when a connection follows the outer lines, a little extra space
outside that line not only looks better, but also prevents the line from being clipped. It
makes sense to keep the offset as well as the space between shapes constant across a
document. The numbers are typeset outside the bounding box of the figure.

Grid cells are numbered from top to bottom starting at the left side, so the left topmost
cell is (1, 1). Later we will see that because cells have names, these numbers play a
minor role.

3 Shapes
A shape is something, typically a text, within a frame. The frame has certain dimensions
and can have some color and background. In this respect it looks like the ConTEXt
command \framed. The most important shapes have been assigned names as indicated
 3

in figure 2. There are more shapes, but they are identified by a number only. The total
number of shapes will quite certainly increase. The shapes up, down, left and right are
not really shapes, but lines that can be used to force a direction.

node action procedure product

decision archive loop wait

sub procedure single multi

document document

right left up down

Figure 2 The shapes.

When no shape is specified, the default shape is used. One can change this default
value with the \setupFLOWshapes command.

\startFLOWchart [cells]
\startFLOWcell
\name {first}
\location {1,1}
\shape {singledocument}
\text {not realy a document}
\stopFLOWcell
\stopFLOWchart

A flow chart consists of cells. Each cell has a name, is positioned somewhere on the
grid, has a certain shape, and normally this shape surrounds text. The shape is drawn
by MetaPost, and the text is placed by TEX. Later we will see that there are some more
fields to fill. Names are local to a chart.

not realy a
document

Figure 3

4 Connections
Shapes can be connected. As shown in figure 4 each shape has four connection points:
top, bottom, left and right. When connecting shapes we refer to their logical names and
specify two of the four directions.
 4

Figure 4 The connection points.

In figure 5 we see three connections. The lines have smooth curves and run across the
grid lines. By using smooth curves, an option that can be turned off, the direction of
touching curves is always clear. Here we use arrows. Smoothing, arrows and dashed
lines are some of the attributes of lines.

first second third

Figure 5 A few connections.

first second

Figure 6 A few
more connections.

There can be more than one connection per shape. When defining such a connection
we first specify the direction. In this example [rl] means connect the right point to
the left one, while [tr] results in a connection between the top and the right point.
The second argument specifies the shape to connect to. As we can see, connections can
point back to their origin shape.

first second third

Figure 7 Going around shapes.

first second

third fourth

Figure 8 Following grid lines.

The connection drawing routines have a rather strong urge to follow grid lines. Figure 8
demonstrates this several times. From the first shape to the third one, we see that the
connection takes the shortest route possible without crossing other shapes. I have to
admit that the routines in themselves are rather stupid, but for normal use they suffice.
 5

Generally speaking, when two lines end at the same point, it makes sense to connect
these. When on the other hand lines originate at the same point or cross eachother,
readers can get confused. Therefore such lines are drawn in such a way that they don’t
touch. In this respect, figure 9 demonstrates a less than optimal chart.

first second

third fourth

Figure 9 Confusing (crossing) grid lines.

5 Adding text
In figure 10 we have added some comment to a connection. Like the dots at the con-
nections, the point halfway the connection shows up in a special debugging mode. The
comment will be placed relative to this point. In figure 10 this is to the left of the point.

from here to there here

there

Figure 10 Comment
to connections.

It will be no surprise that a comment is defined using \comment. Comments can be

anchored to eight locations, simply l, r, t, b, or a combination like tr.

\startFLOWcell
...
\comment [l] {from here to there}
...
\stopFLOWcell

here

from here
to there there

Figure 11 Labels to
connection points.
 6

We can also put labels at the connection points. Often this is preferred over comment
halfway along a connection. Like comments, labels have a dedicated command. Here
we specify the connection point l, r, t or b.

\startFLOWcell
...
\label [l] {to there}
...
\stopFLOWcell

Is there any
here reason to go
from here
to there?

there

Figure 12 Text without shapes.

In figure 12 we see some text without any shapes around it. When shape none is speci-
fied, the whole shape area is available for text.

\startFLOWcell
\shape {none}
\location {2,1}
\text {Is there any reason to go
from here to there?}
\stopFLOWcell

One can force the alignment with the key characters l, r, c, t and b. So, the next def-
inition only places text.

6 Inheritance
When explaining something by using a chart, we often show successive versions of the
chart, where each version adds a new feature. To prevent us from retyping the same
components again and again, it helps to partition the source code of the complete chart
into subcharts. Inclusion of a part is straightforward: the subchart is called by name
and positioned on the grid.

\startFLOWchart [include]

\includeFLOWchart[labels][x=1,y=1]

\startFLOWcell
\shape {none}
\location {2,1}
\text {There is no reason to go
 7

from here to there!}

\stopFLOWcell

\stopFLOWchart

The included sub chart has its own reference point, so one does not have to bother about
positions.

There is no
here reason to go
from here
to there!
from here
to there there

Figure 13 Sharing components.

7 How it works
The charting module, loaded by \usemodule[chart] is only responsible for the TEX part
of the job, which means positioning text and graphics generated by MetaPost. The grid,
shape and connection drawing routines are grouped together in a dedicated MetaPost
module.

Because of the mix of TEX and MetaPost, and because we want to be able to scale charts,
the buffer mechanism is used. The communication between TEX and MetaPost uses the
MetaPost embedding macros that are native to ConTEXt. Additional communication
from MetaPost to ConTEXt is handled in the module itself. This rather fuzzy descrip-
tion is visualized in figure 14. Depending on the general color settings, among the other
processes involved are: color conversion and/or reduction to grayscales, and conver-
sion to pdf. When watching this module in action, don’t feel disturbed by the many
steps involved.

PostScript

User File ConTEXt scalable buffer MetaPost

Data File

Figure 14 The process.

A few pages back we introduced the named shapes. There are however some more
shapes. Each shape is identified by a number. In figure 15 all currently available shapes
are shown. The zero numbered shape is actually a shape, but with zero dimensions.
 8

It can be used as a meeting point for lines. The unused numbers can be used for new
shapes. The maximum number of shapes is limited to 4095, which is a MetaPost limi-
tation.

1 2 3 4 5 6 7 8 9 10

11 12 13 14 15 16 17 18 19 20

21 22 23 24 25 26 27 28 29 30

31 32 33 34 35 36 37 38 39 40

41 42 43 44 45 46 47 48 49 50

51 52 53 54 55 56 57 58 59 60

61 62 63 64 65 66 67 68 69 70

71 72 73 74 75 76 77 78 79 80

Figure 15 All shapes by number. Shape 0 is valid and has zero dimensions.

8 Bonus points
Sometimes charts can become rather large, due to the many shapes used or lines drawn.
At the same time charts can become unclear because more than one connection starts
or ends at a shape. Figure 16 shows a way out of this situation.

TEX dvi PostScript pdf

Figure 16 Even more points.

Defining such a chart is not so much harder than previous cases. Each left, right, top
and bottom point has two companion points: positive and negative. In connections
the left points are: pl, l and nl: positive left, left and negative left, so the first cell in
figure 16 is defined as:

\startFLOWcell
 9

TEX dvi PostScript

pdf

Figure 17 An alternative for figure 16.

TEX dvi PostScript pdf

Figure 18 Yet another alternative for figure 16.

\name {tex}
\location {1,1}
\shape {action}
\text {\TEX}
\connection [prpl] {pdf}
\connection [nrnl] {dvi}
\stopFLOWcell

Alternatively to p and n one may use + and -. As soon as the positive and negative
points are used, the connection drawing routines will take into account the fact that
they are off--center. This does not free users from thinking about better ways to draw
such a chart.

9 Clip and focus

The flowcharter automatically calculates the size of the grid. When needed, one can
force the dimensions and/or clip pieces of a chart. Figure 19 shows such a clip. This
example also shows why the offset, the small area around the outer grid lines, is im-
portant. Figure 19 was produced while the next settings were in action.

\setupFLOWcharts
[x=1,y=1,nx=2,ny=1]

first second

Figure 19 Clipping
a piece of a chart.

Sometimes, for instance when explaining a chart, it makes sense to emphasize one or
more particular cells. Therefore this module offers the ability to focus on cells. In fig-
ure 20 we see that the focus is on the cell with name dvi. This is accomplished by
saying:
 10

\setupFLOWfocus
[framecolor=pragmacolor]
\setupFLOWcharts
[focus=dvi]

TEX dvi PostScript pdf

Figure 20 Gaining some focus.

Clipping and focus bring us to the third way of zooming in: autofocus. Figure 21 shows
what happens when we say:

\setupFLOWfocus
[framecolor=pragmacolor]
\setupFLOWcharts
[focus=dvi,autofocus=dvi,
nx=1,ny=1]

\startFLOWchart [bonus 3]
\startFLOWcell
\name {tex}
\location {1,1}
\shape {action}
\text {\TEX}
\connection [rl] {pdf}
\stopFLOWcell
\startFLOWcell
\name {pdf}
\location {4,1}
\shape {action}
\text {\PDF}
\stopFLOWcell
\stopFLOWchart

Figure 21 Applying autofocus.

In figure 21 we see both focus and auto focus in action.

10 Line types
As is to be expected, we can set up some characteristics of a chart, the shapes, the con-
necting lines, and the focus. When we want dashed lines and a different shape color,
we just say:
 11

\setupFLOWshapes
[framecolor=pragmacolor]
\setupFLOWlines
[framecolor=pragmacolor,
dash=yes]

TEX pdf

Figure 22 Dashed and colored lines.

We can change the characteristics at several levels: chart, line, shape and/or focus. In
the near future some more options will be added. Once the MetaPost module is stable
and documented, the graphic code will also be accessible. The formal definition of the
four setup commands is as follows (these diagrams conform the ConTEXt conventions):

*
\setupFLOWcharts [..,..=..,..]

* width = DIMENSION
height = DIMENSION
offset = DIMENSION
dx = DIMENSION
dy = DIMENSION
nx = NUMBER
ny = NUMBER
x = NUMBER
y = NUMBER
labeloffset = DIMENSION
commentoffset = DIMENSION
exitoffset = DIMENSION
split = yes no
bodyfont = inherits: \setupbodyfont
option = test
focus = TEXT
autofocus = yes no
autofocus = yes no
background =
framecolor = COLOR
backgroundcolor = COLOR
rulethickness = DIMENSION
frame = on off
 12

*
\setupFLOWfocus [..,..=..,..]

* color = COLOR
background = inherits: \setupFLOWshape
backgroundcolor = inherits: \setupFLOWshape
rulethickness = inherits: \setupFLOWshape
offset = inherits: \setupFLOWshape

*
\setupFLOWlines [..,..=..,..]

* color =
arrow =
dash =
radius = DIMENSION
color =
rulethickness =
offset = DIMENSION

*
\setupFLOWshapes [..,..=..,..]

* default =
framecolor =
background =
backgroundcolor =
rulethickness =
offset = none overlay standard DIMENSION

11 Overlays
Why should we limit ourselves to text? In ConTEXt most frames--related features can
have overlays. Because in this flowchart module shapes are drawn by MetaPost, we use
a slightly different approach: there can be overlays but they are sort of clipped by the
shape. Figure 23 illustrates this.

\defineoverlay
[coward]
[{\externalfigure
[cow]
[width=\overlaywidth,
height=\overlayheight]}]

\startFLOWchart [overlay]
\startFLOWcell
\name {alpha}
\location {1,1}
\shape {procedure}
\connection [rl] {beta}
\figure {cow}
 13

\text [lt] {\darkred \bfb COW 1}

\stopFLOWcell
\startFLOWcell
\name {beta}
\location {2,1}
\shape {product}
\connection [rl] {gamma}
\overlay {cow}
\text {\darkgreen \bfb COW 2}
\stopFLOWcell
\startFLOWcell
\name {gamma}
\location {3,1}
\shape {action}
\connection [rl] {alpha}
\overlay {cow}
\text [rb] {\darkblue \bfb COW 3}
\stopFLOWcell
\stopFLOWchart

COW 1
COW 2
COW 3
Figure 23 Overlays.

There are two commands related to overlays. In our example we used: which automati-
cally scales figure cow to the shape size. The normal rules for overlays apply. The width
and height of the overlay are available at the moment the overlay is typeset.

The text is aligned differently in this example and driven by an optional argument that
can take one of the following values: l, r, m, c, t, b, lt, rt, mt, ct, lb, rb, mb, cb.

12 Interaction
One of the reasons for writing this module was that we wanted interactive flowcharts.
The shape text can contain references.1 The shape as a whole becomes a button as soon
as we add the \destination entry:

\startFLOWcell
...
\destination {destination}
...
\stopFLOWcell

1 Currently this only works ok when the chart is not scaled.

 14

Did you
introduction read me
indeed?

Figure 24 Interactive buttons.

When read as pdf file, figure 24 shows quite a few interactive features. The first cell has
a \goto included in the text, like:

\startFLOWcell
...
\text {\goto{introduction}[introduction]}
...
\stopFLOWcell

The second shape is interactive as a whole. This is accomplished by saying:

\startFLOWcell
...
\text {Did you\\read me\\indeed?}
\destination {introduction}
...
\stopFLOWcell

The third cell is a movie, which is only visible in suitable viewers. The movie is included
as an overlay.

\defineoverlay
[fun]
[{\externalfigure
[texwork.mov]
[width=\framedwidth,
height=\framedheight,
preview=yes,
repeat=yes]}]

The last cell is an illustration.

13 Splitting charts
Sometimes a chart does not fit comfortably on the page. In such cases, it makes sense
to split up the chart. There is a dedicated setup command to serve splitting:
 15

*
\setupFLOWsplit [..,..=..,..]

* dx =
dy =
nx =
ny =
command =
before =
after =

An example of splitting is:

\setupFLOWsplit
[nx=5,ny=10,
dx=1,dy=1,
before=,after=\page]

\FLOWchart[mybigflow]

For easy alignment of the split pages, cut marks are added. This can be turned off by
setting marking to off. The n parameters determine the number of cells per split off
subject, and the d parameters specify the overlap: a value of 1 means that each split off
subject has one row and/or columns in common with its neighbour.

The splitter can be used with the split float placement macro:

\splitfloat
{\placefigure{What a big flowchart this is!}}
{\FLOWchart[mybigflow]}

Here every flowchart gets an caption with a decent subnumber.

Related to splitting up charts is the option to define exit points as demonstrated in the
next chart.

\startFLOWchart[metatex]
\setupFLOWcharts
[width=6\bodyfontsize,
height=3\bodyfontsize,
dx=\bodyfontsize,
dy=\bodyfontsize]
\startFLOWcell
\name {texexec 1}
\location {1,1}
\shape {action}
\text {\TEXEXEC}
\connection [rl] {context 1}
\stopFLOWcell
\startFLOWcell
\name {context 1}
 16

\location {2,1}
\shape {action}
\text {\CONTEXT}
\connection [bt] {metapost 1}
\connection [rl] {texexec 2}
\exit [r] {123}
\stopFLOWcell
\startFLOWcell
\name {metapost 1}
\location {2,2}
\shape {action}
\text {\METAPOST}
\stopFLOWcell
\startFLOWcell
\name {texexec 2}
\location {3,1}
\shape {action}
\text {\TEXEXEC}
\connection [rl] {context 2}
\connection [bt] {metapost 2}
\exit [l] {123}
\stopFLOWcell
\startFLOWcell
\name {context 2}
\location {4,1}
\shape {action}
\text {\CONTEXT}
\stopFLOWcell
\startFLOWcell
\name {metapost 2}
\location {3,2}
\shape {action}
\text {\METAPOST}
\stopFLOWcell
\stopFLOWchart

When we ask for subcharts, the exit points will show up. Because they don’t attribute
to the dimensions of the chart, you can still align charts as expected.

TEXexec ConTEXt

MetaPost

\FLOWchart [metatex] [x=1,nx=2,frame=on]

 17

TEXexec ConTEXt

MetaPost

\FLOWchart [metatex] [x=3,nx=2,frame=on]

14 Other features
It is possible to predefine flow charts in a way similar to external figures. Currently this
mechanism is under construction, so describing it would be a bit premature.

Crossing lines, which are often forbidden in charts, can be made less confusing by
adding a gap in the lines to be crossed. This is one of the features that are already
implemented but not yet accessible by the ConTEXt user interface.

Another feature, used in this document, concerns automatic down--scaling. As soon

as we start scaling illustrations, we introduce inconsistent typography, especially in the
bodyfontsize. Therefore, the flow chart macros, when told to, are able to automatically
scale down in steps of 1 point.

This manual was first published in GUST magazine and presented at the anual meeting of the
Polish user group in Bachotek 1999. Next it was published in the MAPS volume 23. After that
it became Up--To--Date number 1999-003, and now it’s part of the manual series. This version
is for MkIV.

Hans Hagen
PRAGMA ADE
Hasselt NL