| 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} |