| 
	    pllegend
	  ( | p_legend_width, | 
| p_legend_height, | |
| opt, | |
| position, | |
| x, | |
| y, | |
| plot_width, | |
| bg_color, | |
| bb_color, | |
| bb_style, | |
| nrow, | |
| ncolumn, | |
| nlegend, | |
| opt_array, | |
| text_offset, | |
| text_scale, | |
| text_spacing, | |
| test_justification, | |
| text_colors, | |
| text, | |
| box_colors, | |
| box_patterns, | |
| box_scales, | |
| box_line_widths, | |
| line_colors, | |
| line_styles, | |
| line_widths, | |
| symbol_colors, | |
| symbol_scales, | |
| symbol_numbers, | |
| symbols ); | 
      Routine for creating a discrete plot legend with a plotted
      filled box, line, and/or line of symbols for each annotated legend
      entry.  (See plcolorbar for similar functionality for creating
      continuous color bars.)  The arguments of pllegend provide control
      over the location and size of the legend as well as the location and
      characteristics of the elements (most of which are optional) within
      that legend.  The resulting legend is clipped at the boundaries of the
      current subpage.  (N.B. the adopted coordinate system used for some of
      the parameters is defined in the documentation of the
      position
p_legend_width
	  (PLFLT_NC_SCALAR
	    Returned value of the
	    legend width in adopted coordinates. This quantity is
	    calculated from plot_widthtext_offsetncolumnnlegendnrow
p_legend_height
	  (PLFLT_NC_SCALAR
	    Returned value of the
	    legend height in adopted coordinates. This quantity is
	    calculated from text_scaletext_spacingnrownlegendnrow
opt
	  (PLINT
	    optPL_LEGEND_TEXT_LEFT bit is set, put the text area
	    on the left of the legend and the plotted area on the
	    right. Otherwise, put the text area on the right of the legend and the
	    plotted area on the left. If the
	    PL_LEGEND_BACKGROUND bit is set, plot a
	    (semitransparent) background for the legend. If the
	    PL_LEGEND_BOUNDING_BOX bit is set, plot a bounding
	    box for the legend. If the PL_LEGEND_ROW_MAJOR bit
	    is set and (both of the possibly internally transformed)
	    nrowncolumn
position
	  (PLINT
	    positionplcolorbar. However,
	    note that the defaults for the position bits (see below) are
	    different than the plcolorbar case.  The combination of the
	    PL_POSITION_LEFT,
	    PL_POSITION_RIGHT,
	    PL_POSITION_TOP,
	    PL_POSITION_BOTTOM,
	    PL_POSITION_INSIDE, and
	    PL_POSITION_OUTSIDE bits specifies one of the 16
	    possible standard positions (the 4 corners and centers of the 4 sides
	    for both the inside and outside cases) of the legend relative to the
	    adopted coordinate system. The corner positions are specified by the
	    appropriate combination of two of the
	    PL_POSITION_LEFT,
	    PL_POSITION_RIGHT,
	    PL_POSITION_TOP, and
	    PL_POSITION_BOTTOM bits while the sides are
	    specified by a single value of one of those bits.  The adopted
	    coordinates are normalized viewport coordinates if the
	    PL_POSITION_VIEWPORT bit is set or normalized
	    subpage coordinates if the PL_POSITION_SUBPAGE bit
	    is set. Default position bits: If none of
	    PL_POSITION_LEFT,
	    PL_POSITION_RIGHT,
	    PL_POSITION_TOP, or
	    PL_POSITION_BOTTOM are set, then use the
	    combination of PL_POSITION_RIGHT and
	    PL_POSITION_TOP. If neither of
	    PL_POSITION_INSIDE or
	    PL_POSITION_OUTSIDE is set, use
	    PL_POSITION_INSIDE. If neither of
	    PL_POSITION_VIEWPORT or
	    PL_POSITION_SUBPAGE is set, use
	    PL_POSITION_VIEWPORT.
	  
x
	  (PLFLT
	    X offset of the legend position in adopted coordinates
	    from the specified standard position of the legend. For positive x,
	    the direction of motion away from the standard position is
	    inward/outward from the standard corner positions or
	    standard left or right positions if the
	    PL_POSITION_INSIDE/PL_POSITION_OUTSIDE
	    bit is set in position
y
	  (PLFLT
	    Y offset of the legend position in adopted coordinates
	    from the specified standard position of the legend. For positive y,
	    the direction of motion away from the standard position is
	    inward/outward from the standard corner positions or standard
	    top or bottom positions if the
	    PL_POSITION_INSIDE/PL_POSITION_OUTSIDE
	    bit is set in position
plot_width
	  (PLFLTHorizontal width in adopted coordinates of the plot area (where the colored boxes, lines, and/or lines of symbols are drawn) of the legend.
bg_color
	  (PLINT
	    The cmap0 color of the background for the legend
	    (PL_LEGEND_BACKGROUND).
	  
bb_color
	  (PLINT
	    The cmap0 color of the bounding-box line for the legend
	    (PL_LEGEND_BOUNDING_BOX).
	  
bb_style
	  (PLINT
	    The pllsty style number for the bounding-box line for the legend
	    (PL_LEGEND_BACKGROUND).
	  
nrow
	  (PLINT
	    The number of rows in the matrix used to render the
	    nlegend legend entries. For internal
	    transformations of nrow, see further remarks
	    under nlegend.
	  
ncolumn
	  (PLINT
	    The number of columns in the matrix used to render the
	    nlegend legend entries. For internal
	    transformations of ncolumn, see further remarks
	    under nlegend.
	  
nlegend
	  (PLINT
            Number of legend entries. The above
	    nrow and ncolumn values
	    are transformed internally to be consistent with
	    nlegend. If either nrow
	    or ncolumn is non-positive it is replaced by
	    1. If the resulting product of nrow and
	    ncolumn is less than
	    nlegend, the smaller of the two (or
	    nrow, if nrow ==
	    ncolumn) is increased so the product is >=
	    nlegend. Thus, for example, the common
	    nrow = 0, ncolumn = 0
	    case is transformed internally to nrow =
	    nlegend, ncolumn = 1;
	    i.e., the usual case of a legend rendered as a single column.
	  
opt_array
	  (PLINT_VECTOR
	    A vector of nlegend values of options to control each
	    individual plotted area corresponding to a legend entry.  If the
	    PL_LEGEND_NONE bit is set, then nothing is
	    plotted in the plotted area.  If the
	    PL_LEGEND_COLOR_BOX,
	    PL_LEGEND_LINE, and/or
	    PL_LEGEND_SYMBOL bits are set, the area
	    corresponding to a legend entry is plotted with a colored box; a line;
	    and/or a line of symbols.
	  
text_offset
	  (PLFLTOffset of the text area from the plot area in units of character width.
text_scale
	  (PLFLTCharacter height scale for text annotations.
text_spacing
	  (PLFLTVertical spacing in units of the character height from one legend entry to the next.
text_justification
	  (PLFLTJustification parameter used for text justification. The most common values of text_justification are 0., 0.5, or 1. corresponding to a text that is left justified, centred, or right justified within the text area, but other values are allowed as well.
text_colors
	  (PLINT_VECTOR
	    A vector containing nlegend cmap0 text colors.
	  
text
	  (PLCHAR_MATRIX
	    A vector of nlegend UTF-8 character strings containing
	    the legend annotations.
	  
box_colors
	  (PLINT_VECTOR
	    A vector containing nlegend cmap0 colors for the discrete colored boxes
	    (PL_LEGEND_COLOR_BOX).
	  
box_patterns
	  (PLINT_VECTOR
	    A vector containing nlegend patterns (plpsty indices) for the discrete colored
	    boxes (PL_LEGEND_COLOR_BOX).
	  
box_scales
	  (PLFLT_VECTOR
	    A vector containing nlegend scales (units of fraction of character height) for
	    the height of the discrete colored boxes
	    (PL_LEGEND_COLOR_BOX).
	  
box_line_widths
	  (PLFLT_VECTOR
	    A vector containing nlegend line widths for the patterns specified by
            box_patterns (PL_LEGEND_COLOR_BOX).
	  
line_colors
	  (PLINT_VECTOR
	    A vector containing nlegend cmap0 line colors
	    (PL_LEGEND_LINE).
	  
line_styles
	  (PLINT_VECTOR
	    A vector containing nlegend line styles (plsty indices)
	    (PL_LEGEND_LINE).
	  
line_widths
	  (PLFLT_VECTOR
	    A vector containing nlegend line widths
	    (PL_LEGEND_LINE).
	  
symbol_colors
	  (PLINT_VECTOR
	    A vector containing nlegend cmap0 symbol colors
	    (PL_LEGEND_SYMBOL).
	  
symbol_scales
	  (PLFLT_VECTOR
	    A vector containing nlegend scale values for the symbol height
	    (PL_LEGEND_SYMBOL).
	  
symbol_numbers
	  (PLINT_VECTOR
	    A vector containing nlegend numbers of symbols to be drawn across the width of
	    the plotted area (PL_LEGEND_SYMBOL).
	  
symbols
	  (PLCHAR_MATRIX
	    A vector of nlegend UTF-8 character strings containing
	    the legend symbols.
	    (PL_LEGEND_SYMBOL).
	  
      Redacted form: pllegend(p_legend_width, p_legend_height,
      opt, position, x, y, plot_width,
      bg_color, bb_color, bb_style,
      nrow, ncolumn,
      opt_array,
      text_offset, text_scale, text_spacing, test_justification,
      text_colors, text,
      box_colors, box_patterns,
      box_scales, box_line_widths,
      line_colors, line_styles, line_widths,
      symbol_colors, symbol_scales,
      symbol_numbers, symbols)
    
This function is used in examples 4, 26, and 33.