Provided by: gmt_4.5.11-1build1_amd64 bug

NAME

       pstext - To plot text strings on maps

SYNOPSIS

       pstext  textfile  -Jparameters  -Rwest/east/south/north[r]  [ -A ] [ -B[p|s]parameters ] [
       -Cdx/dy ] [ -D[j]dx[/dy][v[pen] ] [ -Eazim/elev[+wlon/lat[/z]][+vx0/y0] ] [  -Gcolor  ]  [
       -H[i][nrec]  ]  [  -Jz|Zparameters  ]  [  -K  ]  [  -L  ] [ -N ] [ -O ] [ -P ] [ -Spen ] [
       -U[just/dx/dy/][c|label] ] [ -V ] [ -W[color,][o|O|c|C[pen]] ] [ -X[a|c|r][x-shift[u]] ] [
       -Y[a|c|r][y-shift[u]]  ]  [  -Z[zlevel|+]  ] [ -:[i|o] ] [ -ccopies ] [ -f[i|o]colinfo ] [
       -m[flag] ]

DESCRIPTION

       pstext plots text strings 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, subscript,  superscript,
       and small caps are supported as follows: 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, @# toggles small caps on/off,
       @;color; changes the font color (@;; resets it), @:size: changes the font size (@:: resets
       it),  and @_ toggles underline 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 CHAR_ENCODING must be set to an extended character  set
       in  your .gmtdefaults4 file in order to use the accented characters.  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 text string with the desired fontname.  See the gmtdefaults man page
              for names and numbers of available fonts (or run pstext -L).  The alignment  refers
              to  the part of the text string that will be mapped onto the (x,y) point.  Choose a
              2 character 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  setting  in
              .gmtdefaults4, but this can be overridden on the command line by appending c, i, or
              m to the scale/width value.  When central meridian is optional, default  is  center
              of  longitude  range  on -R option.  Default standard parallel is the equator.  For
              map height, max dimension, or min dimension, append  h,  +,  or  -  to  the  width,
              respectively.
              More details can be found in the psbasemap man pages.

              CYLINDRICAL PROJECTIONS:

              -Jclon0/lat0/scale (Cassini)
              -Jcyl_stere/[lon0/[lat0/]]scale (Cylindrical Stereographic)
              -Jj[lon0/]scale (Miller)
              -Jm[lon0/[lat0/]]scale (Mercator)
              -Jmlon0/lat0/scale (Mercator - Give meridian and standard parallel)
              -Jo[a]lon0/lat0/azimuth/scale (Oblique Mercator - point and azimuth)
              -Jo[b]lon0/lat0/lon1/lat1/scale (Oblique Mercator - two points)
              -Joclon0/lat0/lonp/latp/scale (Oblique Mercator - point and pole)
              -Jq[lon0/[lat0/]]scale (Cylindrical Equidistant)
              -Jtlon0/[lat0/]scale (TM - Transverse Mercator)
              -Juzone/scale (UTM - Universal Transverse Mercator)
              -Jy[lon0/[lat0/]]scale (Cylindrical Equal-Area)

              CONIC PROJECTIONS:

              -Jblon0/lat0/lat1/lat2/scale (Albers)
              -Jdlon0/lat0/lat1/lat2/scale (Conic Equidistant)
              -Jllon0/lat0/lat1/lat2/scale (Lambert Conic Conformal)
              -Jpoly/[lon0/[lat0/]]scale ((American) Polyconic)

              AZIMUTHAL PROJECTIONS:

              -Jalon0/lat0[/horizon]/scale (Lambert Azimuthal Equal-Area)
              -Jelon0/lat0[/horizon]/scale (Azimuthal Equidistant)
              -Jflon0/lat0[/horizon]/scale (Gnomonic)
              -Jglon0/lat0[/horizon]/scale (Orthographic)
              -Jglon0/lat0/altitude/azimuth/tilt/twist/Width/Height/scale (General Perspective).
              -Jslon0/lat0[/horizon]/scale (General Stereographic)

              MISCELLANEOUS PROJECTIONS:

              -Jh[lon0/]scale (Hammer)
              -Ji[lon0/]scale (Sinusoidal)
              -Jkf[lon0/]scale (Eckert IV)
              -Jk[s][lon0/]scale (Eckert VI)
              -Jn[lon0/]scale (Robinson)
              -Jr[lon0/]scale (Winkel Tripel)
              -Jv[lon0/]scale (Van der Grinten)
              -Jw[lon0/]scale (Mollweide)

              NON-GEOGRAPHICAL PROJECTIONS:

              -Jp[a]scale[/origin][r|z] (Polar coordinates (theta,r))
              -Jxx-scale[d|l|ppow|t|T][/y-scale[d|l|ppow|t|T]] (Linear, log, and power scaling)

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

       -R     xmin, xmax, ymin, and ymax specify the Region of interest.  For geographic regions,
              these limits correspond to west, east, south, and north and you may specify them in
              decimal  degrees  or in [+-]dd:mm[:ss.xxx][W|E|S|N] format.  Append r if lower left
              and upper right map coordinates are given instead of w/e/s/n.  The  two  shorthands
              -Rg and -Rd stand for global domain (0/360 and -180/+180 in longitude respectively,
              with -90/+90 in latitude).  Alternatively, specify the name  of  an  existing  grid
              file  and  the  -R  settings  (and grid spacing, if applicable) are copied from the
              grid.  For calendar  time  coordinates  you  may  either  give  (a)  relative  time
              (relative  to  the  selected  TIME_EPOCH and in the selected TIME_UNIT; append t to
              -JX|x), or (b) absolute time of the form [date]T[clock] (append T  to  -JX|x).   At
              least  one  of  date and clock must be present; the T is always required.  The date
              string must be of the form [-]yyyy[-mm[-dd]] (Gregorian calendar) or yyyy[-Www[-d]]
              (ISO  week  calendar),  while  the clock string must be of the form hh:mm:ss[.xxx].
              The use of delimiters and their type and positions must  be  exactly  as  indicated
              (however, input, output and plot formats are customizable; see gmtdefaults).

OPTIONS

       No space between the option flag and the associated arguments.

       -A     Angles  are  given  as  azimuths;  convert  them  to  directions  using the current
              projection.

       -B     Sets map boundary annotation and tickmark intervals; see the psbasemap man page for
              all the details.

       -C     Sets the clearance between the text and the surrounding box [15%].  Only used if -W
              is specified.  Append the unit you want (cm, inch, meter.  or point; if  not  given
              we consult MEASURE_UNIT) or % for a percentage of the font size.

       -D     Offsets  the  text  from  the  projected  (x,y) point by dx,dy [0/0].  If dy is not
              specified then it is set equal to dx.  Use -Dj to offset the  text  away  from  the
              point  instead  (i.e., the text's justification will determine the direction of the
              shift).  Optionally, append v which will draw a line from the original point to the
              shifted  point;  append  a  pen  to  change  the  attributes  for  this line.  (See
              SPECIFYING PENS below).

       -E     Sets the viewpoint's azimuth and elevation (for perspective  view)  [180/90].   For
              frames  used for animation, you may want to append + to fix the center of your data
              domain (or specify a particular world coordinate point with  +wlon0/lat[/z])  which
              will  project  to  the  center of your page size (or specify the coordinates of the
              projected view point with +vx0/y0).  (Not implemented for paragraph mode).

       -G     Sets the shade or color used for drawing the text  [Default  is  BASEMAP_FRAME_RGB,
              the current frame color (by default black)] (See SPECIFYING COLOR below).

       -H     Input  file(s) has header record(s).  If used, the default number of header records
              is N_HEADER_RECS.  Use -Hi if only input data should have header  records  [Default
              will  write  out header records if the input data have them]. Blank lines and lines
              starting with # are always skipped.

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

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

       -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 [Default is Landscape,  see  gmtdefaults  to  change
              this].

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

       -U     Draw  Unix  System time stamp on plot.  By adding just/dx/dy/, the user may specify
              the justification of the stamp and where the stamp should fall on the page relative
              to  lower  left  corner of the plot.  For example, BL/0/0 will align the lower left
              corner of the time stamp with the lower  left  corner  of  the  plot.   Optionally,
              append  a  label,  or  c (which will plot the command string.).  The GMT parameters
              UNIX_TIME, UNIX_TIME_POS, and UNIX_TIME_FORMAT can affect the appearance;  see  the
              gmtdefaults man page for details.  The time string will be in the locale set by the
              environment variable TZ (generally local time).

       -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 no fill].  Append
              o to draw rectangle outline, add a pen to specify pen attributes [width = 1,  color
              =  black,  texture = solid].  use a comma to separate the fill information from the
              outline information if both are present.  Choose upper case  O  to  get  a  rounded
              rectangle.   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).
              (See also SPECIFYING PENS and SPECIFYING COLOR below).

       -X -Y  Shift  plot  origin  relative  to  the  current  origin  by  (x-shift,y-shift)  and
              optionally append the length unit (c, i, m, p).  You can prepend  a  to  shift  the
              origin  back  to  the  original position after plotting, or prepend  r [Default] to
              reset the current origin to the new location.  If -O is used then the  default  (x-
              shift,y-shift)   is   (0,0),   otherwise  it  is  (r1i,  r1i)  or  (r2.5c,  r2.5c).
              Alternatively, give c to align the center coordinate (x or y) of the plot with  the
              center of the page based on current page size.

       -Z     For 3-D projections:  Sets the z-level of the basemap [Default is the bottom of the
              z-axis].  If -Z+ is given we expect each item to have its own level  given  in  the
              3rd column, and -N is implicitly set.  (Not implemented for paragraph mode).

       -:     Toggles  between (longitude,latitude) and (latitude,longitude) input and/or output.
              [Default is (longitude,latitude)].  Append i to select input only or  o  to  select
              output only.  [Default affects both].

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

       -f     Special  formatting  of  input  and/or  output columns (time or geographical data).
              Specify i or o to make this apply only to  input  or  output  [Default  applies  to
              both].   Give one or more columns (or column ranges) separated by commas.  Append T
              (absolute calendar time), t (relative time in chosen TIME_UNIT since TIME_EPOCH), x
              (longitude),  y  (latitude),  or  f (floating point) to each column or column range
              item.  Shorthand -f[i|o]g means -f[i|o]0x,1y (geographic coordinates).

       -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 pertaining to the  typesetting  of  a
              text  paragraph  (the  remaining 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  parjust  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.  Separate paragraphs
              with a blank line.

   SPECIFYING PENS
       pen    The attributes of  lines  and  symbol  outlines  as  defined  by  pen  is  a  comma
              delimetered list of width, color and texture, each of which is optional.  width can
              be  indicated  as  a  measure  (points,   centimeters,   inches)   or   as   faint,
              thin[ner|nest],  thick[er|est],  fat[ter|test],  or  obese.  color specifies a gray
              shade or color (see SPECIFYING COLOR below).  texture is a  combination  of  dashes
              `-' and dots `.'.

   SPECIFYING COLOR
       color  The color of lines, areas and patterns can be specified by a valid color name; by a
              gray shade (in the range 0-255); by a decimal color  code  (r/g/b,  each  in  range
              0-255;  h-s-v,  ranges  0-360,  0-1,  0-1;  or c/m/y/k, each in range 0-1); or by a
              hexadecimal color code (#rrggbb, as used in HTML).  See the gmtcolors  manpage  for
              more information and a full list of color names.

EXAMPLES

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

       pstext text.d -R-30/30/-10/20 -Jm 0.1i -P -B 5 -S 0.5p > plot.ps

       To add a typeset figure caption for a 3-inch wide illustration, use

       pstext -R 0/3/0/5 -JX 3i -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

WINDOWS REMARKS

       Note that under Windows, the percent sign (%) is a variable indicator (like $ under Unix).
       To  indicate  a  plain percentage sign in a batch script you need to repeat it (%%); hence
       the font switching mechanism (@%font% and @%%) may require twice  the  number  of  percent
       signs.   This  only applies to text inside a script or that otherwise is processed by DOS.
       Data files that are opened and read by pstext do not need such duplication.

BUGS

       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 output with epstool or ps2epsi to obtain a correct BoundingBox.

SEE ALSO

       GMT(1), gmtcolors(5), psbasemap(1), pslegend(1), psxy(1)