From 558c838dbb475d7472aeedbb7d2973c3211ed7cb Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Thu, 30 Nov 2006 04:08:34 +0000 Subject: ensure pst-text git-svn-id: svn://tug.org/texlive/trunk@2561 c570f23f-e606-0410-a88d-b1316a301751 --- .../doc/generic/pst-text/pst-text-doc.tex | 508 +++++++++++++++++++++ 1 file changed, 508 insertions(+) create mode 100644 Master/texmf-dist/doc/generic/pst-text/pst-text-doc.tex (limited to 'Master/texmf-dist/doc/generic/pst-text/pst-text-doc.tex') 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[](){}{} +\end{verbatim} + +\begin{description} +\item[] 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[] 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+()+ 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[] any arbitrary object which creates a path. +\item[] 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[]{} +\pscharpath*[]{} +\end{verbatim} + +\begin{description} +\item[] All \PST parameters, insofar as they make sense, may be + specified here. +\item[] 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[]{} % TeX example + ... +\endpscharclip +\pscharclip*[]{}% TeX example + ... +\endpscharclip +\begin{pscharclip}[]{} % LaTeX example + ... +\end{pscharclip} +\begin{pscharclip*}[]{}% 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} -- cgit v1.2.3