summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial.tex
blob: f0523e2aa97dac7b27bc54b933d7965dafc858be (plain)
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
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
\section{Tutorial: A Picture for Karl's Students}

This tutorial is intended for new users of \pgfname\ and \tikzname. It
does not give an exhaustive account of all the features of \tikzname\ or
\pgfname, just of those that you are likely to use right away.

Karl is a math and chemistry high-school teacher. He used to create
the graphics in his worksheets and exams using \LaTeX's |{picture}|
environment. While the results were acceptable, creating the graphics
often turned out to be a lengthy process. Also, there tended to be
problems with lines having slightly wrong angles and circles also
seemed to be hard to get right. Naturally, his students could not care
less whether the lines had the exact right angles and they find
Karl's exams too difficult no matter how nicely they were drawn. But
Karl was never entirely satisfied with the result.

Karl's son, who was even less satisfied with the results (he did not
have to take the exams, after all),  told Karl that he might wish
to try out a new package for creating graphics. A bit confusingly,
this package seems to have two names: First, Karl had to download and 
install a package called \pgfname. Then it turns out that inside this
package there is another package called \tikzname, which is supposed to
stand for ``\tikzname\ ist \emph{kein}  Zeichenprogramm.'' Karl finds this
all a bit strange and \tikzname\ seems to indicate that the package
does not do what he needs. However, having used \textsc{gnu}
software for quite some time and ``\textsc{gnu} not being Unix,''
there seems to be hope yet. His son assures him that \tikzname's name is
intended to warn people that \tikzname\ is not a program that you can
use to draw graphics with your mouse or tablet. Rather, it is more
like a ``graphics language.''


\subsection{Problem Statement}

Karl wants to put a graphic on the next worksheet for his
students. He is currently teaching his students about sine and
cosine. What he would like to have is something that looks like this
(ideally):

\noindent
\begin{tikzpicture}[scale=3,cap=round]
  % Local definitions
  \def\costhirty{0.8660256}

  % Colors
  \colorlet{anglecolor}{green!50!black}
  \colorlet{sincolor}{red}
  \colorlet{tancolor}{orange!80!black}
  \colorlet{coscolor}{blue}

  % Styles
  \tikzstyle axes=[]
  \tikzstyle important line=[very thick]
  \tikzstyle information text=[rounded corners,fill=red!10,inner sep=1ex]

  % The graphic
  \draw[style=help lines,step=0.5cm] (-1.4,-1.4) grid (1.4,1.4);
  
  \draw (0,0) circle (1cm);

  \begin{scope}[style=axes]
    \draw[->] (-1.5,0) -- (1.5,0) node[right] {$x$};
    \draw[->] (0,-1.5) -- (0,1.5) node[above] {$y$};

    \foreach \x/\xtext in {-1, -.5/-\frac{1}{2}, 1}
      \draw[xshift=\x cm] (0pt,1pt) -- (0pt,-1pt) node[below,fill=white] {$\xtext$};
  
    \foreach \y/\ytext in {-1, -.5/-\frac{1}{2}, .5/\frac{1}{2}, 1}
      \draw[yshift=\y cm] (1pt,0pt) -- (-1pt,0pt) node[left,fill=white] {$\ytext$};
  \end{scope}
    
  \filldraw[fill=green!20,draw=anglecolor] (0,0) -- (3mm,0pt) arc(0:30:3mm);
  \draw (15:2mm) node[anglecolor] {$\alpha$};
    
  \draw[style=important line,sincolor]
    (30:1cm) -- node[left=1pt,fill=white] {$\sin \alpha$} +(0,-.5);
  
  \draw[style=important line,coscolor]
    (0,0) -- node[below=2pt,fill=white] {$\cos \alpha$} (\costhirty,0);
  
  \draw[style=important line,tancolor] (1,0) --
    node [right=1pt,fill=white]
    {
      $\displaystyle \tan \alpha \color{black}=
      \frac{{\color{sincolor}\sin \alpha}}{\color{coscolor}\cos \alpha}$
    } (intersection of 0,0--30:1cm and 1,0--1,1) coordinate (t);

  \draw (0,0) -- (t);
  
  \draw[xshift=1.85cm] node [right,text width=6cm,style=information text]
    {
      The {\color{anglecolor} angle $\alpha$} is $30^\circ$ in the
      example ($\pi/6$ in radians). The {\color{sincolor}sine of
        $\alpha$}, which is the height of the red line, is
      \[
      {\color{sincolor} \sin \alpha} = 1/2.
      \]
      By the Theorem of Pythagoras we have ${\color{coscolor}\cos^2 \alpha} +
      {\color{sincolor}\sin^2\alpha} =1$. Thus the length of the blue
      line, which is the {\color{coscolor}cosine of $\alpha$}, must be
      \[
      {\color{coscolor}\cos\alpha} = \sqrt{1 - 1/4} = \textstyle
      \frac{1}{2} \sqrt 3. 
      \]%
      This shows that {\color{tancolor}$\tan \alpha$}, which is the
      height of the orange line, is  
      \[
      {\color{tancolor}\tan\alpha} = \frac{{\color{sincolor}\sin
          \alpha}}{\color{coscolor}\cos \alpha} = 1/\sqrt 3.
      \]%
    };
\end{tikzpicture}


\subsection{Setting up the Environment}

In \tikzname, to draw a picture, at the start of the picture
you need to tell \TeX\ or \LaTeX\ that you want to start a picture. In
\LaTeX\ this is done using the environment |{tikzpicture}|, in plain
\TeX\ you just use |\tikzpicture| to start the picture and
|\endtikzpicture| to end it.

\subsubsection{Setting up the Environment in \LaTeX}

Karl, being a \LaTeX\ user, thus sets up his file as follows:

\begin{codeexample}[code only]
\documentclass{article} % say
\usepackage{tikz}
\begin{document}
We are working on
\begin{tikzpicture}
  \draw (-1.5,0) -- (1.5,0);
  \draw (0,-1.5) -- (0,1.5);
\end{tikzpicture}.
\end{document}
\end{codeexample}

When executed, that is, run via |pdflatex| or via |latex| followed by
|dvips|, the resulting will contain something that looks like this:

\begin{codeexample}[width=7cm]
We are working on
\begin{tikzpicture}
  \draw (-1.5,0) -- (1.5,0);
  \draw (0,-1.5) -- (0,1.5);
\end{tikzpicture}.
\end{codeexample}

Admittedly, not quite the whole picture, yet, but we
do have the axes established. Well, not quite, but we have the lines
that make up the axes drawn. Karl suddenly has a sinking feeling
that the picture is still some way off. 

Let's have a more detailed look at the code. First, the package
|tikz| is loaded. This package is a so-called ``frontend'' to the
basic \pgfname\ system. The basic layer, which is also described in this
manual, is somewhat more, well, basic and thus harder to use. The
frontend makes things easier by providing a simpler syntax.

Inside the environment there are two |\draw| commands. They mean:
``The path, which is specified following the command up to the
semicolon, should be drawn.'' The first path is specified
as |(-1.5,0) -- (0,1.5)|, which means ``a straight line from the point
at position $(-1.5,0)$ to the point at position $(0,1.5)$.'' Here, the
positions are specified within a special coordinate system in which,
initially, one unit is 1cm.

Karl is quite pleased to note that the environment automatically
reserves enough space to encompass the picture.


\subsubsection{Setting up the Environment in Plain \TeX}

