%!TEX root = tzplot-doc.tex
%\begin{document}

%%%=================
\part{Getting Ready}
%%%=================
\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.

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|.

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}
    calc,backgrounds,positioning,intersections,arrows,shapes,patterns,plotmarks,
    decorations.pathreplacing,calligraphy
\end{verbatim}

This package sets the basic 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.
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.

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}

This package also predefined \iisw{abbreviations} of \Tikz's basic placement options as follows:
\label{abbreviations}

\begin{tzsty}{}
% preoccupied (alias) styles
\tikzset{%
  a/.style={above=#1},
  b/.style={below=#1},
  c/.style={centered=#1},
  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}
You can use these abbreviations to place \Tikz's \iisw{main node}\xem{s} but not \iisw{label node}\xem{s}. To place label nodes, use non-abbreviated options or angles instead.


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.

