summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pst-text/pst-text-doc.tex
blob: 8c068aba7b2e3d0c1ec0cfc9cfec47c82da8c264 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
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}