textpath 1.6 for Stephan

git-svn-id: svn://tug.org/texlive/trunk@3968 c570f23f-e606-0410-a88d-b1316a301751

6 files changed, 434 insertions, 221 deletions

diff --git a/Master/texmf-dist/doc/metapost/textpath/CHANGES b/Master/texmf-dist/doc/metapost/textpath/CHANGES
new file mode 100644
index 00000000000..6602622515c
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/textpath/CHANGES
@@ -0,0 +1,12 @@
+Version 1.6 released on 2007-02-11:
+* Fixed: a problem with multiple root signs and textpathCureSqrt=1
+
+* Added: configuration variables
+    textpathAutoScale
+    textpathDraft
+    textpathDebug
+  These options, especially textpathAutoScale, were introduced
+  to help with automatic document generation.
+* Added: Numeric restrictions are now discussed in the manual.
+  
+* Changed: Default value of textpathClip is now 0.
diff --git a/Master/texmf-dist/doc/metapost/textpath/README b/Master/texmf-dist/doc/metapost/textpath/README
index 7f75a43ae3b..4c1d1f85f2e 100644
--- a/Master/texmf-dist/doc/metapost/textpath/README
+++ b/Master/texmf-dist/doc/metapost/textpath/README
@@ -2,7 +2,7 @@
 % http://www.ctan.org/tex-archive/help/Catalogue/licenses.lppl.html
 % for the details of that license.
 
-package: textpath v1.5 2006/12/8
+package: textpath v1.6 2007/02/11
 author: Stephan Hennig (stephanhennig@arcor.de)
 
 
diff --git a/Master/texmf-dist/doc/metapost/textpath/textpath.pdf b/Master/texmf-dist/doc/metapost/textpath/textpath.pdf
index 6abe7f6633b..0d7972b563d 100644
--- a/Master/texmf-dist/doc/metapost/textpath/textpath.pdf
+++ b/Master/texmf-dist/doc/metapost/textpath/textpath.pdf
diff --git a/Master/texmf-dist/doc/metapost/textpath/textpath.tex b/Master/texmf-dist/doc/metapost/textpath/textpath.tex
index 4ecbb8a7e66..6ef26235238 100644
--- a/Master/texmf-dist/doc/metapost/textpath/textpath.tex
+++ b/Master/texmf-dist/doc/metapost/textpath/textpath.tex
@@ -1,4 +1,5 @@
 \documentclass{article}
+\usepackage{amssymb}
 \usepackage{booktabs}
 \usepackage{array}
 \usepackage{graphicx}
@@ -14,15 +15,16 @@
   \endverbatim%
 }
 \begin{document}
-\title{The \pkg\ package\thanks{This document describes \pkg\ v1.5.}}
+\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 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.
+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}
@@ -39,7 +41,7 @@ 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{figure}
 \begin{minipage}[t]{.45\linewidth}
   \centering
   \includegraphics{textpathfigs.1}
@@ -54,11 +56,9 @@ The resulting output is shown in figure~\ref{fig:firstexample}.
 \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{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, 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}:
+\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;
@@ -66,7 +66,7 @@ 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.
+\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.
 
@@ -89,12 +89,11 @@ The last step in setting up the \pkg\ package is adding the following line to th
 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.
+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 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}
@@ -103,8 +102,9 @@ 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.
+\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.}:
@@ -114,35 +114,32 @@ In general, try to stick to simple text.
 
 
 \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}.
+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}.
 
-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}.
+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}
-\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
+\centering
+% \begin{minipage}[t]{.45\linewidth}
+%   \centering
   \includegraphics{textpathfigs.3}
   \caption{Using different fonts in a MetaPost graphic.}
   \label{fig:textpathFont}
-\end{minipage}
+% \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]$.
+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}
-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}).
+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;
@@ -153,31 +150,28 @@ draw textpathFont("\usefont{T1}{bch}{m}{n}\large", "Daisy Duck!",
 \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.
+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}
+  \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.12}
+  \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.
+\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}
@@ -187,7 +181,7 @@ Arguments to the \cmd{textpathRaw} macro are the same as to the \cmd{textpath} m
 \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?
+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.
 
@@ -195,35 +189,46 @@ The reason \cmd{textpathRaw} doesn't fail as badly on mathematical input as it d
 
 \begin{figure}
   \centering
