Debian Codegraph @

texmf-dist/doc/latex/tzplot/tzplot-doc-A-v2.2.tex

raw
1 %!TEX root = tzplot-doc.tex
2 %\begin{document}
3
4 %%%=================
5 %\part{Getting Ready}
6 \part{Prelimiaries}
7 %%%=================
8 \label{p:intro}
9
10 %%==================================
11 \chapter{Introduction}
12
13 %%------------------------------------------------------------
14 \section{About \texttt{tzplot.sty}}
15
16 The |tzplot| package is just a collection of macros based on \TikZ\ to save you time typing \Tikz\ code.
17
18 \paragraph{What you can do with \texttt{tzplot}}
19 In |pstricks|, a line connecting two points |(A)| and |(B)| is drawn by |\psline(A)(B)|.
20 With the package |tzplot|, you can do it by |\tzline(A)(B)|.
21
22 \begin{tztikz}
23 \tzline(A)(B) % is an abbreviation of:
24 \draw (A) -- (B);
25 \end{tztikz}
26 %
27 \begin{tztikz}
28 \tzline[blue](A)(B){my line}[r] % is an abbreviation of:
29 \draw [blue] (A) -- (B) node [right] {my line};
30 \end{tztikz}
31
32 Some macros in this package represent one or a few lines of code, but some represent dozens of lines of \Tikz\ code.
33
34 All of the drawing macros of |tzplot| are prefixed by |\tz|. Of course, it means \Tikz.
35 The syntax of the |tzplot| macros comes from |tikz| and |pstricks|.
36 However, the input mode is more like |pstricks|.
37
38 \paragraph{How to load}
39 To use the |tzplot| package you have to load the package in the preamble of your document as follows:
40
41 \begin{verbatim}
42 \usepackage{tzplot}
43 \end{verbatim}
44
45 The package depends on the packages |tikz|, |xparse|, and |expl3|.
46 And it uses the following \Tikz\ libraries:
47 \begin{verbatim}
48 arrows,backgrounds,calc,intersections,patterns,plotmarks,positioning,shapes,
49 decorations.pathreplacing,calligraphy
50 \end{verbatim}
51
52 In the version 2, more libraries are added to the list of preloaded libraries:
53 \begin{verbatim}
54 arrows.meta, bending, % (for middle arrow tips)
55 decorations.markings, % (for decoration)
56 decorations.pathmorphing, % (for snaked lines)
57 fpu, % (for angle computation)
58 spy % (for later use)
59 \end{verbatim}
60
61 \paragraph{More comments}
62 This package sets the basic \xem{arrow style} to |stealth|.
63 If you don't like this, as an alternative, you can set the style like |\tikzset{>=to}| after the |tzplot| package is loaded.
64
65 This package was originally motivated by drawing graphs in economics.
66 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.
67
68 Finally, note that this is far from a \Tikz\ tutorial.
69 \xem{To make good use of this package, you need to familiarize yourself with \Tikz}.
70
71 %%------------------------------------------------------------
72 \section{Preoccupied style names}
73 \label{s:stylenames}
74
75 This package does not provide any environment.
76 Since all the drawing macros prefixed by |\tz| are just abbreviations of \Tikz\ code,
77 you can use the macros in the |tikzpicture| environment together with any \Tikz\ commands.
78
79 \paragraph{Preoccupied styles}
80 However, there are some preoccupied style names that you should not overwrite.
81 Those are as follows:
82
83 \begin{verbatim}
84 tzdot tzmark tzdotted
85 tzdashed tzhelplines tznode
86 tzshorten tzextend tzshowcontrols
87 \end{verbatim}
88
89 \paragraph{Abbreviated styles}
90 Following the manual of \Tikz, this package also predefines \iisw{abbreviations} (or aliases) of \Tikz's basic placement options for main nodes as follows:
91 \label{abbreviations}
92
93 \begin{tzsty}
94 % preoccupied (alias) styles for main node options
95 \tikzset{%
96 a/.style={above=#1},
97 b/.style={below=#1},
98 c/.style={centered=#1}, % centered, not center
99 l/.style={left=#1},
100 r/.style={right=#1},
101 al/.style={above left=#1},
102 ar/.style={above right=#1},
103 bl/.style={below left=#1},
104 br/.style={below right=#1},
105 }
106 \end{tzsty}
107
108 By these abbreviations (or aliases), we mean that, with the |\tzplot| package, we can use these alias styles in the |\tikzpicture| environment as follows:
109
110 \begin{tztikz}
111 \draw (0,0) -- (1,0) node [ar] {line}; % [ar] = [above right]
112 \end{tztikz}
113
114 \paragraph{Layers}
115 The |tzplot| package also defines graphic layers as follows:
116
117 \begin{tzsty}
118 \pgfdeclarelayer{background}
119 \pgfdeclarelayer{behind}
120 \pgfdeclarelayer{above}
121 \pgfdeclarelayer{foreground}
122
123 \pgfsetlayers{background,behind,main,above,foreground}
124 \end{tzsty}
125 Therefore, you can select the graphic layers in sequence: |background|, |behind|, |main|, |above|, and |foreground|.
126 For example, you can change the layer of a straight line from |main| (default) to |background| as follows:
127
128 \begin{tzcode}[listing only]
129 \begin{tikzpicture}
130 <tzplot macros>
131 <tikz macros>
132 \begin{pgfonlayer}{background}
133 \tzline[blue](0,0)(3,1)
134 \end{pgfonlayer}
135 \end{tikzpicture}
136 \end{tzcode}
137
138 %%------------------------------------------------------------
139 \section{How to read this document}
140
141 In drawing graphs, too many factors are involved: line style, color, fill, label, positioning, shift, and so on.
142 Almost all macros of this package have many arguments that control these factors.
143 Some are mandatory and some are optional.
144 Optional arguments are hidden when not used.
145
146 The document has three essential parts: Part II, Part III, and Part IV.
147 Part II introduces essential macros with only frequently used options.
148 There are many options hidden in the macros introduced in Part II.
149 Some macros are not introduced in Part II.
150 Part III and IV describe all the features of all macros.
151
152 You must get started with Part II.
153 Part II is sufficient for drawing needs in most cases.
154
155 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.
156
157
158 %%==================================
159 \chapter{Changes}
160
161 %%------------------------------------------------------------
162 \section{What's New in version 2.2}
163
164 \paragraph{New macros}
165
166 \begin{itemize}
167 \item |\tzcoortangenttocircle(*)|: to find the tangent points to a circle from a point
168 \end{itemize}
169
170 \paragraph{Redesigned macros}
171
172 \begin{itemize}
173 \item |\tznodecircle(*)|: new options |"<path name>"| and |(<minimum size>)|
174 \end{itemize}
175
176 %%------------------------------------------------------------
177 \section{What's New in version 2.1}
178
179 \paragraph{New macros}
180
181 \begin{itemize}
182 \item |\tzdistance|: distance between two points, $\Delta x$, and $\Delta y$
183 %
184 \listdivider
185 \item |\tzslopeat'|: opposite direction of |\tzslopeat|
186 \item |\tzslope'|: opposite direction of |\tzslope|
187 %
188 \listdivider
189 \item |\tznormalat|: a normal line from a point on a path
190 \item |\tznormalat'|: opposite direction of |\tznormalat|
191 \item |\tznormalat*|: works like |\tzslopeat|, but rotated |90| degrees
192 \item |\tznormalat*'|: works like |\tzslopeat|, but rotated |-90| degrees
193 \item |\tznormal|: a normal line from a point on a path
194 \item |\tznormal'|: opposite direction of |\tznormal|
195 \item |\tznormal*|: works like |\tzslope|, but rotated |90| degrees
196 \item |\tznormal*'|: works like |\tzslope|, but rotated |-90| degrees
197 \item |\settznormallayer|: controls the layer of |\tznormalat| and its variants
198 \item |\settznormalepsilon|
199 \end{itemize}
200
201 \paragraph{Redesigned macros}
202
203 \begin{itemize}
204 \item |\tzaxisx|: added the option |"<path name>"| to find the intercepts easily (by default, |axisx|)
205 \item |\tzaxisy|: added the option |"<path name>"| to find the intercepts easily (by default, |axisy|)
206 \item |\tzaxes|: added the option |"<path name>"| with the default |"axes"|
207 \item |\tzaxesL|: added the option |"<path name>"| with the default |"axesL"|
208 \end{itemize}
209
210 %%------------------------------------------------------------
211 \section{What's New in version 2.0}
212
213 \subsection{New macros}
214
215 New macros have been added.
216
217 \begin{itemize}\tightlist
218 \item |\tzfn'|: (swap version) inverse function of |\tzfn|
219 \item |\tzfnofy|, |\tzfnofy'|: function of |\y|
220 \item |\tzdefLFn|, |\tzdefLFnofy|: to define linear functions
221 \item |\tzLFn(')|, |\tzLFnofy(')|: linear functions
222 \item |\tzLFnXpoint(*)|: linear function intersection points
223 \item |\tzfnmin(')|, |\tzfnmax(')|: envelope curves
224 %
225 \listdivider
226 \item |\tzfnarea(*)|, |\settzfnarealayer|, |\tzfnarealine(')|: to fill the area under graphs
227 \item |\settzfnarealinestyle|
228 \item |\tzpdfZ|, |\tzpdfN(*)|: (predefined) probability density functions of a normal distribution
229 \item |\tzprojs(*)|, |\tzprojsx(*)|, |\tzprojsy(*)|: multiple projection lines
230 \item |\settzpathlayer|: |main| layer by default
231 %
232 \listdivider
233 \item |\tzslope|, |\tzslopeat|
234 \item |\settzslopelayer|, |\settzslopeatlayer|, |\settzslopeepsilon|
235 %
236 \listdivider
237 \item |\tzlink(+)|, |\tzlinks(*)(+)|, |\settzlinkstyle|, |\settzpathstyle|
238 \item |\tzedge(+)|, |\tzedges(+)|
239 %
240 \listdivider
241 \item |\tznodes(*)|: multiple nodes
242 \item |\tznodedots(*)|: multiple node dots
243 \item |\tznoderectangle(*)|, |\tznodebox(*)|, |\tznodeoval(*)|: aliases
244 %
245 \listdivider
246 \item |\tzring(*)|, |\tzcirclering(*)|
247 \item |\tzellipsering(*)|, |\tzovalring(*)|
248 \item |\tzrectanglering(*)|, |\tzframering(*)|, |\tzboxring(*)|
249 \item |\tzbox(*)|
250 %
251 \listdivider
252 \item |\tzpointangle|: angle between points
253 \item |\tzanglemark(*)(')|, |\tzrightanglemark(*)|: angle marks
254 \item |\tzangleresult|, |\tzangleONE|, |\tzangleTWO|: after |\tzanglemark|
255 \item |\settzAAlinestyle|, |\settzanglelayer|, |\settzAAradius|, |\settzRAsize|.
256 %
257 \listdivider
258 \item |\settzmidarrow|: to control middle arrow tips
259 \item |\tzsnake|: snake lines
260 %\item |\tzspy| % (not documented)
261 %%%\item |\tzplotfile| % (not documented)
262 \end{itemize}
263
264
265 \subsection{Extending paths: \texttt{\bs tz<...>AtBegin} and \texttt{\bs tz<...>AtEnd}}
266
267 \begin{itemize}\tightlist
268 \item |\tztoAtBegin|, |\tztoAtEnd|, |\tztosAtBegin|, |\tztosAtEnd| (version 1)
269 \item |\tztoAtBegin|, |\tztoAtEnd|, |\tztosAtBegin|, |\tztosAtEnd| (version 1)
270 \item |\tzlineAtBegin|, |\tzlineAtEnd|, |\tzlinesAtBegin|, |\tzlinesAtEnd|
271 \item |\tzlinkAtBegin|, |\tzlinkAtEnd|, |\tzlinksAtBegin|, |\tzlinksAtEnd|
272 \item |\tzbezierAtBegin|, |\tzbezierAtEnd|
273 \item |\tzparabolaAtBegin|, |\tzparabolaAtEnd|
274 %
275 \listdivider
276 \item |\tzvfn(at)AtBegin|, |\tzvfn(at)AtEnd|
277 \item |\tzhfn(at)AtBegin|, |\tzhfn(at)AtEnd|
278 %
279 \listdivider
280 \item |\tzfnAtBegin|, |\tzfnAtEnd| (version 1)
281 \item |\tzfnofyAtBegin|, |\tzfnofyAtEnd|
282 \item |\tzLFnAtBegin|, |\tzLFnAtEnd|
283 \item |\tzLfnofyAtBegin|, |\tzLFnofyAtEnd|
284 \item |\tzfnminAtBegin|, |\tzfnminAtEnd|, |\tzfnmaxAtBegin|, |\tzfnmaxAtEnd|
285 \item |\tzplotAtBegin|, |\tzplotAtEnd|, |\tzplotcurveAtBegin|, |\tzplotcurveAtEnd|
286 \end{itemize}
287
288
289
290 \subsection{New coordinates}
291
292 \begin{itemize}\tightlist
293 \item |(tzAAmid)|: angle arc midpoint, depending on |\tzanglemark|
294 \item |(tzRAvertex)|: right angle mark vertex, depending on |\tzrightanglemark|
295 \end{itemize}
296
297 \subsection{Error messages}
298
299 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}:
300 \begin{verbatim}
301 ! Package tzplot Error: You may have forgotten a semicolon here or above!
302 \end{verbatim}
303
304 Knowing two coordinates, you can use |\tzLFn| and related macros to graph a linear function through the two points without writing an explicit function.
305 If you inadvertently try \xem{infinite} slopes, you will get an error with the \xem{error message}:
306 \begin{verbatim}
307 ! Package tzplot Error: Perhaps you are trying an 'infinite slope' here or above!
308 \end{verbatim}
309
310 \subsection{Abridged strings to place labels for coordinates, dots, and points}
311 \label{ss:string-replacement}
312
313 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>}}|.
314 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.
315
316 \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.
317
318 \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.
319
320 The macros related to this issue are as follows:
321
322 \begin{itemize}%\tightlist
323 \item dots: |\tzdot(s)|, |\tzcdots(s)|, |\tznodedot(s)|
324 \item coordinates: |\tzcoor(s)|, |\tzcoorsquick|
325 \item intersection points: |\tzXpoint|, |\tzvXpoint|, |\tzhXpoint|, |\tzLFnXpoint|
326 \item plot coordinates: |\tzplot|, |\tzplotcurve|
327 \item and their starred versions.
328 \end{itemize}
329
330 \subsection{New styles for middle arrow tips}
331
332 Some styles for drawing the the \iisw{middle arrow tip}\xem{s} on a path are predefined.
333 \begin{itemize}%\tightlist
334 \item |-->--|: (controllable) middle arrow tip
335 \begin{itemize}
336 \item \icmd{\settzmidarrow} controls the positions and styles of middle arrow tips
337 \end{itemize}
338 \item |--o--|: the circle middle arrow tip
339 \item |--x--|: the cross middle arrow tip
340 \item |--/--|: the diagonal middle arrow tip
341 \end{itemize}
342
343 You can use these styles to draw middle arrow tips as follows:
344
345 \begin{tztikz}
346 \tzlines[-->--,red](0,0)(1,0)(3,1); % default=0.5
347 \tzlines[-->--=0.7](0,0)(1,0)(3,3); % work like
348 \draw [-->--,red](0,0) -- (1,0) -- (3,1);
349 \draw [-->--=0.7](0,0) -- (1,0) -- (3,1);
350 \end{tztikz}
351
352 %%------------------------------------------------------------
353 \section{Remarks}
354
355
356 Some macros have been modified in order to add new features. This does not cause any harm to existing users.
357 \begin{itemize}\tightlist
358 \item |\tznode|: to add new option |<node.code>|
359 \begin{itemize}
360 \item This allows you to use full features (including |foreach|) of the \Tikz's |node| operation.
361 \end{itemize}
362 \item |\tzframe|, |\tzcircle|, |\tzellipse|: to add new option |<code.append>|
363 \begin{itemize}
364 \item Now you can use |even odd rule| to draw rings with these macros.
365 \end{itemize}
366 \end{itemize}
367
368 \bigskip
369 Some macros are ``experimental" and their syntax may change in the future.
370
371 \paragraph{Styles of middle arrow tips in the \texttt{istgame} package}
372 The package |istgame| to draw game trees predefines the styles of the middle arrow tips including |->-|, |-o->|, and |-x-|.
373 \begin{itemize}\firmlist
374 \item The style |->-| defined in |istgame| and |-->--| defined in |tzplot| are a little different from each other in the default values.
375 \begin{itemize}
376 \item Still you may want to use the style |->-| instead of |-->--|. In that case, you can do like this:
377 \begin{verbatim}
378 \tikzset{->-/.style={-->--}}
379 \end{verbatim}
380 \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.
381 \item The best way to use |->-| instead of |-->--| is to upload the |istgame| and follow the instruction of the manual.
382 \end{itemize}
383 \item The styles |--o--| and |--x--| differ in definition and usage from the styles |-o-| and |-x-| of the |istgame| package.
384 \end{itemize}
385
386