ensure pst-text

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

1 files changed, 508 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/generic/pst-text/pst-text-doc.tex b/Master/texmf-dist/doc/generic/pst-text/pst-text-doc.tex
new file mode 100644
index 00000000000..8c068aba7b2
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pst-text/pst-text-doc.tex
@@ -0,0 +1,508 @@
+\documentclass[english]{article}
+%
+\usepackage[T1]{fontenc}
+\usepackage[latin9]{inputenc}
+\listfiles
+\usepackage[scaled]{luximono}
+\usepackage{lmodern}
+\usepackage{xspace}
+\usepackage[bottom]{footmisc}
+\usepackage{tabularx}
+\usepackage{longtable,setspace}
+\usepackage[NewCommands,NewParameters]{ragged2e}
+\usepackage[dvipsnames]{pstricks}
+\usepackage{pst-plot}
+\usepackage{pst-text,pst-grad}
+%
+\def\PST{{\texttt{PSTricks}}\xspace}
+\def\PDF{{\texttt{PDF}}\xspace}
+\def\pst{{\texttt{pstricks}}\xspace}
+\def\PS{PostScript\xspace}
+\newcommand*\CMD[1]{{\UrlFont\texttt{\textbackslash #1}}}
+%
+\def\tIndex#1{\index{#1@{\UrlFont\texttt{#1}}}}
+\def\cIndex#1{\index{#1@\CMD{#1}}}
+\def\pIndex#1{\index{Parameter@\textbf{Parameter}!{\UrlFont\texttt{#1}}}}
+\def\ppIndex#1{\index{Parameter@\textbf{Parameter}!{#1}}}
+\def\sIndex#1{\index{Syntax@\textbf{Syntax}!\CMD{#1}}}
+\def\csIndex#1{\sIndex{#1}\cIndex{#1}}
+\def\PIndex#1{\index{Paket@\textbf{Paket}!\texttt{#1}}}
+\def\mIndex#1{\texttt{#1}\tIndex{#1}\pIndex{#1}}
+%
+\pretolerance=500
+\tolerance=1000 
+\hbadness=3000
+\vbadness=3000
+\hyphenpenalty=400
+
+\usepackage{showexpl}% not a real PSTricks package
+\usepackage{babel}
+\usepackage{makeidx}
+\makeindex
+\usepackage[dvips,colorlinks,linktocpage]{hyperref} % PDF-support
+%
+\renewcommand{\ttdefault}{ul9}% Luxi Mono
+\lstset{keywordstyle=\small\fontfamily{ul9}\bfseries} 
+\lstset{language=PSTricks,moredelim=**[is][\bf\color{blue}]{§}{§}}% oder andere Begrenzer
+%
+
+\begin{document}
+%
+\title{\texttt{pst-text}: Manipulate text and characters}
+\author{Herbert Voß\thanks{Thanks to Lars Kotthoff and Geoff Mercer for translating this documentation!}}
+\maketitle
+
+\begin{abstract}
+\PS principally does not know lines in the proper meaning of the word, but only
+paths\index{path} and those can have any arbitrary form. Along such paths
+arbitrary text may be arranged. The package
+\verb+pst-text+\tIndex{pst-text} supports the setting of text along a path
+and other character manipulations, where several characters 
+naturally result in a text again of course.
+
+It should be noted that the correct result is not guaranteed with every  \verb+DVI-PS+\tIndex{DVI-PS} driver.
+This package was written for Rokicki's\index{Rokicki} 
+\verb+dvips+\tIndex{dvips} programme, which is practically part of every \TeX{}
+distribution.
+\end{abstract}
+
+\tableofcontents
+
+\clearpage
+
+% ---------------------------------------------------------------------------------------
+\section{Text manipulations}\label{sec:psttext:Textmanipulationen}
+% ---------------------------------------------------------------------------------------
+The package \verb+pst-text+ principally defines only one macro.
+\begin{verbatim}
+\pstextpath[<position>](<x,y>){<graphic object>}{<text>}
+\end{verbatim}
+
+\begin{description}
+\item[<position>] specifies the alignment of the text referring to the path.
+\begin{description}
+\item[\texttt{l}] text starts at the beginning of the path (default).
+\item[\texttt{c}] text is aligned symmetrically to the middle of the path.
+\item[\texttt{r}] text ends at the end of the path.
+\end{description}
+As a basic principle it is to be kept in mind that when the text is longer 
+than the path this option has no effect since the path is filled with text 
+and any overflowing text disappears.
+\item[<x,y>] is an offset\index{offset} and denotes the values by which the
+	particular characters shall be translated in $x$ and $y$ direction 
+	relative to the path.
+	\verb+(<x,y>)+ have to be cartesian coordinates as the support for special
+	coordinates allowed by \PST is not
+	possible here. The dimensions of  $x$ and $y$ refer to the current scale. The default is
+	\verb+(0,\TPoffset)+,\cIndex{TPoffset} where \verb+TPoffset+ is set to a
+	length of \verb+-0.7ex+.
+\item[<graphic object>] any arbitrary object which creates a path.
+\item[<text>] the text to set, which may only consist of alphanumeric
+	characters. No macros are possible within the text, 
+	but the text may be put into a \verb+\parbox+.
+\end{description}
+
+\PS does not reserve any space for the output, so that the current text
+is overwritten if corresponding white space has not been  provided by \TeX.
+This can be achieved with a vertical feed (\verb+\vspace+\cIndex{vspace}) or
+with a \verb+pspicture+ environment\tIndex{pspicture}.
+
+\begin{minipage}{4.5cm}
+\begin{pspicture}(-2,-2.5)(2,2.5)
+\psset{linewidth=0.2pt}
+\pstextpath[c](0,0){\pscircle{2}}%
+	{\Large Now just text is written in a circle.}
+\end{pspicture}
+\end{minipage}\hfill%
+\begin{minipage}{\linewidth-4.5cm-1em}
+\begin{lstlisting}
+\begin{pspicture}(-2,-2.5)(2,2.5)
+\psset{linewidth=0.2pt}
+\pstextpath[c](0,0){\pscircle{2}}%
+	{\Large Now just text is written in a circle.}
+\end{pspicture}
+\end{lstlisting}
+\end{minipage}
+
+This first example shows the relatively easy use of the macro. If the path 
+is not required to be drawn the line style\index{line style} can be set to \verb+none+.
+The following example shows the use of the offset option. It is clear that
+every single character is translated, because the beginning and the end of the
+text stayed the same. Since the text was written in a circle, a positive
+specification for \verb+TPoffset+ causes a translation towards the centre of the circle.
+
+\medskip\noindent
+\begin{LTXexample}[width=4.5cm]
+\begin{pspicture}(-2,-2.5)(2,2.5)
+\psset{linewidth=0.2pt}
+\pstextpath[c](0,2ex){\pscircle{2}}%
+	{\Large Now just text is written in a circle.}
+\end{pspicture}
+\end{LTXexample}
+
+% The following example was first published in \cite{girou:01} and represents
+% the original form of the poem ``La colombe poignard� et le jet d'au'' by
+% Guillaume Appolinaire.
+
+% ---------------------------------------------------------------------------------------
+\medskip
+\subsection{Examples}
+% ---------------------------------------------------------------------------------------
+With \verb+\pscustom+ one is offered unlimited
+possibilities for paths. The following example uses the circle again, but
+forms an eight, which is composed of four circle parts to get a continuous path. In
+the second example a square has been appended to a circle. The starting point of the
+path is always the circle at $0$, here marked by $\Rightarrow$.
+
+
+\medskip\noindent
+\begin{LTXexample}[width=4cm]
+\psset{unit=0.75,linestyle=none}
+\begin{pspicture}(-2,-4)(2,4)
+\pstextpath[l](0,0){%
+    \pscustom{
+        \psarcn(0,2){2}{0}{-90}
+        \psarc(0,-2){2}{90}{0}
+        \psarc(0,-2){2}{0}{90}
+        \psarcn(0,2){2}{-90}{0}
+    }%
+}{\large $\Rightarrow$Now we are writing some nonsense text which appears in
+   a large eight in the correct direction.}
+\end{pspicture}
+\end{LTXexample}
+
+\medskip\noindent
+It can be easily seen that in the above example the upper circle is larger than
+the lower. This is because the text is always written on the path, which faces
+towards the inner on the upper circle and towards the outer on the lower circle (or square)
+due to the
+change in direction.
+
+
+\medskip\noindent
+\begin{LTXexample}[width=4cm]
+\begin{pspicture}(-2,-3.25)(2,3.25)
+\psset{linestyle=none}
+\pstextpath[l](0,0){%
+    \pscustom[unit=0.75]{
+        \psarcn(0,2){2}{0}{-90}
+        \pspolygon(0,0)(-1.7,0)(-1.7,-3.4)(1.7,-3.4)(1.7,0)(0,0)
+        \psarcn(0,2){2}{-90}{0}
+    }%
+}{\large $\Rightarrow$Jetzt wollen wir
+   einfach mal einen Text in einer 
+   ziemlich gro�n ACHT  schreiben, 
+   aber richtig rum.}
+\end{pspicture}
+\end{LTXexample}
+
+\medskip\noindent
+The setting of the text along a path is very memory and calculation intensive on the
+\PS side, so that with longer texts some seconds may pass until the desired
+result appears even on faster computers. This is shown in the following example,
+where the text is the beginning of the song ``Into the shining sun''{} by Pink
+Floyd.  Note how the text is truncated as the path is too short to fit the entire text in.
+
+\medskip\noindent
+\begin{center}
+\begin{pspicture}(-3,-3)(3,3)
+\psset{linestyle=none}
+\pstextpath[l](0,0){%
+  \parametricplot[plotstyle=curve,%
+     plotpoints=500]{0}{3000}{%
+       /r {t 1000 div} def t sin r mul t cos r mul } 
+}{
+Where were you when I was burned and broken -
+While the days slipped by from my window watching -
+Where were you when I was hurt and I was helpless -
+Because the things you say and the things you do surround me -
+While you were hanging yourself on someones else's words -
+Dying to believe in what you heard -
+I was staring straight into the shining sun -
+
+Lost in thought and lost in time -
+While the seeds of life and the seeds of change were planted
+Outside the rain fell dark and slow
+While I pondered on this dangerous but irresistible pastime
+}
+\end{pspicture}
+\end{center}
+
+\begin{lstlisting}
+%\usepackage{pst-plot}
+
+\begin{pspicture}(-3,-3)(3,3)
+\psset{linestyle=none}
+\pstextpath[l](0,0){%
+  \parametricplot[plotstyle=curve,%
+     plotpoints=500]{0}{3000}{%
+       /r {t 1000 div} def t sin r mul t cos r mul } 
+}{
+Where were you when I was burned and broken -
+While the days slipped by from my window watching -
+Where were you when I was hurt and I was helpless -
+Because the things you say and the things you do surround me -
+While you were hanging yourself on someones else's words -
+Dying to believe in what you heard -
+I was staring straight into the shining sun -
+
+Lost in thought and lost in time -
+While the seeds of life and the seeds of change were planted
+Outside the rain fell dark and slow
+While I pondered on this dangerous but irresistible pastime
+}
+\end{pspicture}
+\end{lstlisting}
+
+
+\section{Character manipulations}\label{sec:psttext:Zeichenmanipulationen}
+% ---------------------------------------------------------------------------------------
+With character manipulations the same issue with the \verb+DVI-PS+ driver applies, namely that the results are only guaranteed for Rokicki's\index{Rokicki} 
+\verb+dvips+\tIndex{dvips} programme.\index{outline font}
+
+% ---------------------------------------------------------------------------------------
+\subsection{\CMD{pscharpath}}\label{sec:psttext:pscharpath}
+% ---------------------------------------------------------------------------------------
+\csIndex{pscharpath}Although this macro has a name similar to
+\verb+\pstextpath+, it has a completely different meaning.
+%
+\begin{verbatim}
+\pscharpath[<parameters>]{<text>}
+\pscharpath*[<parameters>]{<text>}
+\end{verbatim}
+
+\begin{description}
+\item[<parameters>] All \PST parameters, insofar as they make sense, may be
+	specified here.
+\item[<text>] The text to set, which may only consist of alphanumeric
+	characters, therefore no macros are possible within the text.
+\end{description}
+
+Normally, one will define ones own font size, which is best  done with 
+\verb+\DeclareFixedFont+\cIndex{DeclareFixedFont}, since this macro is very
+fast because it simply sets the size without having to look up any font tables.
+
+\medskip\noindent
+\begin{LTXexample}[width=6.5cm]
+\DeclareFixedFont{\RM}{T1}{ptm}{b}{n}{2cm}
+\pscharpath{\RM TeXnik}\\
+\pscharpath[linecolor=lightgray]{\RM TeXnik}\\
+\psset{fillstyle=gradient,gradbegin=red,gradend=cyan}
+\pscharpath[gradangle=90]{\RM TeXnik}\\
+\pscharpath[linestyle=none,gradangle=-90]{\RM TeXnik}
+\end{LTXexample}
+
+\medskip\noindent
+Normally the path, here the outer line of the characters, is deleted after the
+macro \verb+\pscharpath+ has ended. With the asterisk version it is preserved
+and can be used for other ``baubles''{}, for instance for \verb+\pstextpath+,
+where the saved path can be used as input for the text to set.
+
+
+\medskip\noindent
+\DeclareFixedFont{\SF}{T1}{phv}{b}{n}{2.45cm}
+\begin{center}
+\pstextpath(0,-1ex){\pscharpath*[linestyle=none]{\SF Pink Floyd}}{
+\scriptsize Where were you when I was burned and broken -
+While the days slipped by from my window watching -
+Where were you when I was hurt and I was helpless -
+Because the things you say and the things you do surround me -
+While you were hanging yourself on someones else's words -
+Dying to believe in what you heard -
+I was staring straight into the shining sun -
+
+Lost in thought and lost in time -
+While the seeds of life and the seeds of change were planted
+Outside the rain fell dark and slow
+While I pondered on this dangerous but irresistible pastime
+}
+\end{center}
+
+\begin{lstlisting}
+\DeclareFixedFont{\SF}{T1}{phv}{b}{n}{2.5cm}
+\pstextpath(0,-1ex){%
+  \pscharpath*[linestyle=none]{\SF Pink Floyd}}{
+    \scriptsize < ... Text ... > 
+  }
+\end{lstlisting}
+
+% ---------------------------------------------------------------------------------------
+\subsection{\CMD{pscharclip}}\label{sec:psttext:pscharclip}
+% ---------------------------------------------------------------------------------------
+\csIndex{pscharclip}\verb+\pscharclip+ is practically identical to
+\verb+\pscharpath+ with the only difference being that it sets the clipping
+path\index{clipping path} to the current path.
+%
+\begin{verbatim}
+\pscharclip[<parameters>]{<text>} %  TeX example
+ ... 
+\endpscharclip
+\pscharclip*[<parameters>]{<text>}%  TeX example
+ ... 
+\endpscharclip
+\begin{pscharclip}[<parameters>]{<text>} %  LaTeX example
+ ... 
+\end{pscharclip}
+\begin{pscharclip*}[<parameters>]{<text>}%  LaTeX example
+ ... 
+\end{pscharclip}
+\end{verbatim}
+%
+Using this one can ``write''{} \emph{within} a font, whereas it is not really
+easy to get the ``base''{} congruent. How to deal with this best shall is shown
+in the following worked example. 
+
+The base is best formed as a \verb+minipage+\tIndex{minipage},
+thus enabling it to be moved to arbitrary spots. To have clear coordinates on one hand
+and only the interesting area shown on the other hand, one uses a
+\verb+pspicture*+ environment\tIndex{pspicture*}. Let us presume that we use a
+font size of $3$cm and want to use the width of the whole page.
+%
+\begin{verbatim}
+\begin{pspicture*}(\linewidth,3cm)
+...
+\end{pspicture}
+\end{verbatim}
+%
+The text can be set exactly into the centre with a \verb+\rput+
+instruction\cIndex{rput}.
+
+\DeclareFixedFont{\RM}{T1}{ptm}{b}{n}{3cm}
+\begin{pspicture*}(\linewidth,3cm)
+  \psgrid%
+  \begin{pscharclip}[linewidth=0.1pt]{%
+    \rput(0.5\linewidth,1.5){\RM PSTricks}}%
+  \end{pscharclip}
+\end{pspicture*}
+
+\begin{lstlisting}
+\DeclareFixedFont{\RM}{T1}{ptm}{b}{n}{3cm}
+\begin{pspicture*}(\linewidth,3cm)
+  \psgrid%
+  \begin{pscharclip}[linewidth=0.1pt]{%
+    \rput(0.5\linewidth,1.5){\RM PSTricks}}%
+  \end{pscharclip}
+\end{pspicture*}
+\end{lstlisting}
+
+\medskip
+The text ``lying below''{} the font is put into a \verb+minipage+\tIndex{minipage} of the
+width \verb+\linewidth+\cIndex{linewidth}. Since this text underlies the
+clipping path, it does not matter how long it really is, the essential thing is that the
+the whole area is covered. This is especially important when the text is further manipulated such as rotated.  So one may view the following example with
+\verb+\begin{minipage}{\linewidth}+.
+
+\medskip
+\DeclareFixedFont{\Rm}{T1}{ptm}{m}{n}{2mm}
+\begin{pspicture*}(\linewidth,3cm)
+  \psgrid%
+  \rput{60}(0.5\linewidth,1.5){%
+    \begin{minipage}{0.6\linewidth}
+       \setstretch{0.5}
+       \color{red}
+       \multido{\i=1+1}{500}{\Rm PSTricks }
+    \end{minipage}%
+  }
+\end{pspicture*}
+
+
+\begin{lstlisting}
+\DeclareFixedFont{\Rm}{T1}{ptm}{m}{n}{2mm}
+\begin{pspicture*}(\linewidth,3cm)
+  \psgrid%
+  \rput{60}(0.5\linewidth,1.5){%
+    \begin{minipage}{0.6\linewidth}
+       \setstretch{0.5}
+       \color{red}
+       \multido{\i=1+1}{500}{\Rm PSTricks }
+    \end{minipage}%
+  }
+\end{pspicture*}
+\end{lstlisting}
+
+\medskip
+Both of these can be overlaid where, because of the clipping
+path,\index{clipping path} only the inner of the large letters seems transparent.
+In the second example the \verb+minipage+ has been additionally rotated, the
+line colour was ignored and the line spacing within the \verb+minipage+ was
+halved (package \verb+setspace+\tIndex{setspace}).
+
+\medskip
+\begin{pspicture*}(\linewidth,3cm)
+  \begin{pscharclip}[linewidth=0.1pt]{%
+    \rput(0.5\linewidth,1.5){\RM PSTricks}}%
+  \rput{60}(0.5\linewidth,1.5){%
+    \begin{minipage}{0.6\linewidth}
+       \setstretch{0.5}
+       \color{red}
+       \multido{\i=1+1}{500}{\Rm PSTricks }
+    \end{minipage}%
+  }
+  \end{pscharclip}
+\end{pspicture*}
+
+\begin{pspicture*}(\linewidth,3cm)
+  \begin{pscharclip}[linewidth=0.1pt,linestyle=none]{%
+    \rput(0.5\linewidth,1.5){\RM PSTricks}}%
+    \rput{-60}(0.5\linewidth,1.5){%
+      \begin{minipage}{0.6\linewidth}
+         \setstretch{0.5}
+         \multido{\i=1+1}{500}{\Rm  PSTricks }
+      \end{minipage}%
+  }
+  \end{pscharclip}
+\end{pspicture*}
+
+
+\begin{lstlisting}
+\DeclareFixedFont{\RM}{T1}{ptm}{b}{n}{3cm}
+\DeclareFixedFont{\Rm}{T1}{ptm}{m}{n}{2mm}
+\begin{pspicture*}(\linewidth,3cm)
+  \begin{pscharclip}[linewidth=0.1pt]{%
+    \rput(0.5\linewidth,1.5){\RM PSTricks}}%
+  \rput{60}(0.5\linewidth,1.5){%
+    \begin{minipage}{0.6\linewidth}
+       \setstretch{0.5}
+       \color{red}
+       \multido{\i=1+1}{500}{\Rm PSTricks }
+    \end{minipage}%
+  }
+  \end{pscharclip}
+\end{pspicture*}
+
+\begin{pspicture*}(\linewidth,3cm)
+  \begin{pscharclip}[linewidth=0.1pt,linestyle=none]{%
+    \rput(0.5\linewidth,1.5){\RM PSTricks}}%
+    \rput{-60}(0.5\linewidth,1.5){%
+      \begin{minipage}{0.6\linewidth}
+         \setstretch{0.5}
+         \multido{\i=1+1}{500}{\Rm  PSTricks }
+      \end{minipage}%
+  }
+  \end{pscharclip}
+\end{pspicture*}
+\end{lstlisting}
+
+
+\medskip
+Generally it is not of interest what one bases \verb+\pscharclip+ on.  
+Using things sucha as a graphic can lead to some interesting possibilities. 
+It should be kept in mind 
+that alternatively \verb+pscharpath+\cIndex{pscharpath} may be
+used in conjunction with \verb+psboxfill+\cIndex{psboxfill}.
+
+
+
+
+
+\nocite{*}
+\bgroup
+\raggedright
+\bibliographystyle{plain}
+\bibliography{\jobname}
+\egroup
+
+\printindex
+
+
+\end{document}