1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20\usemodule[abr02]
21
22\usemodule[setupsbasics] \loadsetups[ichart.xml]
23
24\setupexternalfigures
25 [location={local,default}]
26
27\setuplayout
28 [topspace=15mm,
29 header=15mm,
30 headerdistance=0mm,
31 footer=0cm,
32 width=middle,
33 height=middle]
34
35\setuppagenumbering
36 [alternative=doublesided]
37
38\definetypeface [mainface] [rm] [serif] [pagella] [default]
39\definetypeface [mainface] [ss] [sans] [heros] [default]
40\definetypeface [mainface] [tt] [mono] [modern] [default]
41\definetypeface [mainface] [mm] [math] [pagella] [default]
42
43\setupbodyfont[mainface,12pt]
44
45
46\definecolor[maincolor][r=.2,g=.1,b=.3]
47
48\setupwhitespace
49 [big]
50
51\setuptolerance
52 [verytolerant,stretch]
53
54\setuptype
55 [color=maincolor]
56
57\setuptyping
58 [color=maincolor]
59
60\setuphead
61 [section]
62 [style=\bfb,
63 color=maincolor]
64
65\setupinteraction
66 [state=start,
67 color=,
68 contrastcolor=,
69 style=]
70
71\startsetups titlepage
72 \startpagemakeup[doublesided=no,page=no]
73 \useMPgraphic{titlepage}
74 \stoppagemakeup
75 \startstandardmakeup[doublesided=no,page=no]
76 \vfill
77 \startsubject[title=Contents]
78 \startcolumns[distance=4em]
79 \placelist[section][alternative=c,width=2em]
80 \stopcolumns
81 \stopsubject
82 \stopstandardmakeup
83\stopsetups
84
85\startsetups colofon
86 \blank[2*big]
87 \testpage[3]
88 \startpacked
89 \documentvariable{author}\par
90 \documentvariable{affiliation}\par
91 \documentvariable{location}\par
92 \stoppacked
93\stopsetups
94
95\setupdocument
96 [title=No Title,
97 before=\setups{titlepage},
98 after=\setups{colofon}]
99
100
101
102\usemodule[chart]
103
104\setupFLOWcharts
105 [width=2.25cm,
106 height=1.25cm,
107 dx=.25cm,
108 dy=.25cm]
109
110\startuseMPgraphic{titlepage}
111 numeric width, height, delta ;
112 color a, b, c, d ;
113
114 width := PaperWidth ;
115 height := PaperHeight ;
116 delta := width10 ;
117 ahlength := 6delta ;
118
119 a := white2 ;
120 b := white3 ;
121 c := resolvedcolor ("maincolor") ;
122 d := c ;
123
124 path p ; p := unitsquare xscaled width yscaled height ;
125
126 fill p withcolor c ;
127
128 drawarrow llcorner p -- urcorner p withpen pencircle scaled (3.0delta) withcolor a ;
129 draw llcorner p -- urcorner p withpen pencircle scaled (4.0delta) withcolor a ;
130 drawarrow urcorner p -- llcorner p withpen pencircle scaled (2.5delta) withcolor b ;
131 draw llcorner p -- urcorner p withpen pencircle scaled (3.0delta) withcolor b ;
132 drawarrow llcorner p -- urcorner p withpen pencircle scaled (2.0delta) withcolor d ;
133 drawarrow urcorner p -- llcorner p withpen pencircle scaled (1.5delta) withcolor d ;
134
135 draw anchored.lrt(
136 textext("\ss\bf \documentvariable{title}") rotated 90 xsized (3delta4),
137 lrcorner p shifted (delta,3delta4)
138 ) withcolor white ;
139
140 resetarrows ;
141
142 setbounds currentpicture to p ;
143\stopuseMPgraphic
144
145\startdocument
146 [title=Flowcharts,
147 author= Hans Hagen,
148 affiliation=PRAGMA ADE,
149 location=Hasselt NL]
150
151\startsection[reference=introduction,title={Introduction}]
152
153This is just another story of \TEX\ meeting \METAPOST. This time we will focus on
154charts, especially flowcharts. In \CONTEXT\ flowchart support is not part of the
155core functionality, but is provided as a module. Therefore, before you can
156actually define a chart, this module must be loaded:
157
158\starttyping
159\usemodule[chart]
160\stoptyping
161
162Once loaded, you has access to the functionality described here. Before we go
163into detail on the features, we will say some words on history.
164
165When dealing with graphics, it makes sense to use a drawing program. In fact,
166before we started using this module, we did use such programs, and they have
167without doubt their advantages. As soon as \CONTEXT\ supported interactive
168documents, there were means to make graphics interactive, and as long as only a
169few graphics are involved, this mechanism works ok.
170
171And then we suddenly had to make a document with thousands of pages and hundreds
172of often rather complicated flowcharts. Because these charts were tightly
173integrated in the main document, they not only had to be consistent in the use of
174fonts, but also had to be interactive and were to be presented both as a whole
175and in subchart parts. We wanted fonts, colors and the overall appearance as well
176as names of people, places, steps, activities and more to be consistent,
177especially because these charts are constantly updated.
178
179I use the term flowchart here because I want to stress that this module typesets
180charts which cells are connected by lines (often arrows). Our first application
181of this module concerned diagrams that expressed actions and relations between
182those actions, using some techniques originating years ago in programming
183environments: lines were not to cross, one should read from top to bottom and
184left to right, etc. However, the module presented here can be used to draw all
185kind of charts, and all kind of connections. But there are limits.
186
187{\em This manual is mostly the one written of end 1998 when the flowchart module
188showed up in the distribution. In the meantime the code has been rewritten for
189\MKIV\ and some functionality is adapted. But the interface hasnt changed much.}
190
191\stopsection
192
193\startsection[title={The grid}]
194
195A flowchart consists of shapes, positioned on a grid, connected by lines. The
196grid enables the user to anchor the shapes and enables the drawing routines to
197determine connections. One can either explicitly specify the grid, or let it be
198calculated automatically.
199
200\startbuffer[grid]
201\setupFLOWcharts
202 [option=test,
203 nx=4,
204 ny=3,
205 dx=\bodyfontsize,
206 dy=\bodyfontsize,
207 width=6\bodyfontsize,
208 height=4\bodyfontsize,
209 maxwidth=\textwidth]
210
211\startFLOWchart [grid]
212\stopFLOWchart
213\stopbuffer
214
215\placefigure
216 [here][fig:grid]
217 {The grid.}
218 {\getbuffer[grid]\FLOWchart[grid]}
219
220Normally the grid is not visible, unless one enters test mode. The grid in \in
221{figure} [fig:grid] is the result of the definition:
222
223\typebuffer[grid]
224
225The most straightforward way of calling up this chart is by saying:
226
227\starttyping
228\FLOWchart[grid]
229\stoptyping
230
231In \in {figure} [fig:grid] we see a grid an dwithin each cell a shape. Normally
232shapes are smaller than grid cells. This is necessary because connecting lines
233need some room. The offset is important, because when a connection follows the
234outer lines, a little extra space outside that line not only looks better, but
235also prevents the line from being clipped. It makes sense to keep the offset as
236well as the space between shapes constant across a document. The numbers are
237typeset outside the bounding box of the figure.
238
239Grid cells are numbered from top to bottom starting at the left side, so the left
240topmost cell is $(1,1)$. Later we will see that because cells have names, these
241numbers play a minor role.
242
243\stopsection
244
245\startsection[title={Shapes}]
246
247A shape is something, typically a text, within a frame. The frame has certain
248dimensions and can have some color and background. In this respect it looks like
249the \CONTEXT\ command \type {\framed}. The most important shapes have been
250assigned names as indicated in \in {figure} [fig:shapes]. There are more shapes,
251but they are identified by a number only. The total number of shapes will quite
252certainly increase. The shapes {\em up}, {\em down}, {\em left} and {\em right}
253are not really shapes, but lines that can be used to force a direction.
254
255\startFLOWchart [shapes]
256\startFLOWcell \name{a} \location{1,1} \shape{node} \text{node} \stopFLOWcell
257\startFLOWcell \name{b} \location{2,1} \shape{action} \text{action} \stopFLOWcell
258\startFLOWcell \name{c} \location{3,1} \shape{procedure} \text{procedure} \stopFLOWcell
259\startFLOWcell \name{d} \location{4,1} \shape{product} \text{product} \stopFLOWcell
260\startFLOWcell \name{e} \location{1,2} \shape{decision} \text{decision} \stopFLOWcell
261\startFLOWcell \name{f} \location{2,2} \shape{archive} \text{archive} \stopFLOWcell
262\startFLOWcell \name{g} \location{3,2} \shape{loop} \text{loop} \stopFLOWcell
263\startFLOWcell \name{h} \location{4,2} \shape{wait} \text{wait} \stopFLOWcell
264\startFLOWcell \name{i} \location{1,3} \shape{subprocedure} \text{sub procedure} \stopFLOWcell
265\startFLOWcell \name{j} \location{2,3} \shape{singledocument} \text{single document} \stopFLOWcell
266\startFLOWcell \name{k} \location{3,3} \shape{multidocument} \text{multi document} \stopFLOWcell
267
268\startFLOWcell \name{l} \location{1,4} \shape{right} \text{right} \stopFLOWcell
269\startFLOWcell \name{m} \location{2,4} \shape{left} \text{left} \stopFLOWcell
270\startFLOWcell \name{n} \location{3,4} \shape{up} \text{up} \stopFLOWcell
271\startFLOWcell \name{o} \location{4,4} \shape{down} \text{down} \stopFLOWcell
272\stopFLOWchart
273
274\placefigure
275 [here][fig:shapes]
276 {The shapes.}
277 {\tx\FLOWchart[shapes]}
278
279When no shape is specified, the default shape is used. One can change this
280default value with the \type {\setupFLOWshapes} command.
281
282\startbuffer[cells]
283\startFLOWchart [cells]
284 \startFLOWcell
285 \name {first}
286 \location {1,1}
287 \shape {singledocument}
288 \text {not realy a document}
289 \stopFLOWcell
290\stopFLOWchart
291\stopbuffer
292
293\typebuffer[cells]
294
295\getbuffer[cells]
296
297A flow chart consists of cells. Each cell has a name, is positioned somewhere on
298the grid, has a certain shape, and normally this shape surrounds text. The shape
299is drawn by \METAPOST, and the text is placed by \TEX. Later we will see that
300there are some more fields to fill. Names are local to a chart.
301
302\placefigure
303 [][fig:cells]
304 {}{\tx\FLOWchart[cells]}
305
306\stopsection
307
308\startsection[title={Connections}]
309
310Shapes can be connected. As shown in \in {figure} [fig:points] each shape has
311four connection points: top, bottom, left and right. When connecting shapes we
312refer to their logical names and specify two of the four directions.
313
314\startFLOWchart [points]
315\startFLOWcell \name{a} \location{1,1} \shape{procedure} \stopFLOWcell
316\startFLOWcell \name{b} \location{2,1} \shape{product} \stopFLOWcell
317\startFLOWcell \name{c} \location{3,1} \shape{archive} \stopFLOWcell
318\startFLOWcell \name{d} \location{4,1} \shape{multidocument} \stopFLOWcell
319\stopFLOWchart
320
321\placefigure
322 [here][fig:points]
323 {The connection points.}
324 {\tx\setupFLOWcharts[dot=con]\FLOWchart[points]}
325
326In \in {figure} [fig:connect] we see three connections. The lines have smooth
327curves and run across the grid lines. By using smooth curves, an option that can
328be turned off, the direction of touching curves is always clear. Here we use
329arrows. Smoothing, arrows and dashed lines are some of the attributes of lines.
330
331\startFLOWchart [connect]
332 \startFLOWcell
333 \name {alpha}
334 \location {1,1}
335 \shape {procedure}
336 \text {first}
337 \connection [rl] {beta}
338 \stopFLOWcell
339 \startFLOWcell
340 \name {beta}
341 \location {2,1}
342 \shape {product}
343 \text {second}
344 \connection [bl] {alpha}
345 \connection [rl] {gamma}
346 \stopFLOWcell
347 \startFLOWcell
348 \name {gamma}
349 \location {3,1}
350 \shape {action}
351 \text {third}
352 \stopFLOWcell
353\stopFLOWchart
354
355\placefigure
356 [here][fig:connect]
357 {A few connections.}
358 {\tx\setupFLOWcharts[dot=con]\FLOWchart[connect]}
359
360\startFLOWchart [two]
361 \startFLOWcell
362 \name {alpha}
363 \location {1,1}
364 \shape {action}
365 \text {first}
366 \connection [rl] {beta}
367 \connection [rl] {alpha}
368 \stopFLOWcell
369 \startFLOWcell
370 \name {beta}
371 \location {2,1}
372 \shape {loop}
373 \text {second}
374 \connection [tr] {beta}
375 \stopFLOWcell
376\stopFLOWchart
377
378\placefigure
379 {A few more connections.}
380 {\tx\setupFLOWcharts[dot=con]\FLOWchart[two]}
381
382There can be more than one connection per shape. When defining such a connection
383we first specify the direction. In this example \type {[rl]} means connect the
384right point to the left one, while \type {[tr]} results in a connection between
385the top and the right point. The second argument specifies the shape to connect
386to. As we can see, connections can point back to their origin shape.
387
388\startFLOWchart [around]
389 \startFLOWcell
390 \name {alpha}
391 \location {1,1}
392 \shape {procedure}
393 \text {first}
394 \connection [rl] {gamma}
395 \stopFLOWcell
396 \startFLOWcell
397 \name {beta}
398 \location {2,1}
399 \shape {product}
400 \text {second}
401 \stopFLOWcell
402 \startFLOWcell
403 \name {gamma}
404 \location {3,1}
405 \shape {action}
406 \text {third}
407 \stopFLOWcell
408\stopFLOWchart
409
410\placefigure
411 [here][fig:around]
412 {Going around shapes.}
413 {\tx\setupFLOWcharts[dot=con]\FLOWchart[around]}
414
415\startFLOWchart [straight]
416 \startFLOWcell
417 \name {alpha}
418 \location {2,1}
419 \shape {procedure}
420 \text {first}
421 \connection [lt] {gamma}
422 \connection [rt] {delta}
423 \stopFLOWcell
424 \startFLOWcell
425 \name {beta}
426 \location {3,1}
427 \shape {product}
428 \text {second}
429 \connection [tl] {gamma}
430 \stopFLOWcell
431 \startFLOWcell
432 \name {gamma}
433 \location {1,2}
434 \shape {action}
435 \text {third}
436 \connection [rr] {delta}
437 \stopFLOWcell
438 \startFLOWcell
439 \name {delta}
440 \location {3,2}
441 \shape {archive}
442 \text {fourth}
443 \stopFLOWcell
444\stopFLOWchart
445
446\placefigure
447 [here][fig:straight]
448 {Following grid lines.}
449 {\tx\setupFLOWcharts[dot=con]\FLOWchart[straight]}
450
451The connection drawing routines have a rather strong urge to follow grid lines.
452\in {Figure} [fig:straight] demonstrates this several times. From the first shape
453to the third one, we see that the connection takes the shortest route possible
454without crossing other shapes. I have to admit that the routines in themselves
455are rather stupid, but for normal use they suffice.
456
457\startFLOWchart [straightagain]
458 \startFLOWcell
459 \name {alpha}
460 \location {2,1}
461 \shape {procedure}
462 \text {first}
463 \connection [lt] {gamma}
464 \connection [rt] {delta}
465 \stopFLOWcell
466 \startFLOWcell
467 \name {beta}
468 \location {3,1}
469 \shape {product}
470 \text {second}
471 \connection [tl] {gamma}
472 \connection [tt] {alpha}
473 \connection [bt] {delta}
474 \stopFLOWcell
475 \startFLOWcell
476 \name {gamma}
477 \location {1,2}
478 \shape {action}
479 \text {third}
480 \connection [rr] {delta}
481 \stopFLOWcell
482 \startFLOWcell
483 \name {delta}
484 \location {3,2}
485 \shape {archive}
486 \text {fourth}
487 \connection [bb] {gamma}
488 \stopFLOWcell
489\stopFLOWchart
490
491Generally speaking, when two lines end at the same point, it makes sense to
492connect these. When on the other hand lines originate at the same point or cross
493eachother, readers can get confused. Therefore such lines are drawn in such a way
494that they dont touch. In this respect, \in {figure} [fig:white] demonstrates a
495less than optimal chart.
496
497\placefigure
498 [here][fig:white]
499 {Confusing (crossing) grid lines.}
500 {\tx\setupFLOWcharts[dot=con]\FLOWchart[straightagain]}
501
502\stopsection
503
504\startsection[title={Adding text}]
505
506In \in {figure} [fig:comment] we have added some comment to a connection. Like
507the dots at the connections, the point halfway the connection shows up in a
508special debugging mode. The comment will be placed relative to this point. In \in
509{figure} [fig:comment] this is to the left of the point.
510
511\startFLOWchart [comment]
512 \startFLOWcell
513 \name {alpha}
514 \location {1,1}
515 \shape {action}
516 \text {here}
517 \connection [bl] {beta}
518 \comment [l] {from here to there}
519 \stopFLOWcell
520 \startFLOWcell
521 \name {beta}
522 \location {2,2}
523 \shape {action}
524 \text {there}
525 \stopFLOWcell
526\stopFLOWchart
527
528\placefigure
529 [here][fig:comment]
530 {Comment to connections.}
531 {\tx\setupFLOWcharts[dot=mid]\FLOWchart[comment]}
532
533It will be no surprise that a comment is defined using \type {\comment}. Comments
534can be anchored to eight locations, simply \type {l}, \type {r}, \type {t}, \type
535{b}, or a combination like \type {tr}.
536
537\starttyping
538\startFLOWcell
539 ...
540 \comment [l] {from here to there}
541 ...
542\stopFLOWcell
543\stoptyping
544
545\startFLOWchart [labels]
546 \startFLOWcell
547 \name {alpha}
548 \location {1,1}
549 \shape {action}
550 \text {here}
551 \connection [bl] {beta}
552 \label [b] {from here}
553 \stopFLOWcell
554 \startFLOWcell
555 \name {beta}
556 \location {2,2}
557 \shape {action}
558 \text {there}
559 \label [l] {to there}
560 \stopFLOWcell
561\stopFLOWchart
562
563\placefigure
564 [here][fig:labels]
565 {Labels to connection points.}
566 {\tx\setupFLOWcharts[dot=con]\FLOWchart[labels]}
567
568We can also put labels at the connection points. Often this is preferred over
569comment halfway along a connection. Like comments, labels have a dedicated
570command. Here we specify the connection point \type {l}, \type {r}, \type {t} or
571\type {b}.
572
573\starttyping
574\startFLOWcell
575 ...
576 \label [l] {to there}
577 ...
578\stopFLOWcell
579\stoptyping
580
581\startFLOWchart [text]
582 \startFLOWcell
583 \name {alpha}
584 \location {1,1}
585 \shape {action}
586 \text {here}
587 \connection [bl] {beta}
588 \stopFLOWcell
589 \startFLOWcell
590 \name {beta}
591 \location {2,2}
592 \shape {action}
593 \text {there}
594 \stopFLOWcell
595 \startFLOWcell
596 \shape {none}
597 \location {2,1}
598 \text {Is there any reason to go
599 from here to there?}
600 \stopFLOWcell
601\stopFLOWchart
602
603\placefigure
604 [here][fig:text]
605 {Text without shapes.}
606 {\tx\setupFLOWcharts[dot=con]\FLOWchart[text]}
607
608In \in {figure} [fig:text] we see some text without any shapes around it. When
609shape \type {none} is specified, the whole shape area is available for text.
610
611\starttyping
612\startFLOWcell
613 \shape {none}
614 \location {2,1}
615 \text {Is there any reason to go
616 from here to there?}
617\stopFLOWcell
618\stoptyping
619
620One can force the alignment with the key characters \type {l}, \type {r}, \type
621{c}, \type {t} and \type {b}. So, the next definition only places text.
622
623\stopsection
624
625\startsection[title={Inheritance}]
626
627When explaining something by using a chart, we often show successive versions of
628the chart, where each version adds a new feature. To prevent us from retyping the
629same components again and again, it helps to partition the source code of the
630complete chart into subcharts. Inclusion of a part is straightforward: the
631subchart is called by name and positioned on the grid.
632
633\startbuffer[include]
634\startFLOWchart [include]
635
636 \includeFLOWchart[labels][x=1,y=1]
637
638 \startFLOWcell
639 \shape {none}
640 \location {2,1}
641 \text {There is no reason to go
642 from here to there!}
643 \stopFLOWcell
644
645\stopFLOWchart
646\stopbuffer
647
648\typebuffer[include]
649
650The included sub chart has its own reference point, so one does not have to
651bother about positions.
652
653\getbuffer[include]
654
655\placefigure
656 [here][fig:include]
657 {Sharing components.}
658 {\tx\FLOWchart[include]}
659
660\stopsection
661
662\startsection[title={How it works}]
663
664The charting module, loaded by \type {\usemodule[chart]} is only responsible for
665the \TEX\ part of the job, which means positioning text and graphics generated by
666\METAPOST. The grid, shape and connection drawing routines are grouped together
667in a dedicated \METAPOST\ module.
668
669Because of the mix of \TEX\ and \METAPOST, and because we want to be able to
670scale charts, the buffer mechanism is used. The communication between \TEX\ and
671\METAPOST\ uses the \METAPOST\ embedding macros that are native to \CONTEXT.
672Additional communication from \METAPOST\ to \CONTEXT\ is handled in the module
673itself. This rather fuzzy description is visualized in \in {figure}
674[fig:process]. Depending on the general color settings, among the other processes
675involved are: color conversion andor reduction to grayscales, and conversion
676to \PDF. When watching this module in action, dont feel disturbed by the many
677steps involved.
678
679\startFLOWchart [process]
680 \startFLOWcell
681 \name {user file}
682 \location {1,2}
683 \shape {action}
684 \text {User File}
685 \connection [rl] {context}
686 \stopFLOWcell
687 \startFLOWcell
688 \name {context}
689 \location {2,2}
690 \shape {action}
691 \text {\CONTEXT}
692 \connection [nrnl] {buffer}
693 \connection [prl] {metapost}
694 \stopFLOWcell
695 \startFLOWcell
696 \name {buffer}
697 \location {3,2}
698 \shape {action}
699 \text {scalable buffer}
700 \connection [nlnr] {context}
701 \stopFLOWcell
702 \startFLOWcell
703 \name {metapost}
704 \location {4,2}
705 \shape {action}
706 \text {\METAPOST}
707 \connection [rr] {graphic}
708 \connection [rr] {datafile}
709 \stopFLOWcell
710 \startFLOWcell
711 \name {graphic}
712 \location {4,1}
713 \shape {action}
714 \text {\POSTSCRIPT}
715 \connection [lt] {context}
716 \stopFLOWcell
717 \startFLOWcell
718 \name {datafile}
719 \location {4,3}
720 \shape {action}
721 \text {Data File}
722 \connection [lb] {context}
723 \stopFLOWcell
724\stopFLOWchart
725
726\placefigure
727 [here][fig:process]
728 {The process.}
729 {\tx\FLOWchart[process]}
730
731\startbuffer[collection]
732\startFLOWchart [collection]
733 \dorecurse{10}
734 {\dorecurse{8}
735 {\scratchcounter=\numexpr\numexpr##11\relax*10#1\relax
736 \startFLOWcell
737 \name {#1##1}
738 \location {#1,##1}
739 \shape {\the\scratchcounter}
740 \normalexpanded{\label[bc]{\hbox{\tt\the\scratchcounter}}}
741 \stopFLOWcell}}
742\stopFLOWchart
743
744\setupFLOWcharts
745 [width=.08\textwidth,
746 height=.06\textwidth,
747 dx=.01\textwidth,
748 dy=.02\textwidth,
749 linewidth=1pt,
750 dot=yes]
751
752\FLOWchart[collection]
753\stopbuffer
754
755A few pages back we introduced the named shapes. There are however some more
756shapes. Each shape is identified by a number. In \in {figure} [fig:collection]
757all currently available shapes are shown. The zero numbered shape is actually a
758shape, but with zero dimensions. It can be used as a meeting point for lines. The
759unused numbers can be used for new shapes. The maximum number of shapes is
760limited to 4095, which is a \METAPOST\ limitation.
761
762\placefigure
763 [here][fig:collection]
764 {All shapes by number. Shape 0 is valid and has zero dimensions.}
765 {\tx\getbuffer[collection]}
766
767\stopsection
768
769\startsection[title={Bonus points}]
770
771Sometimes charts can become rather large, due to the many shapes used or lines
772drawn. At the same time charts can become unclear because more than one
773connection starts or ends at a shape. \in {Figure} [fig:bonus 1] shows a way out
774of this situation.
775
776\startFLOWchart [bonus 1]
777 \startFLOWcell
778 \name {tex}
779 \location {1,1}
780 \shape {action}
781 \text {\TEX}
782 \connection [prpl] {pdf}
783 \connection [nrnl] {dvi}
784 \stopFLOWcell
785 \startFLOWcell
786 \name {dvi}
787 \location {2,1}
788 \shape {action}
789 \text {\DVI}
790 \connection [prpl] {ps}
791 \connection [nrr] {pdf}
792 \stopFLOWcell
793 \startFLOWcell
794 \name {ps}
795 \location {3,1}
796 \shape {action}
797 \text {\POSTSCRIPT}
798 \connection [rnl] {pdf}
799 \stopFLOWcell
800 \startFLOWcell
801 \name {pdf}
802 \location {4,1}
803 \shape {action}
804 \text {\PDF}
805 \stopFLOWcell
806\stopFLOWchart
807
808\placefigure
809 [here][fig:bonus 1]
810 {Even more points.}
811 {\tx\setupFLOWcharts[dot=all]\FLOWchart[bonus 1]}
812
813\startFLOWchart [bonus 2]
814 \startFLOWcell
815 \name {tex}
816 \location {1,1}
817 \shape {action}
818 \text {\TEX}
819 \connection [bt] {pdf}
820 \connection [rl] {dvi}
821 \stopFLOWcell
822 \startFLOWcell
823 \name {dvi}
824 \location {2,1}
825 \shape {action}
826 \text {\DVI}
827 \connection [rl] {ps}
828 \connection [br] {pdf}
829 \stopFLOWcell
830 \startFLOWcell
831 \name {ps}
832 \location {3,1}
833 \shape {action}
834 \text {\POSTSCRIPT}
835 \connection [br] {pdf}
836 \stopFLOWcell
837 \startFLOWcell
838 \name {pdf}
839 \location {1,2}
840 \shape {action}
841 \text {\PDF}
842 \stopFLOWcell
843\stopFLOWchart
844
845\placefigure
846 [here][fig:bonus 2]
847 {An alternative for \in {figure}[fig:bonus 1].}
848 {\tx\FLOWchart[bonus 2]}
849
850\startFLOWchart [bonus 3]
851 \startFLOWcell
852 \name {tex}
853 \location {1,1}
854 \shape {action}
855 \text {\TEX}
856 \connection [bb] {pdf}
857 \connection [rl] {dvi}
858 \stopFLOWcell
859 \startFLOWcell
860 \name {dvi}
861 \location {2,1}
862 \shape {action}
863 \text {\DVI}
864 \connection [rl] {ps}
865 \connection [tt] {pdf}
866 \stopFLOWcell
867 \startFLOWcell
868 \name {ps}
869 \location {3,1}
870 \shape {action}
871 \text {\POSTSCRIPT}
872 \connection [rl] {pdf}
873 \stopFLOWcell
874 \startFLOWcell
875 \name {pdf}
876 \location {4,1}
877 \shape {action}
878 \text {\PDF}
879 \stopFLOWcell
880\stopFLOWchart
881
882\placefigure
883 [here][fig:bonus 3]
884 {Yet another alternative for \in {figure}[fig:bonus 1].}
885 {\tx\FLOWchart[bonus 3]}
886
887Defining such a chart is not so much harder than previous cases. Each left,
888right, top and bottom point has two companion points: positive and negative. In
889connections the left points are: \type {pl}, \type {l} and \type {nl}: positive
890left, left and negative left, so the first cell in \in {figure} [fig:bonus 1] is
891defined as:
892
893\starttyping
894\startFLOWcell
895 \name {tex}
896 \location {1,1}
897 \shape {action}
898 \text {\TEX}
899 \connection [prpl] {pdf}
900 \connection [nrnl] {dvi}
901\stopFLOWcell
902\stoptyping
903
904Alternatively to \type {p} and \type {n} one may use \type {} and \type {}. As
905soon as the positive and negative points are used, the connection drawing
906routines will take into account the fact that they are offcenter. This does not
907free users from thinking about better ways to draw such a chart.
908
909\stopsection
910
911\startsection[title={Clip and focus}]
912
913The flowcharter automatically calculates the size of the grid. When needed, one
914can force the dimensions andor clip pieces of a chart. \in {Figure}
915[fig:clipped] shows such a clip. This example also shows why the offset, the
916small area around the outer grid lines, is important. \in {Figure} [fig:clipped]
917was produced while the next settings were in action.
918
919\startbuffer[clip]
920\setupFLOWcharts
921 [x=1,y=1,nx=2,ny=1]
922\stopbuffer
923
924\typebuffer[clip]
925
926\placefigure
927 [here][fig:clipped]
928 {Clipping a piece of a chart.}
929 {\tx\getbuffer[clip]\FLOWchart[connect]}
930
931Sometimes, for instance when explaining a chart, it makes sense to emphasize one
932or more particular cells. Therefore this module offers the ability to focus on
933cells. In \in {figure} [fig:focus] we see that the focus is on the cell with name
934\type {dvi}. This is accomplished by saying:
935
936\startbuffer
937\setupFLOWfocus
938 [framecolor=pragmacolor]
939\setupFLOWcharts
940 [focus=dvi]
941\stopbuffer
942
943\typebuffer
944
945\placefigure
946 [here][fig:focus]
947 {Gaining some focus.}
948 {\tx\getbuffer\FLOWchart[bonus 3]}
949
950Clipping and focus bring us to the third way of zooming in: autofocus. \in
951{Figure} [fig:autofocus] shows what happens when we say:
952
953\startbuffer
954\setupFLOWfocus
955 [framecolor=pragmacolor]
956\setupFLOWcharts
957 [focus=dvi,autofocus=dvi,
958 nx=1,ny=1]
959
960\startFLOWchart [bonus 3]
961 \startFLOWcell
962 \name {tex}
963 \location {1,1}
964 \shape {action}
965 \text {\TEX}
966 \connection [rl] {pdf}
967 \stopFLOWcell
968 \startFLOWcell
969 \name {pdf}
970 \location {4,1}
971 \shape {action}
972 \text {\PDF}
973 \stopFLOWcell
974\stopFLOWchart
975\stopbuffer
976
977\typebuffer
978
979\placefigure
980 [here][fig:autofocus]
981 {Applying autofocus.}
982 {\tx\getbuffer\FLOWchart[bonus 3]}
983
984In \in {figure}[fig:autofocus] we see both focus and auto focus in action.
985
986\stopsection
987
988\startsection[title={Line types}]
989
990As is to be expected, we can set up some characteristics of a chart, the shapes,
991the connecting lines, and the focus. When we want dashed lines and a different
992shape color, we just say:
993
994\startbuffer
995\setupFLOWshapes
996 [framecolor=pragmacolor]
997\setupFLOWlines
998 [framecolor=pragmacolor,
999 dash=yes]
1000\stopbuffer
1001
1002\typebuffer
1003
1004\placefigure
1005 [here][fig:lines]
1006 {Dashed and colored lines.}
1007 {\tx\getbuffer\FLOWchart[bonus 3]}
1008
1009We can change the characteristics at several levels: chart, line, shape andor
1010focus. In the near future some more options will be added. Once the \METAPOST\
1011module is stable and documented, the graphic code will also be accessible. The
1012formal definition of the four setup commands is as follows (these diagrams
1013conform the \CONTEXT\ conventions):
1014
1015\setup{setupFLOWcharts}
1016
1017\setup{setupFLOWfocus}
1018
1019\setup{setupFLOWlines}
1020
1021\setup{setupFLOWshapes}
1022
1023\stopsection
1024
1025\startsection[title={Overlays}]
1026
1027Why should we limit ourselves to text? In \CONTEXT\ most framesrelated features
1028can have overlays. Because in this flowchart module shapes are drawn by
1029\METAPOST, we use a slightly different approach: there can be overlays but they
1030are sort of clipped by the shape. \in {Figure} [fig:overlay] illustrates this.
1031
1032\startbuffer
1033\defineoverlay
1034 [coward]
1035 [{\externalfigure
1036 [cow]
1037 [width=\overlaywidth,
1038 height=\overlayheight]}]
1039
1040\startFLOWchart [overlay]
1041 \startFLOWcell
1042 \name {alpha}
1043 \location {1,1}
1044 \shape {procedure}
1045 \connection [rl] {beta}
1046 \figure {cow}
1047 \text [lt] {\darkred \bfb COW 1}
1048 \stopFLOWcell
1049 \startFLOWcell
1050 \name {beta}
1051 \location {2,1}
1052 \shape {product}
1053 \connection [rl] {gamma}
1054 \overlay {cow}
1055 \text {\darkgreen \bfb COW 2}
1056 \stopFLOWcell
1057 \startFLOWcell
1058 \name {gamma}
1059 \location {3,1}
1060 \shape {action}
1061 \connection [rl] {alpha}
1062 \overlay {cow}
1063 \text [rb] {\darkblue \bfb COW 3}
1064 \stopFLOWcell
1065\stopFLOWchart
1066\stopbuffer
1067
1068\typebuffer \getbuffer
1069
1070\placefigure
1071 [here][fig:overlay]
1072 {Overlays.}
1073 {\tx\FLOWchart[overlay]}
1074
1075There are two commands related to overlays. In our example we used: which
1076automatically scales figure {\em cow} to the shape size. The normal rules for
1077overlays apply. The width and height of the overlay are available at the moment
1078the overlay is typeset.
1079
1080The text is aligned differently in this example and driven by an optional
1081argument that can take one of the following values: \type {l}, \type {r}, \type
1082{m}, \type {c}, \type {t}, \type {b}, \type {lt}, \type {rt}, \type {mt}, \type
1083{ct}, \type {lb}, \type {rb}, \type {mb}, \type {cb}.
1084
1085\stopsection
1086
1087\startsection[title={Interaction}]
1088
1089One of the reasons for writing this module was that we wanted interactive
1090flowcharts. The shape text can contain references. \footnote {Currently this only
1091works ok when the chart is not scaled.} The shape as a whole becomes a button as
1092soon as we add the \type {\destination} entry:
1093
1094\starttyping
1095\startFLOWcell
1096 ...
1097 \destination {destination}
1098 ...
1099\stopFLOWcell
1100\stoptyping
1101
1102\startbuffer[movie]
1103\defineoverlay
1104 [fun]
1105 [{\externalfigure
1106 [texwork.mov]
1107 [width=\framedwidth,
1108 height=\framedheight,
1109 preview=yes,
1110 repeat=yes]}]
1111\stopbuffer
1112
1113\getbuffer[movie]
1114
1115\starthelptext [alpha]
1116 \input knuth \blank D.E.Knuth
1117\stophelptext
1118
1119\starthelptext [beta]
1120 \input tufte \blank E.R.Tufte
1121\stophelptext
1122
1123\starthelptext [delta]
1124 \externalfigure[cow][width=\hsize]
1125\stophelptext
1126
1127\startFLOWchart [interactive]
1128
1129 \startFLOWcell
1130 \name {alpha}
1131 \location {1,1}
1132 \shape {procedure}
1133 \connection [rl] {beta}
1134 \text {\goto{introduction}[introduction]}
1135 \stopFLOWcell
1136
1137 \startFLOWcell
1138 \name {beta}
1139 \location {2,1}
1140 \shape {product}
1141 \connection [rl] {gamma}
1142 \text {Did you\\read me\\indeed?}
1143 \destination{introduction}
1144 \stopFLOWcell
1145
1146 \setupFLOWlines[dash=yes]
1147
1148 \startFLOWcell
1149 \name {gamma}
1150 \location {3,1}
1151 \shape {action}
1152 \connection [rl] {alpha}
1153 \overlay {fun}
1154 \stopFLOWcell
1155
1156 \setupFLOWlines[dash=no]
1157
1158 \startFLOWcell
1159 \name {delta}
1160 \location {4,1}
1161 \shape {decision}
1162 \connection [tt] {alpha}
1163 \connection [tt] {beta}
1164 \connection [tt] {gamma}
1165 \figure {cow}
1166 \stopFLOWcell
1167
1168\stopFLOWchart
1169
1170\placefigure
1171 [here][fig:interactive]
1172 {Interactive buttons.}
1173 {\tx\FLOWchart[interactive]}
1174
1175When read as \PDF\ file, \in {figure} [fig:interactive] shows quite a few
1176interactive features. The first cell has a \type {\goto} included in the text,
1177like:
1178
1179\starttyping
1180\startFLOWcell
1181 ...
1182 \text {\goto{introduction}[introduction]}
1183 ...
1184\stopFLOWcell
1185\stoptyping
1186
1187The second shape is interactive as a whole. This is accomplished by saying:
1188
1189\starttyping
1190\startFLOWcell
1191 ...
1192 \text {Did you\\read me\\indeed?}
1193 \destination {introduction}
1194 ...
1195\stopFLOWcell
1196\stoptyping
1197
1198The third cell is a movie, which is only visible in suitable viewers. The movie
1199is included as an overlay.
1200
1201\typebuffer[movie]
1202
1203The last cell is an illustration.
1204
1205\stopsection
1206
1207\startsection[title={Splitting charts}]
1208
1209Sometimes a chart does not fit comfortably on the page. In such cases, it makes
1210sense to split up the chart. There is a dedicated setup command to serve
1211splitting:
1212
1213\setup{setupFLOWsplit}
1214
1215An example of splitting is:
1216
1217\starttyping
1218\setupFLOWsplit
1219 [nx=5,ny=10,
1220 dx=1,dy=1,
1221 before=,after=\page]
1222
1223\FLOWcharts[mybigflow]
1224\stoptyping
1225
1226For easy alignment of the split pages, cut marks are added. This can be turned
1227off by setting \type {marking} to \type {off}. The \type {n} parameters determine
1228the number of cells per split off subject, and the \type {d} parameters specify
1229the overlap: a value of1 means that each split off subject has one row andor
1230columns in common with its neighbour.
1231
1232The splitter can be used with the split float placement macro:
1233
1234\starttyping
1235\splitfloat
1236 {\placefigure{What a big flowchart this is!}}
1237 {\FLOWcharts[mybigflow]}
1238\stoptyping
1239
1240Here every flowchart gets an caption with a decent subnumber.
1241
1242Related to splitting up charts is the option to define exit points as
1243demonstrated in the next chart.
1244
1245\startbuffer
1246\startFLOWchart[metatex]
1247 \setupFLOWcharts
1248 [width=6\bodyfontsize,
1249 height=3\bodyfontsize,
1250 dx=\bodyfontsize,
1251 dy=\bodyfontsize]
1252 \startFLOWcell
1253 \name {texexec 1}
1254 \location {1,1}
1255 \shape {action}
1256 \text {\TEXEXEC}
1257 \connection [rl] {context 1}
1258 \stopFLOWcell
1259 \startFLOWcell
1260 \name {context 1}
1261 \location {2,1}
1262 \shape {action}
1263 \text {\CONTEXT}
1264 \connection [bt] {metapost 1}
1265 \connection [rl] {texexec 2}
1266 \exit [r] {123}
1267 \stopFLOWcell
1268 \startFLOWcell
1269 \name {metapost 1}
1270 \location {2,2}
1271 \shape {action}
1272 \text {\METAPOST}
1273 \stopFLOWcell
1274 \startFLOWcell
1275 \name {texexec 2}
1276 \location {3,1}
1277 \shape {action}
1278 \text {\TEXEXEC}
1279 \connection [rl] {context 2}
1280 \connection [bt] {metapost 2}
1281 \exit [l] {123}
1282 \stopFLOWcell
1283 \startFLOWcell
1284 \name {context 2}
1285 \location {4,1}
1286 \shape {action}
1287 \text {\CONTEXT}
1288 \stopFLOWcell
1289 \startFLOWcell
1290 \name {metapost 2}
1291 \location {3,2}
1292 \shape {action}
1293 \text {\METAPOST}
1294 \stopFLOWcell
1295\stopFLOWchart
1296\stopbuffer
1297
1298\typebuffer \getbuffer
1299
1300\startbuffer[a]
1301\FLOWchart [metatex] [x=1,nx=2,frame=on]
1302\stopbuffer
1303
1304\startbuffer[b]
1305\FLOWchart [metatex] [x=3,nx=2,frame=on]
1306\stopbuffer
1307
1308When we ask for subcharts, the exit points will show up. Because they dont
1309attribute to the dimensions of the chart, you can still align charts as expected.
1310
1311\startlinecorrection[blank] \getbuffer[a] \stoplinecorrection
1312\typebuffer[a]
1313
1314\startlinecorrection[blank] \getbuffer[b] \stoplinecorrection
1315\typebuffer[b]
1316
1317\stopsection
1318
1319\startsection[title={Other features}]
1320
1321It is possible to predefine flow charts in a way similar to external figures.
1322Currently this mechanism is under construction, so describing it would be a bit
1323premature.
1324
1325Crossing lines, which are often forbidden in charts, can be made less confusing
1326by adding a gap in the lines to be crossed. This is one of the features that are
1327already implemented but not yet accessible by the \CONTEXT\ user interface.
1328
1329Another feature, used in this document, concerns automatic downscaling. As soon
1330as we start scaling illustrations, we introduce inconsistent typography,
1331especially in the bodyfontsize. Therefore, the flow chart macros, when told to,
1332are able to automatically scale down in steps of 1point.
1333
1334{\em This manual was first published in GUST magazine and presented at the anual
1335meeting of the Polish user group in Bachotek 1999. Next it was published in the
1336MAPS volume 23. After that it became UpToDate number 1999003, and now its
1337part of the manual series. This version is for \MKIV.}
1338
1339\stopsection
1340
1341\stopdocument
1342 |