addlegend - ancillary GMT utility, written by HGS
 

Usage:

   [set ]posexpr=`echo text |\
.................addlegend -yposexpr [-ddy] [-ttempfile].............\
...........................[+yespace][ [-llength]....................\
                           -psxy options ............................\
                           +pstext options ... [+ffont[/size]] [+oyoff]`

Auxiliary:

    [set ]posexpr=`echo text | addlegpos -yposexpr [-ddy][+yespace]`
       for adding a text line without a symbol

   [set ]posexpr=`backsplegend posexpr`
         before overwriting a line, e.g. composing a symbol.  

Note: psxy-options mark is minus-sign, e.g. -W[pen[/color[type]]
      pstext-  "     "     plus-sign,  e.g. +Wcolor
Purpose:

Adds a pair of psxy and pstext commands to a tempfile, which can be used with   source  (csh) or  (sh/ksh) to draw the legend. Recommended procedure is  pslegend. A number of curve features are saved and repeated in the legend, and explanatory text is expected on STDIN. The basic idea is that you repeat the options of a psxy  command, add a few simple legend options on the command line, and supply a text line. To this end addlegend tolerates but ignores some psxy options like -R -J.

Example (we're in the middle of a GMT script):
    set yloc=0
    psxy file.xy -R -Jx -Sc0.1 -G100/0/0 -W1/0 -K -O -P >> out.ps
    psxy file.xy -R -Jx -W3/255/0/0 -K -O -P >> out.ps
    set yloc=`echo Heartbeat | addlegend -y$yloc -d1 -R -Jx -Sc0.1 -G100/0/0 -W1/0 -w3
/255/0/0 -K -O -P`
    # ...
    # finally
    pslegend -y$yloc -JX2/1 >> out.ps
    echo Ready out.ps

Here, the new options control the location and spacing ( -y -d ), the psxy options for symbol type, symbol fill and symbol outline ( -G -S -W  ) and for line weight and color ( -w ) are significant, and the -R -Jx -K -O -P options are convenient nuisance options
(in csh you could copy the psxy arguments using an array variable and add the few extra needed).

Drawing the legend with  pslegend  will overcore the settings of the -R and -J options, therefore you will need to set them aside for later use. See also pslegend -h

/usr/local/GMT/bin/pslegend      is a symbolic link to
/home/hgs/perlproc/pslegend.pl

The addlegpos command aids in incrementing the position expression and obtaining updated limits. Useful in situations where a user
for instance wants to add extra space above the legend text. 

I/O:
Reads from STDOUT: The explanatory text for the legend.
Prints to  STDOUT: <posexpr>,
new position expression, a suggested next legend position, and current box limits parameters.
Prints to  STDERR:
Runtime messages.

Therefore, a typical call from within a sh or ksh script would read:
   newy=`echo legend-comment | addlegend -y$oldy ...`
or
   ypos=0
   ypos=`echo
legend-comment | addlegend -y$ypos ...`

However, also the following will work, of course:
   #!/bin/sh
...
   oldy=`cat temp.val`
   addlegend -y$oldy ... << END > temp.val
   legend-comment
   END
...

More than one line of text can be entered, but is not recommended for beginners.

Options:
Options that are
proprietary to addlegend:

 -yposexpr   - to place a legend entry at position  posexpr. The next
..................legend line will be  dy  above  posexpr.

..................In general
..................<posexpr> := <pos>[/<min>/<max>[/<mypos>]]

..................Obs! If only  pos  is specified, min and max are reset;
..................then it's your job to keep track of the extrema.
..................To keep min  and  max  while requesting a specific
..................mypos, use  anything/min/max/mypos;
..................then mypos  will be taken and  anything ignored.
..................Since a suggestion for the next expression in the form
..................pos/min/max is returned on STDOUT, you can call
.....................y=`addlegend -y$y ...`         for automatic increment
..................or y=`addlegend -y$y/mypos ...` for user control.
..................Default posexpr = 0

 +yespace      - Above the top line of the legend some extra space may be
................. needed. Specify  espace  in units of lines (-ddy)

 -ddy          - Vertical increment; default dy = -1 (implying downward
..................extension). dy is needed also with the last legend
..................entry as addlegend must reserve space around it.
..................Units are arbitrary internal data units. The -R option
..................of pslegend will have to refer to these units though.

 -tfile        - name of the command file that is assembled by addlegend.
..................Default <file> = .gmtlegend.cmd or, if existent,
..................environment parameter GMTLEGENDCMD

 +ffont[/size][/placement
...............- If given, must start with + (plus!) Default is  +f0/12/5

 -llength      - Endpoint of the line sample. Begin is always 0.1. Default 0.25 

 +ldash        - for dash-dot lines: implies increased length by 0.2, symbol x-offset far left,
............... ..text x-offset +0.1. Can be overridden with subsequent +o -o  

 -o[xoff/]yoff - Offset sample symbol vertically, in units of -ddy.
..................Default xoff = 0.
 +o[xoff/]yoff - Offset sample text vertically, in units of -ddy.
..................Default xoff = 0.

Options that differ from GMT when drawing lines and symbols in the legend:

 -v          - vector sample (symbol is drawn with GMT psvelo)
 -si         - strain symbols (
drawn with GMT psvelo, probably never tested)
 -m          - "mechanism" sample
(symbol is draw with GMT psmeca, not really finished)
 -Wpen
       - Symbol outline
 -wpen       - Line weight and colour
 +Wfill      - Text filling option (pstext)

Options that apply to both  psxy AND pstext:
-P -N
can be given as +P +N

addlegend has the ambition to show in the legend:
 *  line color, thickness, morse-code (from psxy -Wpen)
 *  symbols (from psxy -Ssymbol) including vectors, eventually with error circle
 *  error bars (from psxy -Ebar)

To obtain a specific vector size (to show a representative sample), append  :size  to option -Sv

To tailor the error bar  or the error circle, append :scale  to the -E  or the -Se option, respectively. The scale factor is measured in
fractions of the line spacing, dy. Default is 16 (i.e. results in error bar half width resp. radius = dy/16)

Symbols (error bars) and lines are often plotted in two separate runs of psxy. For the legend, the line attributes can be specified to addlegend after option -w and the symbol outline attributes after option -W. See example 'perspiration' below.
However, addlegend can also compose a symbol; you simply call addlegend several times while avoiding to update the position
expression.

If you need to tell a legend of bars (-Sb) the following will work:

   sb=`awk -v y=$ypos 'BEGIN{print y+0.5}'`

   ... addlegend ... -Sbthick/$sb ...

where 0.5 is the height of the bar, in spite of  the   "value/value/value"   form of  $ypos.

Example:
   psxy -R -JX -W0.2            \
        -G255/0/0 -Sb0.1/${base} \
        -V -K -O -P               >> $psout

   sb=`awk -v y=$ypos 'BEGIN{print y+0.5}'`

   ypos=`echo "Schwiderski" | addlegend -y$ypos -d1 +o.2 -Sb0.1/$sb -w -R -JX -W0.2 -G255/0/0 -P -K -O`
 

If you don't need to distinguish symbol and line pens, use the -Wpen option.

If you don't want a line through the symbol, use an empty -w option.

If legend entries are to be superimposed (most likely for the curve symbol), two calls are needed. Incrementing with -d0 does not seem to work.
The following does:
   set yloco=$yloc
   set yloc=`echo text | addlegend -y$yloc ... +G255 ... `      (introducing one symbol, text colour = background colour)
   set yloc=`echo text | addlegend -y$yloco ...'                         (superimposing another symbol, text colour = black by default)


Example:
The light-gray strings are redundant

#!/bin/sh
psxy bp.dat          -R1998.7/80/1998.8/180 -JX5/5 -Sc0.1 -W3/255/0/0 -P -K -O >> psout.ps

yl=`echo blood pressure |\
     addlegend -y0   -R1998.7/80/1998.8/180 -JX5/5 -Sc0.1 -W3/255/0/0 -P -K -O`

psxy hb.dat          -R -JX -Ss0.1 -W3/0/255/0 -P -K -O >> psout.ps

yl=`echo heart beat |\
     addlegend -y$yl -R -JX -Ss0.1 -W3/0/255/0 -P -K -O`

psxy psp.dat         -R -JX -Sa0.1 -W1/0/127/127 -P -K -O >> psout.ps

psxy psp.dat         -R -JX        -W3/0/255/255 -P -K -O >> psout.ps

yl=`echo perspiration |\
     addlegend -y$yl -R -JX -Sa0.1 -W1/0/127/127 -w3/0/255/255 -P -K -O`

pslegend -y$yl -JX1/1 -X4 -Y4 -P -K -O >> psout.ps