path: root/Master/texmf-dist/doc/metapost/textpath/textpath.tex

\documentclass{article}
\usepackage{amssymb}
\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.6.}}
\author{Stephan Hennig\thanks{stephanhennig@arcor.de}}
\date{\today}
\maketitle

\begin{abstract}
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.
\end{abstract}

\suppressfloats


\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}
\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 text starts at the beginning of the path.

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

\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 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.

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 (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.

\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 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 formulae:  These are supported by a raw interface, see section~\ref{sec:textpathRaw}.  The standard macros don't support mathematical copy.
\item rules:  There's quite sophisticated support for rules in mathematical formulae, but only in the raw interface (see section~\ref{sec:textpathRaw}).
\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:Rotating}.

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

\begin{figure}
\centering
% \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 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]$.



\section{Handling different fonts}\label{sec:textpathFont}
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.

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}



\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.4}
  \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.5}
  \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 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?

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.6}
  \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:OptionsRaw} 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:OptionsRaw} 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 discusses all configuration variables in detail.

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

\begin{listing}
draw textpath("A text too long to fit onto p", p, 0);
begingroup
  interim textpathClip := 1;
  draw textpath("A text too long to fit onto p", p, 0);
endgroup;
\end{listing}

This is convenient since every \cmd{beginfig()} statement already opens a group.


\subsection{Repeating and Shifting}

\subsubsection{Variable \cmd{textpathRepeat}}
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.

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.

\subsubsection{Variables \cmd{textpathStretch} and \cmd{textpathHSpace}}
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.

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.

\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.7}
  \caption{Repeated text manually spaced and centered.}
  \label{fig:textpathHSpace}
  \vspace{\baselineskip}
  \includegraphics{textpathfigs.8}
  \caption{The same text automatically spaced, centered and left aligned.}
  \label{fig:textpathStretch}
\end{figure}



\subsubsection{Variable \cmd{textpathShift}}
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.

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.

\begin{listing}
% Font Brush ScriptX 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.9}
  \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.}
  \label{fig:textpathShift}
\end{figure}

\subsubsection{Variable \cmd{textpathLetterSpace}}
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''.

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

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{Rotating}\label{sec:Rotating}