Karl's wife Gerda, who also happens to be a math teacher, is not a
\LaTeX\ user, but uses plain \TeX\ since she prefers to do things
``the old way.'' She can also use \tikzname. Instead of
|\usepackage{tikz}| she has to write |\input tikz.tex| and instead of
|\begin{tikzpicture}| she writes |\tikzpicture| and  instead of
  |\end{tikzpicture}| she writes |\endtikzpicture|. 

Thus, she would use:
\begin{codeexample}[code only]
%% Plain TeX file
\input tikz.tex
\baselineskip=12pt
\hsize=6.3truein
\vsize=8.7truein
We are working on
\tikzpicture
  \draw (-1.5,0) -- (1.5,0);
  \draw (0,-1.5) -- (0,1.5);
\endtikzpicture.
\bye
\end{codeexample}

Gerda can typeset this file using either |pdftex| or |tex| together
with |dvips|. \tikzname\ will automatically discern which driver she is
using. If she wishes to use |dvipdfm| together with |tex|, she 
either needs to modify the file |pgf.cfg| or can write
|\def\pgfsysdriver{pgfsys-dvipdfm.def}| somewhere \emph{before} she
inputs |tikz.tex| or |pgf.tex|.




\subsection{Straight Path Construction}

The basic building block of all pictures in \tikzname\ is the path. 
A \emph{path} is a series of straight lines and curves that are
connected (that is not the whole picture, but let us ignore the
complications for the moment). You start a path by specifying the
coordinates of the start position as a point in round brackets, as in
|(0,0)|. This is followed by a series of ``path extension
operations.'' The simplest is |--|, which we used already. It must be
followed by another coordinate and it extends the path in a straight
line to this new position. For example, if we were to turn the two
paths of the axes into one path, the following would result:

\begin{codeexample}[]
\tikz \draw (-1.5,0) -- (1.5,0) -- (0,-1.5) -- (0,1.5);
\end{codeexample}

Karl is a bit confused by the fact that there is no |{tikzpicture}|
environment, here. Instead, the little command |\tikz| is used. This
command either takes one argument (starting with an opening brace as in
|\tikz{\draw (0,0) -- (1.5,0)}|, which yields \tikz{\draw (0,0)
 --(1.5,0);}) or collects everything up to the next semicolon and
puts it inside a |{tikzpicture}| environment. As a rule of thumb, all
\tikzname\ graphic drawing commands must occur as an argument of |\tikz|
or inside a |{tikzpicture}| environment. Fortunately, the command
|\draw| will only be defined inside this environment, so there is
little chance that you will accidentally do something wrong here. 



\subsection{Curved Path Construction}

The next thing Karl wants to do is to draw the circle. For this,
straight lines obviously will not do. Instead, we need some way to
draw curves. For this, \tikzname\ provides a special syntax. One or two
``control points'' are needed. The math behind them is not quite
trivial, but here is the basic idea: Suppose you are at point $x$ and
the first control point is $y$. Then the curve will start ``going in
the direction of~$y$ at~$x$,'' that is, the tangent of the curve at $x$
will point toward~$y$. Next, suppose the curve should end at $z$ and
the second support point is $w$. Then the curve will, indeed, end at
$z$ and the tangent of the curve at point $z$ will go through $w$.

Here is an example (the control points have been added for clarity):
\begin{codeexample}[]
\begin{tikzpicture}
  \filldraw [gray] (0,0) circle (2pt)
                   (1,1) circle (2pt)
                   (2,1) circle (2pt)
                   (2,0) circle (2pt);
  \draw (0,0) .. controls (1,1) and (2,1) .. (2,0);
\end{tikzpicture}
\end{codeexample}

The general syntax for extending a path in a ``curved'' way is
|.. controls| \meta{first control point} |and| \meta{second control
  point} |..| \meta{end point}. You can leave out the |and|
\meta{second control point}, which causes the first one to be used 
twice.

So, Karl can now add the first half circle to the picture:

\begin{codeexample}[]
\begin{tikzpicture}
  \draw (-1.5,0) -- (1.5,0);
  \draw (0,-1.5) -- (0,1.5);
  \draw (-1,0) .. controls (-1,0.555) and (-0.555,1) .. (0,1)
               .. controls (0.555,1) and (1,0.555) .. (1,0);
\end{tikzpicture}
\end{codeexample}

Karl is happy with the result, but finds specifying circles in this
way to be extremely awkward. Fortunately, there is a much simpler way.


\subsection{Circle Path Construction}

In order to draw a circle, the path construction operation |circle| can
be used. This operation is followed by a radius in round brackets as in
the following example: (Note that the previous position is used as the
\emph{center} of the circle.)

\begin{codeexample}[]
\tikz \draw (0,0) circle (10pt);
\end{codeexample}

You can also append an ellipse to the path using the |ellipse|
operation. Instead of a single radius you can specify two of them, one
for the $x$-direction and one for the $y$-direction, separated by
|and|: 

\begin{codeexample}[]
\tikz \draw (0,0) ellipse (20pt and 10pt);
\end{codeexample}

To draw an ellipse whose axes are not horizontal and vertical, but
point in an arbitrary direction (a ``turned ellipse'' like \tikz
\draw[rotate=30] (0,0) ellipse (6pt and 3pt);) you can use
transformations, which are explained later. The code for the little
ellipse is |\tikz \draw[rotate=30] (0,0) ellipse (6pt and 3pt);|, by
the way. 

So, returning to Karl's problem, he can write
|\draw (0,0) circle (1cm);| to draw the circle:

\begin{codeexample}[]
\begin{tikzpicture}
  \draw (-1.5,0) -- (1.5,0);
  \draw (0,-1.5) -- (0,1.5);
  \draw (0,0) circle (1cm);
\end{tikzpicture}
\end{codeexample}


At this point, Karl is a bit alarmed that the circle is so small when
he wants the final picture to be much bigger. He is pleased to learn
that \tikzname\ has powerful transformation options and scaling
everything by a factor of three is very easy. But let us leave the
size as it is for the moment to save some space. 




\subsection{Rectangle Path Construction}

The next things we would like to have is the grid in the background.
There are several ways to produce it. For example, one might draw lots of
rectangles. Since rectangles are so common, there is a special syntax
for them: To add a rectangle to the current path, use the |rectangle|
path construction operation. This operation should be followed by another
coordinate and will append a rectangle to the path such that the
previous coordinate and the next coordinates are corners of the
rectangle. So, let us add two rectangles to the picture:

\begin{codeexample}[]
\begin{tikzpicture}
  \draw (-1.5,0) -- (1.5,0);
  \draw (0,-1.5) -- (0,1.5);
  \draw (0,0) circle (1cm);
  \draw (0,0) rectangle (0.5,0.5);
  \draw (-0.5,-0.5) rectangle (-1,-1);
\end{tikzpicture}
\end{codeexample}

While this may be nice in other situations, this is not really leading
anywhere with Karl's problem: First, we would need an awful lot of
these rectangles and then there is the border that is not ``closed.''

So, Karl is about to resort to simply drawing four vertical and four
horizontal lines using the nice |\draw| command, when he learns that
there is a |grid| path construction operation.



\subsection{Grid Path Construction}

The |grid| path operation adds a grid to the current path. It will add
lines making up a grid that fills the rectangle whose one corner is
the current point and whose other corner is the point following the
|grid| operation. For example, the code
|\tikz \draw[step=2pt] (0,0) grid (10pt,10pt);| produces \tikz
\draw[step=2pt] (0,0) grid (10pt,10pt);. Note how the optional
argument for |\draw| can be used to specify a grid width (there are
also |xstep| and |ystep| to define the steppings independently). As
Karl will learn soon, there are \emph{lots} of things that can be
influenced using such options.

