Debian Codegraph @

texmf-dist/doc/latex/polyomino/polyomino.tex

raw
1 %% polyomino.tex
2 %% Copyright 2024-2025 Matthias Floré
3 %
4 % This work may be distributed and/or modified under the
5 % conditions of the LaTeX Project Public License, either version 1.3c
6 % of this license or (at your option) any later version.
7 % The latest version of this license is in
8 % http://www.latex-project.org/lppl.txt
9 % and version 1.3c or later is part of all distributions of LaTeX
10 % version 2005/12/01 or later.
11 %
12 % This work has the LPPL maintenance status `maintained'.
13 %
14 % The Current Maintainer of this work is Matthias Floré.
15 %
16 % This work consists of the files polyomino.pdf, polyomino.sty,
17 % polyomino.tex and README.md.
18 \documentclass[a4paper,english,dvipsnames]{ltxdoc}
19 \usepackage[english]{babel}
20 \usepackage[a4paper,left=2.25cm,right=2.25cm,top=2.5cm,bottom=2.5cm,nohead]{geometry}
21 \usepackage{parskip}
22 \usepackage{mathtools}
23 \usepackage{amssymb}
24 \allowdisplaybreaks
25 \usepackage{pdflscape}
26 \usepackage{polyomino}
27 \input{pgfmanual-en-macros.tex}
28 \usepackage{codehigh}
29 \usepackage{fancyhdr}
30 \pagestyle{fancy}
31 \renewcommand{\headrulewidth}{0pt}
32 \fancyhead{}
33 \ExplSyntaxOn
34 \NewExpandableDocumentCommand \repeatnumber {}
35 { \prg_replicate:nn { \thepage } { * } }
36 \ExplSyntaxOff
37 \fancyfoot[C]{\IfRefUndefinedExpandable{Thesourcecode}{}{\begin{tikzpicture}[scale=0.9]
38 \polyomino[
39 grid,
40 p={*}{style={teal,draw=black}}
41 ]{\repeatnumber}
42 \end{tikzpicture}}}
43 \usepackage[nottoc]{tocbibind}
44 \usepackage{imakeidx}
45 \makeindex[program=makeindex,columns=2,intoc=true]
46 \indexsetup{othercode={\thispagestyle{fancy}}}
47 \AtEndPreamble{\hypersetup{%
48 linktoc=all,
49 pdfstartview=FitH,
50 colorlinks=true,
51 linkcolor=Mahogany,
52 citecolor=ForestGreen,
53 urlcolor=MidnightBlue,
54 bookmarksnumbered=true,
55 pdftitle=The polyomino package,
56 pdfauthor=Matthias Floré,
57 pdfsubject=Manual,
58 pdfkeywords={polyomino,puzzle}}}
59 \setcounter{tocdepth}{2}
60 \setcounter{secnumdepth}{2}
61 \title{The \texttt{polyomino} package\\[12pt]\large Polyominoes using \tikzname{} and \LaTeX3}
62 \author{Matthias Floré\\\href{mailto:[email protected]}{\texttt{[email protected]}}}
63 \date{Version 2.0 (2025/07/24)}%\\[12pt]
64 \begin{document}
65 \maketitle
66 \thispagestyle{fancy}
67 \begin{abstract}
68 \noindent This package is based on the package |tikz| (see \cite{TtTaPGFp}) and can be used to draw polyominoes. It is possible to define custom styles, pics and grids.% This is the manual for version .
69 \end{abstract}
70 \tableofcontents
71 \section{Usage}
72 The package |polyomino| can be used by putting the following in the preamble.
73 \begin{codeexample}[code only]
74 \usepackage{polyomino}
75 \end{codeexample}
76 The package |polyomino| loads the package |tikz|.
77 \section{The command \textbackslash polyomino}
78 \begin{command}{\polyomino\opt{\oarg{options}}\marg{polyomino specification}}
79 This command can be placed inside a |tikzpicture| environment. The \meta{polyomino specification} is a token list. Spaces in this list are ignored. With the initial settings, a |,| starts a new row. Otherwise each element in this list corresponds to a cell. An element can consist of multiple characters by surrounding it with braces. The \meta{options} can be given with the keys described in Section \ref{Keys}.
80 \begin{codeexample}[width=8cm]
81 \pgfkeys{
82 /polyomino,
83 p={F}{style={blue,draw=black,ultra thick}},
84 p={I}{style={brown,draw=black,ultra thick}},
85 p={L}{style={cyan,draw=black,ultra thick}},
86 p={N}{style={gray,draw=black,ultra thick}},
87 p={P}{style={lime,draw=black,ultra thick}},
88 p={T}{style={magenta,draw=black,ultra thick}},
89 p={U}{style={olive,draw=black,ultra thick}},
90 p={V}{style={orange,draw=black,ultra thick}},
91 p={W}{style={pink,draw=black,ultra thick}},
92 p={X}{style={purple,draw=black,ultra thick}},
93 p={Y}{style={red,draw=black,ultra thick}},
94 p={Z}{style={teal,draw=black,ultra thick}}
95 }
96 \begin{tikzpicture}
97 \polyomino[
98 grid
99 ]{
100 UUUVVV,
101 UXUZZV,
102 XXXFZV,
103 IXFFZZ,
104 ILLFFT,
105 ILNTTT,
106 ILNWWT,
107 ILNNWW,
108 PPPNYW,
109 PPYYYY
110 }
111 \end{tikzpicture}
112 \end{codeexample}
113 The algorithm constructs the border of each polyomino. It does not consider holes determined by empty cells. Although it does detect a cell inside a polyomino which has a different style. This is illustrated in the example below.
114 \begin{codeexample}[width=10cm]
115 \begin{tikzpicture}[scale=0.8]
116 \polyomino[
117 p={a}{style={gray,draw=black,thick}}
118 ]{
119 aaaaa,
120 a.a.a,
121 aaaaa
122 }
123 \polyomino[
124 at={(0,-4)},
125 p={a}{style={gray,draw=black,thick}},
126 p={*}{style={white,draw=black,thick}}
127 ]{
128 aaaaa,
129 a*a*a,
130 aaaaa
131 }
132 \end{tikzpicture}
133 \end{codeexample}
134 \end{command}
135 \section{Keys}\label{Keys}
136 The keys in this Section can be given as \meta{options} to the command |\polyomino|.
137
138 There are two key families: |/polyomino| and |/polyomino/p_2|. The key family |/polyomino| is intended for usage in documents whereas |/polyomino/p_2| is not. In the key family |/polyomino|, also keys from the key family |/polyomino/p_2| will be looked up. The second argument from the key |p| only accepts keys from the key family |/polyomino/p_2|.
139 \begin{key}{/polyomino/at=\marg{point} (initially (0,0))}
140 This key defines the bottom left coordinate of the polyomino.
141 \end{key}
142 \begin{key}{/polyomino/p\_2/connected}
143 This key sets the |pic| type (which is activated by the key |pic|) to false. This is the initial setting.
144 \end{key}
145 \begin{key}{/polyomino/p\_2/discrete}
146 This key sets the |pic| type (which is activated by the key |pic|) to true.
147 \end{key}
148 \begin{key}{/polyomino/empty cell=\marg{token list} (initially .)}
149 A cell corresponding to the \meta{token list} in the \meta{polyomino specification} will be left empty.
150
151 A cell corresponding to the empty token list will always be left empty.
152 \end{key}
153 \begin{key}{/polyomino/grid=\opt{\meta{boolean}} (default true, initially false)}
154 If true then a grid is drawn. The grid does not apply to borders of polyominoes. The style of this grid is determined by the key |grid style|. A grid does not apply to a cell with a |pic|.
155 \end{key}
156 \begin{stylekey}{/polyomino/grid style=\marg{options} (initially \normalfont empty)}
157 This key determines the style of the grid.
158 \begin{codeexample}[width=6.5cm]
159 \begin{tikzpicture}[rotate=90]
160 \polyomino[
161 grid,
162 grid style={gray,dash pattern=on 3mm off 4mm on 3mm off 0mm},
163 p={L}{style={darkgray,draw=black}},
164 p={P}{style={green,draw=black}},
165 p={T}{style={violet,draw=black}},
166 p={V}{style={yellow,draw=black}}
167 ]{
168 LTVVV,
169 LTTTV,
170 LTPPV,
171 LLPPP
172 }
173 \end{tikzpicture}
174 \end{codeexample}
175 \end{stylekey}
176 \begin{stylekey}{/polyomino/p\_2/p=\marg{name}\marg{options} (initially \normalfont empty)}
177 This key determines the style of the polyomino with \meta{name} in the \meta{polyomino specification}.
178
179 The \meta{options} only accept keys from the key family |/polyomino/p_2|.
180
181 In the example below, the polyominoes have the same shape but are differentiated by using different names.
182 \begin{codeexample}[width=10cm]
183 \begin{tikzpicture}
184 \pgfkeys{
185 /polyomino,
186 p={a}{},
187 p={b}{},
188 style={fill=none,draw}
189 }
190 \def\example{
191 aa,
192 ab,
193 ab,
194 bb
195 }
196 \polyomino{\example}
197 \polyomino[
198 at={(2,0)}
199 ]{\example}
200 \end{tikzpicture}
201 \end{codeexample}
202 \end{stylekey}
203 \begin{key}{/polyomino/p\_2/pic=\marg{code}}
204 The \meta{code} defines the |pic| which is used for each cell of the polyomino.
205
206 A grid does not apply to a cell with a |pic|.
207 \begin{codeexample}[width=7cm]
208 \begin{tikzpicture}
209 \polyomino[
210 empty cell=*,
211 grid,
212 p={a}{style={red,draw=black}},
213 p={b}{style={blue,draw=black}},
214 p={c}{style={orange,draw=black}},
215 p={circle}{pic={\fill[green] (0,0) circle[radius=0.4];}},
216 row sep=;
217 ]{
218 {} * * b {} c ;
219 a a b b {circle} c ;
220 {circle} a a b c c
221 }
222 \end{tikzpicture}
223 \end{codeexample}
224 \begin{codeexample}[width=5cm]
225 \begin{tikzpicture}
226 \polyomino[
227 p={circle}{
228 pic={\path[pic actions] (0,0) circle[radius=0.45];},
229 style={right color=cyan,left color=red,draw,dashed}
230 },
231 p={L}{
232 pic={
233 \fill[yellow!80!black] (-0.5,-0.5) rectangle +(1,1);
234 \fill[yellow!50,rounded corners] (-0.4,-0.4) rectangle +(0.8,0.8);
235 }
236 },
237 p={square}{
238 pic={\path[pic actions] (-0.45,-0.45) rectangle +(0.9,0.9);},
239 style={fill=magenta,draw,rounded corners}
240 }
241 ]{
242 L {circle} {square} {square} ,
243 L {circle} {circle} {square} ,
244 L L {circle} {circle}
245 }
246 \end{tikzpicture}
247 \end{codeexample}
248 \end{key}
249 \begin{key}{/polyomino/row sep=\marg{token list} (initially ,)}
250 The \meta{token list} in the \meta{polyomino specification} will start a new row.
251 \end{key}
252 \begin{stylekey}{/polyomino/p\_2/style=\marg{options} (initially \normalfont empty)}
253 This key determines the style of the polyomino.
254 \end{stylekey}
255 \section{Version history}
256 \begin{itemize}
257 \item[] \textbf{Version 1.0 (2024/08/01)} First version.
258 \item[] \textbf{Version 2.0 (2025/07/24)} Updated the documentation.
259 \end{itemize}
260 \begin{thebibliography}{9}
261 \bibitem{TtTaPGFp}
262 Till Tantau,
263 \emph{The \tikzname{} and {\upshape\pgfname} Packages},
264 Manual for version 3.1.10,
265 \url{https://ctan.org/pkg/pgf},
266 2023.
267 \end{thebibliography}
268 \clearpage
269 \currentpdfbookmark{\indexname}{\indexname}
270 \printindex
271 \newgeometry{left=2.25cm,right=2.25cm,top=2.25cm,bottom=2.25cm}
272 \pagestyle{plain}
273 \appendix
274 \begin{landscape}
275 \section{The source code}\label{Thesourcecode}
276 \dochighinput[language=latex/latex3]{polyomino.sty}
277 \end{landscape}
278 \end{document}