Debian Codegraph @

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

raw
1 % File: hawkdraw-doc.tex
2 % Copyright 2026 Jasper Habicht (mail(at)jasperhabicht.de).
3 %
4 % This work may be distributed and/or modified under the
5 % conditions of the LaTeX Project Public License version 1.3c,
6 % available at http://www.latex-project.org/lppl/.
7 %
8 % This file is part of the `hawkdraw' package (The Work in LPPL)
9 % and all files in that bundle must be distributed together.
10 %
11 % This work has the LPPL maintenance status `maintained'.
12 %
13 \DocumentMetadata{}
14 \documentclass[a4paper]{article}
15 \def\hawkdrawfileversion{0.0.7}
16 \def\hawkdrawfiledate{25 May 2026}
17
18 \usepackage[T1]{fontenc}
19 \usepackage{Alegreya}
20 \usepackage{AlegreyaSans}
21 \usepackage{FiraMono}
22
23 \usepackage{hawkdraw}
24
25 \usepackage{geometry, longtable, booktabs, siunitx, tcolorbox, hyperref}
26 \geometry{margin=25mm, left=45mm}
27 \DeclareSIUnit{\point}{pt}
28 \urlstyle{same}
29
30 \usepackage{fancyhdr}
31 \pagestyle{fancy}
32 \fancyhf{}
33 \renewcommand{\headrulewidth}{0pt}
34 \fancyfoot[R]{\thepage}
35
36 \ExplSyntaxOn
37 \NewDocumentCommand{\fnstars}{m}{
38 \int_step_inline:nn { \value{#1} } { * }
39 }
40 \ExplSyntaxOff
41
42 \linespread{1.1}\selectfont
43 \addtolength{\skip\footins}{1em plus 5pt}
44 \makeatletter
45 \renewcommand*{\thefootnote}{\fnstars{footnote}}
46 \renewcommand{\@makefnmark}{\normalfont\@thefnmark}
47 \renewcommand{\@makefntext}[1]{%
48 \noindent\hbox to 1em{\normalfont\@thefnmark\hss}~#1%
49 }
50 \makeatother
51
52 \tcbuselibrary{skins,listings}
53 \lstdefinestyle{hawkdrawdocmacro}{
54 basicstyle=\small\ttfamily,
55 literate=*{<}{{{\color{black!50}\guilsinglleft}}}1
56 {>}{{{\color{black!50}\guilsinglright}}}1,
57 keywords={},
58 moredelim=[is][\bfseries]{|}{|},
59 moredelim=[is][\bfseries\itshape]{?}{?},
60 moredelim=[is][\color{black!50}]{!}{!},
61 }
62 \lstdefinestyle{hawkdrawdocmacroalt}{
63 basicstyle=\small\ttfamily,
64 literate=*{<}{{{\color{black!50}\guilsinglleft}}}1
65 {>}{{{\color{black!50}\guilsinglright}}}1,
66 keywords={},
67 moredelim=[is][\bfseries]{!}{!},
68 }
69 \lstdefinestyle{hawkdrawdoccodeexample}{
70 basicstyle=\small\ttfamily,
71 keywords={},
72 }
73
74 \hypersetup{colorlinks}
75
76 \ExplSyntaxOn
77 \int_new:N \l_hawkdraw_doc_change_int
78 \NewDocumentCommand{\changes}{ m m m }{
79 \int_incr:N \l_hawkdraw_doc_change_int
80 \prop_new:c { l_hawkdraw_doc_change_
81 \int_to_roman:n { \l_hawkdraw_doc_change_int } _prop }
82 \prop_put:cnn { l_hawkdraw_doc_change_
83 \int_to_roman:n { \l_hawkdraw_doc_change_int } _prop } { version } {#1}
84 \prop_put:cnn { l_hawkdraw_doc_change_
85 \int_to_roman:n { \l_hawkdraw_doc_change_int } _prop } { date } {#2}
86 \prop_put:cnn { l_hawkdraw_doc_change_
87 \int_to_roman:n { \l_hawkdraw_doc_change_int } _prop } { changes } {#3}
88 }
89 \NewDocumentCommand{\printchanges}{ }{
90 \section{Changes}
91 \begin{description}
92 \setlength\itemsep{0pt}
93 \int_step_inline:nn { \l_hawkdraw_doc_change_int } {
94 \item[
95 \prop_item:cn { l_hawkdraw_doc_change_
96 \int_to_roman:n { ##1 } _prop } { version } ~
97 \normalfont{ (
98 \prop_item:cn { l_hawkdraw_doc_change_
99 \int_to_roman:n { ##1 } _prop } { date }
100 ) }
101 ]
102 \prop_item:cn { l_hawkdraw_doc_change_
103 \int_to_roman:n { ##1 } _prop } { changes }
104 }
105 \end{description}
106 }
107
108 \tl_new:N \l_hawkdraw_doc_doctitle_tl
109 \NewExpandableDocumentCommand{\makedoctitle}{ o m o m m o m }{
110 \hypersetup{
111 pdfauthor={#5},
112 pdftitle={\IfValueTF{#1}{#1}{#2}},
113 pdfsubject={\IfValueTF{#3}{#3}{#4}}
114 }
115 \tl_set:Nn \l_hawkdraw_doc_doctitle_tl {
116 \group_begin:
117 \tcbset{
118 title ~ style ~ hook/.style={
119 boxrule=2pt,
120 fontupper=\huge\ttfamily
121 }
122 }
123 \setlength{\parindent}{0pt}\sffamily
124 \Huge{\bfseries #2}\par\bigskip
125 \Large #4\par\bigskip
126 \large #5
127 \IfValueT{#6}{
128 \,\footnote{#6}\par\bigskip
129 }
130 #7\par\bigskip
131 \rule{\textwidth}{.08em}
132 \group_end:
133 }
134 }
135
136 \NewExpandableDocumentCommand{\printdoctitle}{ }{
137 \tl_use:N \l_hawkdraw_doc_doctitle_tl
138 }
139 \ExplSyntaxOff
140
141 \NewDocumentCommand{\expandablestarcode}{ O{0,0} }{
142 \fill[black!50, shift={([xshift={-10pt}, yshift={-10pt-0.5em}]#1)}]
143 (90:3.75pt)
144 \foreach \i in {1,...,4} {
145 -- ({90+360/5*\i*2}:3.75pt)
146 } -- cycle;
147 }
148
149 \NewDocumentCommand{\expandablestar}{}{
150 \tikz{\expandablestarcode}
151 }
152
153 \NewDocumentCommand{\warning}{}{%
154 \begin{tikzpicture}[overlay, baseline={(w.base)}]
155 \node[circle, fill, black!25!red!10, text=black!25!red, outer sep=0pt]
156 (w) at (-3em,0pt) {\bfseries !};
157 \fill[black!25!red!10]
158 (w.east) |- (w.south) -- cycle;
159 \end{tikzpicture}%
160 }
161
162 \tcbset{
163 size=small,
164 arc=2.5pt,
165 outer arc=2.5pt,
166 colframe=black!10,
167 colback=black!10,
168 title style hook/.style={},
169 }
170
171 \NewTCBListing{macrodef}{ s o O{} }{
172 listing only,
173 listing style={hawkdrawdocmacro},
174 grow to left by=2cm,
175 boxrule=0pt,
176 after={\par\smallskip\noindent},
177 enhanced,
178 IfValueT={#2}{
179 hypertarget=#2
180 },
181 IfBooleanT={#1}{
182 overlay={
183 \expandablestarcode[frame.north east]
184 }
185 },
186 #3
187 }
188
189 \NewTCBListing{codeexample}{ }{
190 listing only,
191 listing style={hawkdrawdoccodeexample},
192 after={\par\smallskip\noindent}
193 }
194
195 \NewTCBListing{codeexamplecolumns}{ }{
196 text side listing,
197 lefthand width=2.5cm,
198 listing style={hawkdrawdoccodeexample},
199 after={\par\smallskip\noindent}
200 }
201
202 \NewTCBListing{macrodeprecated}{ s }{
203 listing only,
204 listing style={hawkdrawdocmacro},
205 boxrule=0pt,
206 width={0.5\linewidth-2.5pt},
207 box align=top,
208 after=\hfill,
209 colframe=black!25!red!10,
210 colback=black!25!red!10,
211 enhanced,
212 IfBooleanT={#1}{
213 overlay={
214 \fill[black!25!red!10]
215 ([yshift={5pt-1.5em}]frame.north east)
216 -- ++(5pt,-5pt) -- ++(-5pt,-5pt)
217 -- cycle;
218 }
219 }
220 }
221
222 \NewTCBListing{macroreplacement}{ }{
223 listing only,
224 listing style={hawkdrawdocmacro},
225 boxrule=0pt,
226 width={0.5\linewidth-2.5pt},
227 box align=top,
228 before={},
229 colframe=black!25!green!10,
230 colback=black!25!green!10
231 }
232
233 \NewTotalTCBox{\macro}{ O{} v }{
234 verbatim,
235 size=tight,
236 arc=1pt,
237 outer arc=1pt,
238 top=0.5pt,
239 bottom=0.5pt,
240 left=2pt,
241 right=2pt,
242 boxrule=0pt,
243 colframe=black!10,
244 colback=black!10,
245 fontupper=\small\ttfamily,
246 #1
247 }{\MathCollectFalse\vphantom{/g}\lstinline^#2^}
248
249 \NewTotalTCBox{\titlemacro}{ s O{} m }{
250 verbatim,
251 size=tight,
252 arc=1pt,
253 outer arc=1pt,
254 top=0.5pt,
255 bottom=0.5pt,
256 left=2pt,
257 right=2pt,
258 boxrule=0pt,
259 colframe=black!10,
260 colback=black!10,
261 fontupper=\small\ttfamily,
262 title style hook,
263 #2
264 }{\vphantom{/g}\IfBooleanT{#1}{\textbackslash}#3}
265
266 \usepackage{hawkdraw}
267
268 \makedoctitle
269 [The hawkdraw package]
270 {The \titlemacro{hawkdraw} package}
271 {A LaTeX package to generate vector graphic output based on the l3draw package and related LaTeX3 modules using a simple syntax}
272 {Jasper Habicht}[E-mail: \href{mailto:[email protected]}{[email protected]}. I am grateful to Joseph Wright, Max Chernoff and Clea F. Rees who helped me improving the code. Victor, the drawing hawk: \textcopyright{} 2026 Hannah Klöber.]
273 {Version \hawkdrawfileversion, released on \hawkdrawfiledate}
274
275 \changes{v0.0.5}{2026/05/18}{First public alpha release.}
276 \changes{v0.0.6}{2026/05/20}{Splitting up code into modules.}
277 \changes{v0.0.7}{2026/05/25}{Adding patterns; adding \titlemacro{at path part} option.}
278
279 \begin{document}
280 \vspace*{-1cm}
281 \noindent\hspace*{-3.5mm}\includegraphics[width=5cm]{victor/victor.pdf}
282
283 \printdoctitle
284
285 \bigskip
286
287 \section{Introduction}
288
289 The \macro{hawkdraw} package allows the user to use a simple syntax similar to Ti\emph{k}Z to generate vector graphic output based on \macro{l3draw} and related LaTeX3 modules such as \macro{l3fp} which provides very precise calculations. The syntax is meant to be simple and flexible but also coherent and logical with the aim of allowing the user to quickly draw graphics. The package name relates to the quickness and agility of hawks and the preciseness of their eyesight.
290
291 The package intends to define a set of user-level commands that can be used for drawing simple graphics. It does not aim to be a substitute for the Ti\emph{k}Z package or to offer a similar scope of application.
292
293 The package is currently still in an experimental stage. The code may be subject to fundamental and frequent changes. The author is grateful for reporting any bugs via GitHub at \url{https://github.com/jasperhabicht/hawkdraw/issues}. A site for asking questions about the package and for suggestions for improvement is available at \url{https://github.com/jasperhabicht/hawkdraw/discussions}.
294
295 \section{Loading the package}
296
297 To install the package, copy the package file \macro{hawkdraw.sty} into the working directory or into the \macro{texmf} directory. After the package has been installed, the \macro{hawkdraw} package is loaded by calling \macro{\usepackage{hawkdraw}} in the preamble of the document.
298
299 The package can be used with PDFLaTeX, LuaLaTeX or XeLaTeX. The package does not load any dependencies, but it needs a LaTeX kernel of 1 June 2022 or newer. It is recommended to use the package with an up-to-date TeX distribution.
300
301 Note that the underlying code of the \macro{l3draw} package is experimental as well and hence might as well change possibly breaking the functionality of this package.
302
303 \section{Main user environment}
304
305 The package has only very few main user commands. Among these, the \macro{hawkdraw} environment is the most important as it is used to define a drawing and most other commands are only defined inside this environment.
306
307 Similar to Ti\emph{k}Z, the \macro{hawkdraw} package makes use of key-value pairs to set options for commands. Some options are available for almost all commands, other have very specific uses. In the descriptions of the options, this manual states which data type the relevant option assumes. The following data types exist:
308
309 \begin{longtable}{ @{} p{2.5cm} p{\dimexpr\textwidth-\tabcolsep-2.5cm} @{} }
310 \toprule
311 \textbf{Data type} & \textbf{Explanation} \\
312 \midrule
313 \macro{boolean} & A boolean only allows the values \macro{true} or \macro{false}. If not stated otherwise, setting the key without a value is equivalent with setting the key to \macro{true}. \\
314 \macro{string} & A string is a concatenation of letters or numbers of any length. Typically, strings do not contain symbols. For example, strings are used for names of points, frames of nodes, patterns or arrow tips. \\
315 \macro{float} & A floating-point number is a number without or with unit that uses a colon as decimal separator. \\
316 \macro{tuple} & A tuple consists of two floating-point numbers without or with unit that are separated by a comma. A tuple may be enclosed by parenthesis. \\
317 \macro{dimension} & A dimension or length is a typical TeX length consisting of a floating point number and a length unit. \\
318 \macro{clist} & A comma-separated list is a list of strings that are separated by commas. Such a list can cosnist of no or only one item as well. If the relevant list can only have a maximum number of items, this is stated in the description of the relevant key. \\
319 \macro{options} & A key-value list consists of comma separated entities of keys that may be followed by an equals sign and a value. A value can be another key-value list. \\
320 \macro{color} & This means a color definition as specified by the \macro{l3color} module. Note that colors defined by the \macro{xcolor} package have no effect when using the \macro{hawkdraw} package. \\
321 \emph{none} & Some keys do not accept any data type as they are only executing some function. \\
322 \bottomrule
323 \end{longtable}
324
325 \begin{macrodef}
326 \\\begin{|hawkdraw|}[<options>]
327 \end{|hawkdraw|}
328 \end{macrodef}
329 The \macro{hawkdraw} environment is the main environment for drawing. It defines most other commands described in the following sections. The following options can be set for the \macro{hawkdraw} environment:
330
331 \begin{macrodef}
332 !instance/!|baseline|={<dimension>}
333 \end{macrodef}
334 The option \macro{baseline} sets the baseline for the environment as dimension. The default baseline is typically the bottom of the the bounding box of the drawing.
335
336 \begin{macrodef}
337 !instance/!|layers|={<clist>}
338 \end{macrodef}
339 The option \macro{layers} sets the layers for the environment as a comma-separated list. The layer \macro{main} must always be present and is the default layer. Layers are drawn in the order they are defined (see \hyperlink{sec:scopes}{below}).
340
341 \begin{macrodef}
342 !instance/!|overlay|={<boolean>}
343 \end{macrodef}
344 The option \macro{overlay} sets the environment to have a zero-sized bounding box.
345
346 \begin{codeexamplecolumns}
347 foo
348 \begin{hawkdraw}[overlay, baseline={0.5ex}]
349 \stroke[stroke color={blue}]
350 (0cm,0cm) circle[radius={0.5cm}] ;
351 \end{hawkdraw}
352 bar
353 \end{codeexamplecolumns}
354
355 \section{Scopes and layers}\label{sec:scopes}
356
357 \begin{macrodef}
358 \\\begin{|scope|}[<options>]
359 \end{|scope|}
360 \end{macrodef}
361 The \macro{scope} environment is only available inside the \macro{hawkdraw} environment. It can be used to create scopes for the localization of path states, style settings and clipping regions.
362
363 \begin{codeexamplecolumns}
364 \begin{hawkdraw}[fill color={blue}]
365 \fill (0cm,0cm) circle[radius={5pt}] ;
366 \begin{scope}[fill color={black}]
367 \fill (1cm,0cm) circle[radius={5pt}] ;
368 \end{scope}
369 \fill (2cm,0cm) circle[radius={5pt}] ;
370 \end{hawkdraw}
371 \end{codeexamplecolumns}
372
373 \begin{macrodef}
374 !scope/!|layer|={<string>}
375 \end{macrodef}
376 The option \macro{layer} sets the scope to be placed on the relevant layer. The layer must be defined beforehand using the \macro{layers} option.
377
378 \begin{codeexamplecolumns}
379 \begin{hawkdraw}[layers={background,main}]
380 \fill[fill color={blue}]
381 (0cm,0cm) circle[radius={0.5cm}] ;
382 \begin{scope}[layer={background}]
383 \fill (0.5cm,0cm) circle[radius={0.5cm}] ;
384 \end{scope}
385 \end{hawkdraw}
386 \end{codeexamplecolumns}
387
388 \section{Path syntax}
389
390 \subsection{Path command and options}
391
392 \begin{macrodef}
393 |\path| <path operations> ;
394 \end{macrodef}
395 The command \macro{\path} is used to to draw a path inside the \macro{hawkdraw} environment. The path is defined by a sequence of points and path construction operations. Each \macro{\path} command must end with a semicolon. The following operations can be used to construct the path:
396
397 \begin{macrodef}
398 |[|<options>|]|
399 \end{macrodef}
400 Options can be for the path using square brackets. The options are the same as for \macro{\hawkdrawset}. Options can be set multiple times for the same path after any point on the path. Some options (such as color options or transformations) will apply to the entire path and the last specified value will be used.
401
402 \subsection{Points on the path}
403
404 Generally, the package makes use of the \macro{l3fp} module of the LaTeX kernel. As such, it is possible to execute calculations on the fly to define the points. The basic form of a point is a tuple of two expressions resulting in a floating-point number where both expressions are separated by a comma.
405
406 It is advisable to enclose the two expressions of the tuple in curly braces in cases where complicated calculations should be executed in order to create a group to ensure proper evaluation and avoiding conflicts with parsing the coordinates, especially when using a syntax for polar points as described below.
407
408 \begin{macrodef}
409 |(|<float>|,|<float>|)|
410 \end{macrodef}
411 Points on the path can be defined using x and y parts as floating-point numbers. The first item in the tuple is the x-coordinate, and the second item is the y-coordinate.
412
413 Points are per default defined as tuples representing the x- and y-coordinate. If floating-point numbers without unit are used, points are assumed per default. If other units are used, these are converted into points internally. The below alternative representations of points are as well calculated into the default tuple representation:
414
415 \begin{macrodef}
416 |(|<float>|>|<float|)|
417 |(|<float|,|<float>|>|<float>|)|
418 \end{macrodef}
419 Points on the path can also be defined using radius and angle parts as floating-point numbers. The first item in the tuple is the radius and the second item is the angle. The first item can contain a comma to define two radii.
420
421
422 \begin{macrodef}
423 |(|<float>|:|<float>|)|
424 |(|<float>|:|<float>|,|<float>|)|
425 \end{macrodef}
426 Points on the path can also be defined using radius and angle parts as floating-point numbers in reversed order. The first item in the tuple is the angle, and the second item is the radius. The seocnd item can contain a comma to define two radii.
427
428 \begin{macrodef}[macro:point]
429 |(|<string>|)|
430 \end{macrodef}
431 Points on the path can finally be referenced using names as strings. Points on the path can be named by either using the \macro{point} or the \macro{node} operation with the given name set via the \macro{nname} option (see \hyperlink{operation:point}{below}).
432
433 \subsection{Path operations}
434
435 \begin{macrodef}
436 |--| (<point>)
437 \end{macrodef}
438 Using \macro{--} a line to the next point is drawn.
439
440 \begin{codeexamplecolumns}
441 \begin{hawkdraw}
442 \path[stroke] (0cm,0cm)
443 -- (2cm,1cm) ;
444 \end{hawkdraw}
445 \end{codeexamplecolumns}
446
447 \begin{macrodef}[][listing style={hawkdrawdocmacroalt}]
448 !|-! (<point>)
449 !-|! (<point>)
450 \end{macrodef}
451 Using \macro{|-} a vertical, then horizontal line to the next point is drawn. Using \macro{-|} a vertical, then horizontal line to the next point is drawn.
452
453 \begin{codeexamplecolumns}
454 \begin{hawkdraw}
455 \path[stroke] (0cm,0cm)
456 |- (2cm,1cm) ;
457 \end{hawkdraw}
458 \end{codeexamplecolumns}
459
460 \begin{codeexamplecolumns}
461 \begin{hawkdraw}
462 \path[stroke] (0cm,0cm)
463 -| (2cm,1cm) ;
464 \end{hawkdraw}
465 \end{codeexamplecolumns}
466
467 \begin{macrodef}
468 |..| (<control point>) |..| (<point>)
469 |..| (<control point>) |&| (<control point>) |..| (<point>)
470 \end{macrodef}
471 The above syntax draws a curve to the next point with a single control point or with two control points.
472
473 \begin{codeexamplecolumns}
474 \begin{hawkdraw}
475 \path[stroke] (0cm,0cm)
476 .. (1cm,1cm)
477 .. (2cm,1cm);
478 \end{hawkdraw}
479 \end{codeexamplecolumns}
480
481 \begin{codeexamplecolumns}
482 \begin{hawkdraw}
483 \path[stroke] (0cm,0cm)
484 .. (0cm,0.5cm) & (1cm,1cm)
485 .. (2cm,1cm);
486 \end{hawkdraw}
487 \end{codeexamplecolumns}
488
489 \begin{macrodef}
490 |!|
491 \end{macrodef}
492 Using \macro{!} the path is closed by drawing a line from the last point to the first point.
493
494 \begin{codeexamplecolumns}
495 \begin{hawkdraw}
496 \path[stroke] (0cm,0cm)
497 -- (2cm,1cm)
498 -- (0cm,1cm) ! ;
499 \end{hawkdraw}
500 \end{codeexamplecolumns}
501
502 \bigskip
503
504 The following path operations require at least one option to be set:
505
506 \begin{macrodef}
507 |circle|[<options>]
508 \end{macrodef}
509 Using the \macro{circle} operation, a circle is drawn with the current point as center.
510
511 \begin{macrodef}
512 !path/circle/!|radius|={<dimension>}
513 \end{macrodef}
514 The radius is specified as a dimension with the \macro{radius} option.
515
516 \begin{codeexamplecolumns}
517 \begin{hawkdraw}
518 \path[stroke] (0cm,0cm)
519 circle[radius={1cm}] ;
520 \end{hawkdraw}
521 \end{codeexamplecolumns}
522
523 \begin{macrodef}
524 |ellipse|[<options>]
525 \end{macrodef}
526 Using the \macro{ellipse} operation, an ellipse is drawn with the current point as center.
527
528 \begin{macrodef}
529 !path/ellipse/!|radius a|={<dimension>}
530 !path/ellipse/!|radius b|={<dimension>}
531 !path/ellipse/!|vector a|={<tuple>}
532 !path/ellipse/!|vector b|={<tuple>}
533 \end{macrodef}
534 The vectors of the ellipse are specified as tuples of dimensions with the \macro{vector a} and \macro{vector b} options. ALternatively, the options \macro{radius a} and \macro{radius b} can be used to define the radii in the x- and y-dimension.
535
536 \begin{codeexamplecolumns}
537 \begin{hawkdraw}
538 \path[stroke] (0cm,0cm)
539 ellipse[
540 radius a={0.5cm},
541 radius b={1cm}
542 ] ;
543 \end{hawkdraw}
544 \end{codeexamplecolumns}
545
546 \begin{codeexamplecolumns}
547 \begin{hawkdraw}
548 \path[stroke] (0cm,0cm)
549 ellipse[
550 vector a={(0.5cm,1cm)},
551 vector b={(0.75cm,0cm)}
552 ] ;
553 \end{hawkdraw}
554 \end{codeexamplecolumns}
555
556 \begin{macrodef}
557 |arc|[<options>]
558 \end{macrodef}
559 Using the \macro{arc} operation, an arc is drawn with the current point as origin.
560
561 \begin{macrodef}
562 !path/arc/!|vector a|={<tuple>}
563 !path/arc/!|vector b|={<tuple>}
564 !path/arc/!|radius a|={<dimension>}
565 !path/arc/!|radius b|={<dimension>}
566 !path/arc/!|angle start|={<float>}
567 !path/arc/!|angle end|={<float>}
568 !path/arc/!|angle delta|={<float>}
569 \end{macrodef}
570 The vectors of the arc are specified as tuples of dimensions with the \macro{vector a} and \macro{vector b} options. ALternatively, the options \macro{radius a} and \macro{radius b} can be used to define the radii in the x- and y-dimension. The angles are specified as dimensions with the \macro{start angle} and \macro{end angle} options. Instead of the \macro{angle end} option, the option \macro{angle delta} can be used.
571
572 \begin{codeexamplecolumns}
573 \begin{hawkdraw}
574 \path[stroke] (0cm,0cm)
575 arc[
576 radius={1cm},
577 angle start={45},
578 angle end={135}
579 ] ;
580 \end{hawkdraw}
581 \end{codeexamplecolumns}
582
583 \begin{codeexamplecolumns}
584 \begin{hawkdraw}
585 \path[stroke] (0cm,0cm)
586 arc[
587 radius a={0.5cm},
588 radius b={1cm},
589 angle start={45},
590 angle delta={90}
591 ] ;
592 \end{hawkdraw}
593 \end{codeexamplecolumns}
594
595 \begin{codeexamplecolumns}
596 \begin{hawkdraw}
597 \path[stroke] (0cm,0cm)
598 arc[
599 vector a={(0.5cm,1cm)},
600 vector b={(0.75cm,0cm)},
601 angle start={45},
602 angle end={135}
603 ] ;
604 \end{hawkdraw}
605 \end{codeexamplecolumns}
606
607 \begin{macrodef}
608 |rectangle|[<options>]
609 \end{macrodef}
610 Using the \macro{rectangle} operation, an rectangle with the current point as origin corner is drawn.
611
612 \begin{macrodef}
613 !path/rectangle/!|corner|={<tuple>}
614 !path/rectangle/!|relative|={<boolean>}
615 \end{macrodef}
616 The other corner of the rectangle is specified as a point (a tuple) with the \macro{corner} option. If the boolean option \macro{relative} is set, the corner point is interpreted as relative to the current point instead of absolute.
617
618 \begin{codeexamplecolumns}
619 \begin{hawkdraw}
620 \path[stroke] (0cm,0cm)
621 rectangle[corner={(2cm,1cm)}] ;
622 \end{hawkdraw}
623 \end{codeexamplecolumns}
624
625 \begin{macrodef}
626 |grid|[<options>]
627 \end{macrodef}
628 Using the \macro{grid} operation, a grid with the current point as origin corner is drawn.
629
630 \begin{macrodef}
631 !path/grid/!|step|={<tuple>}
632 !path/grid/!|corner|={<tuple>}
633 \end{macrodef}
634
635 The step is specified as a comma-separated list of at most two dimensions with the \macro{step} option. The first item in the tuple is the step in the x-direction, and the second item is the step in the y-direction. If only one dimension is given, it is used for both directions. The other corner is specified as a point (a tuple) with the \macro{corner} option.
636
637 \begin{codeexamplecolumns}
638 \begin{hawkdraw}
639 \path[stroke] (0cm,0cm)
640 grid[step={10pt}, corner={(2cm,1cm)}] ;
641 \end{hawkdraw}
642 \end{codeexamplecolumns}
643
644 \begin{codeexamplecolumns}
645 \begin{hawkdraw}
646 \path[stroke] (0cm,0cm)
647 grid[step={5pt,10pt}, corner={(2cm,1cm)}] ;
648 \end{hawkdraw}
649 \end{codeexamplecolumns}
650
651 \subsection{Points and nodes}
652
653 \begin{macrodef}[operation:point]
654 |point|[<options>]
655 \end{macrodef}
656 Using the \macro{point} operation, a point at the current position is defined and named with the given name.
657
658 \begin{macrodef}
659 !path/point/!|at|={<tuple>}
660 !path/point/!|name|={<string>}
661 \end{macrodef}
662 The position of the point can be adjusted with the \macro{at} option which accepts a point (a tuple). The point can be referenced later by using the name in parentheses (see \hyperlink{macro:point}{above}).
663
664 The command \macro{\point} is a shortcut for \macro{\path (0pt, 0pt) point}
665
666 \begin{codeexamplecolumns}
667 \begin{hawkdraw}
668 \path (0,0) point[name={A}, at={(2cm,0.5cm)}] ;
669 \path[stroke] (0cm,0cm) -- (A) -- (0cm,1cm) ;
670 \end{hawkdraw}
671 \end{codeexamplecolumns}
672
673 \begin{macrodef}[key:atpathpart]
674 !path/point/!|at path part|={<float>}
675 \end{macrodef}
676 The position of a point can also be adjusted using the \macro{at path part} option which accespts a floating-point number that defines the position on the last path segment with \num{0} being the previous and \num{1} being the current point.
677
678 \begin{codeexamplecolumns}
679 \begin{hawkdraw}
680 \path[stroke] (0cm,0cm)
681 -- (2cm,1cm)
682 point[name={A}, at path part={0}]
683 point[name={B}, at path part={0.5}]
684 point[name={C}, at path part={0.9}] ;
685 \fill[fill color=red] (A) circle[radius=2pt] ;
686 \fill[fill color=blue] (B) circle[radius=2pt] ;
687 \fill[fill color=green] (C) circle[radius=2pt] ;
688 \end{hawkdraw}
689 \end{codeexamplecolumns}
690
691 \begin{codeexamplecolumns}
692 \begin{hawkdraw}
693 \path[stroke] (0cm,0cm)
694 -| (2cm,1cm)
695 point[name={A}, at path part={0}]
696 point[name={B}, at path part={0.5}]
697 point[name={C}, at path part={0.9}] ;
698 \fill[fill color=red] (A) circle[radius=2pt] ;
699 \fill[fill color=blue] (B) circle[radius=2pt] ;
700 \fill[fill color=green] (C) circle[radius=2pt] ;
701 \end{hawkdraw}
702 \end{codeexamplecolumns}
703
704 \begin{codeexamplecolumns}
705 \begin{hawkdraw}
706 \path[stroke] (0cm,0cm)
707 .. (1cm,1cm)
708 .. (2cm,1cm)
709 point[name={A}, at path part={0}]
710 point[name={B}, at path part={0.5}]
711 point[name={C}, at path part={0.9}] ;
712 \fill[fill color=red] (A) circle[radius=2pt] ;
713 \fill[fill color=blue] (B) circle[radius=2pt] ;
714 \fill[fill color=green] (C) circle[radius=2pt] ;
715 \end{hawkdraw}
716 \end{codeexamplecolumns}
717
718 \begin{codeexamplecolumns}
719 \begin{hawkdraw}
720 \path[stroke] (0cm,0cm)
721 .. (0cm,0.5cm) & (1cm,1cm)
722 .. (2cm,1cm)
723 point[name={A}, at path part={0}]
724 point[name={B}, at path part={0.5}]
725 point[name={C}, at path part={0.9}] ;
726 \fill[fill color=red] (A) circle[radius=2pt] ;
727 \fill[fill color=blue] (B) circle[radius=2pt] ;
728 \fill[fill color=green] (C) circle[radius=2pt] ;
729 \end{hawkdraw}
730 \end{codeexamplecolumns}
731
732 \begin{codeexamplecolumns}
733 \begin{hawkdraw}
734 \path[stroke] (0cm,0cm)
735 arc[
736 radius={1cm},
737 angle start={45},
738 angle end={135}
739 ]
740 point[name={A}, at path part={0}]
741 point[name={B}, at path part={0.5}]
742 point[name={C}, at path part={0.9}] ;
743 \fill[fill color=red] (A) circle[radius=2pt] ;
744 \fill[fill color=blue] (B) circle[radius=2pt] ;
745 \fill[fill color=green] (C) circle[radius=2pt] ;
746 \end{hawkdraw}
747 \end{codeexamplecolumns}
748
749 \begin{codeexamplecolumns}
750 \begin{hawkdraw}
751 \path[stroke] (0cm,0cm)
752 arc[
753 vector a={(0.5cm,1cm)},
754 vector b={(0.75cm,0cm)},
755 angle start={45},
756 angle end={135}
757 ]
758 point[name={A}, at path part={0}]
759 point[name={B}, at path part={0.5}]
760 point[name={C}, at path part={0.9}] ;
761 \fill[fill color=red] (A) circle[radius=2pt] ;
762 \fill[fill color=blue] (B) circle[radius=2pt] ;
763 \fill[fill color=green] (C) circle[radius=2pt] ;
764 \end{hawkdraw}
765 \end{codeexamplecolumns}
766
767 \begin{macrodef}
768 |node|[<options>]{<content>}
769 \end{macrodef}
770 Using the \macro{node} operation, a node at the current position is defined and assigned the relevant content by the relevant argument.
771
772 \begin{macrodef}
773 !path/node/!|at|={<tuple>}
774 !path/node/!|name|={<string>}
775 !path/node/!|at path part|={<float>}
776 !path/node/!|anchor|={<clist>}
777 \end{macrodef}
778 The position of the node can be adjusted with the \macro{at} option which accepts a point (a tuple) or with the \macro{at path part} which accespts a floating-point number (see \hyperlink{key:atpathpart}{above}). The anchor is specified with the \macro{anchor} option which accepts a comma-separated list of at most two poles that define the anchor point as their intersection (see the explanations on coffins). Available poles are \macro{t}, \macro{b}, \macro{l}, \macro{r}, \macro{vc} and \macro{hc}. The node can be named by setting the \macro{name} option.
779
780 \begin{codeexamplecolumns}
781 \begin{hawkdraw}
782 \node {foo} ;
783 \end{hawkdraw}
784 \end{codeexamplecolumns}
785
786 \begin{codeexamplecolumns}
787 \begin{hawkdraw}
788 \stroke (0cm,0cm) -- (1cm,0.5cm)
789 node[anchor={t,l}, stroke] {foo} ;
790 \end{hawkdraw}
791 \end{codeexamplecolumns}
792
793 \begin{macrodef}
794 !path/node/!|width|={<dimension>}
795 \end{macrodef}
796 The width of the node can be set with the \macro{width} option.
797
798 \begin{codeexamplecolumns}
799 \begin{hawkdraw}
800 \stroke (0cm,0cm) -- (1cm,0.5cm)
801 node[stroke, width={1cm}] {foo} ;
802 \end{hawkdraw}
803 \end{codeexamplecolumns}
804
805 \begin{macrodef}
806 !path/node/!|padding|={<clist>}
807 \end{macrodef}
808 Using the \macro{padding} option, the padding between the border of the node and the contents is set. The value is a comma-separated list of one to four dimensions. If four dimensions are given, they apply to the top, left, bottom and right side of the node respectively. If three dimensions are given, the first apples to the top, the second to the left and right side, the third to the bottom. If two dimensions are given, the first applies to the top and bottom and the second to the left and right sides. If only one dimension is given, it is appled to all four sides.
809
810 \begin{codeexamplecolumns}
811 \begin{hawkdraw}
812 \node[
813 stroke,
814 at={(0cm,2cm)},
815 padding={10pt}
816 ] {foo} ;
817 \node[
818 stroke,
819 at={(1.5cm,2cm)},
820 padding={5pt,10pt}
821 ] {foo} ;
822 \node[
823 stroke,
824 at={(0cm,0cm)},
825 padding={5pt,10pt,15pt}
826 ] {foo} ;
827 \node[
828 stroke,
829 at={(1.5cm,0cm)},
830 padding={5pt,10pt,15pt,0pt}
831 ] {foo} ;
832 \end{hawkdraw}
833 \end{codeexamplecolumns}
834
835 \begin{macrodef}
836 !path/node/!|text color|={<color>}
837 !path/node/!|text opacity|={<float>}
838 \end{macrodef}
839 Using the \macro{text color} option, the color of the node contents is set. The default text color is the current (text) color. The option \macro{text opacity} sets the text opacity. The floating-point number should be in the range of \num{0} and \num{1}. The default text opacity is \num{1} (fully opaque). Note that \macro{\DocumentMetadata{}} needs to be set in order to activate support for PDF transparency.
840
841 \begin{macrodef}
842 !path/node/!|frame|={<string>}
843 \end{macrodef}
844 Using the \macro{frame} command, the frame surrounding the node text can be selected. The frame \macro{rectangle} is set per default. All options that are available for paths are also available for node frames.
845
846 \begin{codeexamplecolumns}
847 \begin{hawkdraw}
848 \stroke (0cm,0cm) -- (1cm,0.5cm)
849 node[
850 fill, fill color={yellow},
851 text color={blue},
852 frame={ellipse}
853 ] {foo} ;
854 \end{hawkdraw}
855 \end{codeexamplecolumns}
856
857 The command \macro{\node} is a shortcut for \macro{\path (0pt,0pt) node}
858
859 The following node frames are available, the frame \macro{none} is special as it removes the bounding box from the node altogether:
860
861 \NewDocumentCommand{\nodeframe}{ O{0.5ex} m }{%
862 \begin{hawkdraw}[baseline={#1}]
863 \path (-0.5cm,-0.25cm) rectangle[corner={(1cm,0.5cm)}] ;
864 \node[frame={#2}, stroke] {foo} ;
865 \end{hawkdraw}%
866 }
867
868 \begin{longtable}{ @{} p{2.5cm} p{\dimexpr\textwidth-2\tabcolsep-2.5cm} @{} }
869 \toprule
870 \textbf{Node frame} & \textbf{Name} \\
871 \midrule
872 \nodeframe{none} & \macro{none} \\
873 \nodeframe{rectangle} & \macro{rectangle} \\
874 \nodeframe{ellipse} & \macro{ellipse} \\
875 \nodeframe{circle} & \macro{circle} \\
876 \nodeframe{diamond} & \macro{diamond} \\
877 \bottomrule
878 \end{longtable}
879
880 \section{Mapping operation}
881
882 \begin{macrodef}
883 |map|[<options>]{<code>}
884 \end{macrodef}
885 The \macro{map} operation is used to map over a comma-separated list of items or a range of numbers and execute code for each item that is given by the relevant argument. The code can reference the current item with \macro{#1}. The following options can be set for the command:
886
887 \begin{macrodef}
888 !path/map/!|list|={<clist>}
889 !path/map/!|start|={<float>}
890 !path/map/!|end|={<float>}
891 !path/map/!|step|={<float>}
892 \end{macrodef}
893 The option \macro{list} sets the command to map over a comma-separated list of items. Each item in the list is passed as an argument to the code.
894
895 \begin{codeexamplecolumns}
896 \begin{hawkdraw}
897 \fill
898 map[list={30,150,270}] {
899 (#1:0.75cm) circle[radius={5pt}]
900 } ;
901 \end{hawkdraw}
902 \end{codeexamplecolumns}
903
904 The option \macro{start} sets the start of the range for mapping over a range of numbers as a floating-point number. The default start is \num{1}. The option \macro{end} sets the end of the range for mapping over a range of numbers as a floating-point number. The default end is \num{1}. The option \macro{step} sets the step for the range for mapping over a range of numbers as a floating-point number. The default step is \num{1}.
905
906 The command \macro{\map} is a shortcut for \macro{\path (0pt,0pt) map}
907
908 \begin{codeexamplecolumns}
909 \begin{hawkdraw}
910 \map[start={30}, step={120}, end={270}] { [fill]
911 (#1:0.75cm) circle[radius={5pt}]
912 } ;
913 \end{hawkdraw}
914 \end{codeexamplecolumns}
915
916 \section{Main path options}
917
918 \begin{macrodef}
919 |\hawkdrawset|{<options>}
920 \end{macrodef}
921 The command \macro{\hawkdrawset} is used to set options for paths. It can be used inside or outside of \macro{hawkdraw} environments.
922
923 The following options can be set for the path:
924
925 \subsection{Stroke and fill color, clipping}
926
927 \begin{macrodef}
928 !path/!|stroke|
929 !path/!|fill|
930 !path/!|clip|
931 \end{macrodef}
932 These options add a stroke to the path, fill the path, or use the path as a clipping region for subsequent paths. They can be used in combination. As the clipping region affects all following paths, it is often useful to use it in combination with scopes (see \hyperlink{sec:scopes}{above}).
933
934 The command \macro{\stroke} is a shortcut for \macro{\path [stroke]}.
935
936 The command \macro{\fill} is a shortcut for \macro{\path [fill]}
937
938 The command \macro{\clip} is a shortcut for \macro{\path [clip]}
939
940 \begin{codeexamplecolumns}
941 \begin{hawkdraw}
942 \path[stroke, clip] (0cm,0cm)
943 rectangle[corner={(2cm,1cm)}] ;
944 \fill (1cm,0.5cm)
945 circle[radius={0.6cm}] ;
946 \end{hawkdraw}
947 \end{codeexamplecolumns}
948
949 \begin{macrodef}
950 !path/!|stroke color|={<color>}
951 !path/!|fill color|={<color>}
952 !path/!|stroke opacity|={<float>}
953 !path/!|fill opacity|={<float>}
954 \end{macrodef}
955 The options \macro{stroke color} and \macro{fill color} set the stroke color and the fill color for the path. The default stroke color and fill color is the current (text) color.
956
957 \begin{codeexamplecolumns}
958 \begin{hawkdraw}[line width={5pt}]
959 \path[
960 fill, fill color={yellow},
961 stroke, stroke color={blue}
962 ] (0cm,0cm)
963 rectangle[corner={(2cm,1cm)}] ;
964 \end{hawkdraw}
965 \end{codeexamplecolumns}
966
967 \begin{codeexamplecolumns}
968 \begin{hawkdraw}[line width={5pt}]
969 \path[
970 fill, fill opacity={0.25},
971 stroke, stroke opacity={0.5}
972 ] (0cm,0cm)
973 rectangle[corner={(2cm,1cm)}] ;
974 \end{hawkdraw}
975 \end{codeexamplecolumns}
976
977 The options \macro{stroke opacity} and \macro{fill opacity} set the stroke opacity and the fill opacity for the path. The floating-point number should be in the range of \num{0} and \num{1}. The default stroke opacity and fill opacity is \num{1} (fully opaque). Note that \macro{\DocumentMetadata{}} needs to be set in order to activate support for PDF transparency.
978
979 \subsection{Line styling}
980
981 \begin{macrodef}
982 !path/!|line width|={<dimension>}
983 \end{macrodef}
984 Sets the line width for the path. The default line width is \qty{0.4}{\point}.
985
986 \begin{codeexamplecolumns}
987 \begin{hawkdraw}
988 \stroke
989 (0cm,0cm) -- (2cm,1cm);
990 \end{hawkdraw}
991 \end{codeexamplecolumns}
992
993 \begin{codeexamplecolumns}
994 \begin{hawkdraw}
995 \stroke[line width={5pt}]
996 (0cm,0cm) -- (2cm,1cm) ;
997 \end{hawkdraw}
998 \end{codeexamplecolumns}
999
1000 \begin{macrodef}
1001 !path/!|line cap|={<string>}
1002 !path/!|line join|={<string>}
1003 !path/!|miter limit|={<float>}
1004 \end{macrodef}
1005 The option \macro{line cap} sets the line cap for the path. The possible values are \macro{butt}, \macro{round}, and \macro{rectangle}. The default line cap is \macro{butt}.
1006
1007 \begin{codeexamplecolumns}
1008 \begin{hawkdraw}[line width={5pt}]
1009 \stroke[line cap={round}]
1010 (0cm,0cm) -- (2cm,1cm) ;
1011 \end{hawkdraw}
1012 \end{codeexamplecolumns}
1013
1014 The option \macro{line join} sets the line join for the path. The possible values are \macro{miter}, \macro{round}, and \macro{bevel}. The default line join is \macro{miter}.
1015
1016 The option \macro{miter limit} sets the miter limit for the path. The default miter limit is \num{10}.
1017
1018 \begin{codeexamplecolumns}
1019 \begin{hawkdraw}[line width={5pt}]
1020 \stroke[line join={bevel}]
1021 (0cm,0cm) -- (2cm,0.5cm)
1022 -- (0cm,1cm) ;
1023 \end{hawkdraw}
1024 \end{codeexamplecolumns}
1025
1026 \begin{macrodef}
1027 !path/!|dash pattern|={<clist>}
1028 !path/!|dash phase|={<dimension>}
1029 \end{macrodef}
1030 The option \macro{dash pattern} sets the dash pattern for the path as a comma-separated list of dimensions. Each item in the list is a dimension representing the length of a dash or a gap. The default dash pattern is empty (a solid line).
1031
1032 The option \macro{dash phase} sets the dash phase for the path as a dimension. The default dash phase is \qty{0}{\point}.
1033
1034 \begin{codeexamplecolumns}
1035 \begin{hawkdraw}
1036 \stroke[
1037 dash pattern={10pt,5pt},
1038 dash phase={2.5pt}
1039 ] (0cm,0cm) -- (2cm,1cm) ;
1040 \end{hawkdraw}
1041 \end{codeexamplecolumns}
1042
1043 \subsection{Rounded corners and full rule}
1044
1045 \begin{macrodef}
1046 !path/!|corner arc|={<clist>}
1047 \end{macrodef}
1048 The option \macro{corner arc} the corner arc for the path as a comma-separated list of at most two dimensions. The first applies to the corner formed by the path leading into the corner, and the second applies to the corner formed by the path leading out of the corner. If only one dimension is given, it applies to both corners. The default corner arc is \qty{0}{\point} (sharp corners).
1049
1050 \begin{codeexamplecolumns}
1051 \begin{hawkdraw}
1052 \stroke[corner arc={5pt}] (0cm,0cm)
1053 rectangle[corner={(2cm,1cm)}] ;
1054 \end{hawkdraw}
1055 \end{codeexamplecolumns}
1056
1057 \begin{macrodef}
1058 !path/!|fill rule|={<string>}
1059 \end{macrodef}
1060 The option \macro{fill rule} sets the fill rule for the path. The possible values are \macro{non-zero} and \macro{even-odd}. The default fill rule is \macro{non-zero}. Note that this option is not influenced by scoping.
1061
1062 \begin{codeexamplecolumns}
1063 \begin{hawkdraw}[fill rule={even-odd}]
1064 \fill (0cm,0cm)
1065 rectangle[corner={(2cm,1cm)}]
1066 (1cm,0.5cm)
1067 circle[radius={0.4cm}] ;
1068 \end{hawkdraw}
1069 \end{codeexamplecolumns}
1070
1071 \subsection{Transformations}
1072
1073 \begin{macrodef}
1074 !path/!|shift|={<tuple>}
1075 !path/!|rotate|={<float>}
1076 !path/!|scale|={<tuple>}
1077 !path/!|slant|={<tuple>}
1078 \end{macrodef}
1079 The option \macro{shift} sets the shift for the path as a tuple of dimensions. The first item in the tuple is the shift in the x-direction, and the second item is the shift in the y-direction. The default shift is (\qty{0}{\point}, \qty{0}{\point}).
1080
1081 \begin{codeexamplecolumns}
1082 \begin{hawkdraw}
1083 \stroke[stroke color={blue}]
1084 (0cm,0cm) rectangle[corner={(2cm,1cm)}] ;
1085 \stroke[shift={(5pt,10pt)}]
1086 (0cm,0cm) rectangle[corner={(2cm,1cm)}] ;
1087 \end{hawkdraw}
1088 \end{codeexamplecolumns}
1089
1090 The option \macro{rotate} sets the rotation for the path as a floating-point number representing the angle of rotation. The default rotation is \qty{0}{\degree}.
1091
1092 \begin{codeexamplecolumns}
1093 \begin{hawkdraw}
1094 \stroke[scale={0.25,0.5}]
1095 (0cm,0cm) rectangle[corner={(2cm,1cm)}] ;
1096 \end{hawkdraw}
1097 \end{codeexamplecolumns}
1098
1099 The option \macro{scale} sets the scale for the path as a comma-separated list of at most two floating-point numbers. The first item in the tuple is the scale in the x-direction, and the second item is the scale in the y-direction. If only one number is given, it is used for both directions. The default scale is (\num{1}, \num{1}).
1100
1101 \begin{codeexamplecolumns}
1102 \begin{hawkdraw}
1103 \stroke[rotate={20}]
1104 (0cm,0cm) rectangle[corner={(2cm,1cm)}] ;
1105 \end{hawkdraw}
1106 \end{codeexamplecolumns}
1107
1108 The option \macro{slant} sets the slant for the path as a comma-separated list of at most two floating-point numbers. The first item in the tuple is the slant in the x-direction, and the second item is the slant in the y-direction. If only one number is given, it is used for both directions. The default slant is (\num{0}, \num{0}).
1109
1110 \begin{codeexamplecolumns}
1111 \begin{hawkdraw}
1112 \stroke[slant={0.25,0.5}]
1113 (0cm,0cm) rectangle[corner={(2cm,1cm)}] ;
1114 \end{hawkdraw}
1115 \end{codeexamplecolumns}
1116
1117 \section{Setting styles and colors}
1118
1119 \begin{macrodef}
1120 !path/!|style set|={<options>}
1121 !path/!|style add|={<options>}
1122 \end{macrodef}
1123 To simplify styling, custom keys can be defined via the keys \macro{style set} and \macro{style add}. Both keys accept as value a key-value list consisting of one or multiple custom keys whose relevant value consists of another key-value list describing the relevant style. It is possible to use \macro{#1} as placeholder for one argument. It is also possible to reference to an already define custom key in the definition of another custom key.
1124
1125 The key \macro{style set} defines custom keys and sets their values. The key \macro{style add} appends the relevant key-value list to the existing custom key as defined by \macro{style set}. Note that it is not checked whether a custom key already exists and its definition will be overwritten without a warning.
1126
1127 \begin{codeexamplecolumns}
1128 \begin{hawkdraw}[
1129 style set={
1130 mystyle={
1131 stroke, stroke color={blue},
1132 line width={5pt}
1133 }
1134 }
1135 ]
1136 \path[mystyle]
1137 (0cm,0cm) -- (2cm,1cm) ;
1138 \end{hawkdraw}
1139 \end{codeexamplecolumns}
1140
1141 \begin{macrodef}
1142 |\hawkdrawsetcolor|{<color>}{<model>}{<value>}
1143 \end{macrodef}
1144 The command \macro{\hawkdrawsetcolor} is used to define colors using the \macro{l3color} module. It is recommended to define custom colors in the preamble of the document. If the model is set to \macro{named}, the command expects as value a color expression.
1145
1146 \begin{codeexamplecolumns}
1147 \hawkdrawsetcolor{colorA}{rgb}{0.1,0.5,0.8}
1148 \hawkdrawsetcolor{colorB}{named}{yellow!90!red}
1149 \begin{hawkdraw}[line width={5pt}]
1150 \path[
1151 stroke, stroke color={colorA},
1152 fill, fill color={colorB}
1153 ] (0cm,0cm) rectangle[corner={(2cm,1cm)}] ;
1154 \end{hawkdraw}
1155 \end{codeexamplecolumns}
1156
1157 \subsection{Arrow tips}
1158
1159 \begin{macrodef}
1160 !path/!|arrow start|={<string>}
1161 !path/!|arrow end|={<string>}
1162 \end{macrodef}
1163 The options \macro{arrow start} and \macro{arrow end} set an arrow tip to the start and the end of the current path respectively. Both keys take as value a string representing the name of the relevant arrow tip. The \macro{default} arrow tip is selected per default. Arrow tips are not attached to single points or closed paths.
1164
1165 \begin{codeexamplecolumns}
1166 \begin{hawkdraw}
1167 \stroke[arrow start, arrow end]
1168 (0cm,0cm) -- (2cm,1cm) ;
1169 \end{hawkdraw}
1170 \end{codeexamplecolumns}
1171
1172 \begin{macrodef}
1173 !path/!|arrow style set|={<options>}
1174 !path/!|arrow style add|={<options>}
1175 !path/!|arrow start style set|={<options>}
1176 !path/!|arrow start style add|={<options>}
1177 !path/!|arrow end style set|={<options>}
1178 !path/!|arrow end style add|={<options>}
1179 \end{macrodef}
1180 Arrow tips can be styled using the options \macro{arrow start style set} and \macro{arrow end style set}. The option \macro{arrow style set} sets the same style for start and end arrow tips. The options \macro{arrow start style add}, \macro{arrow end style add} and \macro{arrow style add} append the relevant styles to the existing styles. All options that are available for paths are also available for arrow tips.
1181
1182 \begin{codeexamplecolumns}
1183 \begin{hawkdraw}
1184 \stroke[
1185 arrow end,
1186 arrow style set={fill, fill color=blue}
1187 ]
1188 (0cm,0cm) -- (2cm,1cm) ;
1189 \end{hawkdraw}
1190 \end{codeexamplecolumns}
1191
1192 The following arrow tips are available, of these the last three, \macro{simple}, \macro{straight} and \macro{bar}, should be set together with the option \macro{arrow style set={stroke}}:
1193
1194 \NewDocumentCommand{\arrowexample}{ m }{%
1195 \begin{hawkdraw}[baseline={0.5ex}]
1196 \stroke[arrow end={#1}]
1197 (0cm,0cm) -- (1cm,0cm) ;
1198 \end{hawkdraw}%
1199 }
1200
1201 \begin{longtable}{ @{} p{2.5cm} p{\dimexpr\textwidth-2\tabcolsep-2.5cm} @{} }
1202 \toprule
1203 \textbf{Arrow tip} & \textbf{Name} \\
1204 \midrule
1205 \arrowexample{none} & \macro{none} \\
1206 \arrowexample{default} & \macro{default} \\
1207 \arrowexample{stealth} & \macro{stealth} \\
1208 \arrowexample{triangle} & \macro{triangle} \\
1209 \arrowexample{circle} & \macro{circle} \\
1210 \arrowexample{simple} & \macro{simple} \\
1211 \arrowexample{straight} & \macro{straight} \\
1212 \arrowexample{bar} & \macro{bar} \\
1213 \bottomrule
1214 \end{longtable}
1215
1216 \subsection{Patterns}
1217
1218 Note that in order to be able to use patterns, \macro{\DocumentMetadata{}} needs to be set.
1219
1220 \begin{macrodef}
1221 !path/!|fill pattern|={<string>}
1222 \end{macrodef}
1223 The option \macro{fill pattern} sets a fill pattern for the current path. The key takes as value a string representing the name of the relevant pattern.
1224
1225 \begin{macrodef}
1226 !path/!|pattern style set|={<options>}
1227 !path/!|pattern style add|={<options>}
1228 \end{macrodef}
1229 Patterns can be styled using the options \macro{pattern style set} and \macro{pattern style add}. The option \macro{pattern style set} sets the style for the pattern of the current path. The options \macro{pattern style add} appends the relevant styles to the existing styles. All options that are available for paths are also available for patterns.
1230
1231 \begin{macrodef}
1232 !path/!|pattern x|={<dimension>}
1233 !path/!|pattern y|={<dimension>}
1234 \end{macrodef}
1235 The options \macro{pattern x} and \macro{pattern y} set the dimensions of the pattern in the x and y directions, respectively. The default dimensions of a pattern in both directions are both \qty{10}{\point}.
1236
1237 \begin{codeexamplecolumns}
1238 \begin{hawkdraw}
1239 \path[
1240 fill pattern={dots},
1241 pattern style set={fill color=blue}
1242 ]
1243 (0cm,0cm) rectangle[corner={(2cm,1cm)}] ;
1244 \end{hawkdraw}
1245 \end{codeexamplecolumns}
1246
1247 The following patterns are available:
1248
1249 \NewDocumentCommand{\patternexample}{ m }{%
1250 \begin{hawkdraw}[baseline={0.5ex}]
1251 \path[fill pattern={#1}]
1252 (0cm,0cm) rectangle[corner={(2cm,1cm)}] ;
1253 \end{hawkdraw}%
1254 }
1255
1256 \begin{longtable}{ @{} p{2.5cm} p{\dimexpr\textwidth-2\tabcolsep-2.5cm} @{} }
1257 \toprule
1258 \textbf{Pattern} & \textbf{Name} \\
1259 \midrule
1260 \patternexample{lines} & \macro{lines} \\
1261 \patternexample{hatch} & \macro{hatch} \\
1262 \patternexample{dots} & \macro{dots} \\
1263 \bottomrule
1264 \end{longtable}
1265
1266 \section{User commands}
1267
1268 \begin{macrodef}
1269 |\firstpoint|
1270 |\lastpoint|
1271 \end{macrodef}
1272 The commands \macro{\firstpoint} and \macro{\lastpoint} can be used to access the first and last point of the current path, respectively.
1273
1274 \begin{macrodef}
1275 |\firstslope|
1276 |\lastslope|
1277 \end{macrodef}
1278 The commands \macro{\firstslope} and \macro{\lastslope} can be used to access the slope at the first and last point of the current path, respectively. The slope is represented as the angle with respect to the positive x-axis.
1279
1280 % =====
1281
1282 \printchanges
1283
1284 \end{document}