For Karl, the following code could be used:

\begin{codeexample}[]
\begin{tikzpicture}
  \draw (-1.5,0) -- (1.5,0);
  \draw (0,-1.5) -- (0,1.5);
  \draw (0,0) circle (1cm);
  \draw[step=.5cm] (-1.4,-1.4) grid (1.4,1.4);
\end{tikzpicture}
\end{codeexample}

Having another look at the desired picture, Karl notices that it would
be nice for the grid to be more subdued. (His son told him that grids
tend to be distracting if they are not subdued.) To subdue the grid,
Karl adds two more options to the |\draw| command that draws the
grid. First, he uses the color |gray| for the grid lines. Second, he
reduces the line width to |very thin|. Finally, he swaps the ordering
of the commands so that the grid is drawn first and everything else on
top. 

\begin{codeexample}[]
\begin{tikzpicture}
  \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
  \draw (-1.5,0) -- (1.5,0);
  \draw (0,-1.5) -- (0,1.5);
  \draw (0,0) circle (1cm);
\end{tikzpicture}
\end{codeexample}


\subsection{Adding a Touch of  Style}

Instead of the options |gray,very thin| Karl could also have
said |style=help lines|. \emph{Styles} are predefined sets of options
that can be used to organize how a graphic is drawn. By saying
|style=help lines| you say ``use the style that I (or someone else)
has set for drawing help lines.'' If Karl decides, at some later
point, that grids should be drawn, say, using the color |blue!50|
instead of |gray|, he could say the following:
\begin{codeexample}[code only]
\tikzstyle help lines=[color=blue!50,very thin]
\end{codeexample}
Alternatively, he could have said the following:
\begin{codeexample}[code only]
\tikzstyle help lines+=[color=blue!50]
\end{codeexample}
This would have added the |color=blue!50| option. The |help lines|
style would now contain \emph{two} color options, but 
the second would override the first.

Using styles makes your graphics code more flexible. You can
change the way things look easily in a consistent manner.

