Debian Codegraph @

texmf-dist/doc/metapost/textpath/textpath.tex

raw
1 \documentclass{article}
2 \usepackage{amssymb}
3 \usepackage{booktabs}
4 \usepackage{array}
5 \usepackage{graphicx}
6 \DeclareGraphicsRule{*}{mps}{*}{}
7 \usepackage{verbatim}
8 \newcommand*{\cmd}[1]{\texttt{#1}}
9 \newcommand*{\pkg}{\cmd{textpath.mp}}
10 \newcommand{\user}[1]{\emph{#1}}
11 \newenvironment{listing}{%
12 \small%
13 \verbatim%
14 }{%
15 \endverbatim%
16 }
17 \begin{document}
18 \title{The \pkg\ package\thanks{This document describes \pkg\ v1.6.}}
19 \author{Stephan Hennig\thanks{[email protected]}}
20 \date{\today}
21 \maketitle
22
23 \begin{abstract}
24 The MetaPost package \pkg\ provides macros to typeset 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. Moreover, even mathematical copy can be handled.
25 \end{abstract}
26
27 \suppressfloats
28
29
30 \section{A first example}\label{sec:firstexample}
31 The \pkg\ package provides a \cmd{textpath} macro, that takes three arguments:
32 \begin{enumerate}
33 \item a text string that is valid \LaTeX\ input,
34 \item a path the text should follow, and
35 \item a numeric value that controls justification of the text on the path.
36 \end{enumerate}
37 The macro returns a picture that contains the text transformed to the path. A sample call to \cmd{textpath} could be
38
39 \begin{listing}
40 draw textpath("Greetings from MetaPost!", fullcircle scaled 50bp, 0);
41 \end{listing}
42
43 The resulting output is shown in figure~\ref{fig:firstexample}.
44 \begin{figure}
45 \begin{minipage}[t]{.45\linewidth}
46 \centering
47 \includegraphics{textpathfigs.1}
48 \caption{Our first application.}
49 \label{fig:firstexample}
50 \end{minipage}\hfill
51 \begin{minipage}[t]{.45\linewidth}
52 \centering
53 \includegraphics{textpathfigs.2}
54 \caption{A refined variant.}
55 \label{fig:secondexample}
56 \end{minipage}
57 \end{figure}
58
59 \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 text starts at the beginning of the path.
60
61 \user{But the text is inside the circle.} Yes, by default, text is typeset on the left-hand side of a path---if you were virtually walking down the path. There are configuration options to change that behaviour (see section~\ref{sec:Rotating}), but those won't help in this situation, since as a result text would run right-to-left. Instead, have a look at the following changes to our code and the resulting figure~\ref{fig:secondexample}:
62
63 \begin{listing}
64 path p;
65 p := reverse fullcircle rotated -90 scaled 50bp;
66 draw textpath("Greetings from MetaPost!", p, 0.5);
67 \end{listing}
68
69 \user{What a magic path declaration!} The path now starts at an angle of $-90$ degrees and 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 start and end points of the circle to $-90$ degrees.
70
71 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.
72
73 \subsection{Text strings}
74 \subsubsection{Setting up the \pkg\ package}
75 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.
76
77 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:
78
79 \begin{listing}
80 input latexmp
81 setupLaTeXMP(preamblefile="mypreamble");
82 \end{listing}
83
84 The last step in setting up the \pkg\ package is adding the following line to the \LaTeX\ preamble in file \cmd{mypreamble.tex}:
85
86 \begin{listing}
87 \usepackage{textpathmp}
88 \end{listing}
89 Note the trailing ``mp'' in the \LaTeX\ package name!
90
91 \subsubsection{Restrictions on text input and output}\label{sec:restrictions}
92 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 (cf. figure~\ref{fig:rawMetaPost}). 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.
93
94 \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:
95 \begin{itemize}
96 \item Vertical material is not valid.
97 \item Font selection commands aren't allowed inside a text string. See section~\ref{sec:textpathFont} for a solution.
98 \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.
99 \end{itemize}
100 In general, try to stick to simple text.
101
102 \paragraph{Valid input} However, input may contain:
103 \begin{itemize}
104 \item plain horizontal material,
105 \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.
106 \item mathematical formulae: These are supported by a raw interface, see section~\ref{sec:textpathRaw}. The standard macros don't support mathematical copy.
107 \item rules: There's quite sophisticated support for rules in mathematical formulae, but only in the raw interface (see section~\ref{sec:textpathRaw}).
108 \end{itemize}
109
110 \paragraph{Output} The following restrictions apply to the output of \cmd{textpath} \emph{et al.}:
111 \begin{itemize}
112 \item Ligatures are broken in the output.
113 \end{itemize}
114
115
116 \subsection{Paths}\label{sec:paths}
117 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:Rotating}.
118
119 When a path is too short to carry all text, characters exceeding path boundaries are drawn at the boundaries, by default. Alternatively, text can be clipped or scaled automatically to fits onto the path. All configuration options of the \pkg\ package are described in detail in section~\ref{sec:ClippingScalingDraft}.
120
121 \begin{figure}
122 \centering
123 % \begin{minipage}[t]{.45\linewidth}
124 % \centering
125 \includegraphics{textpathfigs.3}
126 \caption{Using different fonts in a MetaPost graphic.}
127 \label{fig:textpathFont}
128 % \end{minipage}
129 \end{figure}
130
131
132 \subsection{Text justification}
133 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.
134
135 There is a general rule: the point at fraction \cmd{j} of total text width is transformed to the point on the path at fraction \cmd{j} of total path length. Therefore, \cmd{j} should be from the intervall $[0,1]$.
136
137
138
139 \section{Handling different fonts}\label{sec:textpathFont}
140 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 provides an additional macro \cmd{textpathFont} that accepts \LaTeX\ font selection commands in an additional string argument and applies those before the \cmd{soul} package comes into play. Unfortunately, switching the font inside text still isn't possible that way.
141
142 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}).
143
144 \begin{listing}
145 p := reverse fullcircle rotated -90;
146 draw textpathFont("\usefont{T1}{pzc}{m}{n}\huge", "Happy Birthday to",
147 p scaled 400bp, 0.5) withcolor (1, 0.6, 0.2);
148 draw textpathFont("\usefont{T1}{bch}{m}{n}\large", "Daisy Duck!",
149 p scaled 350bp, 0.5) withcolor (0.9, 0.3, 0.1);
150 \end{listing}
151
152
153
154 \section{The raw interface}\label{sec:textpathRaw}
155 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.
156
157 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.
158
159 \begin{figure}
160 \begin{minipage}[t]{.45\linewidth}
161 \centering
162 \includegraphics{textpathfigs.4}
163 \caption{Transforming arbitrary chunks of characters at once using the raw interface.}
164 \label{fig:rawMetaPost}
165 \end{minipage}\hfill
166 \begin{minipage}[t]{.45\linewidth}
167 \centering
168 \includegraphics{textpathfigs.5}
169 \caption{A formula typeset along a path.}
170 \label{fig:rawFormula}
171 \end{minipage}
172 \end{figure}
173
174 \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.
175
176 Arguments to the \cmd{textpathRaw} macro are the same as to the \cmd{textpath} macro. The differences between \cmd{textpath} and \cmd{textpathRaw} are:
177 \begin{itemize}
178 \item Font selection commands are allowed in input to \cmd{textpathRaw}.
179 \item Rules are supported.
180 \item Manual horizontal space is allowed in the input.
181 \item Ligatures are preserved.
182 \end{itemize}
183
184 As we see 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?
185
186 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.
187
188 \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.
189
190 \begin{figure}
191 \centering
192 \includegraphics{textpathfigs.6}
193 \caption{A formula containing fractions.}
194 \label{fig:rawFraction}
195 \end{figure}
196
197 \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:OptionsRaw} describes an option that lets you choose between curved and straight rules.
198
199 \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:OptionsRaw} shows a solution to another problem with root operators not discussed so far.
200
201 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!
202
203
204
205 \section{Configuration variables}\label{sec:Configuration}
206 The \pkg\ offers several configuration options through global variables. Some of them have already been mentioned in the other sections. This chapter discusses all configuration variables in detail.
207
208 Since all of the global variables have been defined as \cmd{newinternal}, changing a setting locally to a group is possible using an \cmd{interim} declaration. That is, the following code \emph{temporarily} switches clipping on inside \cmd{begingroup \ldots\ endgroup}:
209
210 \begin{listing}
211 draw textpath("A text too long to fit onto p", p, 0);
212 begingroup
213 interim textpathClip := 1;
214 draw textpath("A text too long to fit onto p", p, 0);
215 endgroup;
216 \end{listing}
217
218 This is convenient since every \cmd{beginfig()} statement already opens a group.
219
220
221 \subsection{Repeating and Shifting}
222
223 \subsubsection{Variable \cmd{textpathRepeat}}
224 If you want to place multiple copies of a piece of text along a path you don't have to manually copy it in the input. Instead, just pass the original text as an argument to \cmd{textpath} and set variable \cmd{textpathRepeat} to the required number of copies before calling \cmd{textpath}. Valid numbers for \cmd{textpathRepeat} are integer values greater or equal to one. By default, \cmd{textpathRepeat} is set to one.
225
226 Note, that the alignment parameter \cmd{j} still works when setting \cmd{textpathRepeat} to values greater than one. That is, for \cmd{j=0} the first text copy still starts at the beginning of a path and for \cmd{j=1} the last text copy ends at the end of a path.
227
228 \subsubsection{Variables \cmd{textpathStretch} and \cmd{textpathHSpace}}
229 When variable \cmd{textpathRepeat} is to a value greater than one, ``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 one, the amount of space that is inserted between text copies is automatically determined, which is the default. If \cmd{textpathStretch} is set to zero variable \cmd{textpathHSpace} determines the amount of space between text copies. Note, that \cmd{textpathStretch} has only effect when variable \cmd{textpathRepeat} is set to a value larger than one.
230
231 Figures~\ref{fig:textpathHSpace} and~\ref{fig:textpathStretch} show examples of manually and automatically spaced text copies. Note, that when text copies are automatically spaced 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}. You shouldn't be able to spot the start and end points of the path there other than by inspecting the code.
232
233 \begin{listing}
234 f := "\usefont{T1}{pzc}{m}{n}\Large";
235 p := subpath (5.7,6.3) of fullcircle scaled 1400bp;
236 draw p withcolor .8white;
237 textpathRepeat := 3;
238 textpathStretch := 0;
239 textpathHSpace := 10pt;
240 draw textpathFont(f, "Happy Birthday", p, 0.5) withcolor (1, 0.6, 0.2);
241 \end{listing}
242
243 \begin{figure}
244 \centering
245 \includegraphics{textpathfigs.7}
246 \caption{Repeated text manually spaced and centered.}
247 \label{fig:textpathHSpace}
248 \vspace{\baselineskip}
249 \includegraphics{textpathfigs.8}
250 \caption{The same text automatically spaced, centered and left aligned.}
251 \label{fig:textpathStretch}
252 \end{figure}
253
254
255
256 \subsubsection{Variable \cmd{textpathShift}}
257 Variable \cmd{textpathShift} determines the ``vertical'' shifting of characters. That is, text can be shifted orthogonally to a path (\emph{i.e.,} the baseline). Positive values of \cmd{textpathShift} 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.
258
259 In figure~\ref{fig:textpathShift} the thick black border should be both, the path our text follows and the background of the text. Therefore, we need to ``vertically'' center the text on the path. A small negative value for \cmd{textpathShift} serves our purposes well.
260
261 \begin{listing}
262 % Font Brush ScriptX Italic is available on CTAN.
263 f := "\usefont{T1}{pbsi}{xl}{n}\fontsize{2.1pt}{2.1pt}\selectfont";
264 w := 210bp;
265 h := .276w;
266 r := .19h;
267 p := (-.5w,0)--(-.5w,.5h-r)--quartercircle rotated -90 scaled (2r)
268 shifted (-.5w,.5h)--(0,.5h);
269 p := p--reverse p reflectedabout ((0,-1),(0,1));
270 p := p--reverse p reflectedabout ((-1,0),(1,0))--cycle;
271 draw p withpen pensquare scaled 3.5pt;
272 textpathRepeat := 30;
273 textpathShift := -.6pt;
274 draw textpathFont(f, "Fa\ss' Dich kurz!", p, 0.5) withcolor white;
275 label(textext
276 ("\usefont{T1}{bfu}{mb}{n}\fontsize{22pt}{22pt}\selectfont
277 Telephonzelle"), origin);% Bitstream Futura
278 \end{listing}
279
280 \begin{figure}
281 \centering
282 \includegraphics{textpathfigs.9}
283 \caption{An attempt to resemble the style of classic labels (failing badly). At least this is an example of automatically spacing and shifting text on a path.}
284 \label{fig:textpathShift}
285 \end{figure}
286
287 \subsubsection{Variable \cmd{textpathLetterSpace}}
288 When typesetting text along a path with a high curvature the resulting curved text may look squeezed or letter-spaced, depending on path shape. That's because natural inter-letter space refers to unrotated characters and is only proper near the baseline of rotated characters. On a convex shape, therefore, text tends to 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 baseline. The same effect can be seen in figure~\ref{fig:anchor}, \emph{e.g.}, between characters ``a'' and ``i''.
289
290 The \pkg\ package provides means to manually adjust 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. Finding a good value can be a tricky task, but activating debug bit~1 may help here (see section~\ref{sec:Debugging}).
291
292 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.
293
294
295 \subsection{Rotating}\label{sec:Rotating}
296
297 \subsubsection{Variable \cmd{textpathRotation}}
298 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 left-to-right reading cultures.
299
300 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 anchor point of a character lies on the baseline at the horizontal center of its bounding box (see figure~\ref{fig:anchor}). The character is then rotated around its anchor point by an angle corresponding to the slope. 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.
301
302 \begin{figure}
303 \begin{minipage}[t]{.45\linewidth}
304 \centering
305 \includegraphics{textpathfigs.10}
306 \caption{The anchor point of a character.}
307 \label{fig:anchor}
308 \end{minipage}\hfill
309 \begin{minipage}[t]{.45\linewidth}
310 \centering
311 \includegraphics{textpathfigs.11}
312 \caption{Text with an additional rotation of 90 degrees.}
313 \label{fig:textpathRotation}
314 \end{minipage}
315 \end{figure}
316
317 You can manually apply an additional rotation to all 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.
318
319 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}.
320
321 \begin{listing}
322 string f, t;
323 path heart;
324 f := "\usefont{T1}{pzc}{m}{it}\tiny";
325 t := "Love";
326 heart := halfcircle shifted (-0.5bp,0bp)..{dir-50}(0bp,-1.5bp);
327 heart := heart--reverse heart reflectedabout ((0,0),(0,1))--cycle;
328 heart := heart scaled 60bp;
329 textpathRotation := 90;
330 textpathLetterSpace := 1pt;
331 textpathRepeat := 30;
332 draw textpathFont(f, t, heart, 0) withcolor red+0.1green;
333 \end{listing}
334
335
336 \subsubsection{Variable \cmd{textpathAbsRotation}}
337 The interpretation of variable \cmd{textpathRotation} changes when variable \cmd{textpathAbsRotation} is set to a value of one. Then characters are rotated by a fixed angle of \cmd{textpathRotation} degrees, ignoring path slope (see figure~\ref{fig:textpathAbsRotation}). By default, \cmd{textpathAbsRotation} is set to zero.
338
339 \begin{figure}
340 \centering
341 \makebox[0pt][c]{%
342 \includegraphics{textpathfigs.12}%
343 }
344 \caption{Text with an absolute rotation of zero degrees.}
345 \label{fig:textpathAbsRotation}
346 \end{figure}
347
348 \begin{listing}
349 picture pic;
350 f := "\usefont{T1}{fwb}{m}{n}\Large";% From the emerald package
351 t := "Don't panic! Don't panic! Don't panic!";
352 p := origin
353 for i:=1 upto 20: ..(i, sind(i*45)) endfor;
354 p := p xscaled 20 yscaled 35;
355 textpathRotation := 0;
356 textpathAbsRotation := 1;
357 textpathLetterSpace := 6pt;
358 pic := textpathFont(f, t, p, 0);
359 background := black;
360 bboxmargin := 30bp;
361 unfill bbox pic;
362 draw pic withcolor red+green;
363 \end{listing}
364
365 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 convenient feature is explained.
366
367
368 \subsection{Clipping, Scaling and Draft Mode}\label{sec:ClippingScalingDraft}
369
370 \subsubsection{Variable \cmd{textpathClip}}
371 As explained in section~\ref{sec:paths} when total text width is larger than path length characters that don't fit into the path boundaries are clipped. Actually, characters whose anchor point exceeds path boundaries are moved to the corresponding end point of the path, first. Then variable \cmd{textpathClip} is asked whether those characters should be drawn or clipped. If variable \cmd{textpathClip} is set to one, such characters are clipped (first line in figure~\ref{fig:textpathClipAutoScale}). If it is set to zero value the characters are drawn at the boundaries, acting as a visual marker that something went wrong (second line in figure~\ref{fig:textpathClipAutoScale}). By default, \cmd{textpathClip} is set to zero, that is, no characters are lost.
372
373 \begin{figure}
374 \begin{minipage}[t]{.45\linewidth}
375 \centering
376 \includegraphics{textpathfigs.13}
377 \caption{Text on a short horizontal path clipped, not clipped and automatically scaled.}
378 \label{fig:textpathClipAutoScale}
379 \end{minipage}\hfill
380 \begin{minipage}[t]{.45\linewidth}
381 \centering
382 \includegraphics{textpathfigs.14}
383 \caption{The same text in draft mode.}
384 \label{fig:textpathDraft}
385 \end{minipage}
386 \end{figure}
387
388 Whenever the \pkg\ package notices text exceeding path boundaries one of the following warnings is shown on the console depending on variable \cmd{textpathClip}:
389
390 \begin{verbatim}
391 Package textpath warning: Overfull path! Clipped.
392 \end{verbatim}
393 or
394 \begin{verbatim}
395 Package textpath warning: Overfull path! Not Clipped.
396 \end{verbatim}
397
398 Clipping works well with \cmd{textpathRepeat} set to values larger than one.
399
400
401 \subsubsection{Variable \cmd{textpathAutoScale}}
402 When automatically generating documents clipping might not be an option due to potential loss of information. However, finding proper settings for all kinds of input may be a difficult---or impossible---task. Actually, when input is too long to fit onto a path the clean solution were to reflow text or rearrange the layout. If you can't afford that manual work, but still want to be sure that all text appears in the output you can instruct the \pkg\ package to automatically scale input so that it fits onto a path (last line in figure~\ref{fig:textpathClipAutoScale}). Clearly, legibility will suffer from scaling, too. But at least all text remains in order this way.
403
404 Automatic scaling can be activated by setting variable \cmd{textpathAutoScale} to one. Variable \cmd{textpathClip} is ignored in that case. If \cmd{textpathAutoScale} is set to zero, which is the default, scaling is never applied and \cmd{textpathClip} may take effect.
405
406 Whenever text is scaled the following warning is output on the console (the scaling value might be different):
407
408 \begin{verbatim}
409 Package textpath warning: Overfull path! Scaled to 0.66368.
410 \end{verbatim}
411
412 Scaling works well with \cmd{textpathRepeat} set to values larger than one.
413
414
415 \subsubsection{Variable \cmd{textpathDraft}}
416 So far, two ways to recognize overfull paths have been mentioned. When switching off clipping and scaling text that doesn't fit onto a path acts as a visual marker at path boundaries. Additionally, a warning is output on the console.
417
418 To further help spotting overfull paths the \pkg\ package provides a draft mode that can be activated by setting variable \cmd{textpathDraft} to one. In draft mode, if a path is overfull, instead of glyphs the filled bounding boxes of all glyphs are ouput. Clipping and scaling still takes place in draft mode (see figure~\ref{fig:textpathDraft}). However, when scaling is activated in draft mode, input is only scaled in width so that it remains large enough to be easy to spot.
419
420 By default, \cmd{textpathDraft} is set to zero, that is, draft mode is deactivated.
421
422
423
424 \subsection{Options for the raw interface}\label{sec:OptionsRaw}
425
426 \begin{figure}
427 \begin{minipage}[t]{.45\linewidth}
428 \centering
429 \includegraphics{textpathfigs.15}
430 \caption{A formula with straight rules.}
431 \label{fig:textpathFancyStrokesZero}
432 \end{minipage}\hfill
433 \begin{minipage}[t]{.45\linewidth}
434 \centering
435 \includegraphics{textpathfigs.16}
436 \caption{A formula with curved rules.}
437 \label{fig:textpathFancyStrokesOne}
438 \end{minipage}
439 \end{figure}
440
441 \subsubsection{Variable \cmd{textpathFancyStrokes}}
442 The remaining three variables apply only to macro \cmd{textpathRaw}. Figure~\ref{fig:rawFraction} in section~\ref{sec:textpathRaw} 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.
443
444 Figures~\ref{fig:textpathFancyStrokesZero} and~\ref{fig:textpathFancyStrokesOne} show a formula similar to that in figure~\ref{fig:rawFraction}. Clearly, both, the square root and the fraction look more decent with curved strokes.
445
446
447 \subsubsection{Variable \cmd{textpathStrokePrecision}}
448 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.
449
450 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.
451
452
453 \subsubsection{Variable \cmd{textpathCureSqrt}}
454 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 not a glyph, but in most cases a plain rule. If typeset horizontally, both parts overlap so that they visually melt into one glyph.
455
456 \begin{figure}
457 \begin{minipage}[t]{.45\linewidth}
458 \centering
459 \includegraphics{textpathfigs.17}
460 \caption{A curved square root without a gap.}
461 \label{fig:textpathCureSqrt}
462 \end{minipage}\hfill
463 \begin{minipage}[t]{.45\linewidth}
464 \centering
465 \includegraphics{textpathfigs.18}
466 \caption{Another logo that didn't fit as an example in the other sections.}
467 \label{fig:proetcontra}
468 \end{minipage}
469 \end{figure}
470
471 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 \emph{horizontal center} of a glyph (cf. figure~\ref{fig:anchor}). The left-most point of the rule, however, is rotated according to the slope of the path at the \emph{right-most point} of the V part glyph. Both angles are slightly different in general and therefore, V and rule part of a square root miss each other and a gap might become visible.
472
473 For some mathematical fonts 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.
474
475 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. Multiple root operators in \emph{one} formula are ok, however.
476
477 Table~\ref{tab:textpathCureSqrt} lists the font names and slots that are currently supported (known to the author to contain a root sign glyph). If you happen to use a mathematical character set that isn't supported, don't hesitate to contact me. I'd be happy to add them.
478
479 \begin{table}
480 \begin{minipage}[t]{.45\linewidth}
481 \centering
482 \begin{tabular}[t]{>{\ttfamily}l>{\ttfamily}r}
483 \normalfont font name & \normalfont slot\\
484 \addlinespace\toprule\addlinespace
485 cmex10 & 112 \textrm{to} 116\\
486 cmsy5 & 112\\
487 cmsy6 & 112\\
488 cmsy7 & 112\\
489 cmsy8 & 112\\
490 cmsy9 & 112\\
491 cmsy10 & 112\\
492 cmbsy10 & 112\\
493 fourier-mex & 114\\
494 fourier-ms & 112\\
495 MnSymbolE5 & 186\\
496 MnSymbolE5 & 189\\
497 MnSymbolE10 & 186\\
498 \end{tabular}
499 \caption{Fonts supported by option \cmd{textpathCureSqrt}.}
500 \label{tab:textpathCureSqrt}
501 \end{minipage}\hfill
502 \begin{minipage}[t]{.45\linewidth}
503 \centering
504 \begin{tabular}[t]{cl}
505 bit & output\\
506 \addlinespace\toprule\addlinespace
507 0 & item\\
508 1 & item's bounding box\\
509 2 & item's anchor point\\
510 \end{tabular}
511 \caption{The bits of variable \cmd{textpathDebug}.}
512 \label{tab:textpathDebug}
513 \end{minipage}
514 \end{table}
515
516
517 % \suppressfloats
518
519
520 \subsection{Debugging}\label{sec:Debugging}
521
522 \subsubsection{Variable \cmd{textpathDebug}}
523 There is one variable left to be described. For debugging purposes variable \cmd{textpathDebug} lets you control if and how all items, \emph{i.e.}, glyphs and rules, are output. For every item in the input it can be controlled if the item, the item's bounding box, and the item's anchor point shall be drawn. Bits 0 to~2 of variable \cmd{textpathDebug} determine what to output. Table~\ref{tab:textpathDebug} shows the correspondence between bits in \cmd{textpathDebug} and the details to output.
524
525 Bits can be set independently. That is, for a value of, \emph{e.g.}, $3=1+2=2^0+2^1$ all text (and rules) are drawn together with the glyph's bounding box (see figure~\ref{fig:textpathDebug3}), whereas for a value of $6=2+4=2^1+2^2$ bounding boxes and anchor points are drawn (see figure~\ref{fig:textpathDebug6}).
526
527 \begin{figure}%[t]
528 \begin{minipage}[t]{.45\linewidth}
529 \centering
530 \includegraphics{textpathfigs.19}
531 \caption{Debug mode showing glyphs and bounding boxes.}
532 \label{fig:textpathDebug3}
533 \end{minipage}\hfill
534 \begin{minipage}[t]{.45\linewidth}
535 \centering
536 \includegraphics{textpathfigs.20}
537 \caption{Debug mode showing bounding boxes and anchor points.}
538 \label{fig:textpathDebug6}
539 \end{minipage}
540 \end{figure}
541
542 Bounding boxes are drawn with the \cmd{currentpen}. Anchor points are represented by filled circles with a diameter of 3bp. An exception are anchor points of fancy rules, that can't be shown, currently.
543
544 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. When drawing the bounding boxes of the characters one realizes that the left-most and right-most points of the glyph's bounding boxes on the path do line up (see, \emph{e.g.}, figure~\ref{fig:textpathDebug3}).
545
546 \user{Is there a fix?} There's no automatic solution. The problem is that ``G'' and ``!'' have quite different glyph shapes. 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?
547
548
549
550 \subsection{Summary}
551 Table~\ref{tab:configuration} lists all configuration variables, their default values and in what macros they have effect.
552
553 \begin{table}
554 \centering
555 \makebox[0pt][c]{%
556 \begin{tabular}{>{\ttfamily}l>{\raggedleft}p{3em}ccc}
557 \normalfont variable name & \makebox[0pt][r]{default value} & \multicolumn{2}{c}{valid in macros}\\
558 & & \cmd{textpath,} \\ & & \cmd{textpathFont} & \cmd{textpathRaw}\\
559 \addlinespace\toprule\addlinespace
560 textpathRepeat & 1 & \checkmark & \checkmark\\
561 textpathStretch & 1 & \checkmark & \checkmark\\
562 textpathHSpace & 0pt & \checkmark & \checkmark\\
563 textpathShift & 0pt & \checkmark & \checkmark\\
564 textpathLetterSpace & 0pt & \checkmark & \\
565 textpathRotation & 0 & \checkmark & \checkmark\\
566 textpathAbsRotation & 0 & \checkmark & \checkmark\\
567 textpathClip & 1 & \checkmark & \checkmark\\
568 textpathAutoScale & 0 & \checkmark & \checkmark\\
569 textpathDraft & 0 & \checkmark & \checkmark\\
570 textpathFancyStrokes & 1 & & \checkmark\\
571 textpathStrokePrecision & 10 & & \checkmark\\
572 textpathCureSqrt & 1 & & \checkmark\\
573 textpathDebug & 1 & \checkmark & \checkmark\\
574 \end{tabular}%
575 }
576 \caption{Summary of configuration variables.}
577 \label{tab:configuration}
578 \end{table}
579
580
581
582 \section{Numeric considerations}
583 Internally, current MetaPost versions use 16-bit fixed point calculations. However, the largest value that can be stored in a variable is $4096=2^{12}$ (big points). At one point, the \pkg\ package needs to calculate and store the length of a path \cmd{p}. The largest radius of a full circle passed to \cmd{textpath} is therefore approx. 651bp = 9in = 22cm, a bit more than the width of paper formats letter or \textsc{din}~A4. MetaPost is able to handle full circles with a larger radius, however, it cannot compute and store their path length.
584
585 To typeset text along circular paths with a larger radius, the solution is just not to pass to \cmd{textpath} a \cmd{fullcircle scaled 2r}, but to build paths with \cmd{halfcircle}, \cmd{quartercircle} or, even better, just select a minimal sub-path of, \emph{e.g.}, a \cmd{fullcircle} with the \cmd{subpath} command.
586
587
588
589 \section{Epilogue}
590 \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.
591
592 \user{What is the nice calligraphic font you're using throughout this manual?} Since we're mostly dealing with decorative graphics here, \textsc{urw} Zapf Chancery Medium Italic is used in many exampless. This font is part of the \textsc{psnfss} package and should already be installed in your \cmd{texmf} tree. Other decorative fonts with ready-made \LaTeX\ support are Brush ScriptX Italic or the fonts from the Emerald package. All packages are available on \textsc{ctan}.
593
594 \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 baseline legibility decreases fastly. A decorative, but elegant look can be achieved best with large fonts and just slightly indicating a curved baseline, similar to figure~\ref{fig:textpathFont}.
595
596 \bigskip
597 \raggedright\itshape
598 Happy \TeX ing!\par
599 Stephan Hennig
600
601 \end{document}