summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/metapost/textpath/textpath.tex
blob: 4ecbb8a7e664f321390bd528fb1734dba75b6c7c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
\documentclass{article}
\usepackage{booktabs}
\usepackage{array}
\usepackage{graphicx}
\DeclareGraphicsRule{*}{mps}{*}{}
\usepackage{verbatim}
\newcommand*{\cmd}[1]{\texttt{#1}}
\newcommand*{\pkg}{\cmd{textpath.mp}}
\newcommand{\user}[1]{\emph{#1}}
\newenvironment{listing}{%
  \small%
  \verbatim%
}{%
  \endverbatim%
}
\begin{document}
\title{The \pkg\ package\thanks{This document describes \pkg\ v1.5.}}
\author{Stephan Hennig\thanks{stephanhennig@arcor.de}}
\date{\today}
\maketitle

\begin{abstract}
The MetaPost package \pkg\ provides macros to set text along a free path.  It differs from the \cmd{txp.mp} package in that is uses \LaTeX\ to typeset the text and therefore 8-bit characters, \emph{e.g.}, accented characters, are supported and text is kerned.
\end{abstract}



\section{A first example}\label{sec:firstexample}
The \pkg\ package provides a \cmd{textpath} macro, that takes three arguments:
\begin{enumerate}
\item a text string that is valid \LaTeX\ input,
\item a path the text should follow, and
\item a numeric value that controls justification of the text on the path.
\end{enumerate}
The macro returns a picture that contains the text transformed to the path.  A sample call to \cmd{textpath} could be

\begin{listing}
draw textpath("Greetings from MetaPost!", fullcircle scaled 50bp, 0);
\end{listing}

The resulting output is shown in figure~\ref{fig:firstexample}.
\begin{figure}[tp]
\begin{minipage}[t]{.45\linewidth}
  \centering
  \includegraphics{textpathfigs.1}
  \caption{Our first application.}
  \label{fig:firstexample}
\end{minipage}\hfill
\begin{minipage}[t]{.45\linewidth}
  \centering
  \includegraphics{textpathfigs.2}
  \caption{A refined variant.}
  \label{fig:secondexample}
\end{minipage}
\end{figure}

\user{Interesting, but not what I'd expect.}  Well, figure~\ref{fig:firstexample} looks exactly as what we formulated in our MetaPost programme above.  The text is drawn along a circle segment that starts at an angle of zero, runs counter clockwise and the text is left aligned on the path.  Left aligned in this context means that the text starts at the beginning of the path.

\user{But the text is inside the circle.}  Yes, by default, the text is typeset on the left-hand side of the path if you were virtually walking down the path.  There are configuration options to change that behaviour (see section~\ref{sec:textpathRotation}), but those won't help in this situation, since as a result the text would run right-to-left.

Instead, have a look at the following changes to our code and the resulting figure~\ref{fig:secondexample}:

\begin{listing}
path p;
p := reverse fullcircle rotated -90 scaled 50bp;
draw textpath("Greetings from MetaPost!", p, 0.5);
\end{listing}

\user{What a magic path declaration!}  The path now starts at an angle of $-90$ degrees and it runs clockwise.  Did you notice the last parameter to \cmd{textpath} changed to $0.5$ in the programme?  If it were zero, the text would start at the bottom of the circle and run clockwise along the outside of the circle.  With the alignment parameter set to $0.5$ the text is centered on the path.  That's the reason for rotating the start and end points of the circle to $-90$ degrees.

By the way, do you notice anything wrong with figure~\ref{fig:secondexample}?  We'll come back to that problem at the end of this manual.  The next section discusses the parameters of the \cmd{textpath} macro in detail.

\subsection{Text strings}
\subsubsection{Setting up the \pkg\ package}
Internally, the string you pass to \cmd{textpath} as the first argument is processed by \LaTeX\ by means of the \cmd{latexmp} package.  This is hardcoded, currently, but may change in future versions so that you can use conventional \cmd{btex...etex} commands or the \cmd{TEX} macro.

The \cmd{latexmp} package has to be set up with a proper \LaTeX\ preamble.  The easiest way to do so is by providing a preamble file (without \verb+\begin{document}+) and input \cmd{latexmp.mp} using the following lines:

\begin{listing}
input latexmp
setupLaTeXMP(preamblefile="mypreamble");
\end{listing}

The last step in setting up the \pkg\ package is adding the following line to the \LaTeX\ preamble in file \cmd{mypreamble.tex}:

\begin{listing}
\usepackage{textpathmp}
\end{listing}
Note the trailing ``mp'' in the \LaTeX\ package name!

\subsubsection{Restrictions on text input and output}\label{sec:restrictions}
Transforming text onto a path, \emph{i.e.}, rotating and shifting the text, should be done character by character, since otherwise there could be characters that move too far away from the path.  Unfortunately, MetaPost doesn't provide guaranteed character-wise access to a text picture generated by \LaTeX.  Therefore, some provisions have to be taken to enable characer-wise access.  Internally, on the \LaTeX\ side the text string passed to \cmd{textpath} is pre-processed by the \cmd{soul} package.

\paragraph{Invalid input}  Therefore, input must not contain any material \cmd{soul} can't handle.  If you're encountering errors from the \cmd{soul} package on the console delete the corresponding \cmd{ltx-???.tmp} file in your working directory and try with a simpler text string.  Explicitely, the following restrictions apply to input:
\begin{itemize}
\item Vertical material is not valid.
\item Rules are not supported.
\item Font selection commands aren't allowed inside a text string.  See section~\ref{sec:textpathFont} for a solution.
\item If you want to add arbitrary horizontal space in the copy, you should do that with \verb+\<{\kernXpt}+, where X is the desired space.
\end{itemize}
In general, try to stick to simple text.

\paragraph{Valid input}  However, input may contain:
\begin{itemize}
\item plain horizontal material,
\item accented characters:  These are fine in the input as long as you choose the correct input encoding in the \LaTeX\ preamble and you have a font that provides true accented characters, \emph{e.g.}, a font supporting T1 encoding.
\item mathematical copy:  Section~\ref{sec:textpathRaw} explains how to typeset formulae onto a path.
\end{itemize}

\paragraph{Output}  The following restrictions apply to the output of \cmd{textpath} \emph{et al.}:
\begin{itemize}
\item Ligatures are broken in the output.
\end{itemize}


\subsection{Paths}\label{sec:paths}
As mentioned before, by default, text is typeset on the left-hand side of a path.  That is, the text is rotated to have the natural slope of the path at the desired location.  Configuration options to change that behaviour are described in section~\ref{sec:textpathRotation}.

In case total text width is larger than total path length characters that don't fit on the path are clipped by default (see figure~\ref{fig:textpathClip}). Configuration options to change that behaviour are described in section~\ref{sec:textpathClip}.

\begin{figure}
\begin{minipage}[t]{.45\linewidth}
  \centering
  \includegraphics{textpathfigs.4}
  \caption{Text on a short horizontal path clipped and unclipped.}
  \label{fig:textpathClip}
\end{minipage}\hfill
\begin{minipage}[t]{.45\linewidth}
  \centering
  \includegraphics{textpathfigs.3}
  \caption{Using different fonts in a MetaPost graphic.}
  \label{fig:textpathFont}
\end{minipage}
\end{figure}


\subsection{Text justification}
Justification of the text on the path can be controlled by the third parameter~\cmd{j}, which is a numeric value.  Setting it to zero makes the text left aligned, \emph{i.e.}, text starts right at be beginning of a path.  A value of one makes the text right aligned, \emph{i.e.}, text ends at the end point of a path.  A value of $0.5$ centers text on a path.

There is a general rule:  the point at fraction \cmd{j} of the total text width is transformed to the point on the path at fraction \cmd{j} of the total path length.  Therefore, \cmd{j} should be from the intervall $[0,1]$.



\section{Handling different fonts}\label{sec:textpathFont}
The package provides a variant of the \cmd{textpath} macro called \cmd{textpathFont}, that differs from \cmd{textpath} in only one respect.  It takes an additional fourth argument.  That argument is a string containing a valid \LaTeX\ font selection command such as \verb+\itshape+.  The font selection string has to be given as the first argument.  The remaining arguments are the same as for \cmd{textpath} (see figure~\ref{fig:textpathFont}).

\begin{listing}
p := reverse fullcircle rotated -90;
draw textpathFont("\usefont{T1}{pzc}{m}{n}\huge", "Happy Birthday to",
  p scaled 400bp, 0.5) withcolor (1, 0.6, 0.2);
draw textpathFont("\usefont{T1}{bch}{m}{n}\large", "Daisy Duck!",
  p scaled 350bp, 0.5) withcolor (0.9, 0.3, 0.1);
\end{listing}


Since the \cmd{soul} package can't handle font selection commands in the copy, one were stuck to the font that is setup in the \LaTeX\ preamble for the whole MetaPost document.  The \cmd{textpathFont} macro accounts for that by getting the font selection separate from the text and applying it before the \cmd{soul} package comes into play.  Unfortunately, switching the font inside text still isn't possible that way.



\section{The raw interface}\label{sec:textpathRaw}
In case you're fine with \cmd{textpath} and \cmd{textpathFont} and you do not intend to typeset mathematical formulae along a path, you may savely skip this section and read on with section~\ref{sec:configuration} where configuration options are described.

The \pkg\ package provides a third macro \cmd{textpathRaw} to typeset material along a path.  This is the so called raw interface.  As we've seen in section~\ref{sec:restrictions}, input to \cmd{textpath} and \cmd{textpathFont} is pre-processed by the \cmd{soul} package.  In contrast, input to the raw interface isn't pre-processed.  Have a look at figure~\ref{fig:rawMetaPost} to see how MetaPost accesses arbitrary chunks of characters at once without pre-processing on the \LaTeX\ side.

\begin{figure}
\begin{minipage}[t]{.45\linewidth}
  \centering
  \includegraphics{textpathfigs.11}
  \caption{Transforming arbitrary chunks of characters at once using the raw interface.}
  \label{fig:rawMetaPost}
\end{minipage}\hfill
\begin{minipage}[t]{.45\linewidth}
  \centering
  \includegraphics{textpathfigs.12}
  \caption{A formula typeset along a path.}
  \label{fig:rawFormula}
\end{minipage}
\end{figure}

\user{Why is the word ``MetaPost'' broken between letters ``P'' and ``o''?}  In fact, MetaPost doesn't process \emph{arbitrary} chunks of characters.  It rather collects and processes chunks of characters that are typeset without artificial horizontal space between them.  That is, text is broken into chunks by MetaPost at inter word space, kerning, \emph{etc.}  Clearly, in our example kerning took place between glyphs ``P'' and ``o'' while other glyph pairs weren't kerned.

Arguments to the \cmd{textpathRaw} macro are the same as to the \cmd{textpath} macro.  The differences between \cmd{textpath} and \cmd{textpathRaw} are:
\begin{itemize}
\item Font selection commands are allowed in input to \cmd{textpathRaw}.
\item Rules are supported.
\item Manual horizontal space is allowed in the input.
\item Ligatures are preserved.
\end{itemize}

As we've seen in figure~\ref{fig:rawMetaPost}, macros \cmd{textpath} and \cmd{textpathFont} are much better suited to typeset plain text along a path than \cmd{textpathRaw}.  However, there is one application where \cmd{textpathRaw} performs better than \cmd{textpath}: mathematical formulae.  Have a look at figure~\ref{fig:rawFormula}.  Have you ever seen stuff like that with any other text processing or graphics application?

The reason \cmd{textpathRaw} doesn't fail as badly on mathematical input as it does on plain text is that in formulae characters are rarely typeset without extra space between each other.  That is, MetaPost quite often breaks formulae into chunks and hence naturally processes them character-wise.  The exception to this are operator names such as $\log$, $\sin$, $\arctan$ \emph{etc.\@} and sometimes products of variables.  The latter can be avoided by explicitely inserting \verb+\cdot+ between factors.

\user{What about more complicated formulae with fractions \emph{etc.}?}  Have a look at figure~\ref{fig:rawFraction}.  Since rules are explicitely supported by \cmd{textpathRaw} fractions are no problem.

\begin{figure}
  \centering
  \includegraphics{textpathfigs.13}
  \caption{A formula containing fractions.}
  \label{fig:rawFraction}
\end{figure}

\user{Awesome!  The rules are curved, too!}  Yes, since formulae can look awful otherwise the \pkg\ package puts some efforts into that.  Section~\ref{sec:textpathFancyStrokes} describes an option that lets you choose between curved and straight rules.

\user{Any restrictions?}  Well, on concave shapes formulae look even more ugly than plain text.  For a technical restriction, formulae shouldn't be of too large height and depth.  Section~\ref{sec:textpathCureSqrt} shows a solution to another problem with root operators not discussed so far.

That's it---almost.  The remaining chapter describes global variables to configure the \pkg\ package, \emph{i.e.}, the way macros \cmd{textpath}, \cmd{textpathFont} and \cmd{textpathRaw} work.  Quite some interesting effects can be achieved with certain settings.  So don't miss the last chapter!



\section{Configuration variables}\label{sec:configuration}
The \pkg\ offers several configuration options through global variables.  Some of them have already been mentioned in the other sections.  This chapter summarizes all configuration variables.

\subsection{\cmd{textpathClip}}\label{sec:textpathClip}
As explained in section~\ref{sec:paths} when total text width is larger than path length text that doesn't fit into the path boundaries is clipped.  Actually, the location of characters that exeed path boundaries is clipped to the boundaries first.  Then variable \cmd{textpathClip} is read and if it is set to zero value those characters are drawn at the boundary, acting as a visual marker that something went wrong, or, if \cmd{textpathClip} is set to one, those characters are omitted (see figure~\ref{fig:textpathClip}).  By default, \cmd{textpathClip} is set to one, that is, characters may be clipped.


\subsection{\cmd{textpathRepeat}}\label{sec:textpathRepeat}
Variable \cmd{textpathRepeat} determines the number of copys of the text string that should be typeset along a path. Valid are integer values greater or equal to one.  By default, \cmd{textpathRepeat} is set to one.  

Note, that the alignment parameter \cmd{j} still works when setting \cmd{textpathRepeat} to arbitrary values.  That is, for a value of zero text starts at the beginning of a path and for a value of one text ends at the end of a path.

\subsection{\cmd{textpathStretch} and \cmd{textpathHSpace}}\label{sec:textpathStretch}\label{sec:textpathHSpace}
When variable \cmd{textpathRepeat} is greater than one (see section~\ref{sec:textpathRepeat}), horizontal spacing between single copies of the text string is determined manually or automatically, depending on variable \cmd{textpathStretch}.  If \cmd{textpathStretch} is set to zero value variable \cmd{textpathHSpace} determines the spacing between text string copies. If \cmd{textpathStretch} is set to one, spacing is automatically calculated, which is the default.

Figure~\ref{fig:textpathHSpace} shows an example of manually spaced text copies.  Note, that the space on the left and right of the total text is quite unrelated to \cmd{textpathHSpace} and automatically results from path length, text width, the number of text copies, \cmd{textpathHSpace}, and the justification parameter \cmd{j}.

\begin{listing}
f := "\usefont{T1}{pzc}{m}{n}\Large";
p := subpath (5.7,6.3) of fullcircle scaled 1400bp;
draw p withcolor .8white;
textpathRepeat := 3;
textpathStretch := 0;
textpathHSpace := 10pt;
draw textpathFont(f, "Happy Birthday", p, 0.5) withcolor (1, 0.6, 0.2);
\end{listing}

\begin{figure}
  \centering
  \includegraphics{textpathfigs.5}
  \caption{Repeated text manually spaced and centered.}
  \label{fig:textpathHSpace}
\end{figure}

In contrast, when text copies are automatically spaced, \emph{i.e.}, \cmd{textpathStretch} is set to one, the sum of space before and after all text copies equals the space between text copies.  This is quite handy when typesetting text along a cyclic path as in figure~\ref{fig:textpathShift}.


\subsection{\cmd{textpathShift}}\label{sec:textpathShift}
Variable \cmd{textpathShift} determines the amount all characters are shifted orthogonally to a path (the base line).  Positive values result in characters shifted to the left of a path---looking into the natural direction of a path---, while negative values shift characters to the right of a path.

In figure~\ref{fig:textpathShift} the thick black border is both, the path our text should follow and the background of the text.  Therefore, we need to ``vertically'' center the text on the path.  A small negative value of \cmd{textpathShift} serves our purposes well.

\begin{listing}
% Font Brush Script Italic is available on CTAN.
f := "\usefont{T1}{pbsi}{xl}{n}\fontsize{2.1pt}{2.1pt}\selectfont";
w := 210bp;
h := .276w;
r := .19h;
p := (-.5w,0)--(-.5w,.5h-r)--quartercircle rotated -90 scaled (2r)
  shifted (-.5w,.5h)--(0,.5h);
p := p--reverse p reflectedabout ((0,-1),(0,1));
p := p--reverse p reflectedabout ((-1,0),(1,0))--cycle;
draw p withpen pensquare scaled 3.5pt;
textpathRepeat := 30;
textpathShift := -.6pt;
draw textpathFont(f, "Fa\ss' Dich kurz!", p, 0.5) withcolor white;
label(textext
  ("\usefont{T1}{bfu}{mb}{n}\fontsize{22pt}{22pt}\selectfont Telephonzelle"),
  origin);% Bitstream Futura
\end{listing}

\begin{figure}
  \centering
  \includegraphics{textpathfigs.10}
  \caption{An attempt to resemble the style of classic labels.  (Failed badly.)}
  \label{fig:textpathShift}
\end{figure}


\subsection{\cmd{textpathLetterSpace}}\label{sec:textpathLetterSpace}
If you're typesetting text along a path with a high curvature the text may look squeezed or letter-spaced, depending on path shape, because natural inter letter space refers to unrotated characters and is only proper near the base line of rotated characters.  On a convex shape, therefore, text can look letter-spaced where, in fact, it isn't.  In contrast, on a concave shape glyphs may touch each other.  Comparing figures~\ref{fig:firstexample} and~\ref{fig:secondexample} the latter looks lighter, since inter letter space raises with the distance from the base line.  The same effect can be seen in figure~\ref{fig:anchor}, \emph{e.g.}, between characters ``a'' and ``i''.

The \pkg\ package provides means to manually tweak inter letter space.  Before transforming a character onto the path the \pkg\ package inserts an additional amount of horizontal space of width \cmd{textpathLetterSpace} between all characters.  This variable is a good friend when shifting or rotating characters.  By default, \cmd{textpathLetterSpace} is set to zero, that is, text is typeset at its natural width.

Variable \cmd{textpathLetterSpace} has only effect when typesetting text through macros \cmd{textpath} and \cmd{textpathFont}.  In macro \cmd{textpathRaw} this variable is ignored.


\subsection{\cmd{textpathRotation}}\label{sec:textpathRotation}
In section~\ref{sec:paths} it was already mentioned that text turns out on the left-hand side of a path, by default. This is an appropriate setting for cultures where text is read left to right.

The \pkg\ package, internally, calculates for each character in the text string the position of its anchor point on the path and the slope of the path at that location.  The character is then rotated around its anchor point by an angle corresponding to the slope.  The anchor point of a character lies at its horizontal center on the base line (see figure~\ref{fig:anchor}).  Finally, the anchor point is translated to the required coordinates on the path.  As a result, characters appear on the left-hand side of a path.

\begin{figure}
\begin{minipage}[t]{1\linewidth}
  \centering
  \includegraphics{textpathfigs.6}
  \caption{The anchor point of a character.}
  \label{fig:anchor}
\end{minipage}
\end{figure}

You can manually apply an additional rotation to every character by setting variable \cmd{textpathRotation} to a non-zero value.  A value of, \emph{e.g.}, 180 degrees turns each character upside down, so that it turns out on the right-hand side of a path.  A value of, \emph{e.g.}, 90 degrees results in characters ``floating'' with the path.  By default, \cmd{textpathRotation} is set to zero.

In figure~\ref{fig:textpathRotation}, note that the heart shape is derived from half circles and the text would have been running on the inside of the path by default, cf. figure~\ref{fig:firstexample}.

\begin{listing}
string f, t;
path heart;
f := "\usefont{T1}{pzc}{m}{it}\tiny";
t := "Love";
heart := halfcircle shifted (-0.5bp,0bp)..{dir-50}(0bp,-1.5bp);
heart := heart--reverse heart reflectedabout ((0,0),(0,1))--cycle;
heart := heart scaled 60bp;
textpathRotation := 90;
textpathLetterSpace := 1pt;
textpathRepeat := 30;
draw textpathFont(f, t, heart, 0) withcolor red+0.1green;
\end{listing}

\begin{figure}
  \centering
  \includegraphics{textpathfigs.7}
  \caption{Automatically spaced text with an additional rotation of 90 degrees.}
  \label{fig:textpathRotation}
\end{figure}


\subsection{\cmd{textpathAbsRotation}}\label{sec:textpathAbsRotation}
The interpretation of variable \cmd{textpathRotation} changes when variable \cmd{textpathAbsRotation} is set to a value of one.  Then characters are rotated by \cmd{textpathRotation} degrees only, ignoring path slope (see figure~\ref{fig:textpathAbsRotation}).  By default, \cmd{textpathAbsRotation} is set to zero.

\begin{listing}
picture pic;
f := "\usefont{T1}{fwb}{m}{n}\Large";% From the emerald package
t := "Don't panic! Don't panic! Don't panic!";
p := origin
for i:=1 upto 20: ..(i, sind(i*45)) endfor;
p := p xscaled 20 yscaled 35;
textpathRotation := 0;
textpathAbsRotation := 1;
textpathLetterSpace := 6pt;
pic := textpathFont(f, t, p, 0);
background := black;
bboxmargin := 30bp;
unfill bbox pic;
draw pic withcolor red+green;
\end{listing}

\begin{figure}
  \centering
  \makebox[0pt][c]{%
    \includegraphics{textpathfigs.8}%
  }
  \caption{Text without rotation.}
  \label{fig:textpathAbsRotation}
\end{figure}

We could have used \cmd{textpathRepeat} instead of repeating the text manually in the last example as well.  But since that required some more letters to type I chose not to do so.  In case the path definition inside the for loop---or rather the for loop inside the path definition---in the last listing looks uncommon to you, have a look at chapter~10 of the MetaPost manual, where this usage is explained.


\subsection{\cmd{textpathFancyStrokes}}\label{sec:textpathFancyStrokes}
The remaining three variables apply only to macro \cmd{textpathRaw}.  In section~\ref{sec:textpathRaw} figure~\ref{fig:rawFraction} showed a formula containing fractions, where the rules were automatically bent to the shape of the path.  Variable \cmd{textpathFancyStrokes} determines if rules in the input to \cmd{textpathRaw} should appear curved or straight in the output.  A value of zero results in straight rules.  If \cmd{textpathFancyStrokes} is set to one, which is the default, the \pkg\ package tries to adjust the shape of rules to that of the path.

Figures~\ref{fig:textpathFancyStrokesZero} and~\ref{fig:textpathFancyStrokesOne} show a similar formula as in figure~\ref{fig:rawFraction}.  Clearly, both, the square root and the fraction look more decent with curved strokes.

\begin{figure}
\begin{minipage}[t]{.45\linewidth}
  \centering
  \includegraphics{textpathfigs.14}
  \caption{Straight rules in a formula.}
  \label{fig:textpathFancyStrokesZero}
\end{minipage}\hfill
\begin{minipage}[t]{.45\linewidth}
  \centering
  \includegraphics{textpathfigs.15}
  \caption{Curved rules in a formula.}
  \label{fig:textpathFancyStrokesOne}
\end{minipage}
\end{figure}


\subsection{\cmd{textpathStrokePrecision}}\label{sec:textpathStrokePrecision}
When you're typesetting formulae along paths with a high curvature it may be difficult for rules to follow the path.  Variable \cmd{textpathStrokePrecision} determines the number of auxillary points that are calculated along a stroke.  For higher values of \cmd{textpathStrokePrecision} strokes follow a path more precisely.  By default, \cmd{textpathStrokePrecision} is set to a value of ten, which should be enough for most cases.

This variable applies only if \cmd{textpathFancyStrokes} is set to one.  Otherwise, it is ignored.

\subsection{\cmd{textpathCureSqrt}}\label{sec:textpathCureSqrt}
Did you notice the small gap that is still present in the square root operator in figure~\ref{fig:textpathFancyStrokesOne}?  A root sign actually consists of two parts, a leading V part and a trailing horizontal rule spanning the arguments.  The V part, in fact, is a single glyph, while the rule is, well, a rule.  If typeset horizontally, both parts overlap so that they visually melt into one glyph.

When typeset onto a path, the V part is rotated according to the slope of the path at its anchor point, which lies at the horizontal center of the glyph.  The resulting rotating angle is slightly different from the rotating angle that should be applied to the top right corner of the glyph.  Therefore, V and rule part of a square root are missing each other and a gap becomes visible.

The \pkg\ package tries to fill this gap automatically when variable \cmd{textpathCureSqrt} is set to a value of one, which is the default.  In fact, in figure~\ref{fig:textpathFancyStrokesOne} this variable was manually set to zero to provoke the gap.  In figure~\ref{fig:textpathCureSqrt} the gap has been filled.  Don't expect too fancy results from this option in difficult cases.

This variable applies only if \cmd{textpathFancyStrokes} is set to one.  Otherwise, it is ignored.
Moreover, it only works when \cmd{textpathRepeat} is set to a value of one, \emph{i.e.}, there are no multiple copies of formulae.

\begin{figure}
\begin{minipage}[t]{.45\linewidth}
  \centering
  \includegraphics{textpathfigs.16}
  \caption{A curved square root without a gap.}
  \label{fig:textpathCureSqrt}
\end{minipage}\hfill
\begin{minipage}[t]{.45\linewidth}
  \centering
  \includegraphics{textpathfigs.9}
  \caption{Another logo that didn't fit as an example in the other sections.}
  \label{fig:proetcontra}
\end{minipage}\hfill
\end{figure}

\suppressfloats

\subsection{Summary}
Table~\ref{tab:configuration} lists all configuration variables, their default values and in what macros they have effect.

\begin{table}
  \centering
  \begin{tabular}{>{\ttfamily}l>{\raggedleft}p{3em}ccc}
    \normalfont variable name & \makebox[0pt][r]{default value} & \multicolumn{3}{c}{valid in macros}\\
     & & \cmd{textpath} & \cmd{textpathFont} & \cmd{textpathRaw}\\
    \addlinespace\toprule\addlinespace
    textpathClip & 1 & $+$ & $+$ & $+$\\
    textpathRepeat & 1 & $+$ & $+$ & $+$\\
    textpathStretch & 1 & $+$ & $+$ & $+$\\
    textpathHSpace & 0pt & $+$ & $+$ & $+$\\
    textpathShift & 0pt & $+$ & $+$ & $+$\\
    textpathLetterSpace & 0pt & $+$ & $+$ & $-$\\
    textpathRotation & 0 & $+$ & $+$ & $+$\\
    textpathAbsRotation & 0 & $+$ & $+$ & $+$\\
    textpathFancyStrokes & 1 & $-$ & $-$ & $+$\\
    textpathStrokePrecision & 10 & $-$ & $-$ & $+$\\
    textpathCureSqrt & 1 & $-$ & $-$ & $+$\\
%     textpathDebug & 0 & $+$ & $+$ & $+$\\
  \end{tabular}
  \caption{Summary of configuration variables.}
  \label{tab:configuration}
\end{table}


\section{Epilogue}
Do you remember when we asked about a problem with figure~\ref{fig:secondexample} in section~\ref{sec:firstexample}?  \user{Yes, the first and last characters do not visually line up properly!} Well spotted!  Actually, the code is correct.  The problem is that ``G'' and ``!'' have quite different glyph shapes.  When virtually drawing the bounding boxes of the rotated characters one realizes that the left-most and right-most points of the text on the path do line up.

\user{Is there a fix?}  There's no automatic solution.  If the text started, \emph{e.g.}, with letters ``B'', ``E'' or even ``W'' \emph{etc.\@} those characters would visually line up with an exclamation mark.  As a work around for letters ``C'', ``G'' \emph{etc.\@} the alignment parameter could be reduced to a value slightly less that 0.5.  But honestly, did you really notice the difference?

\user{Where's the source code of the last examples?}  The code of all figures shown in this manual can be found in file \cmd{textpathfigs.mp}, which is part of this package.

\user{What is the nice calligraphic font you're using throughout this manual?}  Since we're dealing with decorative graphics here, \textsc{urw} Zapf Chancery Medium Italic available through the \textsc{psnfss} package is used in many examples.  Other decorative fonts with ready-made \LaTeX\ support are Brush Script Italic or the fonts from the \textsc{Emerald} package.  Both packages are available on \textsc{ctan}.

\user{Anything else?} While you're asking, don't try to do too fancy stuff with this package.  Text---and mathematical copy---is most legible when typeset horizontally.  With increasing curvature of the base line legibility decreases fastly.  A decorative, but elegant look can be achieved best by just slightly indicating a curved base line, similar to figure~\ref{fig:textpathFont}.

\bigskip
\raggedright\itshape
Happy \TeX ing!\par
Stephan Hennig

\end{document}