%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Documentation for the jigsaw package
% A package to draw jigsaw pieces with tikz
% Maintained by samcarter
%
% Project repository and bug tracker:
% https://github.com/samcarter/jigsaw
%
% Released under the LaTeX Project Public License v1.3c or later
% See http://www.latex-project.org/lppl.txt
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\documentclass[parskip=half]{scrartcl}

% packages %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\usepackage[T1]{fontenc}	
\usepackage[utf8]{inputenc}		
\usepackage[english]{babel}
\usepackage[bitstream-charter]{mathdesign}
%\usepackage{duckuments}
\usepackage{jigsaw}
\usetikzlibrary{matrix}
\usepackage[most]{tcolorbox}
\usepackage[paper=a4paper,margin=2.9cm]{geometry}
\usepackage{url}
\usepackage{xspace}
\usepackage{scrlayer-scrpage} 
\usepackage[hang,flushmargin,bottom]{footmisc}
\usepackage[colorlinks=true,breaklinks=true,urlcolor=duckblue,linkcolor=duckblue,citecolor=duckblue,filecolor=duckblue]{hyperref}

% macros %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newcommand{\CTAN}{\textsc{CTAN}\xspace}
\newcommand{\TikZ}{Ti\emph{k}Z\xspace}
\newcommand{\miktex}{MiK\TeX\xspace}
\newcommand{\texlive}{\TeX{}Live\xspace}

% customisation %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\definecolor{duckblue}{RGB}{0,70,140}
\definecolor{marmotred}{RGB}{140,20,40}
\addtokomafont{sectioning}{\color{teal}}
\addtokomafont{date}{\normalsize}
\addtokomafont{author}{\normalsize}
\setlength{\footnotemargin}{0.7em}

