Provided by: gmt_4.5.11-1build1_amd64 bug


       pslegend - To plot a map legend


       pslegend textfile -D[x]lon/lat/width/height/just -Jparameters -Rwest/east/south/north[r] [
       -B[p|s]parameters ] [ -Cdx/dy ] [ -F ] [ -Gfill ] [ -K ] [ -Lspacing ] [ -O ]  [  -P  ]  [
       -S[script]  ] [ -U[just/dx/dy/][c|label] ] [ -V ] [ -X[a|c|r][x-shift[u]] ] [ -ccopies ] [
       -Y[a|c|r][y-shift[u]] ]


       pslegend will make legends that can be overlaid on maps.  It reads specific legend-related
       information  from  an  input  file [or stdin].  Because all the elements of the legend can
       already be created with other tools (psxy, pstext) we use those tools by creating a  batch
       job  of  commands that are executed to make the final PostScript overlay.  Because of this
       process, the option exists to  just  output  the  script  which  can  then  be  fine-tuned
       manually.   Unless otherwise noted, annotations will be made using the annotation font and
       size in effect.

              This file contains instruction for the layout of items in the legend.  Each  legend
              item  is  described  by a unique record.  All records begin with a unique character
              that is common to all records of the same kind.  The order of the legend  items  is
              implied  by  the  order of the records.  Ten different record types are recognized,
              and the syntax for each of these records are presented below:

              # comment Records starting with # and blank lines are skipped.

              B cptname offset height [ optional arguments ]
                     The B record will plot a horizontal color bar, psscale-style in the  middle,
                     starting at offset from the left edge, and of the given height.  You may add
                     any additional psscale options from the list: -A -B -E -I -L -M  -N  -S  and

              C textcolor
                     The  C  record  specifies  the  color with which the remaining text is to be
                     printed.  textcolor can be in the form r/g/b, c/m/y/k, or a named color.

              D offset pen
                     The D record results in a horizontal line  with  specified  pen  across  the
                     legend  with  one quarter of the line spacing left blank above and below the
                     line.  Two gaps of offset units are left blank between the  horizontal  line
                     and the left and right frame sides.  (See SPECIFYING PENS below).

              G gap  The  G  record specifies a vertical gap of the given length.  In addition to
                     the standard units (i, c, p) you may use l for lines.

              H fontsize|- font|- header
                     The H  record  plots  a  centered  text  string  using  the  specified  font
                     parameters.  Use - to default to HEADER_FONT_SIZE and HEADER_FONT.

              I imagefile width justification
                     Place  an  EPS  or  Sun raster image in the legend justified relative to the
                     current point.  The image width determines the size  of  the  image  on  the

              L fontsize|- font|- justification label
                     The  L  record  plots a (L)eft, (C)entered, or (R)ight-justified text string
                     within a column using the specified font parameters.  Use -  to  default  to
                     LABEL_FONT_SIZE and LABEL_FONT.

              M slon|- slat length f|p [ -Rw/e/s/n -Jparam ]
                     Place  a  map  scale in the legend.  Specify slon slat, the point on the map
                     where the scale  applies  (slon  is  only  meaningful  for  certain  oblique
                     projections.  If not needed, you must specify - instead), length, the length
                     of the scale in km (append m or n for miles or nautical miles), and f  or  p
                     for  fancy  or  plain scale.  If the -R -J supplied to pslegend is different
                     than the projection needed for the scale, supply the optional -R -J settings
                     as  well.   Append +l to the length to select the default label which equals
                     the distance unit (km, miles, nautical miles) and is justified on top of the
                     scale  [t].   Change this by giving your own label (append +llabel).  Change
                     label justification with  +jjustification  (choose  among  l(eft),  r(ight),
                     t(op),  and  b(ottom)).   Apply  +u  to  append  the  unit  to  all distance
                     annotations along the scale.  If you want to place a  rectangle  behind  the
                     scale,   specify   suitable  +ppen  and/or  +ffill  parameters.   All  these
                     +modifiers are appended to length to make a single string.  (See  SPECIFYING
                     PENS and SPECIFYING FILL below).

              N ncolumns
                     Change  the  number  of  columns  in  the  legend [1]. This only affects the
                     printing of symbols (S) and labels (L).

              S dx1 symbol size fill pen [ dx2 text ]
                     Plots the selected symbol with specified size, fill, and outline (see psxy).
                     The  symbol  is centered at dx1 from the left margin of the column, with the
                     optional explanatory  text  starting  dx2  from  the  margin,  printed  with
                     fontsize  ANNOT_FONT_SIZE_PRIMARY  and font ANNOT_FONT_PRIMARY.  Use - if no
                     fill or outline (pen) is required.  When plotting  just  a  symbol,  without
                     text,  dx2  and  text  can  be  omitted.   Two  psxy symbols require special
                     attention: front (f) and vector (v).  You must prepend  the  length  of  the
                     desired  item  to  the  rest  of  the  symbol  argument;  this  will be used
                     internally to set the correct fault or vector length and  will  be  stripped
                     before passing the arguments to psxy.

              T paragraph-text
                     One  or  more  of  these T records with paragraph-text printed with fontsize
                     ANNOT_FONT_SIZE_PRIMARY and font ANNOT_FONT_PRIMARY (aligned  and  wrapped).
                     To  specify  special positioning and typesetting arrangements, or to enter a
                     paragraph break, use the optional > record.

              V offset pen
                     The V record draws a vertical line between columns (if more than one)  using
                     the  selected  pen  (See SPECIFYING PENS below).  offset is analogous to the
                     offset for the D records but in the vertical direction.

              > paragraph-mode-header-for-pstext
                     Start a new text paragraph by specifying  all  the  parameters  needed  (see
                     pstext  -m  description).   Note  that  pslegend knows what all those values
                     should be, so normally you can leave the entire record (after  >)  blank  or
                     leave  it  out  all  together.   If  you  need  to  set  at least one of the
                     parameters directly, you must specify all and set the ones you want to leave
                     at their default value to -.

       -D     Positions  the  legend  and specifies its size.  The just is a 2-char justification
              string (see pstext) that relates the given position to a point on  the  rectangular
              legend box.  If you want to specify the position in map plot units (i.e., inches or
              cm), use -Dx.

       -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,
              More details can be found in the psbasemap man pages.


              -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)


              -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)


              -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)


              -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)

       -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[][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).


       No space between the option flag and the associated arguments.

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

       -C     Sets the clearance between the legend frame and the internal items [0.15c/0.15c (or

       -F     Draws a border around the legend using FRAME_PEN.

       -G     Select fill shade, color or pattern of the legend box [Default is no  fill].   (See
              SPECIFYING FILL below).

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

       -L     Sets the linespacing factor in units of the current annotation font size [1.1].

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

       -P     Selects  Portrait  plotting  mode  [Default is Landscape, see gmtdefaults to change

       -S     Instead of writing the PostScript plot [Default], output the  GMT  script  used  to
              make the legend to standard output, or optionally to the file script.

       -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

       -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.

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

       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 `.'.

       fill   The attribute fill specifies the solid shade or solid color (see  SPECIFYING  COLOR
              below)  or  the  pattern  used  for  filling  polygons.   Patterns are specified as
              pdpi/pattern, where pattern gives the number of the built-in pattern (1-90) or  the
              name  of  a  Sun  1-, 8-, or 24-bit raster file. The dpi sets the resolution of the
              image.  For  1-bit  rasters:  use  Pdpi/pattern  for  inverse  video,   or   append
              :Fcolor[B[color]]  to  specify  fore-  and  background  colors  (use  color = - for
              transparency).  See GMT Cookbook & Technical Reference Appendix E  for  information
              on individual patterns.

       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.


       To  add  an example of a legend to a Mercator plot ( with the given specifications,

       pslegend -R-10/10/-10/10 -JM 6i -G azure1 -Dx 0.5i/0.5i/5i/3.3i/BL -C 0.1i/0.1i -L 1.2  -F
       -B 5f1 << EOF >>
       G -0.1i
       H 24 Times-Roman My Map Legend
       D 0.2i 1p
       N 2
       V 0 1p
       S 0.1i c 0.15i p300/12 0.25p 0.3i This circle is hachured
       S 0.1i e 0.15i 255/255/0 0.25p 0.3i This ellipse is yellow
       S 0.1i w 0.15i 0/255/0 0.25p 0.3i This wedge is green
       S 0.1i f 0.25i/-1/0.075ilb 0/0/255 0.25p 0.3i This is a fault
       S 0.1i - 0.15i - 0.25tap 0.3i A contour
       S 0.1i v 0.25i/0.02i/0.06i/0.05i 255/0/255 0.25p 0.3i This is a vector
       S 0.1i i 0.15i 0/255/255 0.25p 0.3i This triangle is boring
       V 0 1p
       D 0.2i 1p
       N 1
       M 5 5 600+u f
       G 0.05i
       I SOEST_logo.ras 3i CT
       G 0.05i
       B colors.cpt 0.2i 0.2i
       G 0.05i L 9 4 R Smith et al., @%5%J. Geophys. Res., 99@%%, 2000
       G 0.1i
       T Let us just try some simple text that can go on a few lines.
       T There is no easy way to predetermine how many lines will be required,
       T so we may have to adjust the box height to get the right size box.


       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 pslegend do not need such duplication.


       GMT(1), gmtcolors(5), gmtdefaults(1), psbasemap(1), pstext(1), psxy(1)