| 1 |
\immediate\write18{tex celtic.dtx} |
| 2 |
\documentclass{ltxdoc} |
| 3 |
\usepackage[T1]{fontenc} |
| 4 |
\usepackage{trace} |
| 5 |
\usepackage{lmodern} |
| 6 |
\usepackage{morefloats} |
| 7 |
\usepackage{tikz} |
| 8 |
\usetikzlibrary{celtic} |
| 9 |
\usepackage[numbered]{hypdoc} |
| 10 |
\definecolor{lstbgcolor}{rgb}{0.9,0.9,0.9} |
| 11 |
|
| 12 |
\usepackage{listings} |
| 13 |
\lstloadlanguages{[LaTeX]TeX} |
| 14 |
\lstset{breakatwhitespace=true,breaklines=true,language=TeX} |
| 15 |
|
| 16 |
\usepackage{fancyvrb} |
| 17 |
|
| 18 |
\newenvironment{example} |
| 19 |
{\VerbatimEnvironment |
| 20 |
\begin{VerbatimOut}{example.out}} |
| 21 |
{\end{VerbatimOut} |
| 22 |
\begin{center} |
| 23 |
\setlength{\parindent}{0pt} |
| 24 |
\fbox{\begin{minipage}{.9\linewidth} |
| 25 |
\lstset{breakatwhitespace=true,breaklines=true,language=TeX,basicstyle=\small} |
| 26 |
\lstinputlisting[]{example.out} |
| 27 |
\end{minipage}} |
| 28 |
|
| 29 |
\fbox{\begin{minipage}{.9\linewidth} |
| 30 |
\centering |
| 31 |
\input{example.out} |
| 32 |
\end{minipage}} |
| 33 |
\end{center} |
| 34 |
} |
| 35 |
|
| 36 |
\providecommand*{\url}{\texttt} |
| 37 |
|
| 38 |
\title{The \textsf{celtic} TikZ Library: Documentation} |
| 39 |
\author{Andrew Stacey \\ \url{[email protected]}} |
| 40 |
\date{19th February 2016} |
| 41 |
|
| 42 |
\begin{document} |
| 43 |
\VerbatimFootnotes |
| 44 |
\maketitle |
| 45 |
|
| 46 |
\begin{center} |
| 47 |
\begin{tikzpicture}[ |
| 48 |
scale=.5, |
| 49 |
celtic path/.style={ |
| 50 |
draw, |
| 51 |
double=gray!40, |
| 52 |
red, |
| 53 |
double distance=1mm, |
| 54 |
line width=4pt |
| 55 |
}, |
| 56 |
celtic path 1/.style={ |
| 57 |
green!50!black, |
| 58 |
}, |
| 59 |
] |
| 60 |
\CelticDrawPath{ |
| 61 |
symmetric crossings={ |
| 62 |
1,2,-; |
| 63 |
2,1,|; |
| 64 |
4,3,-; |
| 65 |
3,4,|; |
| 66 |
}, |
| 67 |
size={8,8}, |
| 68 |
} |
| 69 |
\end{tikzpicture} |
| 70 |
\end{center} |
| 71 |
|
| 72 |
\section{Introduction} |
| 73 |
|
| 74 |
This is a little TikZ library for drawing Celtic style knots. |
| 75 |
The particular type of Celtic knot (technically, \emph{link}) is very simple and can be specified by listing the ``walls'' within the region of the knot. |
| 76 |
From this information, it is possible to build the entire link and thus to tell TikZ how render it. |
| 77 |
That is what this library does. |
| 78 |
|
| 79 |
\section{Usage} |
| 80 |
|
| 81 |
The routine is implemented as a TikZ library. |
| 82 |
Thus to use it, add \Verb+celtic+ to the list of TikZ libraries that you load. |
| 83 |
|
| 84 |
\begin{verbatim} |
| 85 |
\usetikzlibrary{celtic} |
| 86 |
\end{verbatim} |
| 87 |
|
| 88 |
The library defines one command which renders a Celtic knot. |
| 89 |
The knot is specified by passing various \emph{key-value} pairs to this command. |
| 90 |
The library also defines styles which can be used to modify the rendering. |
| 91 |
|
| 92 |
\DescribeMacro{\CelticDrawPath}\Verb+\CelticDrawPath{<opt>}+ is the command to render a knot. |
| 93 |
It takes one option which is a list of key-value pairs which specify the knot. |
| 94 |
The allowed key-value pairs are as follows. |
| 95 |
|
| 96 |
\begin{itemize} |
| 97 |
\item \Verb+max steps=N+ The process of finding the paths through the knot (needed to ensure that they are coloured correctly) is iterative. |
| 98 |
Although every care has been taken to ensure that the iteration is confined (and therefore finite), the iteration has been devised with a built-in limit. |
| 99 |
This limit can be adjusted using this key. |
| 100 |
The default is \(20\). |
| 101 |
If the limit is reached, a warning will be issued (and the knot will probably look wrong). |
| 102 |
In that case, use this key to raise the limit. |
| 103 |
|
| 104 |
\item \Verb+flip+ The specification of a Celtic knot in terms of walls does not completely determine it. |
| 105 |
There is an ambiguity as to which crossings are over and which under (once one crossing is determined, all the others follow). |
| 106 |
This key flips all of the crossings and so can be used to switch between the two variants. |
| 107 |
|
| 108 |
\item \Verb+width=W+, \Verb+height=H+, \Verb+size={W,H}+ These set the dimensions on the knot in terms of the number of crossings. |
| 109 |
The numbers must be even. |
| 110 |
|
| 111 |
\item \Verb+crossings+, \Verb+symmetric crossings+ These set the crossings. |
| 112 |
The general format of a crossing is \Verb+x,y,type+ where \Verb+x+ and \Verb+y+ can be either numbers or ranges, using the format \Verb+n:m+\footnote{This package uses \LaTeX3 internally; using a colon as the range separator was a headache to implement.}. |
| 113 |
The type of the crossing is either \Verb+|+ or \Verb+-+ for (respectively) vertical or horizontal walls\footnote{The package attempts to be smart with regard to allowing \Verb+|+ to be active.}. |
| 114 |
Multiple crossing specifications can be given as a semi-colon-delimited list (a final semi-colon is acceptable, making it easy to comment out items in the list). |
| 115 |
The \Verb+symmetric+ variant places walls at four points obtained by applying reflections to the specified crossing. |
| 116 |
|
| 117 |
\item \Verb+ignore crossings+, \Verb+ignore symmetric crossings+ The code works out the paths involved by picking a starting point and direction and then following it, bouncing off walls as appropriate, until it comes back to the beginning. |
| 118 |
It then picks a new starting point and continues until all crossings are used up. |
| 119 |
These keys designate certain points as \emph{disallowed} as starting points. |
| 120 |
This can be used to remove certain regions from the knot, for example to create a border around a rectangle. |
| 121 |
The \Verb+symmetric+ version works \dots\ symmetrically. |
| 122 |
|
| 123 |
\item \Verb+style={<style>}+ The contents of this are passed on to \Verb+\tikzset+. |
| 124 |
(The key-value pairs for the \Verb+\CelticDrawPath+ are actually \LaTeX3 keys, not TikZ keys, so this is the simplest way to pass them through.) |
| 125 |
|
| 126 |
\item \Verb+at=<coordinate>+ This shifts the knot so that the lower left corner is at the coordinate. |
| 127 |
(The default location is \Verb+(0,0)+.) |
| 128 |
The coordinate is passed through TikZ's processing so can be any legal TikZ coordinate. |
| 129 |
|
| 130 |
\item \Verb+inner clip=N+, \Verb+outer clip=N+. The crossings are rendered by redrawing the over paths with a clipping region. |
| 131 |
The size of the clipping region is determined by the line width. |
| 132 |
These keys add a little to that clipping region. |
| 133 |
This can be useful if the overdraws are not large enough, but the added amount should not be so much that the overdraws interfere with each other. |
| 134 |
Some experimentation is needed. |
| 135 |
The \Verb+inner clip+ applies to the background part of the path and the \Verb+outer clip+ to the foreground. |
| 136 |
|
| 137 |
\end{itemize} |
| 138 |
|
| 139 |
As the pieces are rendered, various TikZ styles are invoked. |
| 140 |
|
| 141 |
\begin{itemize} |
| 142 |
\item \Verb+celtic surround+ This style is used for the outer border. |
| 143 |
|
| 144 |
\item \Verb+celtic bar+ This is used for the internal walls. |
| 145 |
It is also used on the outer border (prior to the \Verb+celtic surround+ so it can be overridden). |
| 146 |
|
| 147 |
\item \Verb+celtic path+ This is used for the components of the celtic knot (link). |
| 148 |
|
| 149 |
\item \Verb+celtic path N+ The individual components can be styled using their number (there is a logic to the numbering, but experimentation is the best way to work out which is which). |
| 150 |
|
| 151 |
|
| 152 |
\end{itemize} |
| 153 |
|
| 154 |
\section{Example} |
| 155 |
|
| 156 |
\begin{example} |
| 157 |
\begin{tikzpicture}[ |
| 158 |
scale=.5, |
| 159 |
celtic path/.style={ |
| 160 |
draw, |
| 161 |
double=gray!40, |
| 162 |
red, |
| 163 |
double distance=1mm, |
| 164 |
line width=4pt |
| 165 |
}, |
| 166 |
celtic path 1/.style={ |
| 167 |
green!50!black, |
| 168 |
}, |
| 169 |
celtic path 2/.style={ |
| 170 |
blue, |
| 171 |
}, |
| 172 |
celtic path 3/.style={ |
| 173 |
red!50!black, |
| 174 |
}, |
| 175 |
celtic surround/.style={ |
| 176 |
ultra thick, |
| 177 |
black, |
| 178 |
fill=black |
| 179 |
}, |
| 180 |
] |
| 181 |
\CelticDrawPath{ |
| 182 |
symmetric crossings={ |
| 183 |
4,1:3,|; |
| 184 |
10,1,|; |
| 185 |
5,4,-; |
| 186 |
8,3,-; |
| 187 |
}, |
| 188 |
size={20,10}, |
| 189 |
max steps=50 |
| 190 |
} |
| 191 |
\end{tikzpicture} |
| 192 |
\end{example} |
| 193 |
|
| 194 |
\begin{example} |
| 195 |
\begin{tikzpicture}[ |
| 196 |
scale=.5, |
| 197 |
celtic path/.style={ |
| 198 |
draw, |
| 199 |
double=white, |
| 200 |
red, |
| 201 |
double distance=5pt, |
| 202 |
line width=1pt |
| 203 |
}, |
| 204 |
celtic bar/.style={ |
| 205 |
ultra thick, |
| 206 |
black, |
| 207 |
draw |
| 208 |
}, |
| 209 |
] |
| 210 |
\CelticDrawPath{ |
| 211 |
size={20,10}, |
| 212 |
symmetric crossings={ |
| 213 |
3,4:5,|; |
| 214 |
4:16,3,- |
| 215 |
}, |
| 216 |
ignore symmetric crossings={ |
| 217 |
4:10,5; |
| 218 |
5:10,4 |
| 219 |
}, |
| 220 |
max steps=50 |
| 221 |
} |
| 222 |
\end{tikzpicture} |
| 223 |
\end{example} |
| 224 |
|
| 225 |
\end{document} |
| 226 |
|
| 227 |
% Local Variables: |
| 228 |
% tex-output-type: "pdf18" |
| 229 |
% End: |