Provided by: gmt-common_5.4.5+dfsg-1_all bug

NAME

       pstext - Plot or typeset text on maps

SYNOPSIS

       pstext [ textfiles ]  -Jparameters
        -Rwest/east/south/north[/zmin/zmax][+r] [  -A ]
        -B[p|s]parameters            [            -D[j|J]dx[/dy][+v[pen]]           ]           [
       -F[+a[angle]][+c[justify]][+f[font]][+j[justify]][+h|+l|+r[first] |+ttext|+z[format]] ]  [
       -Gcolor  ]  [   -K ] [  -L ] [  -M ] [  -N ] [  -O ] [  -P ] [  -Ql|u ] [  -To|O|c|C ] [ [
       -Wpen ] [  -Xx_offset ] [  -Yy_offset ] [  -U[stamp] ] [   -Z  ]  [  -acol=name[...]  ]  [
       -eregexp ] [ -fflags ] [ -hheaders ] [ -pflags ] [ -ttransp ] [ -:[i|o] ]

       Note: No space is allowed between the option flag and the associated arguments.

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    Char-esc-seq     and     Appendix
       Chart-Octal-Codes-for-Chars  in  the  GMT  Technical  Reference  and  Cookbook.  Note that
       PS_CHAR_ENCODING must be set to an extended character set in your gmt.conf file  in  order
       to  use  the  accented  characters. Using the -G or -W options, a 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)).

REQUIRED ARGUMENTS

       -Jparameters (more ...)
              Select map projection.

       -Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
              Specify the region of interest.

       For perspective view p, optionally append /zmin/zmax. (more ...)