To build a hierarchy of styles you can have one style use
another. So in order to define a style |Karl's grid| that is based on
the |grid| style Karl could say
\begin{codeexample}[code only]
\tikzstyle Karl's grid=[style=help lines,color=blue!50]
...
\draw[style=Karl's grid] (0,0) grid (5,5);
\end{codeexample}

You can also leave out the |style=|. Thus, whenever \tikzname\ encounters
an options that it does not know about, it will check whether this
option happens to be the name of a style. If so, the style is
used. Thus, Karl could also have written:
\begin{codeexample}[code only]
\tikzstyle Karl's grid=[help lines,color=blue!50]
...
\draw[Karl's grid] (0,0) grid (5,5);
\end{codeexample}

For some styles, like the |very thin| style, it is pretty clear what
the style does and there is no need to say |style=very thin|. For
other styles, like |help lines|, it seems more natural to me to say
|style=help lines|. But, mainly, this is a matter of taste.


\subsection{Drawing Options}

Karl wonders what other options there are that influence how a path is
drawn. He saw already that the |color=|\meta{color} option can be used
to set the line's color. The option |draw=|\meta{color} does nearly
the same, only it sets the color for the lines only and a different
color can be used for filling (Karl will need this when he fills the
arc for the angle).

He saw that the style |very thin| yields very thin lines. Karl is not
really surprised by this and neither is he surprised to learn that |thin|
yields thin lines,  |thick| yields thick lines, |very thick| yields
very thick lines, |ultra thick| yields really, really thick lines and
|ultra thin| yields lines that are so thin that low-resolution printers
and displays will have trouble showing them. He wonders what gives
lines of ``normal'' thickness. It turns out that |thin| is the correct
choice. This seems strange to Karl, but his son explains him that
\LaTeX\ has two commands called |\thinlines| and |\thicklines| and
that |\thinlines| gives the line width of ``normal'' lines, more
precisely, of the thickness that, say, the stem of a letter like ``T''
or ``i'' has. Nevertheless, Karl would like to know whether there is
anything ``in the middle'' between |thin| and |thick|. There is:
|semithick|.

Another useful thing one can do with lines is to dash or dot them. For
this, the two styles |dashed| and |dotted| can be used, yielding
\tikz \draw[dashed] (0,0) -- (10pt,0pt); and \tikz \draw[dotted] (0,0)
-- (10pt,0pt);. Both options also exist in a loose and a dense
version, called |loosely dashed|, |densely dashed|, |loosely dotted|,
and |closely dotted|. If he really, really  needs to, Karl can also
define much more complex dashing patterns with the |dash pattern|
option, but his son insists that dashing is to be used with utmost
care and mostly distracts. Karl's son claims that complicated dashing
patterns are evil. Karl's students do not care about dashing patterns. 



\subsection{Arc Path Construction}

Our next obstacle is to draw the arc for the angle. For this, the
|arc| path construction operation is useful, which draws part of a
circle or ellipse. This |arc| operation must be followed by a triple in 
rounded brackets, where the components of the triple are separated by
colons. The first two components are angles, the last one is a
radius. An example would be |(10:80:10pt)|, which means ``an arc from
10 degrees to 80 degrees on a circle of radius 10pt.'' Karl obviously
needs an arc from $0^\circ$ to $30^\circ$. The radius should be
something relatively small, perhaps around one third of the circle's
radius. This gives: |(0:30:3mm)|.

When one uses the arc path construction operation, the specified arc will
be added with its starting point at the current position. So, we first
have to ``get there.'' 

\begin{codeexample}[]
\begin{tikzpicture}
  \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
  \draw (-1.5,0) -- (1.5,0);
  \draw (0,-1.5) -- (0,1.5);
  \draw (0,0) circle (1cm);
  \draw (3mm,0mm) arc (0:30:3mm);
\end{tikzpicture}
\end{codeexample}

Karl thinks this is really a bit small and he cannot continue unless
he learns how to do scaling. For this, he can add the |[scale=3]|
option. He could add this option to each |\draw| command, but that
would be awkward. Instead, he adds it to the whole environment, which
causes this option to apply to everything within.

\begin{codeexample}[]
\begin{tikzpicture}[scale=3]
  \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
  \draw (-1.5,0) -- (1.5,0);
  \draw (0,-1.5) -- (0,1.5);
  \draw (0,0) circle (1cm);
  \draw (3mm,0mm) arc (0:30:3mm);
\end{tikzpicture}
\end{codeexample}

As for circles, you can specify ``two'' radii in order to get an
elliptical arc.

\begin{codeexample}[]
  \tikz \draw (0,0) arc (0:315:1.75cm and 1cm);
\end{codeexample}


\subsection{Clipping a Path}

In order to save space in this manual, it would be nice to clip Karl's
graphics a bit so that we can focus on the ``interesting''
parts. Clipping is pretty easy in \tikzname. You can use the |\clip|
command clip all subsequent drawing. It works like |\draw|, only it
does not draw anything, but uses the given path to clip everything
subsequently. 

\begin{codeexample}[]
\begin{tikzpicture}[scale=3]
  \clip (-0.1,-0.2) rectangle (1.1,0.75);
  \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
  \draw (-1.5,0) -- (1.5,0);
  \draw (0,-1.5) -- (0,1.5);
  \draw (0,0) circle (1cm);
  \draw (3mm,0mm) arc (0:30:3mm);
\end{tikzpicture}
\end{codeexample}

You can also do both at the same time: Draw \emph{and} clip a
path. For this, use the |\draw| command and add the |clip|
option. (This is not the whole picture: You can also use the |\clip|
command and add the |draw| option. Well, that is also not the whole
picture: In reality, |\draw| is just a shorthand for |\path[draw]|
and |\clip| is a shorthand for |\path[clip]| and you could also say
|\path[draw,clip]|.) Here is an example: 

\begin{codeexample}[]
\begin{tikzpicture}[scale=3]
  \clip[draw] (0.5,0.5) circle (.6cm);
  \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
  \draw (-1.5,0) -- (1.5,0);
  \draw (0,-1.5) -- (0,1.5);
  \draw (0,0) circle (1cm);
  \draw (3mm,0mm) arc (0:30:3mm);
\end{tikzpicture}
\end{codeexample}


\subsection{Parabola and Sine Path Construction}

Although Karl does not need them for his picture, he is pleased to
learn that there are |parabola| and |sin| and |cos| path operations for
adding parabolas and sine and cosine curves to the current path. For the
|parabola| operation, the current point will lie on the parabola as
well as the point given after the parabola operation. Consider
the following example:

\begin{codeexample}[]
\tikz \draw (0,0) rectangle (1,1)  (0,0) parabola (1,1);
\end{codeexample}

It is also possible to place the bend somewhere else:

\begin{codeexample}[]
\tikz \draw[x=1pt,y=1pt] (0,0) parabola bend (4,16) (6,12);
\end{codeexample}

The operations |sin| and |cos| add a sine or cosine curve in the interval
$[0,\pi/2]$ such that the previous current point is at the start of
the curve and the curve ends at the given end point. Here are two
examples:
\begin{codeexample}[]
A sine \tikz \draw[x=1ex,y=1ex] (0,0) sin (1.57,1); curve.
\end{codeexample}

\begin{codeexample}[]
\tikz \draw[x=1.57ex,y=1ex] (0,0) sin (1,1) cos (2,0) sin (3,-1) cos (4,0)
                            (0,1) cos (1,0) sin (2,-1) cos (3,0) sin (4,1);
\end{codeexample}



\subsection{Filling and Drawing}

Returning to the picture, Karl now wants the angle to be ``filled''
with a very light green. For this he uses |\fill| instead of
|\draw|. Here is what Karl does:

\begin{codeexample}[]
\begin{tikzpicture}[scale=3]
  \clip (-0.1,-0.2) rectangle (1.1,0.75);
  \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
  \draw (-1.5,0) -- (1.5,0);
  \draw (0,-1.5) -- (0,1.5);
  \draw (0,0) circle (1cm);
  \fill[green!20!white] (0,0) -- (3mm,0mm) arc (0:30:3mm) -- (0,0);
\end{tikzpicture}
\end{codeexample}

The color |green!20!white| means 20\% green and 80\% white mixed
together. Such color expression are possible since \pgfname\ uses Uwe
Kern's |xcolor| package, see the documentation of that package for
details on color expressions.

What would have happened, if Karl had not ``closed'' the path using
|--(0,0)| at the end? In this case, the path is closed automatically,
so this could have been omitted. Indeed, it would even have been
better to write the following, instead:
\begin{codeexample}[code only]
  \fill[green!20!white] (0,0) -- (3mm,0mm) arc (0:30:3mm) -- cycle;
\end{codeexample}
The |--cycle| causes the current path to be closed (actually the
current part of the current path) by smoothly joining the first and
last point. To appreciate the difference, consider the following
example:

\begin{codeexample}[]
\begin{tikzpicture}[line width=5pt]
  \draw (0,0) -- (1,0) -- (1,1) -- (0,0);
  \draw (2,0) -- (3,0) -- (3,1) -- cycle;
  \useasboundingbox (0,1.5); % make bounding box higher
\end{tikzpicture}
\end{codeexample}

You can also fill and draw a path at the same time using the
|\filldraw| command. This will first draw the path, then fill it. This
may not seem too useful, but you can specify different colors to be
used for filling and for stroking. These are specified as optional
arguments like this:

\begin{codeexample}[]
\begin{tikzpicture}[scale=3]
  \clip (-0.1,-0.2) rectangle (1.1,0.75);
  \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
  \draw (-1.5,0) -- (1.5,0);
  \draw (0,-1.5) -- (0,1.5);
  \draw (0,0) circle (1cm);
  \filldraw[fill=green!20!white, draw=green!50!black]
    (0,0) -- (3mm,0mm) arc (0:30:3mm) -- cycle;
\end{tikzpicture}
\end{codeexample}



\subsection{Shading}

Karl briefly considers the possibility of making the angle ``more
fancy'' by \emph{shading} it. Instead of filling the with a uniform
color, a smooth transition between different colors is used. For this,
|\shade| and |\shadedraw|, for shading and drawing at the same time,
can be used: 

\begin{codeexample}[]
  \tikz \shade (0,0) rectangle (2,1)  (3,0.5) circle (.5cm);
\end{codeexample}
The default shading is a smooth transition from gray to white. To
specify different colors, you can use options:

\begin{codeexample}[]
\begin{tikzpicture}[rounded corners,ultra thick]
  \shade[top color=yellow,bottom color=black] (0,0) rectangle +(2,1);
  \shade[left color=yellow,right color=black] (3,0) rectangle +(2,1);
  \shadedraw[inner color=yellow,outer color=black,draw=yellow] (6,0) rectangle +(2,1);
  \shade[ball color=green] (9,.5) circle (.5cm);
\end{tikzpicture}
\end{codeexample}

For Karl, the following might be appropriate:

\begin{codeexample}[]
\begin{tikzpicture}[scale=3]
  \clip (-0.1,-0.2) rectangle (1.1,0.75);
  \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
  \draw (-1.5,0) -- (1.5,0);
  \draw (0,-1.5) -- (0,1.5);
  \draw (0,0) circle (1cm);
  \shadedraw[left color=gray,right color=green, draw=green!50!black]
    (0,0) -- (3mm,0mm) arc (0:30:3mm) -- cycle;
\end{tikzpicture}
\end{codeexample}

However, he wisely decides that shadings usually only distract without
adding anything to the picture.


\subsection{Specifying Coordinates}

Karl now wants to add the sine and cosine lines. He knows already that
he can use the |color=| option to set the lines's colors. So, what is
the best way to specify the coordinates?

There are different ways of specifying coordinates. The easiest way is
to say something like |(10pt,2cm)|. This means 10pt in $x$-direction
and 2cm in $y$-directions. Alternatively, you can also leave out the
units as in |(1,2)|, which means ``one times the current $x$-vector
plus twice the current $y$-vector.'' These vectors default to 1cm in
the $x$-direction and 1cm in the $y$-direction, respectively.

In order to specify points in polar coordinates, use the notation
|(30:1cm)|, which means 1cm in direction 30 degree. This is obviously
quite useful to ``get to the point $(\cos 30^\circ,\sin 30^\circ)$ on
the circle.'' 

You can add a single |+| sign in front of a coordinate or two of
them as in |+(1cm,0cm)| or |++(0cm,2cm)|. Such coordinates are interpreted
differently: The first form means ``1cm upwards from the previous
specified position'' and the second means ``2cm to the right of the
previous specified position, making this the new specified position.''
For example, we can draw the sine line as follows:

\begin{codeexample}[]
\begin{tikzpicture}[scale=3]
  \clip (-0.1,-0.2) rectangle (1.1,0.75);
  \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
  \draw (-1.5,0) -- (1.5,0);
  \draw (0,-1.5) -- (0,1.5);
  \draw (0,0) circle (1cm);
  \filldraw[fill=green!20,draw=green!50!black]
    (0,0) -- (3mm,0mm) arc (0:30:3mm) -- cycle;
  \draw[red,very thick] (30:1cm) -- +(0,-0.5);
\end{tikzpicture}
\end{codeexample}

Karl used the fact $\sin 30^\circ = 1/2$. However, he very much
doubts that his students know this, so it would be nice to have a way
of specifying ``the point straight down from |(30:1cm)| that lies on
the $x$-axis.'' This is, indeed, possible using a special syntax: Karl
can write \verb!(30:1cm |- 0,0)!. In general, the meaning of
|(|\meta{p}\verb! |- !\meta{q}|)| is ``the intersection of a vertical
line through $p$ and a horizontal line through $q$.''

Next, let us draw the cosine line. One way would be to say
\verb!(30:1cm |- 0,0) -- (0,0)!. Another way is the following: we
``continue'' from where the sine ends: 

\begin{codeexample}[]
\begin{tikzpicture}[scale=3]
  \clip (-0.1,-0.2) rectangle (1.1,0.75);
  \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
  \draw (-1.5,0) -- (1.5,0);
  \draw (0,-1.5) -- (0,1.5);
  \draw (0,0) circle (1cm);
  \filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm) arc
  (0:30:3mm) -- cycle;
  \draw[red,very thick]  (30:1cm) -- +(0,-0.5);
  \draw[blue,very thick] (30:1cm) ++(0,-0.5) -- (0,0);
\end{tikzpicture}
\end{codeexample}

Note the there is no |--| between |(30:1cm)| and |+(0,-0.5)|. In
detail, this path is interpreted as follows: ``First, the |(30:1cm)|
tells me to move by pen to $(\cos 30^\circ,1/2)$. Next, there comes
another coordinate specification, so I move my pen there without drawing
anything. This new point is half a unit down from the last position,
thus it is at $(\cos 30^\circ,0)$. Finally, I move the pen to the
origin, but this time drawing something (because of the |--|).''

To appreciate the difference between |+| and |++| consider the
following example:

\begin{codeexample}[]
\begin{tikzpicture}
  \def\rectanglepath{-- ++(1cm,0cm)  -- ++(0cm,1cm)  -- ++(-1cm,0cm) -- cycle}
  \draw (0,0) \rectanglepath;
  \draw (1.5,0) \rectanglepath;
\end{tikzpicture}
\end{codeexample}

By comparison, when using a single |+|, the coordinates are different:

\begin{codeexample}[]
\begin{tikzpicture}
  \def\rectanglepath{-- +(1cm,0cm)  -- +(1cm,1cm)  -- +(0cm,1cm) -- cycle}
  \draw (0,0) \rectanglepath;
  \draw (1.5,0) \rectanglepath;
\end{tikzpicture}
\end{codeexample}


Naturally, all of this could have been written more clearly and more
economically like this (either with a single of a double |+|): 
\begin{codeexample}[]
\tikz \draw (0,0) rectangle +(1,1)  (1.5,0) rectangle +(1,1);
\end{codeexample}



Karl is left with the line for $\tan \alpha$, which seems difficult to
specify using transformations and polar coordinates. For this he needs
another way of specifying coordinates: Karl can specify intersections
of lines as coordinates. The line for $\tan \alpha$ starts at $(1,0)$
and goes upward to a point that is at the intersection of a line going
``up'' and a line going from the origin through |(30:1cm)|. The syntax
for this point is the following:

\begin{codeexample}[code only]
\draw[very thick,orange] (1,0) -- (intersection of 1,0--1,1 and 0,0--30:1cm);
\end{codeexample}

In the following, two final examples of how to use relative
positioning are presented. Note that the transformation options,
which are explained later, are often more useful for shifting than
relative positioning. 

\begin{codeexample}[]
\begin{tikzpicture}[scale=0.5]
  \draw (0,0) -- (90:1cm) arc (90:360:1cm) arc (0:30:1cm) -- cycle;
  \draw (60:5pt) -- +(30:1cm) arc (30:90:1cm) -- cycle;

  \draw (3,0)  +(0:1cm) -- +(72:1cm) -- +(144:1cm) -- +(216:1cm) --
               +(288:1cm) -- cycle;
\end{tikzpicture}
\end{codeexample}



\subsection{Adding Arrow Tips}

Karl now wants to add the little arrow tips at the end of the axes. He has
noticed that in many plots, even in scientific journals, these arrow tips
seem to missing, presumably because the generating programs cannot
produce them. Karl thinks arrow tips belong at the end of axes. His
son agrees. His students do not care about arrow tips.

It turns out that adding arrow tips is pretty easy: Karl adds the option
|->| to the drawing commands for the axes:

\begin{codeexample}[]
\begin{tikzpicture}[scale=3]
  \clip (-0.1,-0.2) rectangle (1.1,1.51);
  \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
  \draw[->] (-1.5,0) -- (1.5,0);
  \draw[->] (0,-1.5) -- (0,1.5);
  \draw (0,0) circle (1cm);
  \filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm) arc
  (0:30:3mm) -- cycle;
  \draw[red,very thick]    (30:1cm) -- +(0,-0.5);
  \draw[blue,very thick]   (30:1cm) ++(0,-0.5) -- (0,0);
  \draw[orange,very thick] (1,0) -- (intersection of 1,0--1,1 and 0,0--30:1cm);
