The **-l** option
^^^^^^^^^^^^^^^^^

**Syntax**

**-l**\ [*label*]\ [**+D**\ *pen*][**+G**\ *gap*][**+H**\ *header*][**+L**\ [*code*/]\ *text*][**+N**\ *cols*]\
[**+S**\ *size*\ [/*height*]][**+V**\ [*pen*]][**+f**\ *font*][**+g**\ *fill*][**+j**\ *justify*][**+o**\ *off*]\
[**+p**\ *pen*][**+s**\ *scale*][**+w**\ *width*]

    Add a map legend entry to the session legend information file for the current plot.

**Description**

The **-l** option is used to automatically build the *specfile* that is read by the :doc:`/legend` module to create
map or plot legends. This allows detailed and complicated legends that mix a variety of items, such as symbols, free
text, colorbars, scales, images, and more. Yet, a simple legend will suffice for the vast majority of plots displaying
symbols or lines. Optionally, append a text *label* to describe the entry. The following modifiers are supported to
allow further changes to the legend that is built by :doc:`/legend` (upper-case modifiers reflect legend codes described
in :doc:`/legend`, which provides more details and customization):

- **+D** - Draw a horizontal line in the given *pen* before the legend entry is placed [default is no line].
- **+G** - Add the vertical space specified by *gap* [default is no extra space].
- **+H** - Add the specified legend *header* [default is no header].
- **+L** - Set a line *text*. Optionally, prepend a horizontal justification code **L**\ (eft), **C**\ (enter),
  or **R**\ (ight) for *text* [default is **C**].
- **+N** - Change the number of columns used to set the following legend items to *cols* [default is 1].
- **+S** - Override the *size* of the current symbol for the legend or set a *height* if plotting a line or contour
  [default uses the same symbol as plotted].
- **+V** - Start and **+v**\ *pen* to stop drawing vertical line from previous to current horizontal line [default is
  no vertical line].
- **+f** - Set the *font* used for the legend header [default is :term:`FONT_TITLE`].
- **+g** - Set the *fill* used for the legend frame [default is white].
- **+j** - Set placement of the legend using the two-character justification code *justify* [default is **TR**].
- **+o** - Set the *offset* from legend frame to anchor point [default is 0.2c].
- **+p** - Set the *pen* used for the legend frame [default is 1p].
- **+s** - Resize all symbol and length sizes in the legend by *scale* [default is no scaling].
- **+w** - Set legend frame *width* [default is auto].

**Notes**: (1) Default pen is given by :term:`MAP_DEFAULT_PEN`. (2) **+H**, **+g**, **+j**, **+o**, **+p**, **+w**, and
**+s** will only take effect if appended to the very \ first **-l** option for a plot. The **+N** modifier, if appended
to the first **-l** option, affects the legend width (unless set via **+w**); otherwise it just subdivides the available
width among the specified columns. If **legend** is not called explicitly we will call it implicitly when finishing the
plot via :doc:`/end`. (3) If auto-coloring is used for pens or fills and **-l** is set then *label* may contain a
C-format for integers (e.g., %3.3d) or just # and we will use the sequence number with the format to build the label
entries.  Alternatively, give a list of comma-separated labels, or give no label if your segment headers contain label
settings. (4) Due to this mechanism, if your single label actually contains commas, you must replace these with the
octal code for a comma (\\054).
