summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/spath3/calligraphy.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/spath3/calligraphy.tex')
-rw-r--r--Master/texmf-dist/doc/latex/spath3/calligraphy.tex271
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}