NAME

     pstext - To plot text on maps


SYNOPSIS

     pstext textfile  -Jparameters  -Rwest/east/south/north[r]  [
     -Btickinfo  ]  [  -Cdx/dy  ]  -Ddx/dy[v[red/green/blue]  ] [
     -Eazimuth/elevation ] [ -Gred/green/blue ] [ -H[nrec] ] [ -K
     ]  [  -L  ]  [  -M[flag]  ] [ -N ] [ -O ] [ -P ] [ -Spen ] [
     -U[/dx/dy/][label]       ]       [       -V       ]        [
     -W[red/green/blue][o|O|c|C[pen]] ] [ -Xx-shift ] [ -Yy-shift
     ] [ -Zzlevel ] [ -ccopies ] [ -: ]


DESCRIPTION

     pstext plots textstrings of variable size,  font  type,  and
     orientation.  Various map projections are provided, with the
     option to draw and annotate the map  boundaries.  PostScript
     code  is written to standard output.  Greek characters, sub-
     script, superscript, and small caps are  supported  as  fol-
     lows:  The sequence @~ toggles between the selected font and
     Greek (Symbol).  @%no% sets the font to no; @%%  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.16  and Appendix F in the GMT Technical Reference
     and Cookbook.  Note that WANT_EURO_FONT must be set to  TRUE
     in your .gmtdefaults file in order to use the accented char-
     acters.  Using the -W option, a colored rectangle underlying
     the  text  may  be  plotted  (Does not work for strings with
     sub/super scripts, symbols, or composite characters,  except
     in paragraph mode (-M)).

     textfile
          This file contains 1 or more records with (x, y,  size,
          angle,  fontno,  justify,  text).  If no file is given,
          pstext will read standard input.  size is text size  in
          points,  angle is measured in degrees counter-clockwise
          from horizontal, fontno sets  the  font  type,  justify
          sets  the  alignment. If fontno is not an integer, then
          it is  taken  to  be  a  textstring  with  the  desired
          fontname.   See  the gmtdefaults man page for names and
          numbers of avaiable fonts  (or  run  pstext  -L).   The
          alignment  refers  to  the  part of the textstring that
          will be mapped onto the (x,y) point.  Choose a 2  char-
          acter  combination  of  L,  C,  R (for left, center, or
          right) and T, M, B for top, middle, or bottom. e.g., BL
          for lower left.

     -J   Selects  the  map  projection.  Scale  is  UNIT/degree,
          1:xxxxx,  or width in UNIT (upper case modifier).  UNIT
          is cm, inch, or m, depending on the  MEASURE_UNIT  set-
          ting in .gmtdefaults, but this can be overridden on the
          command line by  appending  the  c,  i,  or  m  to  the
          scale/width value.

          CYLINDRICAL PROJECTIONS:

          -Jclon0/lat0/scale (Cassini)
          -Jjlon0/scale (Miller)
          -Jmscale (Mercator - Greenwich and Equator as origin)
          -Jmlon0/lat0/scale (Mercator - Give meridian and  stan-
          dard parallel)
          -Joalon0/lat0/azimuth/scale (Oblique Mercator  -  point
          and azimuth)
          -Joblon0/lat0/lon1/lat1/scale (Oblique Mercator  -  two
          points)
          -Joclon0/lat0/lonp/latp/scale (Oblique Mercator - point
          and pole)
          -Jqlon0/scale   (Equidistant   Cylindrical   Projection
          (Plate Carree))
          -Jtlon0/scale (TM - Transverse Mercator,  with  Equator
          as y = 0)
          -Jtlon0/lat0/scale (TM - Transverse Mercator, set  ori-
          gin)
          -Juzone/scale (UTM - Universal Transverse Mercator)
          -Jylon0/lats/scale (Basic Cylindrical Projection)

          AZIMUTHAL PROJECTIONS:

          -Jalon0/lat0/scale (Lambert).
          -Jelon0/lat0/scale (Equidistant).
          -Jflon0/lat0/horizon/scale (Gnomonic).
          -Jglon0/lat0/scale (Orthographic).
          -Jslon0/lat0/scale (General Stereographic)

          CONIC PROJECTIONS:

          -Jblon0/lat0/lat1/lat2/scale (Albers)
          -Jdlon0/lat0/lat1/lat2/scale (Equidistant)
          -Jllon0/lat0/lat1/lat2/scale (Lambert)

          MISCELLANEOUS PROJECTIONS:

          -Jhlon0/scale (Hammer)
          -Jilon0/scale (Sinusoidal)
          -Jk[f|s]lon0/scale (Eckert IV (f) and VI (s))
          -Jnlon0/scale (Robinson)
          -Jrlon0/scale (Winkel Tripel)
          -Jvlon0/scale (Van der Grinten)
          -Jwlon0/scale (Mollweide)
          NON-GEOGRAPHICAL PROJECTIONS:

          -Jpscale[/origin] (polar (theta,r) coordinates, option-
          ally offset theta [0])
          -Jxx-scale[l|ppow][/y-scale[l|ppow]] (Linear, log,  and
          power scaling)
          More details can be found in the psbasemap manpages.

     -Jz  Sets the vertical scaling (for 3-D maps).  Same  syntax
          as -Jx.

     -R   west, east, south, and  north  specify  the  Region  of
          interest.  To specify boundaries in degrees and minutes
          [and seconds], use the dd:mm[:ss] format.  Append r  if
          lower  left  and  upper right map coordinates are given
          instead of wesn.


