Segment Header Parsing
----------------------

Segment header records may contain one of more of the following options:

**-G**\ *fill*
    Use the new *fill* and turn filling on
**-G-**
    Turn filling off
**-G**
    Revert to default fill (none if not set on command line)
**-L**\ *label*
    Set a label for this segment (e.g., perhaps for quoted lines)
**-W**\ *pen*
    Use the new *pen* and turn outline on
**-W**
    Revert to default pen :term:`MAP_DEFAULT_PEN`
    (if not set on command line)
**-W-**
    Turn outline off
**-Z**\ *zval*
    Obtain fill via cpt lookup using z-value *zval* (what the color is used
    for is controlled further by |-L| or **-W**)
**-Z**\ *NaN*
    Get the NaN color from the CPT
**-t**\ *transparency*
    Obtain transparency and apply it to fill and pen colors.

Custom Symbols
--------------

GMT allows users to define and plot their own custom symbols. This
is done by encoding the symbol using our custom symbol macro code
described in Appendix N. Put all the macro codes for your new symbol in
a file whose extension must be .def; you may then address the symbol
without giving the extension (e.g., the symbol file tsunami.def is used
by specifying **-Sk**\ *tsunami/size*. The definition file can contain
any number of plot code records, as well as blank lines and comment
lines (starting with #). The module will look for the definition files in
(1) the current directory, (2) the ~/.gmt directory, and
(3) the **$GMT_SHAREDIR**/custom directory, in that order.
Freeform polygons (made up of straight line segments and arcs of
circles) can be designed - these polygons can be painted and filled with
a pattern. Other standard geometric symbols can also be used. See Appendix
:ref:`App-custom_symbols` for macro definitions.

GMT4 Vector
-----------

**Note**: The old-style, single-polygon vector available in GMT4 and earlier versions
has been added to GMT5 for backwards compatibility with old scripts.
For reference, the old vector syntax is listed here:
The *size*, if present, will be interpreted as *arrowwidth/headlength/headwidth*.
By default, arrow attributes remain invariant to the length
of the arrow.  To have the size of the vector scale down with decreasing length,
append **n**\ *norm*, so that vectors shorter than *norm* will have their
dimensions scaled by the vector length divided by *norm*.
To center the vector on the balance (mid) point, use **-Svb**; to align point with the vector head,
use **-Svh**; to align point with the vector tail, use **-Svt** [Default].
If the input has the head point's coordinates instead of direction and length, use **-Svs**.
Upper case **B**, **H**, **T**, or **S** will draw a double-headed vector [Default is single head].

Polar Caps
----------

We will automatically determine if a closed polygon is containing
a geographic pole, i.e., being a polar cap.  Such polygons requires special
treatment under the hood to ensure proper filling.  Many tools such
as GIS packages are unable to handle polygons covering a pole and some
cannot handle polygons crossing the Dateline.  They work around this
problem by splitting polygons into a west and east polygon or inserting
artificial helper lines that makes a cut into the pole and back.  Such
doctored polygons may be misrepresented in GMT.

Bezier spline
-------------

The **+s** modifier to pen settings (**-W**) is limited to plotting lines and
polygons.  Lines with embellishments (fronts, decorated, or quoted lines) are
excluded.

Auto-Legend
-----------

The **-l** option for symbols expects the symbol color, size, and type to be given
on the command line.  If you have variable symbol sizes then you must append **+s**\ *size* to set
a suitable size for the legend entry.  For other symbol cases the **-l** option will
be ignored.  Legend entries also work for lines and polygons, but not more complicated
features such as decorated and quoted lines, fronts, etc.

Data Column Order
-----------------

The |-S| option determines how many size columns are required to generate
the selected symbol, but if *size* is not given then we expect to read *size*
from file.  In addition, your use of options |-H|, |-I| and **-t** will
require extra columns.  The order of the data record is fixed regardless of
option order, even if not all items may be activated. We expect data columns
to come in the following order::

    x y [z] [size-columns] [scale] [intens] [transp [transp2]] [trailing-text]

where items given in brackets are optional and under the control of the stated
options: |-C| selects the optional *z* column for color-lookup, |-S| without
a size selects the optional *size-columns* (may be more than one depending on
the selected symbol), |-H| selects the optional *scale* column, |-I| selects
the optional *intens* column, and **-t** selects the optional *transp* column(s).
Trailing text is always optional.  **Notes**: (1) If symbol *code* is not given
by |-S| then it is expected to start the trailing text. (2) You can use **-i** to
rearrange your data record to match the expected format.
