Extend / Add gallery example to explain "symbol" parameter of "Figure.plot"

[yvonnefroehlich]

In PR #1117, the symbol parameter was added to Figure.plot (and similarly for Figure.plot3d in #3559).

As some confusions regarding the style, symbol, and size parameters are likely, we should extend or add a gallery example or / and tutorial which explain this new parameter:

• Maybe we can extend the gallery example Points.
• Add a tutorial "Plotting symbols".

[yvonnefroehlich]

After adding the symbol parameter, there are these four possibilities:

1. same symbol and size: style parameter
2. same symbol but individual sizes: style parameter with size parameter
3. individual symbols but same size: style parameter with symbol parameter
4. individual symbols and sizes: size and symbol parameters

These four cases are covered by the examples in #3598.

[seisman]

The complexity is mainly because:

1. GMT's plot module can plot both lines/polygons and symbols
2. The style parameter (alias of -S) was introduced in the early stage of the project and at that time parameters like size/symbol were not available.

Users may think that size="0.2c", symbol="c" should work, but it doesn't. Currently we don't check if the combinations of style/size/symbol are valid.

I think we should implement the Figure.scatter method, which doesn't have the style parameter.

[seisman]

I think we should implement the Figure.scatter method, which doesn't have the style parameter.

Draft PR at #3602.

[yvonnefroehlich]

Another aspect to think about are Multi-parameter symbols. So far it seems, only single-parameter symbols can be used in the cases 2. and 4. (Multi-parameter symbols make no sense for case 3.).

[seisman]

Multi-parameter symbols needs more parameters than normal symbols. For example, for a rectangle, we need width and height, rather than size. Even in GMT, it's impossible to plot different multi-parameter symbols in a single call, because the number of columns required by different multi-parameter symbols are different.

For these multi-parameter symbols, matplotlib provides them as patches (https://matplotlib.org/stable/api/patches_api.html).