OPTIONAL ARGUMENTS

       textfiles
              This  is  one  or more files containing 1 or more records with (x, y[, font, angle,
              justify], text). The attributes in brackets can alternatively be set  directly  via
              -F.  If  no  files  are  given,  pstext  will  read  standard input. font is a font
              specification with format [size,][font,][color] where size is text size in  points,
              font  is  the font to use, and color sets the font color. To draw outline fonts you
              append  =pen  to  the  font  specification.  The  angle  is  measured  in   degrees
              counter-clockwise  from horizontal, and justify sets the alignment.  If font is not
              an integer, then it is taken to be a text string with the desired font name (see -L
              for available fonts). 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.

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

       -B[p|s]parameters (more ...)
              Set map boundary frame and axes attributes.

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

       -D[j|J]dx[/dy][+v[pen]]
              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 justification will determine the direction of the
              shift). Using -DJ will shorten diagonal offsets at corners by sqrt(2).  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.

       -F[+a[angle]][+c[justify]][+f[font]][+j[justify]][+h|+l|+r[first] |+ttext|+z[format]]
              By default, text will be placed horizontally, using  the  primary  annotation  font
              attributes (FONT_ANNOT_PRIMARY), and centered on the data point. Use this option to
              override these defaults by specifying up to three text attributes (font, angle, and
              justification)   directly   on   the   command   line.  Use  +f  to  set  the  font
              (size,fontname,color); if no font info is given then the input file must have  this
              information  in  one  of its columns. Use +a to set the angle; if no angle is given
              then the input file must have this as a column.  Alternatively,  use  +A  to  force
              text-baselines to convert into the -90/+90 range.  Use +j to set the justification;
              if no justification is given then the input file must have this as a column.  Items
              read  from  the  data  file  should  be  in the same order as specified with the -F
              option. Example: -F+f12p,Helvetica-Bold,red+j+a selects a  12p  red  Helvetica-Bold
              font  and expects to read the justification and angle from the file, in that order,
              after x, y and before text.  In addition, the +c  justification  lets  us  use  x,y
              coordinates  extracted  from  the  -R string instead of providing them in the input
              file. For example -F+cTL gets the x_min, y_max from the -R  string  and  plots  the
              text  at  the Upper Left corner of the map.  Normally, the text to be plotted comes
              from the data record.  Instead, use +h or +l to select the text as the most  recent
              segment  header  or segment label, respectively in a multisegment input file, +r to
              use the record number (counting up from first), +ttext to set a fixed text  string,
              or  +z  to  format  incoming  z  values  to a string using the supplied format [use
              FORMAT_FLOAT_MAP].

       -Gcolor
              Sets the shade or color used for  filling  the  text  box  [Default  is  no  fill].
              Alternatively,  use  -Gc to plot the text and then use the text dimensions (and -C)
              to build clip paths and turn clipping on.  This clipping can  then  be  turned  off
              later with psclip -C.  To not plot the text but activate clipping, use -GC instead.

       -Jz|Zparameters (more ...)
              Set z-axis scaling; same syntax as -Jx.

       -K (more ...)
              Do not finalize the PostScript plot.

       -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 pertaining to the typesetting of a text
              paragraph (the remaining lines until next segment header). The information expected
              is  (x  y  [font  angle  justify] linespace parwidth parjust), where x y font angle
              justify are defined above (font, angle, and justify  can  be  set  via  -F),  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.  Note that here, the justification set via
              -F+j applies to the box alignment since the text justification is set by parjust.

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

       -O (more ...)
              Append to existing PostScript plot.

       -P (more ...)
              Select "Portrait" plot orientation.

       -Q     Change all text to either lower or upper case [Default leaves all text as is].

       -T     Specify the shape of the textbox when using -G and/or -W.  Choose lower case  o  to
              get  a  straight  rectangle  [Default].   Choose  upper  case  O  to  get a rounded
              rectangle. In paragraph mode (-M) you can also choose lower case c to get a concave
              rectangle or upper case C to get a convex rectangle.

       -U[[just]/dx/dy/][c|label] (more ...)
              Draw GMT time stamp logo on plot.

       -V[level] (more ...)
              Select verbosity level [c].

       -Wpen  Sets  the  pen used to draw a rectangle around the text string (see -T) [Default is
              width = default, color = black, style = solid].

       -X[a|c|f|r][x-shift[u]]

       -Y[a|c|f|r][y-shift[u]] (more ...)
              Shift plot origin.

       -Z     For 3-D projections: expect each item to have  its  own  level  given  in  the  3rd
              column, and -N is implicitly set. (Not implemented for paragraph mode).

       -acol=name[...] (more ...)
              Set aspatial column associations col=name.

       -e[~]"pattern" | -e[~]/regexp/[i] (more ...)
              Only accept data records that match the given pattern.

       -f[i|o]colinfo (more ...)
              Specify data types of input and/or output columns.

       -h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
              Skip or produce header record(s).

       -:[i|o] (more ...)
              Swap 1st and 2nd column on input and/or output.

       -p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more ...)
              Select perspective view. (Not implemented for paragraph mode).

       -t[transp] (more ...)
              Set PDF transparency level in percent.

       -^ or just -
              Print a short message about the syntax of the command, then exits (NOTE: on Windows
              just use -).

       -+ or just +
              Print  an  extensive  usage  (help)  message,  including  the  explanation  of  any
              module-specific option (but not the GMT common options), then exits.

       -? or no arguments
              Print  a  complete  usage (help) message, including the explanation of all options,
              then exits.

EXAMPLES

       To plot just the red outlines of the (lon lat text strings) stored in the file text.d on a
       Mercator plot with the given specifications, use

              gmt pstext text.d -R-30/30/-10/20 -Jm0.1i -P -F+f18p,Helvetica,-=0.5p,red -B5 > plot.ps

       To plot a text at the upper left corner of a 10 cm map

              echo TopLeft | gmt pstext -R1/10/1/10 -JX10 -F+cTL -P > plot.ps

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

              gmt pstext -R0/3/0/5 -JX3i -O -h1 -M -N -F+f12,Times-Roman+jLT << EOF >> figure.ps

              This is an unmarked header record not starting with #
              > 0 -0.5 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.

LIMITATIONS

       In  paragraph  mode,  the  presence of composite characters and other escape sequences may
       lead to unfortunate word splitting. Also, if a font is requested with an  outline  pen  it
       will  not  be  used  in paragraph mode.  Note if any single word is wider than your chosen
       paragraph width then the paragraph width is automatically enlarged to fit the widest word.

SEE ALSO

       gmt, gmt.conf, psclip, gmtcolors, psconvert, psbasemap, pslegend, psxy

COPYRIGHT

       2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe