Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-tutorial-chains.tex

raw
1 % Copyright 2019 by Till Tantau
2 %
3 % This file may be distributed and/or modified
4 %
5 % 1. under the LaTeX Project Public License and/or
6 % 2. under the GNU Free Documentation License.
7 %
8 % See the file doc/generic/pgf/licenses/LICENSE for more details.
9
10
11 \section{Tutorial: Diagrams as Simple Graphs}
12
13 In this tutorial we have a look at how graphs and matrices can be used to
14 typeset a diagram.
15
16 Ilka, who just got tenure for her professorship on Old and Lovable Programming
17 Languages, has recently dug up a technical report entitled \emph{The
18 Programming Language Pascal} in the dusty cellar of the library of her
19 university. Having been created in the good old times using pens and rules, it
20 looks like this%
21 \footnote{The shown diagram was not scanned, but rather typeset using
22 \tikzname. The jittering lines were created using the |random steps|
23 decoration.}:
24
25 {
26 \tikzset{
27 nonterminal/.style={
28 % The shape:
29 rectangle,
30 % The size:
31 minimum size=6mm,
32 % The border:
33 very thick,
34 draw=red!50!black!50, % 50% red and 50% black,
35 % and that mixed with 50% white
36 % The filling:
37 top color=white, % a shading that is white at the top...
38 bottom color=red!50!black!20, % and something else at the bottom
39 % Font
40 font=\itshape
41 },
42 terminal/.style={
43 % The shape:
44 rounded rectangle,
45 minimum size=6mm,
46 % The rest
47 very thick,draw=black!50,
48 top color=white,bottom color=black!20,
49 font=\ttfamily},
50 skip loop/.style={to path={-- ++(0,#1) -| (\tikztotarget)}}
51 }
52 \tikzset{terminal/.append style={text height=1.5ex,text depth=.25ex}}
53 \tikzset{nonterminal/.append style={text height=1.5ex,text depth=.25ex}}
54 \pgfmathsetseed{1}
55 \medskip
56 \noindent\begin{tikzpicture}[
57 >=latex,thick,
58 /pgf/every decoration/.style={/tikz/sharp corners},
59 fuzzy/.style={decorate,decoration={random steps,segment length=0.5mm,amplitude=0.15pt}},
60 minimum size=6mm,line join=round,line cap=round,
61 terminal/.style={rectangle,draw,fill=white,fuzzy,rounded corners=3mm},
62 nonterminal/.style={rectangle,draw,fill=white,fuzzy},
63 node distance=4mm]
64
65 \ttfamily
66 \begin{scope}[start chain,
67 every node/.style={on chain},
68 terminal/.append style={join=by {->,shorten >=-1pt,fuzzy,decoration={post length=4pt}}},
69 nonterminal/.append style={join=by {->,shorten >=-1pt,fuzzy,decoration={post length=4pt}}},
70 support/.style={coordinate,join=by fuzzy}]
71 \node [support] (start) {};
72 \node [nonterminal] {unsigned integer};
73 \node [support] (after ui) {};
74 \node [terminal] {.};
75 \node [support] (after dot) {};
76 \node [terminal] {digit};
77 \node [support] (after digit) {};
78 \node [support] (skip) {};
79 \node [support] (before E) {};
80 \node [terminal] {E};
81 \node [support] (after E) {};
82 \node [support,xshift=5mm] (between) {};
83 \node [support,xshift=5mm] (before last) {};
84 \node [nonterminal] {unsigned integer};
85 \node [support] (after last) {};
86 \node [coordinate,join=by ->] (end) {};
87 \end{scope}
88 \node (plus) [terminal,above=of between] {+};
89 \node (minus) [terminal,below=of between] {-};
90
91 \begin{scope}[->,decoration={post length=4pt},rounded corners=2mm,every path/.style=fuzzy]
92 \draw (after ui) -- +(0,.7) -| (skip);
93 \draw (after digit) -- +(0,-.7) -| (after dot);
94 \draw (before E) -- +(0,-1.2) -| (after last);
95 \draw (after E) |- (plus);
96 \draw (plus) -| (before last);
97 \draw (after E) |- (minus);
98 \draw (minus) -| (before last);
99 \end{scope}
100 \end{tikzpicture}
101 \medskip
102
103 For her next lecture, Ilka decides to redo this diagram, but this time perhaps
104 a bit cleaner and perhaps also bit ``cooler''.
105
106 \medskip
107 \noindent\begin{tikzpicture}[point/.style={coordinate},>={Stealth[round]},thick,draw=black!50,
108 tip/.style={->,shorten >=1pt},every join/.style={rounded corners},
109 hv path/.style={to path={-| (\tikztotarget)}},
110 vh path/.style={to path={|- (\tikztotarget)}}]
111 \matrix[column sep=4mm] {
112 % First row:
113 & & & & & & & & & & & \node (plus) [terminal] {+};\\
114 % Second row:
115 \node (p1) [point] {}; & \node (ui1) [nonterminal] {unsigned integer}; &
116 \node (p2) [point] {}; & \node (dot) [terminal] {.}; &
117 \node (p3) [point] {}; & \node (digit) [terminal] {digit}; &
118 \node (p4) [point] {}; & \node (p5) [point] {}; &
119 \node (p6) [point] {}; & \node (e) [terminal] {E}; &
120 \node (p7) [point] {}; & &
121 \node (p8) [point] {}; & \node (ui2) [nonterminal] {unsigned integer}; &
122 \node (p9) [point] {}; & \node (p10) [point] {};\\
123 % Third row:
124 & & & & & & & & & & & \node (minus)[terminal] {-};\\
125 };
126
127 { [start chain]
128 \chainin (p1);
129 \chainin (ui1) [join=by tip];
130 \chainin (p2) [join];
131 \chainin (dot) [join=by tip];
132 \chainin (p3) [join];
133 \chainin (digit) [join=by tip];
134 \chainin (p4) [join];
135 { [start branch=digit loop]
136 \chainin (p3) [join=by {skip loop=-6mm,tip}];
137 }
138 \chainin (p5) [join,join=with p2 by {skip loop=6mm,tip}];
139 \chainin (p6) [join];
140 \chainin (e) [join=by tip];
141 \chainin (p7) [join];
142 { [start branch=plus]
143 \chainin (plus) [join=by {vh path,tip}];
144 \chainin (p8) [join=by {hv path,tip}];
145 }
146 { [start branch=minus]
147 \chainin (minus) [join=by {vh path,tip}];
148 \chainin (p8) [join=by {hv path,tip}];
149 }
150 \chainin (p8) [join];
151 \chainin (ui2) [join=by tip];
152 \chainin (p9) [join,join=with p6 by {skip loop=-11mm,tip}];
153 \chainin (p10) [join=by tip];
154 }
155 \end{tikzpicture}
156 }\medskip
157
158 Having read the previous tutorials, Ilka knows already how to set up the
159 environment for her diagram, namely using a |tikzpicture| environment. She
160 wonders which libraries she will need. She decides that she will postpone the
161 decision and add the necessary libraries as needed as she constructs the
162 picture.
163
164
165 \subsection{Styling the Nodes}
166
167 The bulk of this tutorial will be about arranging the nodes and connecting them
168 using chains, but let us start with setting up styles for the nodes.
169
170 There are two kinds of nodes in the diagram, namely what theoreticians like to
171 call \emph{terminals} and \emph{nonterminals}. For the terminals, Ilka decides
172 to use a black color, which visually shows that ``nothing needs to be done
173 about them''. The nonterminals, which still need to be ``processed'' further,
174 get a bit of red mixed in.
175
176 Ilka starts with the simpler nonterminals, as there are no rounded corners
177 involved. Naturally, she sets up a style:
178 %
179 \begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
180 \begin{tikzpicture}[
181 nonterminal/.style={
182 % The shape:
183 rectangle,
184 % The size:
185 minimum size=6mm,
186 % The border:
187 very thick,
188 draw=red!50!black!50, % 50% red and 50% black,
189 % and that mixed with 50% white
190 % The filling:
191 top color=white, % a shading that is white at the top...
192 bottom color=red!50!black!20, % and something else at the bottom
193 % Font
194 font=\itshape
195 }]
196 \node [nonterminal] {unsigned integer};
197 \end{tikzpicture}
198 \end{codeexample}
199 %
200 Ilka is pretty proud of the use of the |minimum size| option: As the name
201 suggests, this option ensures that the node is at least 6mm by 6mm, but it will
202 expand in size as necessary to accommodate longer text. By giving this option
203 to all nodes, they will all have the same height of 6mm.
204
205 Styling the terminals is a bit more difficult because of the round corners.
206 Ilka has several options how she can achieve them. One way is to use the
207 |rounded corners| option. It gets a dimension as parameter and causes all
208 corners to be replaced by little arcs with the given dimension as radius. By
209 setting the radius to 3mm, she will get exactly what she needs: circles, when
210 the shapes are, indeed, exactly 6mm by 6mm and otherwise half circles on the
211 sides:
212 %
213 \begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
214 \begin{tikzpicture}[node distance=5mm,
215 terminal/.style={
216 % The shape:
217 rectangle,minimum size=6mm,rounded corners=3mm,
218 % The rest
219 very thick,draw=black!50,
220 top color=white,bottom color=black!20,
221 font=\ttfamily}]
222 \node (dot) [terminal] {.};
223 \node (digit) [terminal,right=of dot] {digit};
224 \node (E) [terminal,right=of digit] {E};
225 \end{tikzpicture}
226 \end{codeexample}
227
228 Another possibility is to use a shape that is specially made for typesetting
229 rectangles with arcs on the sides (she has to use the |shapes.misc| library to
230 use it). This shape gives Ilka much more control over the appearance. For
231 instance, she could have an arc only on the left side, but she will not need
232 this.
233 %
234 \begin{codeexample}[preamble={\usetikzlibrary{positioning,shapes.misc}}]
235 \begin{tikzpicture}[node distance=5mm,
236 terminal/.style={
237 % The shape:
238 rounded rectangle,
239 minimum size=6mm,
240 % The rest
241 very thick,draw=black!50,
242 top color=white,bottom color=black!20,
243 font=\ttfamily}]
244 \node (dot) [terminal] {.};
245 \node (digit) [terminal,right=of dot] {digit};
246 \node (E) [terminal,right=of digit] {E};
247 \end{tikzpicture}
248 \end{codeexample}
249 %
250 At this point, she notices a problem. The baseline of the text in the nodes is
251 not aligned:
252 %
253 \begin{codeexample}[setup code,hidden]
254 \tikzset{
255 terminal/.style={
256 % The shape:
257 rounded rectangle,
258 minimum size=6mm,
259 % The rest
260 very thick,draw=black!50,
261 top color=white,bottom color=black!20,
262 font=\ttfamily},
263 }
264 \end{codeexample}
265 %
266 \begin{codeexample}[preamble={\usetikzlibrary{calc,positioning,shapes.misc}}]
267 \begin{tikzpicture}[node distance=5mm]
268 \node (dot) [terminal] {.};
269 \node (digit) [terminal,right=of dot] {digit};
270 \node (E) [terminal,right=of digit] {E};
271
272 \draw [help lines] let \p1 = (dot.base),
273 \p2 = (digit.base),
274 \p3 = (E.base)
275 in (-.5,\y1) -- (3.5,\y1)
276 (-.5,\y2) -- (3.5,\y2)
277 (-.5,\y3) -- (3.5,\y3);
278 \end{tikzpicture}
279 \end{codeexample}
280 %
281 \noindent (Ilka has moved the style definition to the preamble by saying
282 |\tikzset{terminal/.style=...}|, so that she can use it in all pictures.)
283
284 For the |digit| and the |E| the difference in the baselines is almost
285 imperceptible, but for the dot the problem is quite severe: It looks more like
286 a multiplication dot than a period.
287
288 Ilka toys with the idea of using the |base right=of...| option rather than
289 |right=of...| to align the nodes in such a way that the baselines are all on
290 the same line (the |base right| option places a node right of something so that
291 the baseline is right of the baseline of the other object). However, this does
292 not have the desired effect:
293 %
294 \begin{codeexample}[preamble={\usetikzlibrary{positioning,shapes.misc}}]
295 \begin{tikzpicture}[node distance=5mm]
296 \node (dot) [terminal] {.};
297 \node (digit) [terminal,base right=of dot] {digit};
298 \node (E) [terminal,base right=of digit] {E};
299 \end{tikzpicture}
300 \end{codeexample}
301 %
302 The nodes suddenly ``dance around''! There is no hope of changing the position
303 of text inside a node using anchors. Instead, Ilka must use a trick: The
304 problem of mismatching baselines is caused by the fact that |.| and |digit| and
305 |E| all have different heights and depth. If they all had the same, they would
306 all be positioned vertically in the same manner. So, all Ilka needs to do is to
307 use the |text height| and |text depth| options to explicitly specify a height
308 and depth for the nodes.
309 %
310 \begin{codeexample}[preamble={\usetikzlibrary{positioning,shapes.misc}}]
311 \begin{tikzpicture}[node distance=5mm,
312 text height=1.5ex,text depth=.25ex]
313 \node (dot) [terminal] {.};
314 \node (digit) [terminal,right=of dot] {digit};
315 \node (E) [terminal,right=of digit] {E};
316 \end{tikzpicture}
317 \end{codeexample}
318
319
320 \subsection{Aligning the Nodes Using Positioning Options}
321
322 Ilka now has the ``styling'' of the nodes ready. The next problem is to place
323 them in the right places. There are several ways to do this. The most
324 straightforward is to simply explicitly place the nodes at certain coordinates
325 ``calculated by hand''. For very simple graphics this is perfectly alright, but
326 it has several disadvantages:
327 %
328 \begin{enumerate}
329 \item For more difficult graphics, the calculation may become
330 complicated.
331 \item Changing the text of the nodes may make it necessary to recalculate
332 the coordinates.
333 \item The source code of the graphic is not very clear since the
334 relationships between the positions of the nodes are not made
335 explicit.
336 \end{enumerate}
337
338 For these reasons, Ilka decides to try out different ways of arranging the
339 nodes on the page.
340
341 The first method is the use of \emph{positioning options}. To use them, you
342 need to load the |positioning| library. This gives you access to advanced
343 implementations of options like |above| or |left|, since you can now say
344 |above=of some node| in order to place a node above of |some node|, with the
345 borders separated by |node distance|.
346
347 Ilka can use this to draw the place the nodes in a long row:
348 %
349 \begin{codeexample}[setup code,hidden]
350 \tikzset{
351 nonterminal/.style={
352 % The shape:
353 rectangle,
354 % The size:
355 minimum size=6mm,
356 % The border:
357 very thick,
358 draw=red!50!black!50, % 50% red and 50% black,
359 % and that mixed with 50% white
360 % The filling:
361 top color=white, % a shading that is white at the top...
362 bottom color=red!50!black!20, % and something else at the bottom
363 % Font
364 font=\itshape,
365 },
366 }
367 \tikzset{
368 terminal/.append style={text height=1.5ex,text depth=.25ex},
369 nonterminal/.append style={text height=1.5ex,text depth=.25ex},
370 }
371 \end{codeexample}
372 %
373 \begin{codeexample}[preamble={\usetikzlibrary{positioning,shapes.misc}}]
374 \begin{tikzpicture}[node distance=5mm and 5mm]
375 \node (ui1) [nonterminal] {unsigned integer};
376 \node (dot) [terminal,right=of ui1] {.};
377 \node (digit) [terminal,right=of dot] {digit};
378 \node (E) [terminal,right=of digit] {E};
379 \node (plus) [terminal,above right=of E] {+};
380 \node (minus) [terminal,below right=of E] {-};
381 \node (ui2) [nonterminal,below right=of plus] {unsigned integer};
382 \end{tikzpicture}
383 \end{codeexample}
384
385 For the plus and minus nodes, Ilka is a bit startled by their placements.
386 Shouldn't they be more to the right? The reason they are placed in that manner
387 is the following: The |north east| anchor of the |E| node lies at the ``upper
388 start of the right arc'', which, a bit unfortunately in this case, happens to
389 be the top of the node. Likewise, the |south west| anchor of the |+| node is
390 actually at its bottom and, indeed, the horizontal and vertical distances
391 between the top of the |E| node and the bottom of the |+| node are both 5mm.
392
393 There are several ways of fixing this problem. The easiest way is to simply add
394 a little bit of horizontal shift by hand:
395 %
396 \begin{codeexample}[preamble={\usetikzlibrary{positioning,shapes.misc}}]
397 \begin{tikzpicture}[node distance=5mm and 5mm]
398 \node (E) [terminal] {E};
399 \node (plus) [terminal,above right=of E,xshift=5mm] {+};
400 \node (minus) [terminal,below right=of E,xshift=5mm] {-};
401 \node (ui2) [nonterminal,below right=of plus,xshift=5mm] {unsigned integer};
402 \end{tikzpicture}
403 \end{codeexample}
404
405 A second way is to revert back to the idea of using a normal rectangle for the
406 terminals, but with rounded corners. Since corner rounding does not affect
407 anchors, she gets the following result:
408 %
409 \begin{codeexample}[preamble={\usetikzlibrary{positioning,shapes.misc}}]
410 \begin{tikzpicture}[node distance=5mm and 5mm,terminal/.append style={rectangle,rounded corners=3mm}]
411 \node (E) [terminal] {E};
412 \node (plus) [terminal,above right=of E] {+};
413 \node (minus) [terminal,below right=of E] {-};
414 \node (ui2) [nonterminal,below right=of plus] {unsigned integer};
415 \end{tikzpicture}
416 \end{codeexample}
417 %
418 A third way is to use matrices, which we will do later.
419
420 Now that the nodes have been placed, Ilka needs to add connections. Here, some
421 connections are more difficult than others. Consider for instance the
422 ``repeat'' line around the |digit|. One way of describing this line is to say
423 ``it starts a little to the right of |digit| than goes down and then goes to
424 the left and finally ends at a point a little to the left of |digit|''. Ilka
425 can put this into code as follows:
426 %
427 \begin{codeexample}[preamble={\usetikzlibrary{calc,positioning,shapes.misc}}]
428 \begin{tikzpicture}[node distance=5mm and 5mm]
429 \node (dot) [terminal] {.};
430 \node (digit) [terminal,right=of dot] {digit};
431 \node (E) [terminal,right=of digit] {E};
432
433 \path (dot) edge[->] (digit) % simple edges
434 (digit) edge[->] (E);
435
436 \draw [->]
437 % start right of digit.east, that is, at the point that is the
438 % linear combination of digit.east and the vector (2mm,0pt). We
439 % use the ($ ... $) notation for computing linear combinations
440 ($ (digit.east) + (2mm,0) $)
441 % Now go down
442 -- ++(0,-.5)
443 % And back to the left of digit.west
444 -| ($ (digit.west) - (2mm,0) $);
445 \end{tikzpicture}
446 \end{codeexample}
447
448 Since Ilka needs this ``go up/down then horizontally and then up/down to a
449 target'' several times, it seems sensible to define a special \emph{to-path}
450 for this. Whenever the |edge| command is used, it simply adds the current value
451 of |to path| to the path. So, Ilka can set up a style that contains the correct
452 path:
453 %
454 \begin{codeexample}[preamble={\usetikzlibrary{calc,positioning,shapes.misc}}]
455 \begin{tikzpicture}[node distance=5mm and 5mm,
456 skip loop/.style={to path={-- ++(0,-.5) -| (\tikztotarget)}}]
457 \node (dot) [terminal] {.};
458 \node (digit) [terminal,right=of dot] {digit};
459 \node (E) [terminal,right=of digit] {E};
460
461 \path (dot) edge[->] (digit) % simple edges
462 (digit) edge[->] (E)
463 ($ (digit.east) + (2mm,0) $)
464 edge[->,skip loop] ($ (digit.west) - (2mm,0) $);
465 \end{tikzpicture}
466 \end{codeexample}
467
468 Ilka can even go a step further and make her |skip loop| style parameterized.
469 For this, the skip loop's vertical offset is passed as parameter |#1|. Also, in
470 the following code Ilka specifies the start and targets differently, namely as
471 the positions that are ``in the middle between the nodes''.
472 %
473 \begin{codeexample}[preamble={\usetikzlibrary{calc,positioning,shapes.misc}}]
474 \begin{tikzpicture}[node distance=5mm and 5mm,
475 skip loop/.style={to path={-- ++(0,#1) -| (\tikztotarget)}}]
476 \node (dot) [terminal] {.};
477 \node (digit) [terminal,right=of dot] {digit};
478 \node (E) [terminal,right=of digit] {E};
479
480 \path (dot) edge[->] (digit) % simple edges
481 (digit) edge[->] (E)
482 ($ (digit.east)!.5!(E.west) $)
483 edge[->,skip loop=-5mm] ($ (digit.west)!.5!(dot.east) $);
484 \end{tikzpicture}
485 \end{codeexample}
486
487
488 \subsection{Aligning the Nodes Using Matrices}
489
490 Ilka is still bothered a bit by the placement of the plus and minus nodes.
491 Somehow, having to add an explicit |xshift| seems too much like cheating.
492
493 A perhaps better way of positioning the nodes is to use a \emph{matrix}. In
494 \tikzname\ matrices can be used to align quite arbitrary graphical objects in
495 rows and columns. The syntax is very similar to the use of arrays and tables in
496 \TeX\ (indeed, internally \TeX\ tables are used, but a lot of stuff is going on
497 additionally).
498
499 In Ilka's graphic, there will be three rows: One row containing only the plus
500 node, one row containing the main nodes and one row containing only the minus
501 node.
502 %
503 \begin{codeexample}[preamble={\usetikzlibrary{shapes.misc}}]
504 \begin{tikzpicture}
505 \matrix[row sep=1mm,column sep=5mm] {
506 % First row:
507 & & & & \node [terminal] {+}; & \\
508 % Second row:
509 \node [nonterminal] {unsigned integer}; &
510 \node [terminal] {.}; &
511 \node [terminal] {digit}; &
512 \node [terminal] {E}; &
513 &
514 \node [nonterminal] {unsigned integer}; \\
515 % Third row:
516 & & & & \node [terminal] {-}; & \\
517 };
518 \end{tikzpicture}
519 \end{codeexample}
520 %
521 That was easy! By toying around with the row and columns separations, Ilka can
522 achieve all sorts of pleasing arrangements of the nodes.
523
524 Ilka now faces the same connecting problem as before. This time, she has an
525 idea: She adds small nodes (they will be turned into coordinates later on and
526 be invisible) at all the places where she would like connections to start and
527 end.
528 %
529 \begin{codeexample}[preamble={\usetikzlibrary{shapes.misc}}]
530 \begin{tikzpicture}[point/.style={circle,inner sep=0pt,minimum size=2pt,fill=red},
531 skip loop/.style={to path={-- ++(0,#1) -| (\tikztotarget)}}]
532 \matrix[row sep=1mm,column sep=2mm] {
533 % First row:
534 & & & & & & & & & & & \node (plus) [terminal] {+};\\
535 % Second row:
536 \node (p1) [point] {}; & \node (ui1) [nonterminal] {unsigned integer}; &
537 \node (p2) [point] {}; & \node (dot) [terminal] {.}; &
538 \node (p3) [point] {}; & \node (digit) [terminal] {digit}; &
539 \node (p4) [point] {}; & \node (p5) [point] {}; &
540 \node (p6) [point] {}; & \node (e) [terminal] {E}; &
541 \node (p7) [point] {}; & &
542 \node (p8) [point] {}; & \node (ui2) [nonterminal] {unsigned integer}; &
543 \node (p9) [point] {}; & \node (p10) [point] {};\\
544 % Third row:
545 & & & & & & & & & & & \node (minus)[terminal] {-};\\
546 };
547
548 \path (p4) edge [->,skip loop=-5mm] (p3)
549 (p2) edge [->,skip loop=5mm] (p6);
550 \end{tikzpicture}
551 \end{codeexample}
552 %
553 Now, it's only a small step to add all the missing edges.
554
555
556 \subsection{The Diagram as a Graph}
557
558 Matrices allow Ilka to align the nodes nicely, but the connections are not
559 quite perfect. The problem is that the code does not really reflect the paths
560 that underlie the diagram. For this, it seems natural enough to Ilka to use the
561 |graphs| library since, after all, connecting nodes by edges is exactly what
562 happens in a graph. The |graphs| library can both be used to connect nodes that
563 have already been created, but it can also be used to create nodes ``on the
564 fly'' and these processes can also be mixed.
565
566
567 \subsubsection{Connecting Already Positioned Nodes}
568
569 Ilka has already a fine method for positioning her nodes (using a |matrix|), so
570 all that she needs is an easy way of specifying the edges. For this, she uses
571 the |\graph| command (which is actually just a shorthand for |\path graph|). It
572 allows her to write down edges between them in a simple way (the macro
573 |\matrixcontent| contains exactly the matrix content from the previous example;
574 no need to repeat it here):
575 %
576 \begin{codeexample}[setup code,hidden]
577 \def\matrixcontent{
578 % First row:
579 \& \& \& \& \& \& \& \& \& \& \& \node (plus) [terminal] {+};\\
580 % Second row:
581 \node (p1) [point] {}; \& \node (ui1) [nonterminal] {unsigned integer}; \&
582 \node (p2) [point] {}; \& \node (dot) [terminal] {.}; \&
583 \node (p3) [point] {}; \& \node (digit) [terminal] {digit}; \&
584 \node (p4) [point] {}; \& \node (p5) [point] {}; \&
585 \node (p6) [point] {}; \& \node (e) [terminal] {E}; \&
586 \node (p7) [point] {}; \& \&
587 \node (p8) [point] {}; \& \node (ui2) [nonterminal] {unsigned integer}; \&
588 \node (p9) [point] {}; \& \node (p10) [point] {};\\
589 % Third row:
590 \& \& \& \& \& \& \& \& \& \& \& \node (minus)[terminal] {-};\\
591 }
592 \end{codeexample}
593 %
594 \begin{codeexample}[
595 preamble={\usetikzlibrary{graphs,shapes.misc}},
596 pre={\tikzset{ampersand replacement=\&,point/.style={coordinate}}},
597 ]
598 \begin{tikzpicture}[skip loop/.style={to path={-- ++(0,#1) -| (\tikztotarget)}},
599 hv path/.style={to path={-| (\tikztotarget)}},
600 vh path/.style={to path={|- (\tikztotarget)}}]
601 \matrix[row sep=1mm,column sep=2mm] { \matrixcontent };
602
603 \graph {
604 (p1) -> (ui1) -- (p2) -> (dot) -- (p3) -> (digit) -- (p4)
605 -- (p5) -- (p6) -> (e) -- (p7) -- (p8) -> (ui2) -- (p9) -> (p10);
606 (p4) ->[skip loop=-5mm] (p3);
607 (p2) ->[skip loop=5mm] (p5);
608 (p6) ->[skip loop=-11mm] (p9);
609 (p7) ->[vh path] (plus) -> [hv path] (p8);
610 (p7) ->[vh path] (minus) -> [hv path] (p8);
611 };
612 \end{tikzpicture}
613 \end{codeexample}
614
615 This is already pretty near to the desired result, just a few ``finishing
616 touches'' are needed to style the edges more nicely.
617
618 However, Ilka does not have the feeling that the |graph| command is all that
619 hot in the example. It certainly does cut down on the number of characters she
620 has to write, but the overall graph structure is not that much clear -- it is
621 still mainly a list of paths through the graph. It would be nice to specify
622 that, say, there the path from |(p7)| sort of splits to |(plus)| and |(minus)|
623 and then merges once more at |(p8)|. Also, all these parentheses are bit hard
624 to type.
625
626 It turns out that edges from a node to a whole group of nodes are quite easy to
627 specify, as shown in the next example. Additionally, by using the
628 |use existing nodes| option, Ilka can also leave out all the parentheses
629 (again, some options have been moved outside to keep the examples shorter):
630 %
631 \begin{codeexample}[
632 preamble={\usetikzlibrary{arrows.meta,graphs,shapes.misc}},
633 pre={\tikzset{
634 ampersand replacement=\&,
635 point/.style={coordinate},
636 skip loop/.style={to path={-- ++(0,##1) -| (\tikztotarget)}},
637 hv path/.style={to path={-| (\tikztotarget)}},
638 vh path/.style={to path={|- (\tikztotarget)}},
639 }},
640 ]
641 \begin{tikzpicture}[>={Stealth[round]},thick,black!50,text=black,
642 every new ->/.style={shorten >=1pt},
643 graphs/every graph/.style={edges=rounded corners}]
644 \matrix[column sep=4mm] { \matrixcontent };
645
646 \graph [use existing nodes] {
647 p1 -> ui1 -- p2 -> dot -- p3 -> digit -- p4 -- p5 -- p6 -> e -- p7 -- p8 -> ui2 -- p9 -> p10;
648 p4 ->[skip loop=-5mm] p3;
649 p2 ->[skip loop=5mm] p5;
650 p6 ->[skip loop=-11mm] p9;
651 p7 ->[vh path] { plus, minus } -> [hv path] p8;
652 };
653 \end{tikzpicture}
654 \end{codeexample}
655
656
657 \subsubsection{Creating Nodes Using the Graph Command}
658
659 Ilka has heard that the |graph| command is also supposed to make it easy to
660 create nodes, not only to connect them. This is, indeed, correct: When the
661 |use existing nodes| option is not used and when a node name is not surrounded
662 by parentheses, then \tikzname\ will actually create a node whose name and text
663 is the node name:
664 %
665 \begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
666 \tikz \graph [grow right=2cm] { unsigned integer -> d -> digit -> E };
667 \end{codeexample}
668 %
669 Not quite perfect, but we are getting somewhere. First, let us change the
670 positioning algorithm by saying |grow right sep|, which causes new nodes to be
671 placed to the right of the previous nodes with a certain fixed separation
672 (|1em| by default). Second, we add some options to make the node ``look nice''.
673 Third, note the funny |d| node above: Ilka tried writing just |.| there first,
674 but got some error messages. The reason is that a node cannot be called |.| in
675 \tikzname, so she had to choose a different name -- which is not good, since
676 she wants a dot to be shown! The trick is to put the dot in quotation marks,
677 this allows you to use ``quite arbitrary text'' as a node name:
678 %
679 \begin{codeexample}[preamble={\usetikzlibrary{graphs,shapes.misc}}]
680 \tikz \graph [grow right sep] {
681 unsigned integer[nonterminal] -> "."[terminal] -> digit[terminal] -> E[terminal]
682 };
683 \end{codeexample}
684 %
685 Now comes the fork to the plus and minus signs. Here, Ilka can use the grouping
686 mechanism of the |graph| command to create a split:
687 %
688 \begin{codeexample}[preamble={\usetikzlibrary{graphs,shapes.misc}}]
689 \tikz \graph [grow right sep] {
690 unsigned integer [nonterminal] ->
691 "." [terminal] ->
692 digit [terminal] ->
693 E [terminal] ->
694 {
695 "+" [terminal],
696 "" [coordinate],
697 "-" [terminal]
698 } ->
699 ui2/unsigned integer [nonterminal]
700 };
701 \end{codeexample}
702 %
703 Let us see, what is happening here. We want two |unsigned integer| nodes, but
704 if we just were to use this text twice, then \tikzname\ would have noticed that
705 the same name was used already in the current graph and, being smart (actually
706 too smart in this case), would have created an edge back to the already-created
707 node. Thus, a fresh name is needed here. However, Ilka also cannot just write
708 |unsigned integer2|, because she wants the original text to be shown, after
709 all! The trick is to use a slash inside the node name: In order to ``render''
710 the node, the text following the slash is used instead of the node name, which
711 is the text before the slash. Alternatively, the |as| option can be used, which
712 also allows you to specify how a node should be rendered.
713
714 It turns out that Ilka does not need to invent a name like |ui2| for a node
715 that she will not reference again anyway. In this case, she can just leave out
716 the name (write nothing before |/|), which always stands for a ``fresh,
717 anonymous'' node name.
718
719 Next, Ilka needs to add some coordinates in between of some nodes where the
720 back-loops should got and she needs to shift the nodes a bit:
721 %
722 \begin{codeexample}[
723 preamble={\usetikzlibrary{arrows.meta,graphs,shapes.misc}},
724 pre={\tikzset{
725 skip loop/.style={to path={-- ++(0,##1) -| (\tikztotarget)}},
726 hv path/.style={to path={-| (\tikztotarget)}},
727 vh path/.style={to path={|- (\tikztotarget)}},
728 }},
729 ]
730 \begin{tikzpicture}[>={Stealth[round]}, thick, black!50, text=black,
731 every new ->/.style={shorten >=1pt},
732 graphs/every graph/.style={edges=rounded corners}]
733 \graph [grow right sep, branch down=7mm] {
734 / [coordinate] ->
735 unsigned integer [nonterminal] --
736 p1 [coordinate] ->
737 "." [terminal] --
738 p2 [coordinate] ->
739 digit [terminal] --
740 p3 [coordinate] --
741 p4 [coordinate] --
742 p5 [coordinate] ->
743 E [terminal] --
744 q1 [coordinate] ->[vh path]
745 { [nodes={yshift=7mm}]
746 "+" [terminal],
747 q2/ [coordinate],
748 "-" [terminal]
749 } -> [hv path]
750 q3 [coordinate] --
751 /unsigned integer [nonterminal] --
752 p6 [coordinate] ->
753 / [coordinate];
754
755 p1 ->[skip loop=5mm] p4;
756 p3 ->[skip loop=-5mm] p2;
757 p5 ->[skip loop=-11mm] p6;
758 };
759 \end{tikzpicture}
760 \end{codeexample}
761
762 All that remains to be done is to somehow get rid of the strange curves between
763 the |E| and the unsigned integer. They are caused by \tikzname's attempt at
764 creating an edge that first goes vertical and then horizontal but is actually
765 just horizontal. Additionally, the edge should not really be pointed; but it
766 seems difficult to get rid of this since the \emph{other} edges from |q1|,
767 namely to |plus| and |minus| should be pointed.
768
769 It turns out that there is a nice way of solving this problem: You can specify
770 that a graph is |simple|. This means that there can be at most one edge between
771 any two nodes. Now, if you specify an edge twice, the options of the second
772 specification ``win''. Thus, by adding two more lines that ``correct'' these
773 edges, we get the final diagram with its complete code:
774 %
775 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,graphs,shapes.misc}}]
776 \tikz [>={Stealth[round]}, black!50, text=black, thick,
777 every new ->/.style = {shorten >=1pt},
778 graphs/every graph/.style = {edges=rounded corners},
779 skip loop/.style = {to path={-- ++(0,#1) -| (\tikztotarget)}},
780 hv path/.style = {to path={-| (\tikztotarget)}},
781 vh path/.style = {to path={|- (\tikztotarget)}},
782 nonterminal/.style = {
783 rectangle, minimum size=6mm, very thick, draw=red!50!black!50, top color=white,
784 bottom color=red!50!black!20, font=\itshape, text height=1.5ex,text depth=.25ex},
785 terminal/.style = {
786 rounded rectangle, minimum size=6mm, very thick, draw=black!50, top color=white,
787 bottom color=black!20, font=\ttfamily, text height=1.5ex, text depth=.25ex},
788 shape = coordinate
789 ]
790 \graph [grow right sep, branch down=7mm, simple] {
791 / -> unsigned integer[nonterminal] -- p1 -> "." [terminal] -- p2 -> digit[terminal] --
792 p3 -- p4 -- p5 -> E[terminal] -- q1 ->[vh path]
793 {[nodes={yshift=7mm}]
794 "+"[terminal], q2, "-"[terminal]
795 } -> [hv path]
796 q3 -- /unsigned integer [nonterminal] -- p6 -> /;
797
798 p1 ->[skip loop=5mm] p4;
799 p3 ->[skip loop=-5mm] p2;
800 p5 ->[skip loop=-11mm] p6;
801
802 q1 -- q2 -- q3; % make these edges plain
803 };
804 \end{codeexample}
805
806
807 %% TODOsp: a commented subsection
808 % \subsection{Using Chains}
809 %
810 % Matrices allow Ilka to align the nodes nicely, but the connections are
811 % not quite perfect. The problem is that the code does not really
812 % reflect the paths that underlie the diagram.
813 %
814 %
815 % For this reason, Ilka decides to try out \emph{chains} by including
816 % the |chain| library. Basically, a chain is just a sequence of
817 % (usually) connected nodes. The nodes can already have been constructed
818 % or they can be constructed as the chain is constructed (or these
819 % processes can be mixed).
820 %
821 % \subsubsection{Creating a Simple Chain}
822 %
823 %
824 % Ilka starts with creating a chain from scratch. For this, she starts a
825 % chain using the |start chain| option in a scope. Then, inside the
826 % scope, she uses the |on chain| option on nodes to add them to the
827 % chain.
828 % \begin{codeexample}[]
829 % \begin{tikzpicture}[start chain,node distance=5mm]
830 % \node [on chain,nonterminal] {unsigned integer};
831 % \node [on chain,terminal] {.};
832 % \node [on chain,terminal] {digit};
833 % \node [on chain,terminal] {E};
834 % \node [on chain,nonterminal] {unsigned integer};
835 % \end{tikzpicture}
836 % \end{codeexample}
837 % (Ilka will add the plus and minus nodes later.)
838 %
839 % As can be seen, the nodes of a chain are placed in a row. This can be
840 % changed, for instance by saying |start chain=going below| we get a
841 % chain where each node is below the previous one.
842 %
843 % The next step is to \emph{join} the nodes of the chain. For this, we
844 % add the |join| option to each node. This joins the node with the
845 % previous node (for the first node nothing happens).
846 % \begin{codeexample}[]
847 % \begin{tikzpicture}[start chain,node distance=5mm]
848 % \node [on chain,join,nonterminal] {unsigned integer};
849 % \node [on chain,join,terminal] {.};
850 % \node [on chain,join,terminal] {digit};
851 % \node [on chain,join,terminal] {E};
852 % \node [on chain,join,nonterminal] {unsigned integer};
853 % \end{tikzpicture}
854 % \end{codeexample}
855 % In order to get a arrow tip, we redefine the |every join| style. Also,
856 % we move the |join| and |on chain| options to the |every node|
857 % style so that we do not have to repeat them so often.
858 % \begin{codeexample}[]
859 % \begin{tikzpicture}[start chain,node distance=5mm, every node/.style={on chain,join}, every join/.style={->}]
860 % \node [nonterminal] {unsigned integer};
861 % \node [terminal] {.};
862 % \node [terminal] {digit};
863 % \node [terminal] {E};
864 % \node [nonterminal] {unsigned integer};
865 % \end{tikzpicture}
866 % \end{codeexample}
867 %
868 %
869 % \subsubsection{Branching and Joining a Chain}
870 %
871 % It is now time to add the plus and minus signs. They obviously
872 % \emph{branch off} the main chain. For this reason, we start a branch
873 % for them using the |start branch| option.
874 % \begin{codeexample}[]
875 % \begin{tikzpicture}[start chain,node distance=5mm, every node/.style={on chain,join}, every join/.style={->}]
876 % \node [nonterminal] {unsigned integer};
877 % \node [terminal] {.};
878 % \node [terminal] {digit};
879 % \node [terminal] {E};
880 % \begin{scope}[start branch=plus]
881 % \node (plus) [terminal,on chain=going above right] {+};
882 % \end{scope}
883 % \begin{scope}[start branch=minus]
884 % \node (minus) [terminal,on chain=going below right] {-};
885 % \end{scope}
886 % \node [nonterminal,join=with plus,join=with minus] {unsigned integer};
887 % \end{tikzpicture}
888 % \end{codeexample}
889 %
890 % Let us see, what is going on here. First, the |start branch| begins a
891 % branch, starting with the node last created on the current chain,
892 % which is the |E| node in our case. This is implicitly also the first
893 % node on this branch. A branch is nothing different from a chain, which
894 % is why the plus node is put on this branch using the |on chain|
895 % option. However, this time we specify the placement of the node
896 % explicitly using |going |\meta{direction}. This causes the plus sign
897 % to be placed above and right of the |E| node. It is automatically
898 % joined to its predecessor on the branch by the implicit |join|
899 % option.
900 %
901 % When the first branch ends, only the plus node has been added and the
902 % current chain is the original chain once more and we are back to the
903 % |E| node. Now we start a new branch for the minus node. After this
904 % branch, the current chain ends at |E| node once more.
905 %
906 % Finally, the rightmost unsigned integer is added to the (main) chain,
907 % which is why it is joined correctly with the |E| node. The two
908 % additional |join| options get a special |with| parameter. This allows
909 % you to join a node with a node other than the predecessor on the
910 % chain. The |with| should be followed by the name of a node.
911 %
912 % Since Ilka will need scopes more often in the following, she includes
913 % the |scopes| library. This allows her to replace |\begin{scope}|
914 % simply by an opening brace and |\end{scope}| by the corresponding
915 % closing brace. Also, in the following example we reference
916 % the nodes |plus| and |minus| using
917 % their automatic name: The $i$th node on a chain is called
918 % |chain-|\meta{i}. For a branch \meta{branch}, the $i$th node is called
919 % |chain/|\meta{branch}|-|\meta{i}. The \meta{i} can be replaced by
920 % |begin| and |end| to reference the first and (currently) last node on
921 % the chain.
922 %
923 % \begin{codeexample}[]
924 % \begin{tikzpicture}[start chain,node distance=5mm, every on chain/.style={join}, every join/.style={->}]
925 % \node [on chain,nonterminal] {unsigned integer};
926 % \node [on chain,terminal] {.};
927 % \node [on chain,terminal] {digit};
928 % \node [on chain,terminal] {E};
929 % { [start branch=plus]
930 % \node (plus) [terminal,on chain=going above right] {+};
931 % }
932 % { [start branch=minus]
933 % \node (minus) [terminal,on chain=going below right] {-};
934 % }
935 % \node [nonterminal,on chain,join=with chain/plus-end,join=with chain/minus-end] {unsigned integer};
936 % \end{tikzpicture}
937 % \end{codeexample}
938 %
939 %
940 % The next step is to add intermediate coordinate nodes in the same
941 % manner as Ilka did for the matrix. For them, we change the |join|
942 % style slightly, namely for these nodes we do not want an arrow
943 % tip. This can be achieved either by (locally) changing the
944 % |every join| style or, which is what is done in the below example, by
945 % giving the desired style using |join=by ...|, where |...| is the style
946 % to be used for the join.
947 %
948 % \begin{codeexample}[]
949 % \begin{tikzpicture}[start chain,node distance=5mm and 2mm,
950 % every node/.style={on chain},
951 % nonterminal/.append style={join=by ->},
952 % terminal/.append style={join=by ->},
953 % point/.style={join=by -,circle,fill=red,minimum size=2pt,inner sep=0pt}]
954 % \node [point] {}; \node [nonterminal] {unsigned integer};
955 % \node [point] {}; \node [terminal] {.};
956 % \node [point] {}; \node [terminal] {digit};
957 % \node [point] {}; \node [point] {};
958 % \node [point] {}; \node [terminal] {E};
959 % \node [point] {};
960 % { [node distance=5mm and 1cm] % local change in horizontal distance
961 % { [start branch=plus]
962 % \node (plus) [terminal,on chain=going above right] {+};
963 % }
964 % { [start branch=minus]
965 % \node (minus) [terminal,on chain=going below right] {-};
966 % }
967 % \node [point,below right=of plus,join=with chain/plus-end by ->,join=with chain/minus-end by ->] {};
968 % }
969 % \node [nonterminal] {unsigned integer};
970 % \node [point] {};
971 % \end{tikzpicture}
972 % \end{codeexample}
973 %
974 %
975 % \subsubsection{Chaining Together Already Positioned Nodes}
976 %
977 % The final step is to add the missing arrows. We can also use branches
978 % for them (even though we do not have to, but it is good practice and
979 % they exhibit the structure of the diagram in the code).
980 %
981 % Let us start with the repeat loop around the |digit|. This can be
982 % thought of as a branch that starts at the point after the digit and
983 % that ends at the point before the digit. However, we have already
984 % constructed the point before the digit! In such cases, it is possible
985 % to ``chain in'' an already positioned node, using the |\chainin|
986 % command. This command must be followed by a coordinate that contains a
987 % node name and optionally some options. The effect is that the named
988 % node is made part of the current chain.
989 %
990 % \begin{codeexample}[pre={\tikzset{node distance=5mm and 2mm,
991 % every node/.style={on chain},
992 % terminal/.append style={join=by ->},
993 % point/.style={join=by -,circle,fill=red,minimum size=2pt,inner sep=0pt}}}]
994 % \begin{tikzpicture}[start chain] % plus some styles that are not shown
995 % \node [point] {};
996 % \node (before digit) [point] {};
997 % \node [terminal] {digit};
998 % \node [point] {};
999 % { [start branch=digit loop]
1000 % \chainin (before digit) [join=by {->,skip loop=-5mm}];
1001 % }
1002 % \node [point] {};
1003 % \end{tikzpicture}
1004 % \end{codeexample}
1005 %
1006 %
1007 % \subsubsection{Combined Use of Matrices and Chains}
1008 %
1009 % Ilka's final idea is to combine matrices and chains in the following
1010 % manner: She will use a matrix to position the nodes. However, to show
1011 % the logical ``flow structure'' inside the diagram, she will create
1012 % chains and branches that show what is going on.
1013 %
1014 % Ilka starts with the matrix we had earlier, only with slightly adapted
1015 % styles. Then she writes down the main chain and its branches:
1016 %
1017 % \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
1018 % \begin{tikzpicture}[point/.style={coordinate},>={Stealth[round]},thick,draw=black!50,
1019 % tip/.style={->,shorten >=1pt},every join/.style={rounded corners},
1020 % hv path/.style={to path={-| (\tikztotarget)}},
1021 % vh path/.style={to path={|- (\tikztotarget)}}]
1022 % \matrix[column sep=4mm] {
1023 % % First row:
1024 % & & & & & & & & & & & \node (plus) [terminal] {+};\\
1025 % % Second row:
1026 % \node (p1) [point] {}; & \node (ui1) [nonterminal] {unsigned integer}; &
1027 % \node (p2) [point] {}; & \node (dot) [terminal] {.}; &
1028 % \node (p3) [point] {}; & \node (digit) [terminal] {digit}; &
1029 % \node (p4) [point] {}; & \node (p5) [point] {}; &
1030 % \node (p6) [point] {}; & \node (e) [terminal] {E}; &
1031 % \node (p7) [point] {}; & &
1032 % \node (p8) [point] {}; & \node (ui2) [nonterminal] {unsigned integer}; &
1033 % \node (p9) [point] {}; & \node (p10) [point] {};\\
1034 % % Third row:
1035 % & & & & & & & & & & & \node (minus)[terminal] {-};\\
1036 % };
1037 %
1038 % { [start chain]
1039 % \chainin (p1);
1040 % \chainin (ui1) [join=by tip];
1041 % \chainin (p2) [join];
1042 % \chainin (dot) [join=by tip];
1043 % \chainin (p3) [join];
1044 % \chainin (digit) [join=by tip];
1045 % \chainin (p4) [join];
1046 % { [start branch=digit loop]
1047 % \chainin (p3) [join=by {skip loop=-6mm,tip}];
1048 % }
1049 % \chainin (p5) [join,join=with p2 by {skip loop=6mm,tip}];
1050 % \chainin (p6) [join];
1051 % \chainin (e) [join=by tip];
1052 % \chainin (p7) [join];
1053 % { [start branch=plus]
1054 % \chainin (plus) [join=by {vh path,tip}];
1055 % \chainin (p8) [join=by {hv path,tip}];
1056 % }
1057 % { [start branch=minus]
1058 % \chainin (minus) [join=by {vh path,tip}];
1059 % \chainin (p8) [join=by {hv path,tip}];
1060 % }
1061 % \chainin (p8) [join];
1062 % \chainin (ui2) [join=by tip];
1063 % \chainin (p9) [join,join=with p6 by {skip loop=-11mm,tip}];
1064 % \chainin (p10) [join=by tip];
1065 % }
1066 % \end{tikzpicture}
1067 % \end{codeexample}