% from https://tex.stackexchange.com/a/147848
\def\beginlstdelim#1#2#3%
{%
    \def\endlstdelim{#2\egroup}%
    \ttfamily#1\bgroup\color{#3}\aftergroup\endlstdelim%
}

\lstdefinestyle{jigsawstyle}{%
	language={[latex]TeX},
	tabsize=2,
	breaklines,
	basicstyle=\footnotesize\ttfamily,
	commentstyle={\color{teal}\slshape}, 
	columns=fullflexible,
	texcsstyle=*\color{duckblue}\bfseries,
	keywordstyle=\color{red!60!black}\bfseries,
	morekeywords={tikzpicture,scope},
	moretexcs={path,node,draw,clip,pic,includegraphics,color,piece,tile,jigsaw},
	delim ={[s][\ttfamily\color{green!50!black}]{$}{$}},
	moredelim=[is][\footnotesize\ttfamily\color{orange!70!black}]{|}{|},
	moredelim={[s][\color{gray}]{<}{>}},
%	moredelim = **[is][\beginlstdelim{\{}{\}}{orange!70!black}]{\{}{\}},
%	moredelim = **[is][\beginlstdelim{[}{]}{orange!70!black}]{[}{]},
}

\tcbset{%
	colframe=teal,
	arc=2mm,
	fonttitle=\bfseries,
	sidebyside,
	listing options={style=jigsawstyle},
	center lower,
	righthand width=5.7cm,
	bottom=0pt, 
	top=0pt,
	sidebyside gap=10pt
}

\lstset{style=jigsawstyle}

% meta %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\title{The jigsaw package}
\subtitle{Drawing jigsaw pieces in \TikZ}
\author{%
	\texorpdfstring{
		\begin{tikzpicture}
			 \piece[lightgray!70!white]{1}{-1}{1}{-1}
		\end{tikzpicture}\\[0.8em]		
		\texttt{samcarter}\\
		\url{https://github.com/samcarter/jigsaw}\\
		\url{https://www.ctan.org/pkg/jigsaw}
	}{samcarter}}
\date{Version v0.4 \textendash{} 2023/02/21}

\begin{document}
\maketitle

\section{Introduction}
\label{intro}

The jigsaw package allows to draw adjustable jigsaw pieces in \TikZ, to combine them and even to automatically create complete jigsaws. It is based on the TeX.Stackexchange answers \url{https://tex.stackexchange.com/a/446296/36296}.

The package is included in both \texlive and \miktex and available from \CTAN (\url{https://ctan.org/pkg/jigsaw}). The development version of this package is located at \url{github.com/samcarter/jigsaw}. If you have any problems, ideas or other feedback, please make constructive use of its bug tracker.

Copyright \raisebox{0.2em}{\tiny\fontfamily{cmr}\selectfont\textcopyright} \texttt{samcarter}. Permission is granted to copy, distribute and\slash or modify this software under the terms of the LaTeX project public licence, version 1.3c or later \url{http://www.latex-project.org/lppl.txt}.

\section{Usage}

An individual jigsaw piece can be drawn with

\begin{tcolorbox}[title={Jigsaw piece}]
\begin{lstlisting}
\piece{<bottom>}{<right>}{<top>}{<left>}
\end{lstlisting}
\tcblower
\begin{tikzpicture}
	 \piece{1}{-1}{1}{1}
\end{tikzpicture}
\end{tcolorbox}

wherein arguments specify for each side if it should be a tab (-1), a straight line (0) or a slot (1). The following example will produce a jigsaw piece with one tab sticking out, one straight boarder and two slots:

\begin{tcblisting}{title={Jigsaw piece}}
\begin{tikzpicture}
	 \piece{1}{-1}{0}{1}
\end{tikzpicture}
\end{tcblisting}

With an optional argument, a fill colour can be passed to the piece:

\begin{tcblisting}{title={Filled piece}}
\begin{tikzpicture}
	 \piece[teal]{-1}{1}{-1}{1}
\end{tikzpicture}
\end{tcblisting}

Or to change the line colour:

\begin{tcblisting}{title={Coloured piece}}
\begin{tikzpicture}
	\color{teal}\piece{-1}{-1}{1}{1}
\end{tikzpicture}
\end{tcblisting}

The piece shape is also available as \TikZ \verb|pic|:

\begin{tcblisting}{title={\texttt{pic}}}
\begin{tikzpicture}
	\path (2,-3) pic[
    fill=lightgray, draw=teal, ultra thick, 
    scale=2, pic text={Some Text},
    pic text options={text=violet}
  ]{piece={1}{-1}{1}{0}};
\end{tikzpicture}
\end{tcblisting}

Using the \TikZ \verb|pic| allows to apply various \TikZ option like \verb|scale| or add text in the centre of the piece via \verb|pic text={...}|.

The shapes of the jigsaw pieces are designed to seamlessly fit into each other which allows to produce tile patters in various ways:

\begin{tcblisting}{title={Manual tile pattern}}
\begin{tikzpicture}
\begin{scope}
    \piece[teal]{1}{1}{0}{0}
\end{scope}
\begin{scope}[xshift=1cm]
    \piece[lightgray]{1}{0}{0}{-1}
\end{scope}
\begin{scope}[yshift=-1cm]
    \piece[lightgray]{0}{-1}{-1}{0}
\end{scope}
\begin{scope}[xshift=1cm,yshift=-1cm]
    \piece[teal]{0}{0}{-1}{1}
\end{scope}
\end{tikzpicture}
\end{tcblisting}

\begin{tcblisting}{title={Manual pattern using \texttt{\textbackslash pic}}}
\begin{tikzpicture}
\pic at (0,1) [fill=lightgray,draw]
  {piece={1}{1}{0}{0}};
\pic at (1,1) [fill=teal]
  {piece={1}{0}{0}{-1}};  
\pic at (0,0) [fill=teal]
  {piece={0}{-1}{-1}{0}};  
\pic at (1,0) [fill=lightgray,draw]
  {piece={0}{0}{-1}{1}};     
\end{tikzpicture}
\end{tcblisting}

\begin{tcblisting}{title={Manual pattern using Ti\emph{k}Z matrix}}
% \usetikzlibrary{matrix}
\begin{tikzpicture}
\matrix [nodes=draw]{
\pic [fill=lightgray]{piece={-1}{1}{0}{0}};&
\pic [fill=teal]{piece={1}{0}{0}{-1}}; \\
\pic [fill=teal]{piece={0}{-1}{1}{0}}; &
\pic [fill=lightgray]{piece={0}{0}{-1}{1}};\\
};
\end{tikzpicture}
\end{tcblisting}

Manually position each jigsaw piece at the correct position can be tedious, therefore the command \lstinline|\tile[<colour>]{<bottom>}{<right>}{<top>}{<left>}| was added. It can be used outside of of the \lstinline|tikzpicture| environment to place the pieces besides each other like normal letters in a text. Line breaks have to be added at the appropriate positions and one has to be careful not to introduce additional spaces between the jigsaw pieces from unprotected line endings.

\begin{tcblisting}{title={The tile command}}
\tile[violet]{1}{1}{0}{0}%
\tile[lightgray]{1}{-1}{0}{-1}%
\tile[teal]{1}{0}{0}{1}

\tile[teal]{1}{-1}{-1}{0}%
\tile[violet]{1}{-1}{-1}{1}%
\tile[lightgray]{-1}{0}{-1}{1}

\tile[lightgray]{0}{-1}{-1}{0}%
\tile[teal]{0}{-1}{-1}{1}%
\tile[violet]{0}{0}{1}{1}
\end{tcblisting}

Finally there is also the possibility to automatically generate complete jigsaw puzzles using the command \lstinline|\jigsaw{<x>}{<y>}|, with \lstinline|<x>| and \lstinline|<y>| the number of rows and columns, respectively.

\begin{tcblisting}{title={Automatic jigsaw generation}}
\begin{tikzpicture}
\jigsaw{6}{4}
\end{tikzpicture}
\end{tcblisting}

This automatically generated jigsaw can also be overlaid on a picture:

\begin{tcblisting}{title={Overlaid image}}
\begin{tikzpicture}
\clip (0,0) rectangle (6,4);
\node at (3,2) {%
  \includegraphics[width=6cm,height=4cm]{example-image-duck}%
};
\jigsaw{6}{4}
\end{tikzpicture}
\end{tcblisting}

\end{document}