% !TeX spellcheck = en_US
% !TeX root = tikz-ext-manual.tex
% Copyright 2022 by Qrrbrbirlbel
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
\part{Introduction}
\begin{multicols}{2}
\section{Usage}
This package is called |tikz-ext|, however,
one can't load it via |\usepackage|.%
\footnote{Except for \texttt{pgfcalendar-ext} and \texttt{pgffor-ext}.}
Instead, this package consists mostly of
\pgfname\space and \tikzname\space libraries
which are loaded by either |\usepgflibrary| or |\usetikzlibrary|.

\section{Why do we need it?}
Since I have been answering questions on
\hyperlink{https://tex.stackexchange.com}{TeX.sx}
I've noticed that some questions come up again and again,
every time with a slightly different approach on how to solve them.

I don't like reinventing the wheel which is why I've gathered
the solutions of my answers in this package.

\section{Having problems?}
Note however, that most of these extensions haven't been
stress-tested properly and might be considered
experimental.

Don't hesitate to open an issue on GitHub.
You probably found a bug.

\newcolumn
\section{Namespaces and \tikzextname\ macros}
Since some parts of this package have existed in some form since 2013,
the choice for key names and in which \pgfname keys namespace they reside
is not always optimal.
They often reside in the main |/tikz| or |/pgf| path.
Similar applies to macro names.

Starting with version~0.6, the namespace for almost all keys is |/tikz/ext|
or |/pgf/ext|. The same applies to macros that shall be starting with |\tikzext| or |\pgfext|.

Starting with version~0.6,
\tikzextname\ provides commands that return the current version for compatibility testing.
The second simply increments with every release
so that the first doesn't need to be parsed.
\begin{command}{\tikzextversion}
  Returns \texttt{\tikzextversion}.
\end{command}
\begin{command}{\tikzextversionnumber}
  Returns \texttt{\tikzextversionnumber}.
\end{command}
%
Also there's |\tikzextset| and |\pgfextset|.
\begin{command}{\tikzextset\marg{options}}
  This command will process the \meta{options} using the
  |\pgfkeys| command with the default path set to |/tikz/ext|.
\end{command}
\begin{command}{\pgfextset\marg{options}}
  This command will process the \meta{options} using the
  |\pgfkeys| command with the default path set to |/pgf/ext|.
\end{command}

\newcolumn
\section{Compatibility with older versions}
As discussed in the previous section,
keys and commands of extensions that existed before version~0.6
that do not appear in this manual are considered deprecated.

\begin{key}{/\tikzext/compat=\mchoice{pre 0.6, 0.6, warn, newest} (default pre 0.6)}
  This sets the global compatibility setting for every extension of this package
  (whether already loaded or not).

  The choice |warn| gives out warning for deprecated keys or commands
  but still executes them if they were not not in use when an extension was loaded.
  
  For version 0.6 this is actually the default settings so that active documents
  keep working -- for now.
  
  The following table shows the compatibility settings for each extension.
  \newcommand*\X{$\checkmark$}%
  \newcommand*\Xdef{\X\kern-.65em\X}%
  A \X\ denotes an available setting where \Xdef\ denotes the default compatibility setting.
  A -- denotes that it is not different than the |newest| setting.
  \begin{center}
  \begin{tabular}{>{\ttfamily ext.}l ccc}
    \toprule
    \multicolumn{1}{l}{Extension}                        & warn  & pre 0.6 & 0.6 \\ \midrule
    \multicolumn{1}{l}{\ttfamily pgfcalendar-ext}        & \Xdef &   \X    & --  \\
    \multicolumn{1}{l}{\quad\ttfamily ext.calendar-plus} &       &         &     \\ \midrule[.5\lightrulewidth]
    arrows                                               & \Xdef &   \X    & --  \\
    layers                                               & \Xdef &   \X    & --  \\
    node-families                                        & \Xdef &   \X    & --  \\
    nodes                                                & \Xdef &   \X    & --  \\
    paths.arcto                                          & \Xdef &   \X    & --  \\ \addlinespace
    paths.ortho                                          & \Xdef &   \X    & --  \\
    paths.timer                                          & \Xdef &   \X    & --  \\
    patterns.images                                      & \Xdef &   \X    & --  \\
    pgffor-ext                                           & \Xdef &   \X    & --  \\
    pgfkeys-plus                                         & \Xdef &   \X    & --  \\
    positioning-plus                                     & \Xdef &   \X    & --  \\ \addlinespace
    scalepicture                                         & \Xdef &   \X    & --  \\
    shapes                                               & \Xdef &   \X    & --  \\
    transformations.mirror                               & \Xdef &   \X    & --  \\
    topaths.arcthrough                                   & \Xdef &   \X    & --  \\ \bottomrule
  \end{tabular}
  \end{center}
  
  For future version, it is planned that the default compatibility setting will not be |warn|.
\end{key}

\newcolumn\noindent
For each available extension the compatibility setting can be adjusted as well
after the extension is loaded.
\begin{keylist}[/\tikzext/compat]{%
  pgfcalendar-ext=\meta{version} (default pre 0.6),
  arrows=\meta{version} (default pre 0.6),
  layers=\meta{version} (default pre 0.6),
  nodes=\meta{version} (default pre 0.6),
  node-families=\meta{version} (default pre 0.6),
  paths.arcto=\meta{version} (default pre 0.6),
  paths.ortho=\meta{version} (default pre 0.6),
  paths.timer=\meta{version} (default pre 0.6),
  patterns.images=\meta{version} (default pre 0.6),
  pgffor-ext=\meta{version} (default pre 0.6),
  pgfkeys-plus=\meta{version} (default pre 0.6),
  positioning-plus=\meta{version} (default pre 0.6),
  scalepicture=\meta{version} (default pre 0.6),
  shapes=\meta{version} (default pre 0.6),
  transformations.mirror=\meta{version} (default pre 0.6),
  topaths.arcthrough=\meta{version} (default pre 0.6)%
}
  For \meta{version} the same choices are valid as for the main |compat| key.
  It should be noted that at this point, a compatibility setting can't really be reversed
  since they only forward arguments from an old key or command to the new version.
  
  The old names are given as a subtitle to the new one in the sections that introduce them.
\end{keylist}
\end{multicols}