-  \includegraphics{textpathfigs.13}
+  \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:textpathFancyStrokes} describes an option that lets you choose between curved and straight rules.
+\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:textpathCureSqrt} shows a solution to another problem with root operators not discussed so far.
+\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 summarizes all configuration variables.
+\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{\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{Repeating and Shifting}
 
-\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.  
+\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 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.
+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.
 
-\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.
+\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.
 
-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}.
+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";
@@ -237,21 +242,24 @@ draw textpathFont(f, "Happy Birthday", p, 0.5) withcolor (1, 0.6, 0.2);
 
 \begin{figure}
   \centering
-  \includegraphics{textpathfigs.5}
+  \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}
 
-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.
+\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 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.
+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 Script Italic is available on CTAN.
+% Font Brush ScriptX Italic is available on CTAN.
 f := "\usefont{T1}{pbsi}{xl}{n}\fontsize{2.1pt}{2.1pt}\selectfont";
 w := 210bp;
 h := .276w;
@@ -265,43 +273,50 @@ 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
+  ("\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.)}
+  \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''.
 
-\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 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}).
 
-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.
+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.
 
-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}
 
-\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.
+\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 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.
+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]{1\linewidth}
+\begin{minipage}[t]{.45\linewidth}
   \centering
-  \includegraphics{textpathfigs.6}
+  \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 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.
+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}.
+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;
@@ -317,21 +332,23 @@ 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
-  \includegraphics{textpathfigs.7}
-  \caption{Automatically spaced text with an additional rotation of 90 degrees.}
-  \label{fig:textpathRotation}
+  \makebox[0pt][c]{%
+    \includegraphics{textpathfigs.12}%
+  }
+  \caption{Text with an absolute rotation of zero degrees.}
+  \label{fig:textpathAbsRotation}
 \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!";
+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;
@@ -345,108 +362,236 @@ 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
-  \makebox[0pt][c]{%
-    \includegraphics{textpathfigs.8}%
-  }
-  \caption{Text without rotation.}
-  \label{fig:textpathAbsRotation}
+  \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}
 
-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.
+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.
 
 
-\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.
+\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.
 
-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.
+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.14}
-  \caption{Straight rules in a formula.}
+  \includegraphics{textpathfigs.15}
+  \caption{A formula with straight rules.}
   \label{fig:textpathFancyStrokesZero}
 \end{minipage}\hfill
 \begin{minipage}[t]{.45\linewidth}
   \centering
-  \includegraphics{textpathfigs.15}
-  \caption{Curved rules in a formula.}
+  \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.
 
-\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.
+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.
 
-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.
+\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.
 
-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.
+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.
 
-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.
+\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.16}
+  \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.9}
+  \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}
 
-\suppressfloats
+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{3}{c}{valid in macros}\\
-     & & \cmd{textpath} & \cmd{textpathFont} & \cmd{textpathRaw}\\
+    \normalfont variable name & \makebox[0pt][r]{default value} & \multicolumn{2}{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}
+    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{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?
+\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 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{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 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}.
+\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
diff --git a/Master/texmf-dist/doc/metapost/textpath/textpathfigs.mp b/Master/texmf-dist/doc/metapost/textpath/textpathfigs.mp
index 0e09b6c3b23..8aed0b40216 100644
--- a/Master/texmf-dist/doc/metapost/textpath/textpathfigs.mp
+++ b/Master/texmf-dist/doc/metapost/textpath/textpathfigs.mp
@@ -2,13 +2,14 @@ input latexmp
 setupLaTeXMP(preamblefile="textpathfigs");
 input textpath
 
-prologues := 1;
+prologues := 0;
 
 beginfig(1);
   draw textpath("Greetings from MetaPost!", fullcircle scaled 50bp, 0)
     withcolor (0.2,0.2,0.6);
 endfig;
 
+
 beginfig(2);
 path p;
   p := reverse fullcircle rotated -90 scaled 50bp;
@@ -28,54 +29,106 @@ endfig;
 
 beginfig(4);
 path p;
-  p := (origin--(1bp,0bp)) scaled 75bp;
+  p := reverse fullcircle rotated -90 scaled 50bp;
   draw p withcolor .8white;
-  draw textpath("Greetings from MetaPost!", p, 0.5) withcolor (0.2,0.2,0.6);
-  p := p shifted (0,-20bp);
+  draw textpathRaw("Greetings from MetaPost!", p, 0.5) withcolor (0.2,0.2,0.6);
+endfig;
+
+
+beginfig(5);
+path p;
+  p := reverse halfcircle scaled 80bp;
   draw p withcolor .8white;
-  textpathClip := 0;
-  draw textpath("Greetings from MetaPost!", p, 0.5) withcolor (0.2,0.2,0.6);
+  draw textpathRaw("\LARGE$x^2+y^2=r^2$", p, 0.5) withcolor (0.2,0.2,0.6);
+endfig;
+
+
+beginfig(6);
+path p;
+  p := reverse halfcircle xscaled 150bp yscaled 80;
+  draw p withcolor .8white;
+  interim textpathShift := 7pt;
+  draw textpathRaw("\Large$\frac{(x-u)^2}{a^2}+\frac{(y-v)^2}{b^2}=1$", p, 0.5) withcolor (0.2,0.2,0.6);
 endfig;
 
-textpathClip := 1;
 
 
-beginfig(5);
+beginfig(7);
 path p;
 string f;
   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);
