path: root/Master/texmf-dist/doc/generic/pst-text/pst-text-doc.tex

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