\end{tikzpicture}
\end{codeexample}

If Karl had used the option |<-| instead of |->|, arrow tips would
have been put at the beginning of the path. The option |<->| puts
arrow tips at both ends of the path.

There are certain restrictions to the kind of paths to which arrow tips
can be added. As a rule of thumb, you can add arrow tips only to a
single open ``line.'' For example, you should not try to add tips to,
say, a rectangle or a circle. (You can try, but no guarantees as to what
will happen now or in future versions.) However, you can add arrow
tips to curved paths and to paths that have several segments, as in
the following examples:

\begin{codeexample}[]
\begin{tikzpicture}
  \draw [<->] (0,0) arc (180:30:10pt);
  \draw [<->] (1,0) -- (1.5cm,10pt) -- (2cm,0pt) -- (2.5cm,10pt);
\end{tikzpicture}
\end{codeexample}

Karl has a more detailed look at the arrow that \tikzname\ puts at the
end. It looks like this when he zooms it: \tikz { \useasboundingbox
  (0pt,-.5ex) rectangle (10pt,.5ex); \draw[->,line width=1pt] (0pt,0pt) --
  (10pt,0pt); }. The shape seems vaguely familiar and, indeed, this is
exactly the end of \TeX's standard arrow used in something like
$f\colon A \to B$.


Karl likes the arrow, especially since it is not ``as thick'' as the
arrows offered by many other packages. However, he expects that,
sometimes, he might need to use some other kinds of arrow.
To do so, Karl can say |>=|\meta{right arrow tip kind}, where
\meta{right arrow tip kind} is a special arrow tip specification. For
example, if Karl says |>=stealth|, then he tells \tikzname\
that he would like  ``stealth-fighter-like'' arrow tips: 

\begin{codeexample}[]
\begin{tikzpicture}[>=stealth]
  \draw [->] (0,0) arc (180:30:10pt);
  \draw [<<-,very thick] (1,0) -- (1.5cm,10pt) -- (2cm,0pt) -- (2.5cm,10pt);
