diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/spath3/calligraphy.tex')
| -rw-r--r-- | Master/texmf-dist/doc/latex/spath3/calligraphy.tex | 271 |
1 files changed, 271 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/spath3/calligraphy.tex b/Master/texmf-dist/doc/latex/spath3/calligraphy.tex new file mode 100644 index 00000000000..7690e5c5b73 --- /dev/null +++ b/Master/texmf-dist/doc/latex/spath3/calligraphy.tex @@ -0,0 +1,271 @@ +\immediate\write18{tex spath3_doc.dtx} +\documentclass{ltxdoc} +\usepackage[T1]{fontenc} +\usepackage{trace} +\usepackage{lmodern} +\usepackage{morefloats} +\usepackage{tikz} +\usetikzlibrary{decorations.pathreplacing,calligraphy,matrix} +\usepackage[numbered]{hypdoc} +\definecolor{lstbgcolor}{rgb}{0.9,0.9,0.9} + +\usepackage{listings} +\lstloadlanguages{[LaTeX]TeX} +\lstset{ + breakatwhitespace=true, + breaklines=true, + language=[LaTeX]TeX, + basicstyle=\small\ttfamily, + keepspaces=true, + columns=fullflexible +} + +\usepackage{fancyvrb} + +\newenvironment{example} + {\VerbatimEnvironment + \begin{VerbatimOut}{example.out}} + {\end{VerbatimOut} + \begin{center} + \setlength{\parindent}{0pt} + \fbox{\begin{minipage}{.9\linewidth} + \lstinputlisting[]{example.out} + \end{minipage}} + + \fbox{\begin{minipage}{.9\linewidth} + \input{example.out} + \end{minipage}} +\end{center} +} + +\providecommand*{\url}{\texttt} +\GetFileInfo{spath3.sty} + +\title{The \textsf{calligraphy} Package: Documentation} +\author{Andrew Stacey \\ \url{loopspace@mathforge.org}} +\date{\fileversion~from \filedate} + +\begin{document} + +\maketitle + + \section{Pre-Introduction} + This library is built on top of a package for manipulating PGF's \emph{soft paths} called \texttt{spath3}. + Version 2.0 of \texttt{spath3} involved considerable reorganisation of the code. + I tried to ensure that this didn't affect this library but it is extremely likely that I wasn't fully successful. + 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. + + \section{Introduction} +The \Verb+calligraphy+ TikZ library is designed to enable calligraphic style drawings in TikZ. +The idea is to be able to ``stroke'' a line with a ``pen''. +As a simple example, compare the two lines in the following picture. + +\begin{example} +\begin{center} +\begin{tikzpicture} +\pen (-135:.25) -- (45:.25); +\draw[line width=.5cm] (0,0) .. controls +(45:1) and +(-135:1) .. ++(3,0); +\calligraphy (0,-1) .. controls +(45:1) and +(-135:1) .. ++(3,0); +\end{tikzpicture} +\end{center} +\end{example} + +The paths are identical in definition but the first is drawn using the standard TikZ path with a line width of .5cm. +The second is ``stroked'' with a calligraphic pen of width .5cm angled at 45 degrees. +\section{How It Works} +To know how to use this library, it is worth knowing a little about how it works. +A ``pen'' is a path, as is the line that is the template for the pen stroke. +The two paths are joined together to form a region which is filled. +Thus in constructing the example given in the introduction, the following path is built. +\begin{center} +\begin{tikzpicture} +\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); +\draw[<-] (op) -- ++(0,-.5) node[anchor=north] {original path}; +\draw[<-] (pp) -- ++(.5,0) node[anchor=west] {pen path}; +\draw[<-] (opr) -- ++(0,.5) node[anchor=south] {original path reversed}; +\draw[<-] (ppr) -- ++(-.5,0) node[anchor=east] {pen path reversed}; +\end{tikzpicture} +\end{center} +What is important to note about this is that the ``pen'' isn't \emph{actually} dragged along the path, it is merely a simulation. +This can be shown with the following simple example. +The first is a continuous path that goes past the angle of the pen and thus the upstroke would involve pushing the pen. +The second is how it is meant to be done, the second line is drawn from top to bottom. +However, as the direction of the path isn't important, the same effect can be obtained by ``lifting the nib'' between the lines. +\begin{example} +\begin{center} +\begin{tikzpicture} +\pen (-135:.125) -- (45:.125); +\calligraphy (0,0) -- (1,0) -- (1,1); +\calligraphy (2,0) -- (3,0) (3,1) -- (3,0); +\calligraphy (4,0) -- (5,0) +(0,0) -- (5,1); +\end{tikzpicture} +\end{center} +\end{example} +It should work as expected providing the following golden rule is not violated: +\begin{quotation} +Never \emph{push} a calligraphic pen. +\end{quotation} +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. +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. +The paths for both pens and templates can be reasonably complicated. +They can contain gaps, but should not contain closed paths, nor rectangles. +The implementation works by breaking a path into its constituent pieces (broken up by ``move to''s) and working bit by bit. +\begin{example} +\begin{center} +\begin{tikzpicture} +\pen (-135:.25) -- (-135:.125) (45:.125) -- (45:.25); +\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); +\end{tikzpicture} +\end{center} +\end{example} +\section{Copperplate} +Copperplate pens are somewhat special. +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. +Specifying a copperplate pen is straightforward: it is a pen with no thickness. +\begin{example} +\begin{center} +\begin{tikzpicture}[line width=2pt] +\pen (0,0); +\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); +\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); +\end{tikzpicture} +\end{center} +\end{example} +With a copperplate pen, the segments of a path are tapered. +Copperplate and normal pens can be mixed. +Any part of the pen specification that has no length is treated as a copperplate pen. +\begin{example} +\begin{center} +\begin{tikzpicture}[line width=1pt] +\pen (-135:.125) -- (0,0) (45:.125); +\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); +\end{tikzpicture} +\end{center} +\end{example} +%% \section{Annotations} +%% As an addition, calligraphic paths can be annotated to show how they were constructed. +%% A path with an arrow is drawn at a set offset from the last part of the path. +%% \begin{example} +%% \begin{center} +%% \begin{tikzpicture}[line width=1pt] +%% \pen (-135:.125) -- (0,0) (45:.125); +%% \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); +%% \end{tikzpicture} +%% \end{center} +%% \end{example} +\section{Style Options} +There are plenty of options for styling the paths and pens. +\subsection{Definition Options} +Internally, making a pen is a two-step process. +First a pen has to be \emph{defined} and then \emph{processed}. +To define a pen, the user has to specify a path. +That path is stored in a global macro and so can be accessed in throughout the document. +However, before being used, the pen has to be processed. +At this stage, the pen is converted from a macro in to a special object. +These special objects are local and cannot (at present) be made global. +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. +There is a shortcut command that (via a bit of suspicious hackery) does all this within a \Verb+tikzpicture+ group. +However, if a pen is to be used in several different pictures, it must be processed outside the group in which it is defined. +The following macros and keys are used to set up and use a pen. +%All the keys are in the \Verb+/pgf/calligraphy+ family. +\begin{itemize} +\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. +It can take one option which will be the pen name, if not specified then \Verb+default+ is assumed. +The resulting path will not be counted for bounding box considerations. +When the pen is used, the origin will correspond to the path along which it is dragged. +\item \DescribeMacro{pen name}The key \Verb+pen name=name+ sets the name for the current pen. +This can be used either when defining or using a pen. +\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. +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. +%% These macros also change the ``key family'' to \Verb+/pgf/calligraphy+ so that any further options do not need their full path. +%% \item \DescribeMacro{\processpen}The macro \Verb+\processpen+ processes a pen so that it is set up for using later on. +%% As remarked earlier, it has to be given at least at the outermost grouping of where it will be used. +%% It takes an optional argument which is the pen name. +%% 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). +\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). +%% \item \DescribeMacro{\calligraphy}The macro \Verb+\calligraphy+ is a shortcut for specifying a path with the key \Verb+use pen+ already set. +%% This macro also changes the ``key family'' to \Verb+/pgf/calligraphy+ so that any further options do not need their full path. +\end{itemize} +\subsection{Style Options} +There are various options available for styling the calligraphic paths. +%% 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. +%% Any unknown keys are processed as follows: +%% \begin{enumerate} +%% \item A check is made to see if a pen of that name has been defined. +%% If so, that pen is used. +%% This is similar to the \Verb+\node[shape]+ syntax +%% \item A check is made to see if the unknown key corresponds to a colour. +%% If so, that colour is installed as the pen colour. +%% This is similar to the colour handling of TikZ paths. +%% (In fact, it uses the same code.) +%% \item All other unknown options are passed on to TikZ. +%% \end{enumerate} +The style options are as follows. +\begin{itemize} +\item \DescribeMacro{pen colour}The \Verb+pen colour+ style defines the default colour to be used. +Since calligraphic paths are sometimes filled and sometimes stroked, this ensures that the colour is used correctly. +\item \DescribeMacro{nib style}It is possible to style particular ``nibs'' (i.e., segments of the pen path) separately. +This is the \Verb+nib style+ option, which takes two arguments. +The first is the index of the part of the nib and the second is the style options to be applied. +\item \DescribeMacro{stroke style}It is also possible to style particular parts of the template path. +One way to do this is to use the \Verb+stroke style+ key, which takes two arguments. +The first is the index of the part of the stroke and the second is the style options to be applied. +\item \DescribeMacro{this stroke style}It is also possible to style particular parts of the template path as the path is constructed. +This is done by putting \Verb+[this stroke style={}]+ in the template path at the relevant part. +The style is saved and applied to that segment of the template path. +\item \DescribeMacro{taper}The tapering of copperplate paths can be controled by the \Verb+taper+ option. +It takes arguments \Verb+none+, \Verb+both+, \Verb+start+, and \Verb+end+. +\item \DescribeMacro{weight}\DescribeMacro{heavy}\DescribeMacro{light}Copperplate paths come in two ``weights'': \emph{heavy} and \emph{light}. +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. +Weights can be specified by either \Verb+weight=weight+ or just \Verb+heavy+ and \Verb+light+. +It is possible to change the weight for different components of a path using the \Verb+stroke style+ key. +With tapering, this means that one can easily vary from a light stroke to a heavy one. +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+. +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. +%% \item \DescribeMacro{annotate}The key \Verb+annotate+ switches on annotations. +%% 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. +%% This latter takes two options: the node number and the style to be applied. +%% The annotation path and annotation node styles take ordinary TikZ styling options. +\end{itemize} +\begin{example} +\begin{center} +\begin{tikzpicture} +\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); +\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); +\end{tikzpicture} +\end{center} +\end{example} +\section{Decorations} +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. +The current decorations are: +\begin{itemize} +\item \DescribeMacro{calligraphic brace}\Verb+calligraphic brace+ for a brace. +\item \DescribeMacro{calligraphic straight parenthesis}\Verb+calligraphic straight parenthesis+ for a parenthesis with straight middle component. +\item \DescribeMacro{calligraphic curved parenthesis}\Verb+calligraphic curved parenthesis+ for a parenthesis with a curved middle component. +\end{itemize} +All the above use the \Verb+amplitude+ option to specify their size. +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. +\begin{example} +\begin{center} +\begin{tikzpicture} +\draw[decorate,decoration={calligraphic brace,amplitude=4mm},ultra thick] (0,0) -- (0,8); +\draw[line width=2pt,decorate,decoration={brace,amplitude=10},line cap=round] (1,0) -- ++(0,8); +\node[anchor=south west,minimum height=8cm,outer sep=0pt,left delimiter=\{] (a) at (2,0) {}; +\draw[decorate,decoration={calligraphic straight parenthesis,amplitude=4mm},ultra thick] (3,0) -- ++(0,8); +\draw[decorate,decoration={calligraphic curved parenthesis,amplitude=4mm},ultra thick] (4,0) -- ++(0,8); +\node[anchor=south west,minimum height=8cm,outer sep=0pt,left delimiter=(] (a) at (5,0) {}; +\end{tikzpicture} +\end{center} +\end{example} +\section{Pre-Defined Pens} +The following pens are predefined: +\begin{itemize} +\item \DescribeMacro{copperplate}\Verb+copperplate+: +\begin{example} +\begin{center} +\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}]; +\end{center} +\end{example} +\end{itemize} + +\end{document} |