Figure.inset: Deprecate parameter margin to clearance (Will be removed in v0.20.0)

[yvonnefroehlich]

Description of proposed changes

To make the parameter name consistent with Figure.suplot and to consider that a list can be passed with different margins for the different sides.
Note: Since GMT 6.4.0 -M is changed to -C (see #4296 (comment)), so it should be not margins but clearance (see #4296 (comment)).

Preview:

Guidelines

• General Guidelines for Pull Request
• Guidelines for Contributing Documentation
• Guidelines for Contributing Code

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash command is:

• /format: automatically format and lint the code

[seisman]

It's a good time to decide the implemention of the margins parameter. The GMT documentation says:

Reserve a space of dimension clearance between the actual inset plot area and the given inset box on the specified side, using side values from w, e, s, or n, or x for both w and e or y for both s and n. No side means all sides. The option is repeatable to set aside space on more than one side. Alternatively, if all sides are to be set you can also give a pair of values separated by slashes (for setting separate horizontal and vertical margins), or the full set of four separate margins. Such space will be left untouched by the inset map plotting. Append units as desired [Default is set by PROJ_LENGTH_UNIT].

So, the GMT CLI usage can be:

• -C1: for all sides
• -C1/2: for x and y sides, respectively
• -C1/2/3/4: for w, e, s, and n sides, respectively

Or, it's possible to set margins with repeated options, e.g.,

• -Cx1
• -Cx1 -Cy2
• -Cw1 -Cs3
• -Cw1 -Ce2 -Cs3 -Cn4

I feel it's technically possible but difficult to support both. To keep it simple, I would prefer to only support the first usage, i.e.,:

• margins=1
• margins=(1, 2)
• margins=(1, 2, 3, 4)

To set margins for specific sides only, users can set it to 0. For example,

• -Cx1 is equivalent to margins=(1, 0)
• -Cw1 -Cs3 is equivalent to margins=(1, 0, 3, 0)

[seisman]

Actually, it should be clearance instead.

In subplot, -C is aliased to clearance and -M is aliased to margins.

[yvonnefroehlich]

Actually, it should be clearance instead.

In subplot, -C is aliased to clearance and -M is aliased to margins.

With the change from -M to -C we should also change the parameter name in PyGMT to have this consistent. Updatde to clearance in commit 77fadde.

[seisman]

I feel this PR is good to merge. We can update the docstrings of Figure.inset and Figure.subplot in a separate PR.