+  interim textpathRepeat := 3;
+  interim textpathStretch := 0;
+  interim textpathHSpace := 10pt;
+  draw textpathFont(f, "Happy Birthday!", p, 0.5) withcolor (1, 0.6, 0.2);
 endfig;
 
-textpathRepeat := 1;
-textpathStretch := 1;
 
+beginfig(8);
+path p[];
+string f;
+  f := "\usefont{T1}{pzc}{m}{n}\Large";
+  p1 := subpath (5.7,6.3) of fullcircle scaled 1400bp;
+  p2 := p1 shifted (0bp,-30bp);
+  draw p1 withcolor .8white;
+  draw p2 withcolor .8white;
+  interim textpathRepeat := 3;
+  interim textpathStretch := 1;
+  draw textpathFont(f, "Happy Birthday!", p1, 0.5) withcolor (1, 0.6, 0.2);
+  draw textpathFont(f, "Happy Birthday!", p2, 0) withcolor (1, 0.6, 0.2);
+endfig;
 
-beginfig(6);
+
+beginfig(9);
+string f;
+path p;
+numeric r,h,w;
+picture pic;
+% 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;
+  interim textpathRepeat := 30;
+  interim 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
+endfig;
+
+
+beginfig(10);
 string f;
 path p;
 picture pic;
 numeric lenp, lenpic, tb, k;
 color daisy;
   daisy := (0.9, 0.3, 0.1);
-  f := "\usefont{T1}{bch}{m}{n}\fontsize{40pt}{40pt}\selectfont";
-  p := subpath (2.7,5.3) of reverse fullcircle rotated -90 scaled 100bp;
+  f := "\usefont{T1}{bch}{m}{n}\fontsize{48pt}{48pt}\selectfont";
+  p := subpath (2.7,5.3) of reverse fullcircle rotated -90 scaled 120bp;
   draw p withcolor .8white;
-  textpathAbsRotation := 1;
-  draw textpathFont(f, "Daisy", p, 0.5) withcolor (white-daisy) + 0.8daisy;
+  interim textpathAbsRotation := 1;
+  draw textpathFont(f, "Daisy", p, 0.5) withcolor daisy + 0.85(white-daisy);
   textpathAbsRotation := 0;
+  interim textpathDebug := 2;
+  pickup pencircle scaled .2bp;
+  draw textpathFont(f, "Daisy", p, 0.5) withcolor .6white;
+  textpathDebug := 1;
   draw textpathFont(f, "Daisy", p, 0.5) withcolor daisy;
-  pic := strToPic(f & "\spaced{Daisy}");
-  draw textpathPic(pic, p, 0.5, "debug");
+  textpathDebug := 4;
+  draw textpathFont(f, "Daisy", p, 0.5) withcolor .6white;
 endfig;
 
 
-beginfig(7);
+beginfig(11);
 string f, t;
 path heart;
   f := "\usefont{T1}{pzc}{m}{it}\tiny";
@@ -83,134 +136,128 @@ path heart;
   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;
+  interim textpathRotation := 90;
+  interim textpathLetterSpace := 1pt;
+  interim textpathRepeat := 30;
   draw textpathFont(f, t, heart, 0.5) withcolor red+0.1green;
 endfig;
 
-textpathRepeat := 1;
-
 
-beginfig(8);
+beginfig(12);
 path p;
 string f, t;
 picture pic;
   f := "\usefont{T1}{fwb}{m}{n}\Large";% From the emerald package
