summaryrefslogtreecommitdiff
path: root/graphics/pgf/contrib/tzplot/tzplot-doc-A-v2.0.tex
blob: 6f7f1d385084f8e20c845abd4a9f5ccafc813012 (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
%!TEX root = tzplot-doc.tex
%\begin{document}

%%%=================
%\part{Getting Ready}
\part{Prelimiaries}
%%%=================
\label{p:intro}

%%==================================
\chapter{Introduction}

%%------------------------------------------------------------
\section{About \texttt{tzplot.sty}}

The |tzplot| package is just a collection of macros based on \TikZ\ to save you time typing \Tikz\ code.

\paragraph{What you can do with \texttt{tzplot}}
In |pstricks|, a line connecting two points |(A)| and |(B)| is drawn by |\psline(A)(B)|.
With the package |tzplot|, you can do it by |\tzline(A)(B)|.

\begin{tztikz}{}
\tzline(A)(B)                    % is an abbreviation of:
  \draw (A) -- (B);
\end{tztikz}
%
\begin{tztikz}{}
\tzline[blue](A)(B){my line}[r]  % is an abbreviation of:
  \draw [blue] (A) -- (B) node [right] {my line};
\end{tztikz}

Some macros in this package represent one or a few lines of code, but some represent dozens of lines of \Tikz\ code.

All of the drawing macros of |tzplot| are prefixed by |\tz|. Of course, it means \Tikz.
The syntax of the |tzplot| macros comes from |tikz| and |pstricks|.
However, the input mode is more like |pstricks|.

\paragraph{How to load}
To use the |tzplot| package you have to load the package in the preamble of your document as follows:

\begin{verbatim}
    \usepackage{tzplot}
\end{verbatim}

The package depends on the packages |tikz|, |xparse|, and |expl3|.
And it uses the following \Tikz\ libraries:
\begin{verbatim}
    arrows,backgrounds,calc,intersections,patterns,plotmarks,positioning,shapes,
    decorations.pathreplacing,calligraphy
\end{verbatim}

In the version 2, more libraries are added to the list of preloaded libraries:
\begin{verbatim}
    arrows.meta, bending,         % (for middle arrow tips)
    decorations.markings,         % (for decoration)
    decorations.pathmorphing,     % (for snaked lines)
    fpu,                          % (for angle computation)
    spy                           % (for later use)
\end{verbatim}

\paragraph{More comments}
This package sets the basic \xem{arrow style} to |stealth|.
If you don't like this, as an alternative, you can set the style like |\tikzset{>=to}| after the |tzplot| package is loaded.

This package was originally motivated by drawing graphs in economics.
Therefore, the macros in this package have been selected and developed for drawing graphs efficiently in economics. However, this package will do a good job of drawing basic graphics in any fields.

Finally, note that this is far from a \Tikz\ tutorial.
\xem{To make good use of this package, you need to familiarize yourself with \Tikz}.

%%------------------------------------------------------------
\section{Preoccupied style names}
\label{s:stylenames}

This package does not provide any environment.
Since all the drawing macros prefixed by |\tz| are just abbreviations of \Tikz\ code,
you can use the macros in the |tikzpicture| environment together with any \Tikz\ commands.

\paragraph{Preoccupied styles}
However, there are some preoccupied style names that you should not overwrite.
Those are as follows:

\begin{verbatim}
    tzdot            tzmark           tzdotted
    tzdashed         tzhelplines      tznode
    tzshorten        tzextend         tzshowcontrols
\end{verbatim}

\paragraph{Abbreviated styles}
Following the manual of \Tikz, this package also predefines \iisw{abbreviations} (or aliases) of \Tikz's basic placement options for main nodes as follows:
\label{abbreviations}

\begin{tzsty}{}
% preoccupied (alias) styles for main node options
\tikzset{%
  a/.style={above=#1},
  b/.style={below=#1},
  c/.style={centered=#1},  % centered, not center
  l/.style={left=#1},
  r/.style={right=#1},
  al/.style={above left=#1},
  ar/.style={above right=#1},
  bl/.style={below left=#1},
  br/.style={below right=#1},
}
\end{tzsty}

By these abbreviations (or aliases), we mean that, with the |\tzplot| package, we can use these alias styles in the |\tikzpicture| environment as follows:

\begin{tztikz}{}
\draw (0,0) -- (1,0) node [ar] {line};  % [ar] = [above right]
\end{tztikz}

\paragraph{Layers}
The |tzplot| package also defines graphic layers as follows:

\begin{tzsty}{}
\pgfdeclarelayer{background}
\pgfdeclarelayer{behind}
\pgfdeclarelayer{above}
\pgfdeclarelayer{foreground}

\pgfsetlayers{background,behind,main,above,foreground}
\end{tzsty}
Therefore, you can select the graphic layers in sequence: |background|, |behind|, |main|, |above|, and |foreground|.
For example, you can change the layer of a straight line from |main| (default) to |background| as follows:

\begin{tzcode}[listing only]{1}
\begin{tikzpicture}
\tzhelplines(4,3)
  <tzplot macros>
  <tikz macros>
\begin{pgfonlayer}{background}
  \tzline[blue](0,0)(3,1)
\end{pgfonlayer}
\end{tikzpicture}
\end{tzcode}

%%------------------------------------------------------------
\section{How to read this document}

In drawing graphs, too many factors are involved: line style, color, fill, label, positioning, shift, and so on.
Almost all macros of this package have many arguments that control these factors.
Some are mandatory and some are optional.
Optional arguments are hidden when not used.

The document has three essential parts: Part II, Part III, and Part IV.
Part II introduces essential macros with only frequently used options.
There are many options hidden in the macros introduced in Part II.
Some macros are not introduced in Part II.
Part III and IV describe all the features of all macros.

You must get started with Part II.
Part II is sufficient for drawing needs in most cases.

Unless you are an experienced user of \Tikz, it is recommended to move on to Part III and Part IV once you become familiar with Part II. In the meantime, use Part III and Part IV for reference only. Use the list of contents and the index efficiently to find macros you need.


%%==================================
\chapter{Changes}

%%------------------------------------------------------------
\section{What's New}

\subsection{New macros}

New macros have been added.

\begin{itemize}\tightlist
\item |\tzfn'|: (swap version) inverse function of |\tzfn|
\item |\tzfnofy|, |\tzfnofy'|: function of |\y|
\item |\tzdeffn|, |\tzdeffnofy|: to define functions
\item |\tzdefLFn|, |\tzdefLFnofy|: define linear functions
\item |\tzLFn(')|, |\tzLFnofy(')|: linear functions
\item |\tzLFnXpoint(*)|: linear function intersection points
\item |\tzfnmin(')|, |\tzfnmax(')|: envelope curves
%
\listdivider
\item |\tzfnarea(*)|, |\settzfnarealayer|, |\tzfnarealine(')|: to fill the area under graphs
\item |\settzfnarealinestyle|
\item |\tzpdfZ|, |\tzpdfN(*)|: probability density functions of a normal distribution
\item |\tzprojs(*)|, |\tzprojsx(*)|, |\tzprojsy(*)|: multiple projection lines
\item |\settzpathlayer|: |main| layer by default
%
\listdivider
\item |\tzslope|, |\tzslopeat|
\item |\settzslopelayer|, |\settzslopeatlayer|, |\settzslopeepsilon|
%
\listdivider
\item |\tzlink(+)|, |\tzlinks(*)(+)|, |\settzlinkstyle|, |\settzpathstyle|
\item |\tzedge(+)|, |\tzedges(+)|
%
\listdivider
\item |\tznodes(*)|: multiple nodes
\item |\tznodedots(*)|: multiple node dots
\item |\tznoderectangle(*)|, |\tznodebox(*)|, |\tznodeoval(*)|: aliases
%
\listdivider
\item |\tzring(*)|, |\tzcirclering(*)|
\item |\tzellipsering(*)|, |\tzovalring(*)|
\item |\tzrectanglering(*)|, |\tzframering(*)|, |\tzboxring(*)|
\item |\tzbox(*)|
%
\listdivider
\item |\tzpointangle|: angle between points
\item |\tzanglemark(*)(')|, |\tzrightanglemark(*)|: angle marks
\item |\tzangleresult|, |\tzangleONE|, |\tzangleTWO|: after |\tzanglemark|
\item |\settzAAlinestyle|, |\settzanglelayer|, |\settzAAradius|, |\settzRAsize|.
%
\listdivider
\item |\settzmidarrow|: to control middle arrow tips
\item |\tzsnake|: snake lines
%\item |\tzspy| % (not documented)
%%%\item |\tzplotfile| % (not documented)
\end{itemize}


\subsection{Extending paths: \texttt{\bs tz<...>AtBegin} and \texttt{\bs<...>AtEnd}}

\begin{itemize}\tightlist
\item |\tztoAtBegin|, |\tztoAtEnd|, |\tztosAtBegin|, |\tztosAtEnd| (version 1)
\item |\tztoAtBegin|, |\tztoAtEnd|, |\tztosAtBegin|, |\tztosAtEnd| (version 1)
\item |\tzlineAtBegin|, |\tzlineAtEnd|, |\tzlinesAtBegin|, |\tzlinesAtEnd|
\item |\tzlinkAtBegin|, |\tzlinkAtEnd|, |\tzlinksAtBegin|, |\tzlinksAtEnd|
\item |\tzbezierAtBegin|, |\tzbezierAtEnd|
\item |\tzparabolaAtBegin|, |\tzparabolaAtEnd|
%
\listdivider
\item |\tzvfn(at)AtBegin|, |\tzvfn(at)AtEnd|
\item |\tzhfn(at)AtBegin|, |\tzhfn(at)AtEnd|
%
\listdivider
\item |\tzfnAtBegin|, |\tzfnAtEnd| (version 1)
\item |\tzfnofyAtBegin|, |\tzfnofyAtEnd|
\item |\tzLFnAtBegin|, |\tzLFnAtEnd|
\item |\tzLfnofyAtBegin|, |\tzLFnofyAtEnd|
\item |\tzfnminAtBegin|, |\tzfnminAtEnd|, |\tzfnmaxAtBegin|, |\tzfnmaxAtEnd|
\item |\tzplotAtBegin|, |\tzplotAtEnd|, |\tzplotcurveAtBegin|, |\tzplotcurveAtEnd|
\end{itemize}



\subsection{New coordinates}

\begin{itemize}\tightlist
\item |(tzAAmid)|: angle arc midpoint, depending on |\tzanglemark|
\item |(tzRAvertex)|: right angle mark vertex, depending on |\tzrightanglemark|
\end{itemize}

\subsection{Error messages}

Some macros, called \iisw{semicolon version}s, accept any number of coordinates. You MUST indicate when the coordinate iteration ends with a \xem{semicolon} |;|. Without the semicolon, an error occurs with the \iisw{error message}:
\begin{verbatim}
! Package tzplot Error: You may have forgotten a semicolon here or above!
\end{verbatim}

Knowing two coordinates, you can use |\tzLFn| and related macros to graph a linear function through the two points without writing an explicit function.
If you inadvertently try \xem{infinite} slopes, you will get an error with the \xem{error message}:
\begin{verbatim}
! Package tzplot Error: Perhaps you are trying an 'infinite slope' here or above!
\end{verbatim}

\subsection{Abridged strings to place labels for coordinates, dots, and points}
\label{ss:string-replacement}

In \Tikz, a label to a main node is placed by the |label| option. The syntax of the |label| option is |label={[<label opt>]<angle>:{<label>}}|.
In \Tikz, The position of labels is specified by \xem{angles}. The positioning words like |above|, |below|, |below right|, and so on can be used and they are interpreted in \Tikz\ as the corresponding angles.

\xem{Just to avoid frequent coding errors}, from the version 2, the |tzplot| package provides the \xem{abridged strings} |a|, |b|, |c|, |br|, and so on that you can use instead of angles. With the |tzplot| package, the user input |a| is replaced by |above|, |[b]| by |below|, |c| by |center| (\xem{not} |centered| for the main node option), |br| by |below right|, and similarly for other abridged strings.

\remark This is just a \iisw{string replacement} that is not related to the function of \Tikz. By this we mean that we \xem{cannot use} these abridged strings to place labels, instead of angels, in the |tikzpicture| environment without using the related |\tz<...>| macros.

The macros related to this issue are as follows:

\begin{itemize}\tightlist
\item dots: |\tzdot(s)|, |\tzcdots(s)|, |\tznodedot(s)|
\item coordinates: |\tzcoor(s)|, |\tzcoorsquick|
\item intersection points: |\tzXpoint|, |\tzvXpoint|, |\tzhXpoint|, |\tzLFnXpoint|
\item plot coordinates: |\tzplot|, |\tzplotcurve|
\item and their starred versions.
\end{itemize}

\subsection{New styles for middle arrow tips}

Some styles for drawing the the \iisw{middle arrow tip}\xem{s} on a path are predefined.
\begin{itemize}\tightlist
\item |-->--|: (controllable) middle arrow tip
  \begin{itemize}
  \item \icmd{\settzmidarrow} controls the positions and styles of middle arrow tips
  \end{itemize}
\item |--o--|: the circle middle arrow tip
\item |--x--|: the cross middle arrow tip
\item |--/--|: the diagonal middle arrow tip
\end{itemize}

You can use these styles to draw middle arrow tips as follows:

\begin{tztikz}{}
\tzlines[-->--,red](0,0)(1,0)(3,1);         % default=0.5
\tzlines[-->--=0.7](0,0)(1,0)(3,3);         % work like
  \draw [-->--,red](0,0) -- (1,0) -- (3,1);
  \draw [-->--=0.7](0,0) -- (1,0) -- (3,1);
\end{tztikz}

%%------------------------------------------------------------
\section{Remarks}


Some macros have been modified in order to add new features. This does not cause any harm to existing users.
\begin{itemize}\tightlist
\item |\tznode|: to add new option |<node.code>|
  \begin{itemize}
  \item This allows you to use full features (including |foreach|) of the \Tikz's |node| operation.
  \end{itemize}
\item |\tzframe|, |\tzcircle|, |\tzellipse|: to add new option |<code.append>|
  \begin{itemize}
  \item Now you can use |even odd rule| to draw rings with these macros.
  \end{itemize}
\end{itemize}

\bigskip
Some macros are ``experimental" and their syntax may change in the future.

\paragraph{Styles of middle arrow tips in the \texttt{istgame} package}
The package |istgame| to draw game trees predefines the styles of the middle arrow tips including |->-|, |-o->|, and |-x-|.
\begin{itemize}\firmlist
\item The style |->-| defined in |istgame| and |-->--| defined in |tzplot| are a little different from each other in the default values.
  \begin{itemize}
  \item Still you may want to use the style |->-| instead of |-->--|. In that case, you can do like this:
  \begin{verbatim}
  \tikzset{->-/.style={-->--}}
  \end{verbatim}
  \item \xem{However}, it is important to understand that changing the style to |->-| may override the style of |->-| defined in other package, depending on which package is loaded first.
  \item The best way to use |->-| instead of |-->--| is to upload the |istgame| and follow the instruction of the manual.
  \end{itemize}
\item The styles |--o--| and |--x--| differ in definition and usage from the styles |-o-| and |-x-| of the |istgame| package.
\end{itemize}