\subsubsection{Variable \cmd{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 left-to-right reading cultures.

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.

\begin{figure}
\begin{minipage}[t]{.45\linewidth}
  \centering
  \includegraphics{textpathfigs.10}
  \caption{The anchor point of a character.}
  \label{fig:anchor}
\end{minipage}\hfill
\begin{minipage}[t]{.45\linewidth}
  \centering
  \includegraphics{textpathfigs.11}
  \caption{Text with an additional rotation of 90 degrees.}
  \label{fig:textpathRotation}
\end{minipage}
\end{figure}

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.

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}


\subsubsection{Variable \cmd{textpathAbsRotation}}
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.

\begin{figure}
  \centering
  \makebox[0pt][c]{%
    \includegraphics{textpathfigs.12}%
  }
  \caption{Text with an absolute rotation of zero degrees.}
  \label{fig:textpathAbsRotation}
\end{figure}

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

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.


\subsection{Clipping, Scaling and Draft Mode}\label{sec:ClippingScalingDraft}

\subsubsection{Variable \cmd{textpathClip}}
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.

\begin{figure}
\begin{minipage}[t]{.45\linewidth}
  \centering
  \includegraphics{textpathfigs.13}
  \caption{Text on a short horizontal path clipped, not clipped and automatically scaled.}
  \label{fig:textpathClipAutoScale}
\end{minipage}\hfill
\begin{minipage}[t]{.45\linewidth}
  \centering
  \includegraphics{textpathfigs.14}
  \caption{The same text in draft mode.}
  \label{fig:textpathDraft}
\end{minipage}
\end{figure}

Whenever the \pkg\ package notices text exceeding path boundaries one of the following warnings is shown on the console depending on variable \cmd{textpathClip}:

\begin{verbatim}
  Package textpath warning:  Overfull path!  Clipped.
\end{verbatim}
or
\begin{verbatim}
  Package textpath warning:  Overfull path!  Not Clipped.
\end{verbatim}

Clipping works well with \cmd{textpathRepeat} set to values larger than one.


\subsubsection{Variable \cmd{textpathAutoScale}}
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.

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.

Whenever text is scaled the following warning is output on the console (the scaling value might be different):

\begin{verbatim}
  Package textpath warning:  Overfull path!  Scaled to 0.66368.
\end{verbatim}

Scaling works well with \cmd{textpathRepeat} set to values larger than one.


\subsubsection{Variable \cmd{textpathDraft}}
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.

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.

By default, \cmd{textpathDraft} is set to zero, that is, draft mode is deactivated.



\subsection{Options for the raw interface}\label{sec:OptionsRaw}

\begin{figure}
\begin{minipage}[t]{.45\linewidth}
  \centering
  \includegraphics{textpathfigs.15}
  \caption{A formula with straight rules.}
  \label{fig:textpathFancyStrokesZero}
\end{minipage}\hfill
\begin{minipage}[t]{.45\linewidth}
  \centering
  \includegraphics{textpathfigs.16}
  \caption{A formula with curved rules.}
  \label{fig:textpathFancyStrokesOne}
\end{minipage}
\end{figure}

\subsubsection{Variable \cmd{textpathFancyStrokes}}
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.

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.


\subsubsection{Variable \cmd{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.


\subsubsection{Variable \cmd{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 not a glyph, but in most cases a plain rule.  If typeset horizontally, both parts overlap so that they visually melt into one glyph.

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

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.

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.

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.

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.

\begin{table}
\begin{minipage}[t]{.45\linewidth}
  \centering
  \begin{tabular}[t]{>{\ttfamily}l>{\ttfamily}r}
    \normalfont font name & \normalfont slot\\
    \addlinespace\toprule\addlinespace
         cmex10        & 112 \textrm{to} 116\\
         cmsy5         & 112\\
         cmsy6         & 112\\
         cmsy7         & 112\\
         cmsy8         & 112\\
         cmsy9         & 112\\
         cmsy10        & 112\\
         cmbsy10       & 112\\
         fourier-mex   & 114\\
         fourier-ms    & 112\\
         MnSymbolE5    & 186\\
         MnSymbolE5    & 189\\
         MnSymbolE10   & 186\\
  \end{tabular}
  \caption{Fonts supported by option \cmd{textpathCureSqrt}.}
  \label{tab:textpathCureSqrt}
\end{minipage}\hfill
\begin{minipage}[t]{.45\linewidth}
  \centering
  \begin{tabular}[t]{cl}
    bit & output\\
    \addlinespace\toprule\addlinespace
    0 & item\\
    1 & item's bounding box\\
    2 & item's anchor point\\
  \end{tabular}
\caption{The bits of variable \cmd{textpathDebug}.}
\label{tab:textpathDebug}
\end{minipage}
\end{table}


% \suppressfloats


\subsection{Debugging}\label{sec:Debugging}

\subsubsection{Variable \cmd{textpathDebug}}
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.

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

\begin{figure}%[t]
\begin{minipage}[t]{.45\linewidth}
  \centering
  \includegraphics{textpathfigs.19}
  \caption{Debug mode showing glyphs and bounding boxes.}
  \label{fig:textpathDebug3}
\end{minipage}\hfill
\begin{minipage}[t]{.45\linewidth}
  \centering
  \includegraphics{textpathfigs.20}
  \caption{Debug mode showing bounding boxes and anchor points.}
  \label{fig:textpathDebug6}
\end{minipage}
\end{figure}

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.

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

\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?



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

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



\section{Numeric considerations}
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.

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.



\section{Epilogue}
\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 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}.

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

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

\end{document}