%!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]
\begin{tikzpicture}
  <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 styles, colors, filling, labels, 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 in version 2.2}

\paragraph{New macros}

\begin{itemize}
\item |\tzcoortangenttocircle(*)|: to find the tangent points to a circle from a point
\end{itemize}

\paragraph{Redesigned macros}

\begin{itemize}
\item |\tznodecircle(*)|: new options |"<path name>"| and |(<minimum size>)|
\end{itemize}

%%------------------------------------------------------------
\section{What's New in version 2.1}

\paragraph{New macros}

\begin{itemize}
\item |\tzdistance|: distance between two points, $\Delta x$, and $\Delta y$
%
\listdivider
\item |\tzslopeat'|: opposite direction of |\tzslopeat|
\item |\tzslope'|: opposite direction of |\tzslope|
%
\listdivider
\item |\tznormalat|: a normal line from a point on a path
\item |\tznormalat'|: opposite direction of |\tznormalat|
\item |\tznormalat*|: works like |\tzslopeat|, but rotated |90| degrees
\item |\tznormalat*'|: works like |\tzslopeat|, but rotated |-90| degrees
\item |\tznormal|: a normal line from a point on a path
\item |\tznormal'|: opposite direction of |\tznormal|
\item |\tznormal*|: works like |\tzslope|, but rotated |90| degrees
\item |\tznormal*'|: works like |\tzslope|, but rotated |-90| degrees
\item |\settznormallayer|: controls the layer of |\tznormalat| and its variants
\item |\settznormalepsilon|
\end{itemize}

\paragraph{Redesigned macros}

\begin{itemize}
\item |\tzaxisx|: added the option |"<path name>"| to find the intercepts easily (by default, |axisx|)
\item |\tzaxisy|: added the option |"<path name>"| to find the intercepts easily (by default, |axisy|)
\item |\tzaxes|: added the option |"<path name>"| with the default |"axes"|
\item |\tzaxesL|: added the option |"<path name>"| with the default |"axesL"|
\end{itemize}

%%------------------------------------------------------------
\section{What's New in version 2.0}

\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 |\tzdefLFn|, |\tzdefLFnofy|: to 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(*)|: (predefined) 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 tz<...>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 \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}