-  t := "Don't panic! Don't panic! Don't panic!";
+  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;
+  interim textpathRotation := 0;
+  interim textpathAbsRotation := 1;
+  interim textpathLetterSpace := 6pt;
   pic := textpathFont(f, t, p, 0);
   background := black;
-  bboxmargin := 30bp;
+  interim bboxmargin := 30bp;
   unfill bbox pic;
   draw pic withcolor red+green;
 endfig;
 
-textpathAbsRotation := 0;
-textpathLetterSpace := 0pt;
 
-
-beginfig(9);
-string f;
+beginfig(13);
 path p;
-  f := "\usefont{T1}{pzc}{m}{it}\fontsize{56pt}{56pt}\selectfont";
-  p := reverse fullcircle rotated 33 scaled 150bp;
-  textpathLetterSpace := -3pt;
-  draw textpathFont(f, "Pro \&", p, 1) withcolor (1, 0.6, 0.2);
-  textpathLetterSpace := 0pt;
-  f := "\usefont{T1}{pzc}{m}{it}\fontsize{48pt}{48pt}\selectfont";
-  p := fullcircle rotated 33 scaled 145bp;
-  draw textpathFont(f, "Con\<{\kern-2pt}tra", p, 0.0) withcolor (1, 0.6, 0.2);
+  p := (origin--(1bp,0bp)) scaled 75bp;
+  draw p withcolor .8white;
+  interim textpathClip := 1;
+  draw textpath("Greetings from MetaPost!", p, 0.5) withcolor (0.2,0.2,0.6);
+  p := p shifted (0,-20bp);
+  draw p withcolor .8white;
+  textpathClip := 0;
+  draw textpath("Greetings from MetaPost!", p, 0.5) withcolor (0.2,0.2,0.6);
+  p := p shifted (0,-20bp);
+  draw p withcolor .8white;
+  interim textpathAutoScale := 1;
+  draw textpath("Greetings from MetaPost!", p, 0.5) withcolor (0.2,0.2,0.6);
 endfig;
 
 
-beginfig(10);
-string f;
+beginfig(14);
 path p;
-numeric r,h,w;
-picture pic;
-% 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
+  interim textpathDraft := 1;
+  p := (origin--(1bp,0bp)) scaled 75bp;
+  draw p withcolor .8white;
+  interim textpathClip := 1;
+  draw textpath("Greetings from MetaPost!", p, 0.5) withcolor (0.2,0.2,0.6);
+  p := p shifted (0,-20bp);
+  draw p withcolor .8white;
+  textpathClip := 0;
+  draw textpath("Greetings from MetaPost!", p, 0.5) withcolor (0.2,0.2,0.6);
+  p := p shifted (0,-20bp);
+  draw p withcolor .8white;
+  interim textpathAutoScale := 1;
+  draw textpath("Greetings from MetaPost!", p, 0.5) withcolor (0.2,0.2,0.6);
 endfig;
 
-textpathRepeat := 1;
-textpathShift := 0pt;
 
-
-beginfig(11);
+beginfig(15);
 path p;
-  p := reverse fullcircle rotated -90 scaled 50bp;
+  p := reverse halfcircle xscaled 150bp yscaled 80;
   draw p withcolor .8white;
-  draw textpathRaw("Greetings from MetaPost!", p, 0.5) withcolor (0.2,0.2,0.6);
+  interim textpathShift := 9pt;
+  interim textpathFancyStrokes := 0;
+  draw textpathRaw("\Large$y = v+b\sqrt{1-\frac{(x-u)^2}{a^2}}$", p, 0.5) withcolor (0.2,0.2,0.6);
 endfig;
 
 
-beginfig(12);
+beginfig(16);
 path p;
-  p := reverse halfcircle scaled 80bp;
+  p := reverse halfcircle xscaled 150bp yscaled 80;
   draw p withcolor .8white;
-  draw textpathRaw("\LARGE$x^2+y^2=r^2$", p, 0.5) withcolor (0.2,0.2,0.6);
+  interim textpathShift := 9pt;
+  interim textpathFancyStrokes := 1;
+  interim textpathCureSqrt := 0;
+  draw textpathRaw("\Large$y = v+b\sqrt{1-\frac{(x-u)^2}{a^2}}$", p, 0.5) withcolor (0.2,0.2,0.6);
 endfig;
 
 
-beginfig(13);
+beginfig(17);
 path p;