\end{tikzpicture}
\end{codeexample}%>>

Karl wonders whether such a military name for the arrow type is really
necessary. He is not really mollified when his son tells him that
Microsoft's PowerPoint uses the same name. He decides to have his
students discuss this at some point.

In addition to |stealth| there are several other predefined arrow tip
kinds Karl can choose from, see
Section~\ref{section-library-arrows}. Furthermore, he can define
arrows types himself, if he needs new ones. 




\subsection{Scoping}

Karl saw already that there are numerous graphic options that affect how
paths are rendered. Often, he would like to apply certain options to
a whole set of graphic commands. For example, Karl might wish to draw
three paths using a |thick| pen, but would like everything else to
be drawn ``normally.''

If Karl wishes to set a certain graphic option for the whole picture,
he can simply pass this option to the |\tikz| command or to the
|{tikzpicture}| environment (Gerda would pass the options to
|\tikzpicture|). However, if Karl wants to apply graphic options to a
local group, he put these commands inside a |{scope}| environment
(Gerda uses |\scope| and |\endscope|). This environment takes graphic
options as an optional argument and these options apply to everything
inside the scope, but not to anything outside.

Here is an example:

\begin{codeexample}[]
\begin{tikzpicture}[ultra thick]
  \draw (0,0) -- (0,1);
  \begin{scope}[thin]
    \draw (1,0) -- (1,1);
    \draw (2,0) -- (2,1);
  \end{scope}
  \draw (3,0) -- (3,1);  
\end{tikzpicture}
\end{codeexample}

Scoping has another interesting effect: Any changes to the clipping
area are local to the scope. Thus, if you say |\clip| somewhere inside
a scope, the effect of the |\clip| command ends at the end of the
scope. This is useful since there is no other way of ``enlarging'' the
clipping area.

Karl has also already seen that giving options to commands like
|\draw| apply only to that command. In turns out that the situation is
slightly more complex. First, options to a command like |\draw| are
not really options to the command, but they are ``path options'' and
can be given anywhere on the path. So, instead of
|\draw[thin] (0,0) -- (1,0);| one can also write
|\draw (0,0) [thin] -- (1,0);| or |\draw (0,0) -- (1,0) [thin];|; all
of these have the same effect. This might seem strange since in the
last case, it would appear that the |thin| should take effect only
``after'' the line from $(0,0)$ to $(1,0)$ has been draw. However,
most graphic options only apply to the whole path. Indeed, if you say
both |thin| and |thick| on the same path, the last option given will
``win.''

When reading the above, Karl notices that only ``most'' graphic
options apply to the whole path. Indeed, all transformation options do
\emph{not} apply to the whole path, but only to ``everything following
them on the path.'' We will have a more detailed look at this in a
moment. Nevertheless, all options given during a path construction
apply only to this path. 



\subsection{Transformations}

When you specify a  coordinate like |(1cm,1cm)|, where is that
coordinate placed on the page? To determine the position, \tikzname,
\TeX, and \textsc{pdf} or PostScript all apply certain transformations
to the given coordinate in order to determine the finally position on
the page. 

\tikzname\ provides numerous options that allow you to transform
coordinates in \pgfname's private coordinate system. For example, the
|xshift| option allows you to shift all subsequent points by a certain
amount:

\begin{codeexample}[]
\tikz \draw (0,0) -- (0,0.5) [xshift=2pt] (0,0) -- (0,0.5);
\end{codeexample}

It is important to note that you can change transformation ``in the
middle of a path,'' a feature that is not supported by \pdf\
or PostScript. The reason is that \pgfname\ keeps track of its own
transformation matrix.

Here is a more complicated example:
\begin{codeexample}[]
\begin{tikzpicture}[even odd rule,rounded corners=2pt,x=10pt,y=10pt]
  \filldraw[fill=examplefill] (0,0)   rectangle (1,1)
    [xshift=5pt,yshift=5pt]   (0,0)   rectangle (1,1)
                [rotate=30]   (-1,-1) rectangle (2,2);
\end{tikzpicture}
\end{codeexample}

The most useful transformations are |xshift| and |yshift| for
shifting, |shift| for shifting to a given point as in |shift={(1,0)}|
or |shift={+(0,0)}| (the braces are necessary so that \TeX\ does not
mistake the comma for separating options), |rotate| for rotating by a
certain angle (there is also a |rotate around| for rotating around a
given point), |scale| for scaling by a certain factor, |xscale| and
|yscale| for scaling only in the $x$- or $y$-direction (|xscale=-1| is
a flip), and |xslant| and |yslant| for slanting. If these
transformation and those that I have not mentioned are not
sufficient,  the |cm| option allows you to apply an arbitrary
transformation matrix. Karl's students, by the way, do not know what a
transformation matrix is. 



\subsection{Repeating Things: For-Loops}

Karl's next aim is to add little ticks on the axes at positions $-1$,
$-1/2$, $1/2$, and $1$. For this, it would be nice to use some kind of
``loop,'' especially since he wishes to do the same thing at each of
these positions. There are different packages for doing this. \LaTeX\
has its own internal command for this, |pstricks| comes along with the
powerful |\mulitdo| command. All of these can be used together with
\pgfname\ and \tikzname, so if you are familiar with them, feel free to
use them. \pgfname\ introduces yet another command, called |\foreach|,
which I introduced since I could never remember the syntax of the other
packages. |\foreach| is defined in the package |pgffor| and can be used
independently of \pgfname. \tikzname\ includes it automatically.

In its basic form, the |\foreach| command is easy to use:
\begin{codeexample}[]
\foreach \x in {1,2,3} {$x =\x$, }
\end{codeexample}

The general syntax is |\foreach| \meta{variable}| in {|\meta{list of
    values}|} |\meta{commands}. Inside the \meta{commands}, the
\meta{variable} will be assigned to the different values. If the
\meta{commands} do not start with a brace, everything up to the
next semicolon is used as \meta{commands}.

For Karl and the ticks on the axes, he could use the following code:

\begin{codeexample}[]
\begin{tikzpicture}[scale=3]
  \clip (-0.1,-0.2) rectangle (1.1,1.51);
  \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
  \filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm) arc
  (0:30:3mm) -- cycle;
  \draw[->] (-1.5,0) -- (1.5,0);
  \draw[->] (0,-1.5) -- (0,1.5);
  \draw (0,0) circle (1cm);

  \foreach \x in {-1cm,-0.5cm,1cm}
    \draw (\x,-1pt) -- (\x,1pt);
  \foreach \y in {-1cm,-0.5cm,0.5cm,1cm}
    \draw (-1pt,\y) -- (1pt,\y);
\end{tikzpicture}
\end{codeexample}

As a matter of fact, there are many different ways of creating the
ticks. For example, Karl could have put the |\draw ...;| inside curly
braces. He could also have used, say,
\begin{codeexample}[code only]
\foreach \x in {-1,-0.5,1}
  \draw[xshift=\x cm] (0pt,-1pt) -- (0pt,1pt);
\end{codeexample}

Karl is curious what would happen in a more complicated situation
where there are, say, 20 ticks. It seems bothersome to explicitly
mention all these numbers in the set for |\foreach|. Indeed, it is
possible to use |...| inside the |\foreach| statement to iterate over 
a large number of values (which must, however, be dimensionless
real numbers) as in the following example: 

