explain_symbols.rst_

**-S**\ [*symbol*][*size*]
    Plot symbols (including vectors, wedges, fronts, decorated or quoted lines).
    If present, *size* is symbol size in the default unit set by
    :term:`PROJ_LENGTH_UNIT` (unless **c**, **i**, or **p** is appended). If the symbol
    code (see below) is not given it will be read from the last column in
    the input data; this scheme cannot be used in conjunction with binary input.
    Optionally, append **c**, **i**, or **p** to indicate that the size information
    in the input data is in units of cm, inch, or point, respectively [Default is
    :term:`PROJ_LENGTH_UNIT`]. **Note**: If you provide *both* size and symbol via the
    input file you *must* use :term:`PROJ_LENGTH_UNIT` to indicate the unit
    used for the symbol size or append the units to the sizes listed in the file.
    If symbol sizes are expected via one or more data columns then you may convert
    those values to suitable symbol sizes via the **-i** mechanism. The general
    input expectations are:

    *coordinates* [ *value* ] [ *parameters* ] [ *symbol* ]

    where *coordinates* is two or three columns specifying the location of a point,
    the optional *value* is required when |-C| is used to control color, the optional
    *parameters* is required when no symbol size is specified, and the trailing
    text with leading *symbol* code is required when the symbol code is not specified
    on the command line.  **Note**: *parameters* may represent more than one *size*
    column as some symbols require several parameters to be defined (e.g., a circle
    just needs one column, a rectangle needs two dimensions, while an ellipse needs an
    orientation and two dimensions, and so on); see specifics below.  When there is only
    a single parameter we will refer to it as *size*.

    You can also change symbols by adding the required |-S| option to any of
    your multi-segment headers.

    We will first outline the 14 basic geometric symbols that only require
    a *single* parameter: *size*.

    .. figure:: /_images/GMT_base_symbols1.*
        :width: 600 px
        :align: center

        The 14 basic geometric symbols available, shown with their symbol codes.
        Four symbols (**-**\ \|\ **+**\ \|\ **x**\ \|\ **y**) are line-symbols only
        (|-W|), one (the point **p** only takes a color via |-G|) while the rest
        may have outline (|-W|) and fill (|-G|) specified.
        The thin circles represent the circumscribing circle of the same size.

    **-S-**\ *size*
        x-dash (-). *size* is the length of a short horizontal (x-dir) line segment.

    **-S+**\ *size*
        Plus (+). *size* is diameter of circumscribing circle.

    **-Sa**\ *size*
        St\ **a**\ r. *size* is diameter of circumscribing circle.

    **-Sc**\ *size*
        **c**\ ircle. *size* is diameter of circle.

    **-Sd**\ *size*
        **d**\ iamond. *size* is diameter of circumscribing circle.

    **-Sg**\ *size*
        Octa\ **g**\ on. *size* is diameter of circumscribing circle.

    **-Sh**\ *size*
        **h**\ exagon. *size* is diameter of circumscribing circle.

    **-Si**\ *size*
        **i**\ nverted triangle. *size* is diameter of circumscribing circle.

    **-Sn**\ *size*
        Pe\ **n**\ tagon. *size* is diameter of circumscribing circle.

    **-Sp**\ *size*
        **p**\ oint. No size needs to be specified (1 pixel is used).

    **-Ss**\ *size*
        **s**\ quare. *size* is diameter of circumscribing circle.

    **-St**\ *size*
        **t**\ riangle. *size* is diameter of circumscribing circle.

    **-Sx**\ *size*
        Cross (x). *size* is diameter of circumscribing circle.

    **-Sy**\ *size*
        y-dash (\|). *size* is the length of a short vertical (y-dir) line segment.

    **Notes**: (1) The uppercase symbols **A**, **C**, **D**, **G**, **H**, **I**, **N**,
    **S**, **T** are normalized to have the same *area* as a circle with
    diameter *size*, while the *size* of the corresponding lowercase symbols
    refers to the diameter of a circumscribed circle. (2) The stroke-only symbols
    **x**, **y**, **+** and **-** will derive their pen widths from the symbol size
    and their pen color from |-G| or |-C|. In that sense they behave as the other
    symbols (but no outline).  You can override this behavior by specifying |-W|,
    modify it by adjusting :term:`MAP_STROKE_WIDTH` [15%], or set it to zero to
    rely on pen defaults (and |-W|).

    The next collection shows five symbols that require two or more parameters, and
    some have optional modifiers to enhance the symbol appearance.

    .. figure:: /_images/GMT_base_symbols2.*
        :width: 600 px
        :align: center

        Five basic geometric multi-parameter symbols, shown with their symbol codes.
        All take two or three parameters to define the symbol; see below for details.
        Upper-case versions **E**, **J**, and **W** are similar to **e**, **j** and **w**
        but expect geographic azimuths and distances.

    **-Se**\ [*direction*/]\ *major_axis*\ [/*minor_axis*]
        **e**\ llipse. If not given, then *direction* (in degrees counter-clockwise from horizontal),
        *major_axis*, and *minor_axis* must be found after the *coordinates* [and *value*] columns. This option yields
        a Cartesian ellipse whose shape is unaffected by the map projection.  If only a single
        *argument* is given then we plot a degenerate ellipse (circle) with that diameter.

    **-SE**\ [*azimuth*/]\ *major_axis*\ [/*minor_axis*]
        Same as **-Se**, except *azimuth* (in degrees east of north) should be
        given instead of *direction*. The *azimuth* will be mapped into an angle
        based on the chosen map projection (**-Se** leaves the directions
        unchanged.)  Furthermore, *major_axis* and *minor_axis* must be given in
        geographical instead of plot-distance units.  For degenerate ellipses (i.e.,
        circles) with just a *diameter* given via the input data, use **-SE-**, while on
        the command line **-SE**\ *diameter* will plot the degenerate ellipse. For a
        linear projection we assume the dimensions are given in the same units as |-R|.
        For allowable geographical units, see `Units`_ and append desired unit to the dimension(s);
        if dimensions are read from the input then either just append the unit for these values
        or append the unit to each dimension in the file (do not do both) [Default is k for km].
        The shape of the ellipse will be affected by the properties of the map projection.

    **-Sj**\ [*direction*/]\ *width*\ [/*height*]
        Rotated rectangle. If not given, then *direction* (in degrees counter-clockwise from
        horizontal), *width*, and *height* must be found after the location [and *value*] columns.
        If only a single *argument* is given then we plot a degenerate rectangle (square) with given size.

    **-SJ**\ [*azimuth*/]\ *width*\ [/*height*]
        Same as **-Sj**, except *azimuth* (in degrees east of north) should be
        given instead of *direction*. The *azimuth* will be mapped into an angle
        based on the chosen map projection (**-Sj** leaves the directions
        unchanged.) Furthermore, the two dimensions must be given in geographical
        instead of plot-distance units. For a degenerate rectangle (i.e., square)
        with one *dimension* expected to be given via the input data, use **-SJ-**, while on
        the command line **-SJ**\ *side* will plot the degenerate rectangle (square). For
        a linear projection we assume the dimensions are given in the same units as |-R|.
        For allowable geographical units, see `Units`_ and append desired unit to the dimension(s);
        if dimensions are read from the input then either just append the unit for these values
        or append the unit to each dimension in the file (do not do both) [Default is k for km].
        The shape of the rectangle will be affected by the properties of the map projection.

    **-Sr**\ *width*/*height*
        **r**\ ectangle. If *width*/*height* are not given, then these
        dimensions must be found after the location [and *value*] columns.  Alternatively, append **+s**
        and then the diagonal corner coordinates are expected after the location [and *value*] columns instead.

    **-SR**\ *width*/*height*/*radius*
        **R**\ ounded rectangle. If *width*/*height*/*radius* are not given, then the
        two dimensions and corner radius must be found after the location [and *value*] columns.

    **-Sw**\ [*outer*\ [/*startdir*/*stopdir*]][**+a**\ [*dr*]][**+i**\ [*inner*]][**+p**\ *pen*][**+r**\ [*da*]]
        Pie **w**\ edge. Give the outer diameter *outer*, *startdir* and *stopdir*.
        These are directions (in degrees counter-clockwise from horizontal) for wedge.
        Parameters not appended are read from file after the location [and *value*] columns.
        Append **+i** and append a nonzero inner diameter *inner* or it will be read last [0].
        Append **+a**\ [*dr*] to draw the arc line (at inner and outer diameter);
        if *dr* is appended then we draw all arc lines separated radially by *dr*.
        Append **+r**\ [*da*] to draw radial lines (at start and stop directions)
        if *da* is appended then we draw all radial lines separated angularly by *da*.
        These spider-web lines are drawn using the current pen unless **+p**\ *pen* is added.

    **-SW**\ [*outer*\ [/*startaz*/*stopaz*]][**+a**\ [*dr*]][**+i**\ [*inner*]][**+p**\ *pen*][**+r**\ [*da*]]
        Same as **-Sw**, except azimuths (in degrees east of north) should
        be given instead of the two directions. The azimuths will be mapped
        into angles based on the chosen map projection (**-Sw** leaves the
        directions unchanged).  The two diameters are expected in geographic units.
        For allowable geographical units, see `Units`_ and append desired unit to the dimension(s);
        if dimensions are read from the input then either just append the unit for these values
        or append the unit to each dimension in the file (do not do both) [Default is k for km].
        However, if specified on the command line we also accept plot dimension units.
        Append **+i** and append a nonzero inner diameter *inner* or it will be read last [0].
        Append **+a**\ [*dr*] to draw the arc line (at inner and outer diameter);
        if *dr* is appended then we draw all arc lines separated radially by *dr*.
        Append **+r**\ [*da*] to draw radial lines (at start and stop directions)
        if *da* is appended then we draw all radial lines separated angularly by *da*.
        These spider-web lines are drawn using the current pen unless **+p**\ *pen* is added.

    Text is normally placed with :doc:`text` but there are times we wish to treat a character
    of even a string as a symbol to be plotted:

    .. figure:: /_images/GMT_base_symbols3.*
        :width: 600 px
        :align: center

        A text symbol can be any letter or string (up to 256 characters) and you may specify
        specific fonts (size and type) and control outline and the fill properties. Note there
        is no mechanism to perfectly center the string; see |-D| to make a simple global adjustment.

    **-Sl**\ *size*\ **+t**\ *string*\ [**+a**\|\ **A**\ *angle*]\ [**+f**\ *font*][**+j**\ *justify*]
        **l**\ etter or text string (less than 256 characters). Give size, and
        append **+t**\ *string* after the size. **Note**: The size is only approximate;
        no individual scaling is done for different characters. Remember to
        escape special characters like \*. Optionally, you may append **+a** to change the
        angle with the horiontal [0] or use **+A** to indicate map azimuth instead, **+f**\ *font*
        to select a particular font [Default is :term:`FONT_ANNOT_PRIMARY`] and
        **+j**\ *justify* to change justification [CM].

    The next type of symbol is the horizontal or vertical bar:

    .. figure:: /_images/GMT_base_symbols4.*
        :width: 700 px
        :align: center

        We may place vertical (**b**) or horizontal (**B**) bars, and they may extend from the
        *base* of your choosing.  The thickness of a bar can be a given dimension or can be
        specified in the units of that axis so its width scales with the projection and region.
        Using modifiers **+v** or **+i** you can also plot multi-band bars with colors set via |-C|,
        and **+s** can represent those as groups of individual bars instead.

    **-Sb**\ [*size*\ [**c**\|\ **i**\|\ **p**\|\ **q**]][**+b**\ \|\ **B**\ [*base*]][**+v**\|\ **i**\ *ny*][**+s**\ [*gap*]]
        Vertical **b**\ ar extending from *base* to y. The *size* is bar width.
        Append **q** if *size* is a quantity in x-units [Default is plot-distance units **c**\|\ **i**\|\ **p**].
        By default, *base* = 0. Append **+b**\ [*base*] to change this
        value. If *base* is not appended then we read it from the last input
        data column.  Use **+B**\ [*base*] if the bar height is measured relative
        to *base* [Relative to origin]. Normally, the bar requires a single input *y*-value.
        To plot multi-band bars, please append **+v**\|\ **i**\ *ny*, where *ny* indicates the
        total number of bands in the bar (and hence the number of values required to follow
        the x,y coordinate pair in the input).  Here, **+i** means we must accumulate the
        bar values from the increments *dy*, while **+v** means we get the complete
        values relative to *base* in increasing order. Normally, the bands are plotted as sections of a final single bar.
        Use **+s** to instead split the bar into *ny* side-by-side, individual and thinner bars. The
        optional *gap* is a percent (of fraction) of *size* for adding gaps between the bars [none],
        where *size* is the combined width of all the individual, thinner bars plus the gaps.
        Multi-band bars require |-C| with one color per band (CPT z-values must be 0, 1, ..., *ny* - 1).
        Thus, input records are either (*x y1 y2 ... yn*) or (*x dy1 dy2 ... dyn*).

    **-SB**\ [*size*\ [**c**\|\ **i**\|\ **p**\|\ **q**]][**+b**\ \|\ **B**\ [*base*]][**+v**\|\ **i**\ *nx*][**+s**\ [*gap*]]
        Horizontal **B**\ ar extending from *base* to x. The *size* is bar width.
        Append **q** if *size* is a quantity in y-units [Default is plot-distance units **c**\|\ **i**\|\ **p**].
        By default, *base* = 0. Append **+b**\ [*base*] to change this
        value. If *base* is not appended then we read it from the last input
        data column.  Use **+B**\ [*base*] if the bar length is measured relative
        to *base* [Relative to origin]. Normally, the bar requires a single input *x*-value.
        To plot multi-band bars, please append **+v**\|\ **i**\ *nx*, where *nx* indicates the
        total number of bands in the bar (and hence the number of values required to follow
        the x,y coordinate pair in the input).  Here, **+i** means we must accumulate the
        bar value from the increments *dx*, while **+v** means we get the complete
        values relative to *base* in increasing order. Normally, the bands are plotted as sections of a final single bar.
        Use **+s** to instead split the bar into *nx* side-by-side, individual and thinner bars. The
        optional *gap* is a percent (of fraction) of *size* for adding gaps between the bars [none],
        where *size* is the combined width of all the individual, thinner bars plus the gaps.
        Multi-band bars require |-C| with one color per band (CPT z-values must be 0, 1, ..., *nx* - 1).
        Thus, input records are either (*x1 y x2 ... xn*) or (*dx1 y dx2 ... dxn*).

    The next family of symbols are all different types of *vectors*. Apart from requiring parameters
    such as *length* and *direction* (or optionally the coordinates of the end point), we also
    offer a rich set of modifiers to customize the vector head(s).

    .. figure:: /_images/GMT_base_symbols5.*
        :width: 600 px
        :align: center

        There are three classes of vectors: Cartesian (left), circular (center) and geographic (right).
        While their use is slightly different, they all share common modifiers that affect how
        they are displayed.

    **-Sm**\ *size*\ [**+**\ *vecmodifiers*]
        **m**\ ath angle arc, optionally with one or two arrow heads [Default is
        no arrow heads]. The *size* is the length of the vector head. Arc width
        is set by |-W|, with vector head outlines defaulting to half of arc width.
        The *radius* of the arc and its *start* and *stop* directions (in degrees
        counter-clockwise from horizontal) must be given after the location [and *value*]
        columns. See `Vector Attributes`_ for specifying other attributes.

    **-SM**\ *size*\ [**+**\ *vecmodifiers*]
        Same as **-Sm** but switches to straight angle symbol if *start* and *stop*
        angles subtend 90 degrees exactly.

    **-Sv**\ *size*\ [**+**\ *vecmodifiers*]
        **v**\ ector. The *direction* (in degrees counter-clockwise from
        horizontal) and *length* must be found after the location [and *value*] columns,
        and *size*, if not specified on the command-line, should be present as well,
        pushing the other items to later columns.
        The *size* is the length of the vector head. Vector stem width is set by |-W|,
        with head outline pen width defaulting to half of stem pen width.
        See `Vector Attributes`_ for specifying this and other attributes.

    **-SV**\ *size*\ [**+**\ *vecmodifiers*]
        Same as **-Sv**, except *azimuth* (in degrees east of north) should be
        given instead of *direction*. The *azimuth* will be mapped into an angle
        based on the chosen map projection (**-Sv** leaves the directions
        unchanged.) If your *length* is not in plot units but in arbitrary
        user units (e.g., a rate in mm/yr) then you can use the **-i** option
        to scale the corresponding column via the **+s**\ *scale* modifier.
        See `Vector Attributes`_ for specifying symbol attributes.

    **-S=**\ *size*\ [**+**\ *vecmodifiers*]
        Geographic vector. Here, *azimuth* (in degrees east from north) and geographical *length*
        must be found after the location [and *value*] columns. The *size* is the length of the
        vector head. Vector width is set by |-W|. See `Vector Attributes`_
        for specifying attributes. **Note**: Geovector stems are drawn as thin
        filled polygons and hence pen attributes like dashed and dotted are
        not available. For allowable geographical units for the length, see `Units`_ [k].
        If your *length* is not in distance units but in arbitrary user units (e.g., a rate in
        mm/yr) then you can use the **-i** option to scale the corresponding column via the **+s**\ *scale* modifier.

    The next symbol is the programmable *custom* symbol:

    .. figure:: /_images/GMT_base_symbols6.*
        :width: 600 px
        :align: center

        Custom symbols are designed using the :ref:`Custom Symbol Macro Language <Custom_symbols>`.
        We supply about 40 custom symbols, and users have contributed discipline-specific
        symbols for structural geology and marine biology that you can explore from
        the :ref:`RESOURCES page <symbols_gallery>`, so you have lots of
        examples to use as a template.  The language allows you to design symbols that
        take many parameters and can make decisions based on these parameters.

    **-S**\ [**k**\ *name*\ [/\ *size*]]
        A **k**\ ustom symbol. We will look for a symbol definition file called *name*\ .def in
        (1) the current directory, (2) in ~/.gmt or (3) in **$GMT_SHAREDIR**/custom.
        The symbol in the definition file is of normalized unit size by default;
        the appended *size* will scale the symbol accordingly. Users may create their own
        custom \*.def files; see `Custom Symbols`_ below.
        Alternatively, you can supply an EPS file instead of a \*.def file and
        we will scale and place that graphic as a symbol.  If *size* is not given then we
        expect in from the input file. **Note**: To also give the name of the custom
        symbol via the input, the trailing text must start with the symbol name which must
        include the leading **k**. The *size* must either be given as a numerical column
        (as for all other symbols) or be added to the name with the required slash.

    The last group of symbols are all special *lines* with embellishments along them.
    The first symbol is called a *front* and has specific
    symbols distributed along the curve.  Typical uses are weather fronts, fault lines,
    and more.  While the line appearance is controlled by |-W|, there are many modifiers
    to control the selection and appearance of the along-line symbols:

    .. figure:: /_images/GMT_base_symbols7.*
        :width: 600 px
        :align: center

        Fronts offer various symbols, such as squares, triangles and circles that may be
        plotted centered or as a half-symbols on one side.  Special options exist for indicating
        motion (e.g., faults) along a line.

    **-Sf**\ [±]\ *gap*\ [/*size*][**+l**\|\ **+r**][**+b**\|\ **c**\|\ **f**\|\ **s**\ [*angle*]\ \|\ **t**\ \|\ **v**][**+o**\ *offset*][**+p**\ [*pen*]].
        Draw a **f**\ ront. Supply distance *gap* between symbols and symbol *size*.
        If *gap* is negative, it is interpreted to mean the *number* of symbols along the
        front instead. If *gap* has a leading + then we use the value exactly as given
        [Default will start and end each line with a symbol, hence the *gap* is adjusted to fit].
        If *size* is missing it is set to 30% of the *gap*, except when *gap* is negative
        and *size* is thus required.  Append **+l** or **+r** to plot symbols on the left or
        right side of the front [Default is centered]. Append **+**\ *type* to
        specify which symbol to plot: **b**\ ox, **c**\ ircle, **f**\ ault,
        **s**\ lip, **t**\ riangle or in\ **v**\ erted triangle. [Default is **f**\ ault]. Slip means
        left-lateral or right-lateral strike-slip arrows (centered is not an
        option). The **+s** modifier optionally accepts the angle used to draw
        the vector [20]. Alternatively, use **+S** which draws arcuate arrow
        heads. Append **+o**\ *offset* to offset the first symbol from the
        beginning of the front by that amount [0]. The chosen symbol is drawn
        with the same pen as set for the line (i.e., via |-W|). To use an
        alternate pen, append **+p**\ *pen*. To skip the outline, just use
        **+p** with no argument.  To make the main front line invisible, add **+i**.  **Note**:
        By placing **-Sf** options in the segment headers that differ from the one on
        the command line you can change the front types on a segment-by-segment basis.

    The next type of embellished line is called a *quoted* line, which is our term for
    a line with text along it, similar to an annotated contour in a contour map. There is
    a rich set of directives and modifiers available to select a specific outcome:

    .. figure:: /_images/GMT_base_symbols8.*
        :width: 600 px
        :align: center

        Quoted lines (**-Sq**) are lines with text.  However, the text can be static, read via files,
        or be quantities computed along the line.  This example just shows a wiggly line with
        a text-aligned label.  A rich set of modifier controls the appearance.

    **-Sq**\ **d**\|\ **D**\|\ **f**\|\ **l**\|\ **L**\|\ **n**\|\ **N**\|\ **s**\|\ **S**\|\ **x**\|\ **X**\ *posinfo*\ [:*labelinfo*]
        **q**\ uoted line, i.e., lines with occasional annotations such as contours. Append
        a required algorithm code and *posinfo* that control the placement of labels along the quoted lines.
        **Note**: The colon separates the algorithm settings from the label information.
        Choose among six controlling algorithms:

            **d**\ *dist*\ [**c**\|\ **i**\|\ **p**][/\ *frac*] or **D**\ *dist*\ [**d**\|\ **e**\|\ **f**\|\ **k**\|\ **m**\|\ **M**\|\ **n**\|\ **s**][/\ *frac*]
                For lower case **d**, give distances between labels on the plot in
                your preferred measurement unit **c** (cm), **i** (inch), or **p**
                (points), while for upper case **D**, specify distances in map units
                and append the unit; choose among **e** (m), **f** (foot), **k**
                (km), **M** (mile), **n** (nautical mile) or **u** (US survey foot),
                and **d** (arc degree), **m** (arc minute), or **s** (arc second).
                [Default is 10\ **c** or 4\ **i**]. As an option, you can append
                append *frac* which will place the first label at the distance *d = dist*
                :math:`\times` *frac* from the start of a line (and every
                *dist* thereafter). If not given, *frac* defaults to 0.25.

            **f**\ *file.txt*\ [/*slop*\ [**c**\|\ **i**\|\ **p**]]
                Read the ASCII file *file.txt* and places labels at locations in the
                file that best matches locations along the quoted lines. Labels will
                only be placed if the coordinates match the line coordinates to
                within a distance of *slop* (append desired unit or we use
                :term:`PROJ_LENGTH_UNIT`). The default *slop* is zero, meaning only
                exact coordinate matches will do.

            **l**\|\ **L**\ *line1*\ [,\ *line2*,...]
                Give the coordinates of the end points for one or more comma-separated straight line segments.
                Labels will be placed where these lines intersect the quoted lines.
                The format of each *line* specification is *start_lon*/*start_lat*/*stop_lon*/*stop_lat*.
                Both *start_lon*/*start_lat* and *stop_lon*/*stop_lat* can be replaced by a 2-character key
                that uses the justification format employed in **text** to indicate a point on the frame or
                center of the map, given as [LCR][BMT]. Alternatively, select **L** to interpret the point
                pairs as defining great circle segments [Default is straight lines].

            **n**\|\ **N**\ *n_label*\ [/*min_dist*\ [**c**\|\ **i**\|\ **p**]]
                Specify the number of equidistant labels for quoted lines
                [1]. Upper case **N** starts labeling exactly at the start of the
                line [Default centers them along the line]. **N**-1 places one
                justified label at start, while **N**\ +1 places one justified label
                at the end of quoted lines. Optionally, append
                /*min_dist*\ [**c**\|\ **i**\|\ **p**] to enforce a
                minimum distance separation between successive labels.

            **s**\|\ **S**\ *n_label*\ [/*min_dist*\ [**c**\|\ **i**\|\ **p**]]
                Same as **n**\|\ **N**\ *n_label* but implies that the input data are
                first to be converted into a series of 2-point line segments before plotting.

            **x**\|\ **X**\ *xfile.txt*
                Read the ASCII multisegment file *xfile.txt* and places labels at the
                intersections between the quoted lines and the lines in *xfile.txt*.
                **X** will resample the lines first along great-circle arcs.
                In addition, you may optionally append
                **+r**\ *radius*\ [**c**\|\ **i**\|\ **p**] to set a minimum
                label separation in the x-y plane [no limitation].

            The optional *labelinfo* controls the specifics of the label
            formatting.  If not provided we default to the text "N/A".  The argument
            consists of a concatenated string made up of any of the following modifiers:

            **+a**\ *angle*
                Force annotations at a fixed angle, **+an** for line-normal, or
                **+ap** for line-parallel [Default].

            **+c**\ *dx*\ [/*dy*]
                Set clearance between label and optional text box. Append
                **c**\|\ **i**\|\ **p** to specify the unit or % to indicate a
                percentage of the label font size [15%].

            **+d**\ [*pen*]
                Turn on debug, which will draw helper points and lines to illustrate
                the workings of the quoted line setup. Optionally append the pen
                to use [:term:`MAP_DEFAULT_PEN`].

            **+e**
                Delay plotting of the text. This is used to build a clip path
                based on the text, then lay down other overlays while that clip path
                is in effect, then turning off clipping with clip **-Cs** which
                finally plots the pending text.

            **+f**\ *font*
                Set the desired font [Default :term:`FONT_ANNOT_PRIMARY` with its
                size changed to 9p].

            **+g**\ [*color*]
                Select opaque text boxes [Default is transparent]; optionally
                specify the color [Default is :term:`PS_PAGE_COLOR`].

            **+i**
                Make the main quoted line invisible [Draw it per |-W|].

            **+j**\ *just*
                Set label justification [Default is MC]. Ignored when
                **-SqN**\|\ **n**\ +\|-1 is used.

            **+l**\ *label*
                Set the constant label text. **Note**: if the text length exceeds
                the line length then no text will appear.

            **+L**\ *flag*
                Set the label text according to the specified flag:

                **+Lh**
                Take the label from the current segment header (first scan for
                an embedded **-L**\ *label* option, if not use the first word
                following the segment flag). For multiple-word labels, enclose
                entire label in double quotes.
                **+Ld**
                Take the Cartesian plot distances along the line as the label;
                append **c**\|\ **i**\|\ **p** as the unit [Default is
                :term:`PROJ_LENGTH_UNIT`].
                **+LD**
                Calculate actual map distances; append
                **d\|e\|f\|k\|n\|M\|n\|s** as the unit [Default is
                **d**\ (egrees), unless label placement was based on map
                distances along the lines in which case we use the same unit
                specified for that algorithm]. Requires a map projection to be
                used.
                **+Lf**
                Use text after the 2nd column in the fixed label location file
                as the label. Requires the fixed label location setting.
                **+Lx**
                As **+Lh** but use the headers in the *xfile.txt* instead.
                Requires the crossing file option.

            **+n**\ *dx*\ [/*dy*]
                Nudge the placement of labels by the specified amount (append
                **c**\|\ **i**\|\ **p** to specify the units). Increments
                are considered in the coordinate system defined by the
                orientation of the line; use **+N** to force increments in the
                plot x/y coordinates system [no nudging]. Not allowed with **+v**.

            **+o**
                Select rounded rectangular text box [Default is rectangular].
                Not applicable for curved text (**+v**) and only makes sense for
                opaque text boxes.

            **+p**\ [*pen*]
                Draw outline of text boxes [Default is no outline];
                optionally specify pen for outline [Default is width = 0.25p,
                color = black, style = solid].

            **+r**\ *min_rad*
                Will not place labels where the line's radius of curvature is
                less than *min_rad* [Default is 0].

            **+t**\ [*file*]
                Save line label *x, y, angle, text* to *file* [Line_labels.txt].

            **+u**\ *unit*
                Append *unit* to all line labels [Default is no unit].

            **+v**
                Specify curved labels following the path [Default is straight labels].

            **+w**
                Specify how many (*x*,\ *y*) points will be used to estimate smooth
                label angles [Default is 10].

            **+x**\ [*first*,\ *last*]
                Append the suffixes *first* and *last* to the corresponding labels.
                This modifier is only available when **-SqN2** is in effect.  Used
                to annotate the start and end of a line (e.g., a cross-section),
                append two text strings separated by comma
                [Default just adds a prime to the second label].

            **+=**\ *prefix*
                Prepend *prefix* to all line labels [Default is no prefix].

        **Note**: By placing **-Sq** options in the segment headers that differ from the one on
        the command line you can change the quoted text attributes on a segment-by-segment basis.

    The final type of embellished line is called a *decorated* line (**-S~**).  It is a hybrid
    between a *front* and *quoted* lines in that it offers symbols similar to a front
    but the placement can be specified in ways similar to the quoted line.  However, no built-in
    clipping exists, such as for quoted lines:

    .. figure:: /_images/GMT_base_symbols9.*
        :width: 600 px
        :align: center

        Decorated lines with eleven squares evenly spaced along the line.  By default,
        the symbol is aligned with the line trend, but numerous modifiers allow you to
        customize the appearance, including to make the line invisible.

    **-S~**\ **d**\|\ **D**\|\ **f**\|\ **l**\|\ **L**\|\ **n**\|\ **N**\|\ **s**\|\ **S**\|\ **x**\|\ **X**\ *posinfo*\ :*symbolinfo*
        Decorated line, i.e., lines with symbols placed along them. Append
        a required algorithm code and *posinfo* that control the placement of symbols along the decorated lines.
        **Note**: The colon separates the algorithm settings from the required symbol information.
        Choose among six controlling algorithms:

            **d**\ *dist*\ [**c**\|\ **i**\|\ **p**][/\ *frac*] or **D**\ *dist*\ [**d**\|\ **e**\|\ **f**\|\ **k**\|\ **m**\|\ **M**\|\ **n**\|\ **s**][/\ *frac*]
                For lower case **d**, give distances between symbols on the plot in
                your preferred measurement unit **c** (cm), **i** (inch), or **p**
                (points), while for upper case **D**, specify distances in map units
                and append the unit; choose among **e** (m), **f** (foot), **k**
                (km), **M** (mile), **n** (nautical mile) or **u** (US survey foot),
                and **d** (arc degree), **m** (arc minute), or **s** (arc second).
                [Default is 10\ **c** or 4\ **i**]. As an option, you can append
                append *frac* which will place the first symbol at the distance *d = dist*
                :math:`\times` *frac* from the start of a line (and every
                *dist* thereafter). If not given, *frac* defaults to 0.25.

            **f**\ *file.txt*\ [/*slop*\ [**c**\|\ **i**\|\ **p**]]
                Read the ASCII file *file.txt* and place symbols at locations in the
                file that matches locations along the decorated lines. Symbols will
                only be placed if the coordinates match the line coordinates to
                within a distance of *slop* (append desired unit or we use
                :term:`PROJ_LENGTH_UNIT`). The default *slop* is zero, meaning only
                exact coordinate matches will do.

            **l**\|\ **L**\ *line1*\ [,\ *line2*,...]
                Give the coordinates of the end points for one or more comma-separated straight line segments.
                Symbols will be placed where these lines intersect the decorated lines.
                The format of each *line* specification is *start_lon*/*start_lat*/*stop_lon*/*stop_lat*.
                Both *start_lon*/*start_lat* and *stop_lon*/*stop_lat* can be replaced by a 2-character key
                that uses the justification format employed in **text** to indicate a point on the frame or
                center of the map, given as [LCR][BMT].
                **L** will interpret the point pairs as defining great circles [Default is straight line].

            **n**\|\ **N**\ *n_symbol*\ [/*min_dist*\ [**c**\|\ **i**\|\ **p**]]
                Specify the number of equidistant symbols for decorated lines
                [1]. Upper case **N** starts placing symbols exactly at the start of the
                line [Default centers them along the line]. **N**-1 places one symbol
                at start, while **N**\ +1 places one symbol at the end of decorated lines.
                Optionally, append /*min_dist*\ [**c**\|\ **i**\|\ **p**] to enforce a
                minimum distance separation between successive symbols.

            **s**\|\ **S**\ *n_symbol*\ [/*min_dist*\ [**c**\|\ **i**\|\ **p**]]
                Same as **n**\|\ **N**\ *n_symbol* but implies that the input data are
                first to be converted into a series of 2-point line segments before plotting.

            **x**\|\ **X**\ *xfile.txt*
                Read the ASCII multisegment file *xfile.txt* and places symbols at the
                intersections between the decorated lines and the lines in *xfile.txt*.
                **X** will resample the lines first along great-circle arcs.

            The required *symbolinfo* controls the specifics of the symbol selection and
            formatting and consists of a concatenated string made up of any of
            the following modifiers:

            **+a**\ *angle*
                Force symbols at a fixed angle, **+an** for line-normal, or
                **+ap** for line-parallel [Default].

            **+d**\ [*pen*]
                Turn on debug, which will draw helper points and lines to illustrate
                the workings of the decorated line setup. Optionally append the pen
                to use [:term:`MAP_DEFAULT_PEN`].

            **+g**\ [*fill*]
                Set the symbol fill [no fill].

            **+i**
                Make the main decorated line invisible [Draw it using pen settings provided by |-W|].

            **+n**\ *dx*\ [/*dy*]
                Nudge the placement of symbols by the specified amount (append
                **c**\|\ **i**\|\ **p** to specify the units). Increments
                are considered in the coordinate system defined by the
                orientation of the line; use **+N** to force increments in the
                plot x/y coordinates system [no nudging].

            **+p**\ [*pen*]
                Draw the outline of symbols [Default is no outline];
                optionally specify pen for outline [Default is width = 0.25p,
                color = black, style = solid].

            **+s**\ <symbol><size> or **+sk**\ *customsymbol*/*size*
                Specify the code and size of the decorative symbol.
                Custom symbols need to be simple, i.e., not require data columns,
                or be a single EPS file.  Hence, valid symbols are limited to the
                plain geometric one-parameter symbols and the custom symbol (**k**).

            **+w**
                Specify how many (*x*,\ *y*) points will be used to estimate
                symbol angles [Default is 10].

        If neither **+g** nor **+p** are set we select the default pen outline (:term:`MAP_DEFAULT_PEN`).
        **Note**: By placing **-S~** options in the segment headers that differ from the one on
        the command line you can change the decorated lines on a segment-by-segment basis.