-  p := reverse halfcircle xscaled 160bp yscaled 80;
+  p := reverse halfcircle xscaled 150bp yscaled 80;
   draw p withcolor .8white;
-  textpathShift := 7pt;
-  draw textpathRaw("\Large$\frac{(x-u)^2}{a^2}+\frac{(y-v)^2}{b^2}=1$", p, 0.5) withcolor (0.2,0.2,0.6);
+  interim textpathShift := 9pt;
+  interim textpathFancyStrokes := 1;
+  interim textpathCureSqrt := 1;
+  draw textpathRaw("\Large$y = v+b\sqrt{1-\frac{(x-u)^2}{a^2}}$", p, 0.5) withcolor (0.2,0.2,0.6);
 endfig;
 
 
-beginfig(14);
+beginfig(18);
+string f;
 path p;
-  p := reverse halfcircle xscaled 160bp yscaled 80;
-  draw p withcolor .8white;
-  textpathShift := 9pt;
-  textpathFancyStrokes := 0;
-  draw textpathRaw("\Large$y = v+b\sqrt{1-\frac{(x-u)^2}{a^2})}$", p, 0.5) withcolor (0.2,0.2,0.6);
+  f := "\usefont{T1}{pzc}{m}{it}\fontsize{56pt}{56pt}\selectfont";
+  p := reverse fullcircle rotated 33 scaled 150bp;
+  interim textpathLetterSpace := -3pt;
+  draw textpathFont(f, "Pro \&", p, 1) withcolor (1, 0.6, 0.2);
+  interim textpathLetterSpace := 0pt;
+  f := "\usefont{T1}{pzc}{m}{it}\fontsize{48pt}{48pt}\selectfont";
+  p := fullcircle rotated 33 scaled 145bp;
+  draw textpathFont(f, "Con\<{\kern-2pt}tra", p, 0.0) withcolor (1, 0.6, 0.2);
 endfig;
 
 
-beginfig(15);
+beginfig(19);
 path p;
-  p := reverse halfcircle xscaled 160bp yscaled 80;
-  draw p withcolor .8white;
-  textpathShift := 9pt;
-  textpathFancyStrokes := 1;
-  textpathCureSqrt := 0;
-  draw textpathRaw("\Large$y = v+b\sqrt{1-\frac{(x-u)^2}{a^2})}$", p, 0.5) withcolor (0.2,0.2,0.6);
+  p := reverse fullcircle rotated -90 scaled 50bp;
+  interim textpathDebug := 1 + 2;
+  draw textpath("Greetings from MetaPost!", p, 0.5) withcolor (0.2,0.2,0.6);
 endfig;
 
-beginfig(16);
+
+beginfig(20);
 path p;
-  p := reverse halfcircle xscaled 160bp yscaled 80;
-  draw p withcolor .8white;
-  textpathShift := 9pt;
-  textpathFancyStrokes := 1;
-  textpathCureSqrt := 1;
-  draw textpathRaw("\Large$y = v+b\sqrt{1-\frac{(x-u)^2}{a^2})}$", p, 0.5) withcolor (0.2,0.2,0.6);
+  p := reverse fullcircle rotated -90 scaled 50bp;
+  interim textpathDebug := 2 + 4;
+  draw textpath("Greetings from MetaPost!", p, 0.5) withcolor (0.2,0.2,0.6);
 endfig;
 
-textpathShift := 0pt;
 
 end
diff --git a/Master/texmf-dist/doc/metapost/textpath/textpathfigs.tex b/Master/texmf-dist/doc/metapost/textpath/textpathfigs.tex
index 054c1cce8ce..3dedccd9343 100644
--- a/Master/texmf-dist/doc/metapost/textpath/textpathfigs.tex
+++ b/Master/texmf-dist/doc/metapost/textpath/textpathfigs.tex
@@ -1,3 +1,12 @@
 \RequirePackage{fix-cm}
 \documentclass{article}
+% \usepackage[T1]{fontenc}
+% \usepackage{MinionPro}
+% \usepackage{fourier}
 \usepackage{textpathmp}
+% \usepackage{amsmath}
+% \def\hksqrt{\mathpalette\DHLhksqrt}
+% \def\DHLhksqrt#1#2{\setbox0=\hbox{$#1\sqrt{#2\,}$}\dimen0=\ht0
+% \advance\dimen0-0.2\ht0
+% \setbox2=\hbox{\vrule height\ht0 depth -\dimen0}%
+% {\box0\lower0.4pt\box2}}