\begin{codeexample}[]
\tikz \foreach \x in {1,...,10}
        \draw (\x,0) circle (0.4cm);
\end{codeexample}

If you provide \emph{two} numbers before the |...|, the |\foreach|
statement will use their difference for the stepping:

\begin{codeexample}[]
\tikz \foreach \x in {-1,-0.5,...,1}
       \draw (\x cm,-1pt) -- (\x cm,1pt);
\end{codeexample}

We can also nest loops to create interesting effects:

\begin{codeexample}[]
\begin{tikzpicture}
  \foreach \x in {1,2,...,5,7,8,...,12}
    \foreach \y in {1,...,5}
    {
      \draw (\x,\y) +(-.5,-.5) rectangle ++(.5,.5);
      \draw (\x,\y) node{\x,\y};
    }
\end{tikzpicture}
\end{codeexample}

The |\foreach| statement can do even trickier stuff, but the above
gives the idea.




\subsection{Adding Text}

Karl is, by now, quite satisfied with the picture. However, the most
important parts, namely the labels, are still missing! 

\tikzname\ offers an easy-to-use and powerful system for adding text and,
more generally, complex shapes to a picture at specific positions. The
basic idea is the following: When \tikzname\ is constructing a path and
encounters the keyword |node| in the middle of a path, it
reads a \emph{node specification}. The keyword |node| is typically
followed by some options and then some text between curly braces. This
text is put inside a normal \TeX\ box (if the node specification
directly follows a coordinate, which is usually the case, \tikzname\ is
able to perform some magic so that it is even possible to use verbatim
text inside the boxes) and then placed at the current position, that
is, at the last specified position (possibly shifted a bit, according
to the given options). However, all nodes are drawn only after the
path has been completely drawn/filled/shaded/clipped/whatever.  

\begin{codeexample}[]
\begin{tikzpicture}
  \draw (0,0) rectangle (2,2);
  \draw (0.5,0.5) node [fill=examplefill]
                       {Text at \verb!node 1!}
     -- (1.5,1.5) node {Text at \verb!node 2!};
\end{tikzpicture}
\end{codeexample}

Obviously, Karl would not only like to place nodes \emph{on} the last
specified position, but also to the left or the 
right of these positions. For this, every node object that you
put in your picture is equipped with several \emph{anchors}. For
example, the |north| anchor is in the middle at the upper end of the shape,
the |south| anchor is at the bottom and the |north east| anchor is in
the upper right corner. When you given the option |anchor=north|, the
text will be placed such that this northern anchor will lie on the
current position and the text is, thus, below the current
position. Karl uses this to draw the ticks as follows:

\begin{codeexample}[]
\begin{tikzpicture}[scale=3]
  \clip (-0.6,-0.2) rectangle (0.6,1.51);
  \draw[step=.5cm,style=help lines] (-1.4,-1.4) grid (1.4,1.4);
  \filldraw[fill=green!20,draw=green!50!black]
    (0,0) -- (3mm,0mm) arc (0:30:3mm) -- cycle;
  \draw[->] (-1.5,0) -- (1.5,0);   \draw[->] (0,-1.5) -- (0,1.5);
  \draw (0,0) circle (1cm);

  \foreach \x in {-1,-0.5,1}
    \draw (\x cm,1pt) -- (\x cm,-1pt) node[anchor=north] {$\x$};
  \foreach \y in {-1,-0.5,0.5,1}
    \draw (1pt,\y cm) -- (-1pt,\y cm) node[anchor=east] {$\y$};
\end{tikzpicture}
\end{codeexample}

This is quite nice, already. Using these anchors, Karl can now add
most of the other text elements. However, Karl thinks that, though
``correct,'' it is quite counter-intuitive that in order to place something
\emph{below} a given point, he has to use the \emph{north} anchor. For
this reason, there is an option called |below|, which does the
same as |anchor=north|. Similarly, |above right| does the same as
|anchor=south east|. In addition, |below| takes an optional
dimension argument. If given, the shape will additionally be shifted
downwards by the given amount. So, |below=1pt| can be used to put
a text label below some point and, additionally shift it  1pt
downwards. 

Karl is not quite satisfied with the ticks. He would like to have
$1/2$ or $\frac{1}{2}$ shown instead of $0.5$, partly to show off the
nice capabilities of \TeX\ and \tikzname, partly because for positions
like $1/3$ or $\pi$ it is certainly very much preferable to have the
``mathematical'' tick there instead of just the ``numeric'' tick.
His students, on the other hand, prefer $0.5$ over $1/2$
since they are not too fond of fractions in general.

Karl now faces a problem: For the |\foreach| statement, the position
|\x| should still be given as |0.5| since \tikzname\ will not know where
|\frac{1}{2}| is supposed to be. On the other hand, the typeset text
should really be  |\frac{1}{2}|. To solve this problem, |\foreach|
offers a special syntax: Instead of having one variable |\x|, Karl can
specify two (or even more) variables separated by a slash as in
|\x / \xtext|. Then, the elements in the set over which |\foreach|
iterates must also be of the form \meta{first}|/|\meta{second}. In
each iteration, |\x| will be set to \meta{first} and |\xtext| will be
set to \meta{second}. If no \meta{second} is given, the \meta{first}
will be used again. So, here is the new code for the ticks: 

\begin{codeexample}[]
\begin{tikzpicture}[scale=3]
  \clip (-0.6,-0.2) rectangle (0.6,1.51);
  \draw[step=.5cm,style=help lines] (-1.4,-1.4) grid (1.4,1.4);
  \filldraw[fill=green!20,draw=green!50!black]
    (0,0) -- (3mm,0mm) arc (0:30:3mm) -- cycle;
  \draw[->] (-1.5,0) -- (1.5,0); \draw[->] (0,-1.5) -- (0,1.5);
  \draw (0,0) circle (1cm);

  \foreach \x/\xtext in {-1, -0.5/-\frac{1}{2}, 1}
    \draw (\x cm,1pt) -- (\x cm,-1pt) node[anchor=north] {$\xtext$};
  \foreach \y/\ytext in {-1, -0.5/-\frac{1}{2}, 0.5/\frac{1}{2}, 1}
    \draw (1pt,\y cm) -- (-1pt,\y cm) node[anchor=east] {$\ytext$};
\end{tikzpicture}
\end{codeexample}

Karl is quite pleased with the result, but his son points out that
this is still not perfectly satisfactory: The grid and the circle
interfere with the numbers and decrease their legibility. Karl is not
very concerned by this (his students do not even notice), but his son
insists that there is an easy solution: Karl can add the
|[fill=white]| option to fill out the background of the text shape
with a white color. 

The next thing Karl wants to do is to add the labels like $\sin
\alpha$. For this, he would like to place a label ``in the middle of
line.'' To do so, instead of specifying the label
|node {$\sin\alpha$}|  directly after one of the endpoints of the line
(which would place 
the label at that endpoint), Karl can give the label directly after
the |--|, before the coordinate. By default, this places the label in
the middle of the line, but the |pos=| options can be used to modify
this. Also, options like |near start| and |near end| can be used to
modify this position:


