Debian Codegraph @

texmf-dist/doc/latex/celtic/celtic_doc.tex

raw
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: