Improve documentation for +r option in the regions tutorial

[core-man]

Description of proposed changes

The +rincrement option in the tutorial for ISO code may mislead some new GMT users (originally posted in #983 (comment)).

---

+r option in GMT DOC

Append +r to modify exact bounding box coordinates obtained from the polygon(s): Append inc, xinc/yinc, or winc/einc/sinc/ninc to adjust the final region boundaries to be multiples of these steps [default is no adjustment]. Alternatively, use +R to extend the region outward by adding these increments instead, or +e which is like +r but it ensures that the bounding box extends by at least 0.25 times the increment [no extension]. As an example, -RFR+r1 will select the national bounding box of France rounded to nearest integer degree.

Take JP as an example:

import pygmt
fig = pygmt.Figure()
fig.coast(
    region="JP",
    projection="M12c",
    land="lightgray",
)
print(fig.region)

Output:

[122.938515 145.820877  20.528774  45.523136]

Use [+r|R|e[incs]] option:

• JP+R1: [121.938515 146.820877 19.528774 46.523136]
• JP+R2: [120.938515 147.820877 18.528774 47.523136]
• JP+R3: [119.938515 148.820877 17.528774 48.523136]
• JP+r1: [122. 146. 20. 46.]
• JP+r2: [122. 146. 20. 46.]
• JP+r3: [120. 147. 18. 48.]
• JP+e1: [122. 147. 20. 46.]
• JP+e2: [122. 148. 20. 48.]
• JP+e3: [120. 147. 18. 48.]

We can see:

• +Rinc extends the region outward by adding these increments (using +R3, 119.938515 = 122.938515 - 3)
• +rinc adjusts the final region boundaries to be multiples of these steps (using +r3, 120, 147, 18, 48 are multiples of 3)
• +einc is similar to +rinc (final region boundaries to be multiples of these steps), but it ensures that the bounding box extends by at least 0.25 times the increment. So, +e1 adjusts 145.820877 to be 147 instead of 146 by +r1 since 146-145.820877=0.18 < 0.25*1. +e2 adjusts 145.820877 to be 148, 45.523136 to be 48 for the same reason.

---

Related to #983 and #996.

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If adding new functionality, add an example to docstrings or tutorials.

Slash Commands

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

• /format: automatically format and lint the code
• /test-gmt-dev: run full tests on the latest GMT development version

[willschlitzer]

Good updates.