OPTIONS

     No space between the option flag and  the  associated  argu-
     ments.

     -B   Sets map boundary tickmark intervals. See psbasemap for
          details.

     -C   Sets the clearance between the text and the surrounding
          box [0.15c/0.15c (or 0.05i/0.05i)].  Only used if -W is
          specified.

     -D   Shifts the projected (x,y) point by  dx,dy  [0/0].   In
          paragraph mode (-M), one may append v which will draw a
          line from the original  point  to  the  shifted  point.
          Optionally append a pen for this line.

     -E   Sets the viewpoint's azimuth and  elevation  (for  per-
          spective  view)  [180/90].   (Not implemented for para-
          graph mode).

     -G   Sets the gray-shade (0-255) or color  (r/g/b,  each  0-
          255) used for drawing the text.  [Default is black]

     -H   Input file(s) has Header record(s).  Number  of  header
          records  can  be  changed  by editing your .gmtdefaults
          file.  If used, GMT default is 1 header record.

     -K   More PostScript code will be  appended  later  [Default
          terminates the plot system].

     -L   Lists the font-numbers and font-names  available,  then
          exits.

     -M   Paragraph mode.  Files must be multiple segment  files.
          Segments  are separated by a special record whose first
          character must be flag [Default is '>'].   Starting  in
          the  3rd column, we expect to find information pertain-
          ing to the typesetting of a text paragraph (the remain-
          ing  lines until next segment header).  The information
          expected is (x y size angle  fontno  justify  linespace
          parwidth  parjust), where x y size angle fontno justify
          are defined above, while linespace and parwidth are the
          linespacing  and  paragraph  width,  respectively.  The
          justification of the text paragraph is governed by par-
          just   which  may  be  l(eft),  c(enter),  r(ight),  or
          j(ustified).  The segment header is followed by one  or
          more  lines  with paragraph text.  Text may contain the
          escape sequences discussed above as well as three more:
          @;r/g/b;  changes  the  font  color  (@;;  resets  it),
          @:size: changes the font size (@:: resets it),  and  @_
          toggles  underline  on/off.  Separate paragraphs with a
          blank line.

     -N   Do NOT clip text at map boundaries [Default will clip].

     -O   Selects Overlay plot mode [Default  initializes  a  new
          plot system].

     -P   Selects  Portrait  plotting  mode   [GMT   Default   is
          Landscape, see gmtdefaults to change this].

     -S   Draw text outline. Append pen attributes.  (Not  imple-
          mented for paragraph mode).

     -U   Draw Unix System time stamp on plot.  User may  specify
          where the lower left corner of the stamp should fall on
          the  page  relative  to  lower  left  corner  of  plot.
          Optionally,  append  a label, or c (which will plot the
          command string.)

     -V   Selects verbose mode, which will send progress  reports
          to stderr [Default runs "silently"].

     -W   Paint a rectangle beneath the text string.   Set  color
          [Default  is  255/255/255  (white)].   Append o to draw
          rectangle outline, add a pen to specify pen  attributes
          [1/0/0/0].   Choose  upper case O to get a rounded rec-
          tangle (only in paragraph mode).  Choose lower  case  c
          to  get  a  concave rectangle (only in paragraph mode).
          Choose upper case C to get a convex rectangle (only  in
          paragraph mode).

     -X -Y
          Shift origin of plot by (x-shift,y-shift).   Prepend  a
          for  absolute  coordinates;  the default (r) will reset
          plot origin.

     -Z   For 3-D projections:  Sets the z-level of  the  basemap
          [0].  (Not implemented for paragraph mode).

     -:   Toggles      between      (longitude,latitude)      and
          (latitude,longitude)    input/output.     [Default   is
          (longitude,latitude)].

     -c   Specifies the number of plot copies. [Default is 1]


EXAMPLES

     To plot the outlines of the textstrings stored in  the  file
     text.d on a Mercator plot with the given specifications, try

     pstext  text.d  -R-30/30/-10/20  -Jm0.1i  -P  -B5  -S0.5p  >
     plot.ps

     To add a typeset figure caption for a 3-inch wide  illustra-
     tion, try

     pstext -R0/3/0/5 -JX3i -O -H -M -N << EOF >> figure.ps
     This is an optional header record
     > 0 -0.5 12 0 4 LT 13p 3i j
     @%5%Figure 1.@%%  This illustration  shows  nothing  useful,
     but it still needs
     a figure caption.  Highlighted in @;255/0/0;red@;;  you  can
     see the locations
     of cities where it is @_impossible@_ to get  any  good  Thai
     food; these are to be avoided.
     EOF


BUGS

     Except for paragraph mode, the horizontal  justification  of
     surrounding  rectangles  does  not  work when Greek symbols,
     sub-  and  superscripts,  and/or  composite  characters  are
     imbedded in the textstring.  In paragraph mode, the presence
     of composite characters and other escape sequences may  lead
     to unfortunate word splitting.
     The -N option does not adjust the BoundingBox information so
     you  may  have  to  post-process  the PostScript outout with
     epstool or ps2epsi to obtain a correct BoundingBox.


SEE ALSO

     gmt(l), psbasemap(l)