.TH PSTEXT l DATE
#ifdef SI
#define UNIT cm
#define CLEARENCE 0.15/0.15
#else
#define UNIT inch
#define CLEARENCE 0.05/0.05
#endif
.SH NAME
pstext \- To plot textstrings on maps
.SH SYNOPSIS
\fBpstext\fP \fItextfile\fP \fB\-J\fP\fIparameters\fP \fB\-R\fIwest/east/south/north\fP[\fIr\fP] 
[ \fB\-B\fP\fItickinfo\fP ] [ \fB\-C\fP\fIdx/dy\fP ] [ \fB\-E\fP\fIazimuth/elevation\fP ] 
[ \fB\-G\fP\fIred/green/blue\fP ] [ \fB\-H\fP ] [ \fB\-K\fP ] [ \fB\-L\fP ] [ \fB\-N\fP ] [ \fB\-O\fP ] [ \fB\-P\fP ] 
[ \fB\-S\fP\fIpen\fP ] [ \fB\-U\fP[\fI/dx/dy/\fP][\fIlabel\fP] ] [ \fB\-V\fP ] [ \fB\-W\fP[\fIred/green/blue\fP][\fBo\fP] ] 
[ \fB\-X\fP\fIx-shift\fP ] [ \fB\-Y\fP\fIy-shift\fP ] [ \fB\-Z\fP\fIzlevel\fP ] [ \fB\-c\fP\fIcopies\fP ] [ \fB\-:\fP ]
.SH DESCRIPTION
\fBpstext\fP plots textstrings of variable size, font type, and orientation.  Various map projections are
provided, with the option to draw and annotate the map boundaries. \fIPostScript\fP code is written to
standard output.  Greek characters, subscript, superscript, and small caps are supported as follows: The sequence @~ toggles
between the selected font and Greek (Symbol).  @%\fIno\fP% sets the font to \fIno\fP; @%% resets the
font to the starting font, @- toggles subscripts on/off, @+ toggles
superscript on/off, and @# toggles small caps on/off.  @@ prints the @ sign.  @e, @o, @a,
@E, @O, @A give the accented Scandinavian characters.  Composite characters (overstrike) may be
indicated with the @!<char1><char2> sequence, which will print the two characters on top of
each other.  To learn the octal codes for symbols not available on the keyboard and some accented European characters,
see Section 4.15 in the \fBGMT\fP Technical Reference and Cookbook.  Note that WANT_EURO_FONT must be set to TRUE in your .gmtdefaults file in order to use the accented characters.  Using the \fB\-W\fP option, a colored rectangle underlying the text may
be plotted  (Does not work for strings with sub/super scripts, symbols, or composite characters).
.TP
\fItextfile\fP
This file contains 1 or more records with (\fIx, y, size, angle, fontno, justify, text\fP).
If no file is given, \fBpstext\fP will read standard input.
\fIsize\fP is text size in points, \fIangle\fP is measured in degrees counter-clockwise from horizontal, 
\fIfontno\fP sets the font type, \fIjustify\fP sets the alignment. 
If \fIfontno\fP starts with a leading hyphen, then the remainder of \fIfontno\fP is taken to be a textstring with the desired fontname.  See the \fBgmtdefaults\fP man page
for names and numbers of avaiable fonts (or run \fBpstext \-L\fP).  The alignment number refers to the
part of the textstring that will be mapped onto the (\fIx,y\fP) point: 1 = Lower Left corner, 2 = Lower Center,
3 = Lower Right, 5 = Mid Left, 6 = Mid Center, 7 = Mid Right, 9 = Upper Left, 10 = Upper Center,
11 = Upper Right.
#include "explain_-j.txt"
#include "explain_-Jz.txt"
#include "explain_-R.txt"
.SH OPTIONS
No space between the option flag and the associated arguments.
#include "explain_-b.txt"
.TP
.B \-C
Sets the clearance (in UNIT) between the text and the surrounding box [CLEARENCE].
Only used if \fB\-W\fP is specified.
.TP
.B \-E
Sets the viewpoint's azimuth and elevation (for perspective view) [180/90]
.TP
.B \-F
Sets the color used for Frame and annotations.  [Default is black]
.TP
.B \-G
Sets the gray-shade (0-255) or color (r/g/b, each 0-255) used for drawing the text.  [Default is black]
#include "explain_-H.txt"
#include "explain_-K.txt"
.TP
.B \-L
Lists the font-numbers and font-names available, then exits.
.TP
.B \-N
Do NOT clip text at map boundaries [Default will clip].
#include "explain_-O.txt"
#include "explain_-P.txt"
.TP
.B \-S
Draw text outline. Append pen attributes.
#include "explain_-U.txt"
#include "explain_-V.txt"
.TP
.B \-W
Paint a rectangle beneath the text string.  Set color [Default is 255/255/255 (white)].  Append o
to draw rectangle outline.
#include "explain_-XY.txt"
.TP
.B \-Z
For 3-D projections:  Sets the z-level of the basemap [0].
#include "explain_-t.txt"
#include "explain_-c.txt"
.SH EXAMPLES
To plot the outlines of the textstrings stored in the file text.d on a Mercator plot with
the given specifications, try
.br
.sp
pstext text.d \fB\-R\fP-30/30/-10/20 \fB\-Jm\fP0.1 \fB\-P \-B\fP5 \fB\-S\fP2 > plot.ps
.SH SEE ALSO
gmt, psbasemap
.SH BUGS
The horizontal justification of surrounding rectangles does not work when Greek symbols, sub- and
superscripts, and/or composite characters are imbedded in the textstring.
#include "refs.i"
