Figure.text: Allow passing a sequence of offset to the 'offset' parameter

[seisman]

Passing a sequence of offsets to Figure.text is frequently used but not supported yet.

This PR supports it and also migrates offset to the new alias system.

[weiji14]

Should we keep the "c" unit specifier? The gmt.conf docs say:

It is recommended that users specify the units for distances and lengths by appending c (cm), i (inch), or p (points) when changing parameters using any of these methods. By default, when no unit is specified the value will be assumed to be cm for parameters not related to fonts or pen thicknesses and will be assumed to be points for parameters related to fonts or pen thicknesses.

So recommended is to append the unit, but no unit means centimeter in some but not all cases (I guess offset counts as non-font/pen thickness?). Maybe keep it as ("0c", "0.3c") to be clearer?

[seisman]

Yes, appending the unit specifier is recommended in the GMT CLI. However, in PyGMT, I feel it is more natural to use plain numbers for quantities such as offsets, widths, and sizes. They are much shorter to type and can also be used directly in calculations.

[Copilot]

Pull request overview

This PR updates pygmt.Figure.text to accept tuple/sequence forms for the offset parameter and migrates offset handling to PyGMT’s newer AliasSystem, with corresponding documentation and example updates.

Changes:

• Add offset to Figure.text’s signature and handle it via AliasSystem (-D option) with sep="/" and size=2.
• Update the text docstring to document tuple-style offsets.
• Update gallery/tutorial examples to use numeric/tuple offsets instead of unit-suffixed strings.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
pygmt/src/text.py	Adds offset parameter + AliasSystem wiring for -D, and updates documentation for tuple offsets.
examples/tutorials/basics/text.py	Switches fig.text(..., offset=...) examples from strings (e.g., "1c/-0.5c") to tuples.
examples/gallery/symbols/points_cities.py	Updates offset example usage from "0.12c" to 0.12.
examples/gallery/lines/vector_heads_tails.py	Updates offset example usage from string to tuple.
examples/gallery/lines/quoted_lines.py	Updates offset example usage from string to tuple.
examples/gallery/lines/linestyles.py	Updates offset example usage from strings to tuples.
examples/gallery/lines/linefronts.py	Updates offset example usage from string to tuple.
examples/gallery/lines/decorated_lines.py	Updates offset example usage from string to tuple.
examples/gallery/images/cross_section.py	Updates offset example usage from string to tuple and adjusts the comment accordingly.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.