Debian Codegraph @

texmf-dist/doc/latex/spath3/calligraphy.tex

raw
1 %\immediate\write18{tex spath3_doc.dtx}
2 \documentclass{ltxdoc}
3 \usepackage[T1]{fontenc}
4 \usepackage{trace}
5 \usepackage{lmodern}
6 \usepackage{morefloats}
7 \usepackage{tikz}
8 \usetikzlibrary{decorations.pathreplacing,calligraphy,matrix}
9 \usepackage[numbered]{hypdoc}
10 \definecolor{lstbgcolor}{rgb}{0.9,0.9,0.9}
11
12 \usepackage{listings}
13 \lstloadlanguages{[LaTeX]TeX}
14 \lstset{
15 breakatwhitespace=true,
16 breaklines=true,
17 language=[LaTeX]TeX,
18 basicstyle=\small\ttfamily,
19 keepspaces=true,
20 columns=fullflexible
21 }
22
23 \usepackage{fancyvrb}
24
25 \newenvironment{example}
26 {\VerbatimEnvironment
27 \begin{VerbatimOut}{example.out}}
28 {\end{VerbatimOut}
29 \begin{center}
30 \setlength{\parindent}{0pt}
31 \fbox{\begin{minipage}{.9\linewidth}
32 \lstinputlisting[]{example.out}
33 \end{minipage}}
34
35 \fbox{\begin{minipage}{.9\linewidth}
36 \input{example.out}
37 \end{minipage}}
38 \end{center}
39 }
40
41 \providecommand*{\url}{\texttt}
42 \GetFileInfo{spath3.sty}
43
44 \pdfstringdefDisableCommands{%
45 \def\\{}%
46 \def\url#1{<#1>}%
47 }
48
49 \title{The \textsf{calligraphy} Package: Documentation}
50 \author{Andrew Stacey \\ \url{[email protected]}}
51 \date{\fileversion~from \filedate}
52
53 \begin{document}
54
55 \maketitle
56
57 \section{Pre-Introduction}
58 This library is built on top of a package for manipulating PGF's \emph{soft paths} called \texttt{spath3}.
59 Version 2.0 of \texttt{spath3} involved considerable reorganisation of the code.
60 I tried to ensure that this didn't affect this library but it is extremely likely that I wasn't fully successful.
61 If something that used to work no longer does, please do let me know either by opening an issue on github (\url{https://github.com/loopspace/spath3}) or at the above email.
62
63 \section{Introduction}
64 The \Verb+calligraphy+ TikZ library is designed to enable calligraphic style drawings in TikZ.
65 The idea is to be able to ``stroke'' a line with a ``pen''.
66 As a simple example, compare the two lines in the following picture.
67
68 \begin{example}
69 \begin{center}
70 \begin{tikzpicture}
71 \pen (-135:.25) -- (45:.25);
72 \draw[line width=.5cm] (0,0) .. controls +(45:1) and +(-135:1) .. ++(3,0);
73 \calligraphy (0,-1) .. controls +(45:1) and +(-135:1) .. ++(3,0);
74 \end{tikzpicture}
75 \end{center}
76 \end{example}
77
78 The paths are identical in definition but the first is drawn using the standard TikZ path with a line width of .5cm.
79 The second is ``stroked'' with a calligraphic pen of width .5cm angled at 45 degrees.
80 \section{How It Works}
81 To know how to use this library, it is worth knowing a little about how it works.
82 A ``pen'' is a path, as is the line that is the template for the pen stroke.
83 The two paths are joined together to form a region which is filled.
84 Thus in constructing the example given in the introduction, the following path is built.
85 \begin{center}
86 \begin{tikzpicture}
87 \draw (0,-1) .. controls +(45:1) and +(-135:1) .. node (op) {} ++(3,0) -- node (pp) {} ++(45:.5) .. controls +(-135:1) and +(45:1) .. node (opr) {} ++(-3,0) -- node (ppr) {} (0,-1);
88 \draw[<-] (op) -- ++(0,-.5) node[anchor=north] {original path};
89 \draw[<-] (pp) -- ++(.5,0) node[anchor=west] {pen path};
90 \draw[<-] (opr) -- ++(0,.5) node[anchor=south] {original path reversed};
91 \draw[<-] (ppr) -- ++(-.5,0) node[anchor=east] {pen path reversed};
92 \end{tikzpicture}
93 \end{center}
94 What is important to note about this is that the ``pen'' isn't \emph{actually} dragged along the path, it is merely a simulation.
95 This can be shown with the following simple example.
96 The first is a continuous path that goes past the angle of the pen and thus the upstroke would involve pushing the pen.
97 The second is how it is meant to be done, the second line is drawn from top to bottom.
98 However, as the direction of the path isn't important, the same effect can be obtained by ``lifting the nib'' between the lines.
99 \begin{example}
100 \begin{center}
101 \begin{tikzpicture}
102 \pen (-135:.125) -- (45:.125);
103 \calligraphy (0,0) -- (1,0) -- (1,1);
104 \calligraphy (2,0) -- (3,0) (3,1) -- (3,0);
105 \calligraphy (4,0) -- (5,0) +(0,0) -- (5,1);
106 \end{tikzpicture}
107 \end{center}
108 \end{example}
109 It should work as expected providing the following golden rule is not violated:
110 \begin{quotation}
111 Never \emph{push} a calligraphic pen.
112 \end{quotation}
113 This is good advice for ordinary calligraphy as well, so a path that is realisable as an honest calligraphic path should be fine with this library.
114 Actually since, as remarked above, the direction of the path isn't important, a more accurate golden rule would be that one should never swap from pushing to pulling or vice versa without lifting the pen off the paper; but that isn't as succinct.
115 The paths for both pens and templates can be reasonably complicated.
116 They can contain gaps, but should not contain closed paths, nor rectangles.
117 The implementation works by breaking a path into its constituent pieces (broken up by ``move to''s) and working bit by bit.
118 \begin{example}
119 \begin{center}
120 \begin{tikzpicture}
121 \pen (-135:.25) -- (-135:.125) (45:.125) -- (45:.25);
122 \calligraphy (0,0) .. controls +(45:1) and +(-135:1) .. +(3,0) ++(1.5,0) .. controls +(-135:2) and +(45:2) .. +(0,-4) (0,-4) .. controls +(45:1) and +(-135:1) .. +(3,0);
123 \end{tikzpicture}
124 \end{center}
125 \end{example}
126 \section{Copperplate}
127 Copperplate pens are somewhat special.
128 They are ``thin'' so don't need the same treatment as a ``thick'' pen, but one should be able to vary the pressure with a copperplate pen to get a variation of thickness.
129 Specifying a copperplate pen is straightforward: it is a pen with no thickness.
130 \begin{example}
131 \begin{center}
132 \begin{tikzpicture}[line width=2pt]
133 \pen (0,0);
134 \calligraphy[heavy] (0,0) .. controls +(45:1) and +(-135:1) .. +(3,0) ++(1.5,0) .. controls +(-135:2) and +(45:2) .. +(0,-3) (0,-3) .. controls +(45:1) and +(-135:1) .. +(3,0);
135 \calligraphy[light] (4,0) .. controls +(45:1) and +(-135:1) .. +(3,0) ++(1.5,0) .. controls +(-135:2) and +(45:2) .. +(0,-3) (4,-3) .. controls +(45:1) and +(-135:1) .. +(3,0);
136 \end{tikzpicture}
137 \end{center}
138 \end{example}
139 With a copperplate pen, the segments of a path are tapered.
140 Copperplate and normal pens can be mixed.
141 Any part of the pen specification that has no length is treated as a copperplate pen.
142 \begin{example}
143 \begin{center}
144 \begin{tikzpicture}[line width=1pt]
145 \pen (-135:.125) -- (0,0) (45:.125);
146 \calligraphy (0,0) .. controls +(45:1) and +(-135:1) .. +(3,0) ++(1.5,0) .. controls +(-135:2) and +(45:2) .. +(0,-3) (0,-3) .. controls +(45:1) and +(-135:1) .. +(3,0);
147 \end{tikzpicture}
148 \end{center}
149 \end{example}
150 %% \section{Annotations}
151 %% As an addition, calligraphic paths can be annotated to show how they were constructed.
152 %% A path with an arrow is drawn at a set offset from the last part of the path.
153 %% \begin{example}
154 %% \begin{center}
155 %% \begin{tikzpicture}[line width=1pt]
156 %% \pen (-135:.125) -- (0,0) (45:.125);
157 %% \calligraphy[annotate] (0,0) .. controls +(45:1) and +(-135:1) .. +(3,0) ++(1.5,0) .. controls +(-135:2) and +(45:2) .. +(0,-3) (0,-3) .. controls +(45:1) and +(-135:1) .. +(3,0);
158 %% \end{tikzpicture}
159 %% \end{center}
160 %% \end{example}
161 \section{Style Options}
162 There are plenty of options for styling the paths and pens.
163 \subsection{Definition Options}
164 Internally, making a pen is a two-step process.
165 First a pen has to be \emph{defined} and then \emph{processed}.
166 To define a pen, the user has to specify a path.
167 That path is stored in a global macro and so can be accessed in throughout the document.
168 However, before being used, the pen has to be processed.
169 At this stage, the pen is converted from a macro in to a special object.
170 These special objects are local and cannot (at present) be made global.
171 Thus whilst a pen can be \emph{defined} inside a group, the \emph{processing} stage has to happen in the outermost group in which the pen is going to be used.
172 There is a shortcut command that (via a bit of suspicious hackery) does all this within a \Verb+tikzpicture+ group.
173 However, if a pen is to be used in several different pictures, it must be processed outside the group in which it is defined.
174 The following macros and keys are used to set up and use a pen.
175 %All the keys are in the \Verb+/pgf/calligraphy+ family.
176 \begin{itemize}
177 \item \DescribeMacro{define pen}If the \Verb+define pen+ key is specified on a path then that path will be used to define a pen.
178 It can take one option which will be the pen name, if not specified then \Verb+default+ is assumed.
179 The resulting path will not be counted for bounding box considerations.
180 When the pen is used, the origin will correspond to the path along which it is dragged.
181 \item \DescribeMacro{pen name}The key \Verb+pen name=name+ sets the name for the current pen.
182 This can be used either when defining or using a pen.
183 \item \DescribeMacro{\pen}\DescribeMacro{\definepen}The macros \Verb+\pen+ and \Verb+\definepen+ are analogous to the TikZ commands \Verb+\draw+ or \Verb+\fill+ in that they act like a path command but store the path as a pen.
184 The difference between them is that \Verb+\definepen+ is to be used outside a TikZ picture (it contains its own \Verb+\tikz+ command) and \Verb+\pen+ inside.
185 %% These macros also change the ``key family'' to \Verb+/pgf/calligraphy+ so that any further options do not need their full path.
186 %% \item \DescribeMacro{\processpen}The macro \Verb+\processpen+ processes a pen so that it is set up for using later on.
187 %% As remarked earlier, it has to be given at least at the outermost grouping of where it will be used.
188 %% It takes an optional argument which is the pen name.
189 %% This is only needed if the pen will be used in a group other than the one in which it is defined (or if the hackery that means this isn't needed with the \Verb+\pen+ command fails for some unknown reason).
190 \item \DescribeMacro{use pen}The key \Verb+use pen=name+ on a path means that that path should be ``stroked'' with the pen (\Verb+default+ if no name is given, or none specified via the \Verb+pen name+ key).
191 %% \item \DescribeMacro{\calligraphy}The macro \Verb+\calligraphy+ is a shortcut for specifying a path with the key \Verb+use pen+ already set.
192 %% This macro also changes the ``key family'' to \Verb+/pgf/calligraphy+ so that any further options do not need their full path.
193 \end{itemize}
194 \subsection{Style Options}
195 There are various options available for styling the calligraphic paths.
196 %% All of these are in the \Verb+/pgf/calligraphy+ key family, but the \Verb+\calligraphy+ command automatically switches to that family so the key path is not needed.
197 %% Any unknown keys are processed as follows:
198 %% \begin{enumerate}
199 %% \item A check is made to see if a pen of that name has been defined.
200 %% If so, that pen is used.
201 %% This is similar to the \Verb+\node[shape]+ syntax
202 %% \item A check is made to see if the unknown key corresponds to a colour.
203 %% If so, that colour is installed as the pen colour.
204 %% This is similar to the colour handling of TikZ paths.
205 %% (In fact, it uses the same code.)
206 %% \item All other unknown options are passed on to TikZ.
207 %% \end{enumerate}
208 The style options are as follows.
209 \begin{itemize}
210 \item \DescribeMacro{pen colour}The \Verb+pen colour+ style defines the default colour to be used.
211 Since calligraphic paths are sometimes filled and sometimes stroked, this ensures that the colour is used correctly.
212 \item \DescribeMacro{nib style}It is possible to style particular ``nibs'' (i.e., segments of the pen path) separately.
213 This is the \Verb+nib style+ option, which takes two arguments.
214 The first is the index of the part of the nib and the second is the style options to be applied.
215 \item \DescribeMacro{stroke style}It is also possible to style particular parts of the template path.
216 One way to do this is to use the \Verb+stroke style+ key, which takes two arguments.
217 The first is the index of the part of the stroke and the second is the style options to be applied.
218 \item \DescribeMacro{this stroke style}It is also possible to style particular parts of the template path as the path is constructed.
219 This is done by putting \Verb+[this stroke style={}]+ in the template path at the relevant part.
220 The style is saved and applied to that segment of the template path.
221 \item \DescribeMacro{taper}The tapering of copperplate paths can be controled by the \Verb+taper+ option.
222 It takes arguments \Verb+none+, \Verb+both+, \Verb+start+, and \Verb+end+.
223 \item \DescribeMacro{weight}\DescribeMacro{heavy}\DescribeMacro{light}Copperplate paths come in two ``weights'': \emph{heavy} and \emph{light}.
224 The weight also affects the tapering: by default a light path is tapered to nothing whilst a heavy path is tapered to the width of a light path.
225 Weights can be specified by either \Verb+weight=weight+ or just \Verb+heavy+ and \Verb+light+.
226 It is possible to change the weight for different components of a path using the \Verb+stroke style+ key.
227 With tapering, this means that one can easily vary from a light stroke to a heavy one.
228 The relevant widths are controlled by the keys \DescribeMacro{heavy line width}\Verb+heavy line width+ and the \DescribeMacro{light line width}\Verb+light line width+.
229 The \DescribeMacro{taper line width}\Verb+taper line width+, is set automatically by the weight but can be altered afterwards using the \Verb+taper line width+ key.
230 %% \item \DescribeMacro{annotate}The key \Verb+annotate+ switches on annotations.
231 %% The style of the annotations is controlled by the keys \DescribeMacro{annotation style}\Verb+annotation style+, \DescribeMacro{annotation shift}\Verb+annotation shift+ which controls how the annotation path is shifted from the final component of the calligraphic path, \DescribeMacro{annotation nodes style}\Verb+annotation nodes style+ for global style of the nodes, \DescribeMacro{annotation node style}\Verb+annotation node style+ for styling of particular nodes.
232 %% This latter takes two options: the node number and the style to be applied.
233 %% The annotation path and annotation node styles take ordinary TikZ styling options.
234 \end{itemize}
235 \begin{example}
236 \begin{center}
237 \begin{tikzpicture}
238 \calligraphy[pen colour=green,nib style={2}{color=red}] (0,0) .. controls +(45:1) and +(-135:1) .. +(3,0) ++(1.5,0) .. controls +(-135:2) and +(45:2) .. +(0,-3) (0,-3) .. controls +(45:1) and +(-135:1) .. +(3,0);
239 \calligraphy[line width=1pt] (0,-4) .. controls +(45:1) and +(-135:1) .. +(3,0) ++(1.5,0) .. controls +(-135:2) and +(45:2) .. +(0,-3) (0,-7) .. controls +(45:1) and +(-135:1) .. +(3,0);
240 \end{tikzpicture}
241 \end{center}
242 \end{example}
243 \section{Decorations}
244 If a TikZ/PGF decorations library is loaded prior to this library, then the \Verb+calligraphy+ library defines some decorations that use the calligraphic paths, specifically with the copperplate nib.
245 The current decorations are:
246 \begin{itemize}
247 \item \DescribeMacro{calligraphic brace}\Verb+calligraphic brace+ for a brace.
248 \item \DescribeMacro{calligraphic straight parenthesis}\Verb+calligraphic straight parenthesis+ for a parenthesis with straight middle component.
249 \item \DescribeMacro{calligraphic curved parenthesis}\Verb+calligraphic curved parenthesis+ for a parenthesis with a curved middle component.
250 \end{itemize}
251 All the above use the \Verb+amplitude+ option to specify their size.
252 The following is an example of their use, together with the standard \Verb+brace+ and the \Verb+delimiter+ key from the \Verb+matrix+ library for comparison.
253 \begin{example}
254 \begin{center}
255 \begin{tikzpicture}
256 \draw[decorate,decoration={calligraphic brace,amplitude=4mm},ultra thick] (0,0) -- (0,8);
257 \draw[line width=2pt,decorate,decoration={brace,amplitude=10},line cap=round] (1,0) -- ++(0,8);
258 \node[anchor=south west,minimum height=8cm,outer sep=0pt,left delimiter=\{] (a) at (2,0) {};
259 \draw[decorate,decoration={calligraphic straight parenthesis,amplitude=4mm},ultra thick] (3,0) -- ++(0,8);
260 \draw[decorate,decoration={calligraphic curved parenthesis,amplitude=4mm},ultra thick] (4,0) -- ++(0,8);
261 \node[anchor=south west,minimum height=8cm,outer sep=0pt,left delimiter=(] (a) at (5,0) {};
262 \end{tikzpicture}
263 \end{center}
264 \end{example}
265 \section{Pre-Defined Pens}
266 The following pens are predefined:
267 \begin{itemize}
268 \item \DescribeMacro{copperplate}\Verb+copperplate+:
269 \begin{example}
270 \begin{center}
271 \tikz \calligraphy[copperplate] (0,0) .. controls +(1,-1) and +(-1,1) .. ++(3,0) [this stroke style={light,taper=start}] +(0,0) .. controls +(1,-1) and +(-1,1) .. ++(3,0) [this stroke style={heavy}] +(0,0) .. controls +(1,-1) and +(-1,1) .. ++(3,0) [this stroke style={light,taper=end}];
272 \end{center}
273 \end{example}
274 \end{itemize}
275
276 \end{document}