DOC: Move description of distcal to the Technical Reference section (#3868)

Co-authored-by: Michael Grund <[email protected]>
Co-authored-by: Yvonne Fröhlich <[email protected]>

Author: 3 people

Diff for: doc/techref/common_parameters.md

@@ -1,6 +1,24 @@
 # Common Parameters
 
 ```{glossary}
+``distcalc``
+    Determine how spherical distances are calculated. Valid values are:
+
+    - ``"g"``: Perform great circle distance calculations, with parameters such as
+      distance increments or radii compared against calculated great circle distances
+      [Default].
+    - ``"e"``: Select ellipsoidal (or geodesic) mode for the highest precision but
+      slowest calculation time.
+    - ``"f"``: Select Flat Earth mode, which gives a more approximate but faster result.
+
+    **Note:** (1) All spherical distance calculations depend on the current ellipsoid
+    ({gmt-term}`PROJ_ELLIPSOID`), the definition of the mean radius
+    ({gmt-term}`PROJ_MEAN_RADIUS`), and the specification of the latitude type
+    ({gmt-term}`PROJ_AUX_LATITUDE`). Geodesic distance calculations are also controlled
+    by the algorithm to use for geodesic calculations ({gmt-term}`PROJ_GEODESIC`).
+    (2) Coordinate transformations that can use ellipsoidal or spherical forms will
+    first consult this parameter if given.
+
 ``verbose``
     Select verbosity level, which modulates the messages written to stderr.
 

Diff for: pygmt/helpers/decorators.py

@@ -81,18 +81,8 @@
             """,
     "distcalc": r"""
         distcalc : str
-            **e**\|\ **f**\|\ **g**.
-            Determine how spherical distances are calculated.
-
-            - **e**: Ellipsoidal (or geodesic) mode
-            - **f**: Flat Earth mode
-            - **g**: Great circle distance [Default]
-
-            All spherical distance calculations depend on the current ellipsoid
-            (:gmt-term:`PROJ_ELLIPSOID`), the definition of the mean radius
-            (:gmt-term:`PROJ_MEAN_RADIUS`), and the specification of latitude type
-            (:gmt-term:`PROJ_AUX_LATITUDE`). Geodesic distance calculations is also
-            controlled by method (:gmt-term:`PROJ_GEODESIC`).""",
+            Determine how spherical distances are calculated
+            [:term:`Full usage <distcalc>`].""",
     "fill": r"""
         fill : str
             Set color or pattern for filling symbols or polygons