Add a separate documentation for supported plot and distance units

Author: seisman

doc/techref/index.md

@@ -10,6 +10,7 @@ visit the {gmt-docs}`GMT Technical Reference <reference.html>`.
 
 common_parameters.md
 projections.md
+units.md
 fonts.md
 text_formatting.md
 encodings.md

doc/techref/units.md

@@ -0,0 +1,34 @@
+# Units
+
+GMT uses two unit groups: **dimension units** (plot units) and **distance units** (Earth distances).
+
+(plot-units)=
+## Dimension Units (Plot Units)
+
+Use these for map widths, offsets, symbol sizes, pen widths, etc.
+
+| Code | Unit | Notes |
+|------|------|-------|
+| `c` | Centimeter | Default for most dimensions |
+| `i` | Inch | 1 inch = 2.54 cm |
+| `p` | Point | 1 point = 1/72 inch |
+
+**Defaults:** If no unit is given, GMT uses {gmt-term}`PROJ_LENGTH_UNIT` (default is `c`).
+Fonts and pen thicknesses default to `p`.
+
+(distance-units)=
+## Distance Units
+
+GMT supports various distance units for geographic calculations.
+
+| Code | Unit | Notes |
+|------|------|-------|
+| `d` | Degree | Arc degree |
+| `m` | Minute of arc | 1/60 degree |
+| `s` | Second of arc | 1/3600 degree |
+| `e` | Meter | Default distance unit |
+| `k` | Kilometer | 1000 meters |
+| `f` | Foot | 0.3048 meters |
+| `u` | US Survey Foot | 1200/3937 meters |
+| `M` | Statute Mile | 1.60934 km |
+| `n` | Nautical Mile | 1.852 km |

pygmt/src/grdproject.py

@@ -81,16 +81,15 @@ def grdproject(  # noqa: PLR0913
         When set to ``True``, do the inverse transformation, from rectangular to
         geographical [Default is ``False``].
     unit
-        Set the projected measure unit. Valid values are ``"c"`` (centimeters),
-        ``"i"`` (inches), and ``"p"`` (points) [Default is set by
-        :gmt-term:`PROJ_LENGTH_UNIT`]. Cannot be used with ``scaling``.
+        Set the projected measure unit. See :doc:`/techref/units#plot-units` for
+        supported units [Default is set by :gmt-term:`PROJ_LENGTH_UNIT`]. Cannot be used
+        with ``scaling``.
     scaling
         Force 1:1 scaling, i.e., output (or input, see ``inverse``) data are in actual
-        projected meters. To specify other units, set it to ``"f"`` (feet),
-        ``"k"`` (kilometers), ``"M"`` (statute miles), ``"n"`` (nautical miles),
-        ``"u"`` (US survey feet), ``"i"`` (inches), ``"c"`` (centimeters), or
-        ``"p"`` (points). Without ``scaling``, the output (or input, see ``inverse``) is
-        in the units specified by :gmt-term:`PROJ_LENGTH_UNIT` (but see ``unit``).
+        projected meters. To specify other units, set it to
+        a supported distance unit or plot unit (see :doc:`/techref/units`). Without
+        ``scaling``, the output (or input, see ``inverse``) is in the units specified
+        by :gmt-term:`PROJ_LENGTH_UNIT` (but see ``unit``).
     $projection
     $region
     $verbose