\begin{codeexample}[]
\begin{tikzpicture}[scale=3]
  \clip (-2,-0.2) rectangle (2,0.8);
  \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
  \filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm) arc
  (0:30:3mm) -- cycle;
  \draw[->] (-1.5,0) -- (1.5,0) coordinate (x axis);
  \draw[->] (0,-1.5) -- (0,1.5) coordinate (y axis);
  \draw (0,0) circle (1cm);
    
  \draw[very thick,red]
    (30:1cm) -- node[left=1pt,fill=white] {$\sin \alpha$} (30:1cm |- x axis);
  \draw[very thick,blue]
    (30:1cm |- x axis) -- node[below=2pt,fill=white] {$\cos \alpha$} (0,0);
  \draw[very thick,orange] (1,0) -- node [right=1pt,fill=white]
    {$\displaystyle \tan \alpha \color{black}=
      \frac{{\color{red}\sin \alpha}}{\color{blue}\cos \alpha}$}
    (intersection of 0,0--30:1cm and 1,0--1,1) coordinate (t);

  \draw (0,0) -- (t);
  
  \foreach \x/\xtext in {-1, -0.5/-\frac{1}{2}, 1}
    \draw (\x cm,1pt) -- (\x cm,-1pt) node[anchor=north,fill=white] {$\xtext$};
  \foreach \y/\ytext in {-1, -0.5/-\frac{1}{2}, 0.5/\frac{1}{2}, 1}
    \draw (1pt,\y cm) -- (-1pt,\y cm) node[anchor=east,fill=white] {$\ytext$};
\end{tikzpicture}
\end{codeexample}

You can also position labels on curves and, by adding the |sloped|
option, have them rotated such that they match the line's slope. Here
is an example:

\begin{codeexample}[]
\begin{tikzpicture}
  \draw (0,0) .. controls (6,1) and (9,1) ..
    node[near start,sloped,above] {near start}
    node {midway}
    node[very near end,sloped,below] {very near end} (12,0);
\end{tikzpicture}
\end{codeexample}

It remains to draw the explanatory text at the right of the
picture. The main difficulty here lies in limiting the width of the
text ``label,'' which is quite long, so that line breaking is
used. Fortunately, Karl can use the option |text width=6cm| to get the
desired effect. So, here is the full code:

\begin{codeexample}[code only]
\begin{tikzpicture}[scale=3,cap=round]
  % Local definitions
  \def\costhirty{0.8660256}

  % Colors
  \colorlet{anglecolor}{green!50!black}
  \colorlet{sincolor}{red}
  \colorlet{tancolor}{orange!80!black}
  \colorlet{coscolor}{blue}

  % Styles
  \tikzstyle{axes}=[]
  \tikzstyle{important line}=[very thick]
  \tikzstyle{information text}=[rounded corners,fill=red!10,inner sep=1ex]

  % The graphic
  \draw[style=help lines,step=0.5cm] (-1.4,-1.4) grid (1.4,1.4);
  
  \draw (0,0) circle (1cm);

  \begin{scope}[style=axes]
    \draw[->] (-1.5,0) -- (1.5,0) node[right] {$x$} coordinate(x axis);
    \draw[->] (0,-1.5) -- (0,1.5) node[above] {$y$} coordinate(y axis);

    \foreach \x/\xtext in {-1, -.5/-\frac{1}{2}, 1}
      \draw[xshift=\x cm] (0pt,1pt) -- (0pt,-1pt) node[below,fill=white] {$\xtext$};
  
    \foreach \y/\ytext in {-1, -.5/-\frac{1}{2}, .5/\frac{1}{2}, 1}
      \draw[yshift=\y cm] (1pt,0pt) -- (-1pt,0pt) node[left,fill=white] {$\ytext$};
  \end{scope}
    
  \filldraw[fill=green!20,draw=anglecolor] (0,0) -- (3mm,0pt) arc(0:30:3mm);
  \draw (15:2mm) node[anglecolor] {$\alpha$};
    
  \draw[style=important line,sincolor]
    (30:1cm) -- node[left=1pt,fill=white] {$\sin \alpha$} (30:1cm |- x axis);
  
  \draw[style=important line,coscolor]
    (30:1cm |- x axis) -- node[below=2pt,fill=white] {$\cos \alpha$} (0,0);
  
  \draw[style=important line,tancolor] (1,0) -- node[right=1pt,fill=white] {
    $\displaystyle \tan \alpha \color{black}=
    \frac{{\color{sincolor}\sin \alpha}}{\color{coscolor}\cos \alpha}$}
    (intersection of 0,0--30:1cm and 1,0--1,1) coordinate (t);

  \draw (0,0) -- (t);
  
  \draw[xshift=1.85cm]
    node[right,text width=6cm,style=information text]
    {
      The {\color{anglecolor} angle $\alpha$} is $30^\circ$ in the
      example ($\pi/6$ in radians). The {\color{sincolor}sine of
        $\alpha$}, which is the height of the red line, is
      \[
      {\color{sincolor} \sin \alpha} = 1/2.
      \]
      By the Theorem of Pythagoras ...
    };
\end{tikzpicture}
\end{codeexample}


\subsection{Nodes}

Placing text at a given position is just a special case of a more
general underlying mechanism. When you say |\draw (0,0) node{text};|,
what actually happens is that a rectangular node, anchored at its center, is
put at position $(0,0)$. On top of the rectangular node the text
|text| is drawn. Since no action is specified for the rectangle (like
|draw| or |fill|), the rectangle is actually discarded and only the
text is shown. However, by adding |fill| or |draw|, we can make the
underlying shape visible. Furthermore, we can \emph{change} the
shape using for example |shape=circle| or just |circle|. If we include
the package |pgflibraryshapes| we also get |ellipse|:


\begin{codeexample}[]
\begin{tikzpicture}
  \path (0,0)   node[ellipse,fill=examplefill,draw]
                  (h1) {hello world}
        (0.5,2) node[circle,shade,ball color=examplefill]
                  (h2) {hello world};
  \draw [->,shorten >=2pt] (h1.north) -- (h2.south);
\end{tikzpicture}
\end{codeexample}

As the above example shows, we can add the a name to a node by
putting it in parentheses between |node| and the |{|\meta{text}|}|
(you can also use the |name=| option). This will make \tikzname\ remember your node and all
its anchors. You can then refer to these anchors when specifying
coordinates. The syntax is |(|\meta{node
  name}|.|\meta{anchor}|)|. Currently, and also in the near future, 
\emph{this will not work across pictures since \tikzname\ looses track
  of the positions when it returns control to \TeX.} Magic hackery is
possible for certain drivers, but a portable implementation seems
impossible (just think of a possible \textsc{svg} driver). 

The option |shorten >| causes lines to be shortened by 2pt at the
end. Similarly, |shorten <| can be used to shorten (or even lengthen)
lines at the beginning. This is possible even if no arrow is drawn.

It is not always necessary to specify the anchor. If you do not give
an anchor, \tikzname\ will try to determine a reasonable border anchor by
itself (if \tikzname\ fails to find anything useful, it will use the
center instead). Here is a typical example:

\begin{codeexample}[]
\begin{tikzpicture}
  \begin{scope}[shape=circle,minimum size=1cm,fill=examplefill]
    \tikzstyle{every node}=[draw,fill]
    \node (q_A) at (0,0) {$q_A$};
    \node (q_E) at (6,0) {$q_E$};
    \node (q_1) at (2,0) {$q_1$};
    \node (q_2) at (4,2) {$q_2$};
  \end{scope}
  \draw (q_A) -- (q_1) -- (q_2) -| (q_E);
  \draw[->,shorten >=2pt] (q_A) .. controls +(75:1.4cm) and +(105:1.4cm) .. node[above] {$x$} (q_A);
\end{tikzpicture}
\end{codeexample}

In the example, we used the |\node| command, which is an abbreviation
for |\path node|.